@bongos/core 1.19.372 → 1.19.374

package/scripts/gds/ship-land.js

@@ -406,6 +406,80 @@ function rerunGateReviewIfStale(branch, headSha) {
   return ghArgvOk(['run', 'rerun', String(id)]);
 }
 
+// ---------- why the push failed, and whether retrying can ever help ----------
+//
+// A failed `git push` already parks the task at `confirmed` and opens no PR,
+// which is correct. What was wrong (task 1003293) was the ADVICE: "Fix the push
+// and re-ship" is useless for the most common cause, because re-shipping fails
+// identically every time and the reconciler cannot heal a branch that was never
+// pushed. The task then sits at `confirmed` with its code on one laptop, looking
+// like an ordinary pending land. That happened twice in one session — both times
+// on a commit touching .github/workflows/, both times invisible until someone
+// checked git instead of the log.
+//
+// So the distinction that matters is TERMINAL vs transient. A terminal failure
+// must name the actual remedy; a transient one may honestly say "re-ship".
+// `argvOk` runs the push with stdio:'inherit', so git's own message reaches the
+// log but nothing ever reads it — these patterns read it.
+const PUSH_DIAGNOSES = [
+  {
+    id: 'workflow_scope',
+    // GitHub's wording: "refusing to allow an OAuth App to create or update
+    // workflow `.github/workflows/x.yml` without `workflow` scope".
+    match: /without .{0,3}workflow.{0,3} scope|refusing to allow (?:an?|the) \S+ (?:App|integration)/i,
+    terminal: true,
+    why: 'this branch changes a file under .github/workflows/, and the credential git used has no `workflow` scope — GitHub refuses that push regardless of how often it is retried',
+    fix: 'push over SSH once, then re-run the ship:\n    git push git@github.com:<owner>/<repo>.git <branch>\n  (or re-authenticate the CLI with the `workflow` scope: gh auth refresh -h github.com -s workflow)',
+  },
+  {
+    id: 'protected_branch',
+    match: /GH006|protected branch|required status check/i,
+    terminal: true,
+    why: 'branch protection refused the push outright',
+    fix: 'land through a pull request instead of pushing directly, or have an admin adjust the rule',
+  },
+  {
+    id: 'auth',
+    match: /Authentication failed|could not read Username|Permission denied \(publickey\)|remote: Invalid username or password|403 Forbidden/i,
+    terminal: true,
+    why: 'git could not authenticate to the remote at all',
+    fix: 'restore the credential (gh auth login, or an SSH key the remote accepts), then re-run the ship',
+  },
+  {
+    id: 'stale_branch',
+    match: /non-fast-forward|fetch first|behind its remote counterpart|Updates were rejected/i,
+    terminal: false,
+    why: 'the remote branch has commits this checkout does not',
+    fix: 'git fetch && git rebase origin/<branch>, then re-run the ship',
+  },
+];
+
+// Pure: classify a failed push from git's stderr. Exported + tested.
+// An unrecognised failure is reported as NON-terminal on purpose — "try again"
+// is the safe default when we do not know, and a wrong "this can never work"
+// would send someone hunting a problem that does not exist.
+function pushDiagnosis(stderr) {
+  const text = String(stderr == null ? '' : stderr);
+  for (const d of PUSH_DIAGNOSES) {
+    if (d.match.test(text)) return { id: d.id, terminal: d.terminal, why: d.why, fix: d.fix };
+  }
+  return { id: 'unknown', terminal: false, why: 'the push failed for a reason this lane does not recognise', fix: 'read git\'s message above, resolve it, then re-run the ship' };
+}
+
+// Push, capturing stderr so it can be diagnosed — and echoing it so the log still
+// shows exactly what git said, which stdio:'inherit' gave us for free.
+function pushCapturing(branch, deps = {}) {
+  const exec = deps.execFileSync || require('node:child_process').execFileSync;
+  try {
+    exec('git', ['push', 'origin', branch], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { ok: true, stderr: '' };
+  } catch (e) {
+    const stderr = [e && e.stderr, e && e.stdout].filter(Boolean).join('\n');
+    if (stderr) process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
+    return { ok: false, stderr };
+  }
+}
+
 // ciLandLocal — today's local path: this machine pushes the branch + opens the PR
 // + enables auto-merge via git + gh. async since task 1169 — it asks the server to
 // post the gate-author-trust attestation between the push and the PR open.
@@ -413,9 +487,24 @@ async function ciLandLocal(taskId, branch, valueSummary) {
   const headSha = gitOk('git rev-parse HEAD');
 
   console.log(`  pushing ${branch} to origin...`);
-  if (!gitArgvOk(['push', 'origin', branch])) {
-    console.log('  ci-land: push failed; task stays at confirmed. Fix the push and re-ship.');
-    return landBailed(`could not push ${branch} to origin`, `node scripts/gds/ship.js ${taskId}`);
+  const pushed = pushCapturing(branch);
+  if (!pushed.ok) {
+    const d = pushDiagnosis(pushed.stderr);
+    console.log(`  ci-land: push FAILED — ${d.why}.`);
+    console.log(`  ci-land: nothing was pushed and no PR exists; task stays at confirmed.`);
+    if (d.terminal) {
+      // The important line. Re-shipping cannot fix this, and the reconciler
+      // cannot heal a branch that never reached the remote — so do not say
+      // "re-ship" and leave the work stranded on one machine.
+      console.log('  ci-land: RE-SHIPPING WILL FAIL THE SAME WAY. Do this instead:');
+      console.log(`    ${d.fix}`);
+    } else {
+      console.log(`  ci-land: to retry — ${d.fix}`);
+    }
+    return landBailed(
+      `could not push ${branch} to origin (${d.id})`,
+      d.terminal ? d.fix.split('\n')[0] : `node scripts/gds/ship.js ${taskId}`,
+    );
   }
 
   // task 1169 (ADR 0058): attest the author's trust tier on the head SHA BEFORE
@@ -545,6 +634,8 @@ function pollCiDeploy(taskId, branch, headSha) {
 
 module.exports = {
   localHistoryRewritten, // task 1003221 — the append-only discriminator
+  pushDiagnosis, // task 1003293 — a terminal push failure must not advise a retry
+  PUSH_DIAGNOSES,
   ciLand,
   classifyLandOutcome,
   formatPublishFailure,

package/src/module-api.js

@@ -1174,8 +1174,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.370 with no explicit bump. run 32904582252. (task 1002620)
 //   1.19.372 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.371 with no explicit bump. run 32905166786. (task 1002620)
+//   1.19.373 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.372 with no explicit bump. run 32906118616. (task 1002620)
+//   1.19.374 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.373 with no explicit bump. run 32906477349. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.372'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.374'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/bump_version.mjs

@@ -16,7 +16,10 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
-const { bumpPatch, CONST_RE } = require(path.join(ROOT, 'scripts', 'gds', 'bump-version.js'));
+const bump = require(path.join(ROOT, 'scripts', 'gds', 'bump-version.js'));
+const { bumpPatch, CONST_RE } = bump;
+// The LIVE test below reads this repo's real release history (task 1003202).
+const { execFileSync } = require('node:child_process');
 
 const SAMPLE = [
   '// prologue',
@@ -111,3 +114,76 @@ test('publish.yml wires the terminator: guard step present, every armed step gat
   const gates = (PUBLISH_YML.match(/steps\.relhead\.outputs\.release_head == 'false'/g) || []).length;
   assert.ok(gates >= 7, `every post-guard armed step must carry the gate (setup-node, install, resolve, bump, pack, publish, tag) — found ${gates}`);
 });
+
+// ---------------------------------------------------------------------------
+// laneReleasedVersions — the token-free "is this version already published?"
+// (task 1003202 / blocker 1000115, the OIDC trusted-publishing migration).
+//
+// publish.yml used to ask the REGISTRY, which needs a credential: @bongos/core is
+// private, so an unauthenticated `npm view` is a flat E404 rather than a "no".
+// OIDC authenticates `npm publish` and nothing else, so keeping that check would
+// have reported "not taken" every run, skipped the auto-bump, and collided on the
+// published version — working for exactly one release before breaking. git holds
+// the same answer, needs no auth, and is the source the cascade terminator above
+// already trusts.
+// ---------------------------------------------------------------------------
+
+test('laneReleasedVersions reads the versions this lane announced', () => {
+  const subjects = [
+    'release: core 1.19.368 — CI auto-patch carrier (publish-on-merge, ADR 0161)',
+    'Merge pull request #385 from lars589/some-branch',
+    'release: core 1.19.367 — CI auto-patch carrier (publish-on-merge, ADR 0161)',
+    'feat(security): something unrelated',
+  ];
+  const v = bump.laneReleasedVersions(subjects);
+  assert.deepEqual([...v].sort(), ['1.19.367', '1.19.368']);
+  assert.equal(v.has('1.19.369'), false, 'a version never announced must read as free');
+});
+
+test('a HUMAN release commit is NOT counted — that version still needs publishing', () => {
+  // The same distinction RELEASE_COMMIT_RE was written to make for the cascade
+  // terminator. Counting it here would skip the publish of a hand-cut release.
+  const v = bump.laneReleasedVersions([
+    'release: core 1.19.2 — carrier for the init-blocker fixes',
+    'release: core 1.20.0 — hand-cut minor',
+  ]);
+  assert.equal(v.size, 0);
+});
+
+test('malformed and empty input yields an empty set, never a throw', () => {
+  // This runs inside the publish lane. A crash here would take down releases;
+  // an empty set degrades to "nothing is taken", which the publish itself
+  // catches with EPUBLISHCONFLICT — loud, and nothing wrong ships.
+  assert.equal(bump.laneReleasedVersions([]).size, 0);
+  assert.equal(bump.laneReleasedVersions().size, 0);
+  assert.equal(bump.laneReleasedVersions([null, undefined, '', 42]).size, 0);
+});
+
+test('laneReleasedVersions and isReleaseCommit agree on what a lane release looks like', () => {
+  // They share RELEASE_COMMIT_RE on purpose: if one ever recognises a subject the
+  // other does not, the cascade terminator and the version check disagree about
+  // the same commit, and the lane either double-publishes or silently no-ops.
+  const subjects = [
+    'release: core 1.19.368 — CI auto-patch carrier (publish-on-merge, ADR 0161)',
+    'release: core 1.19.2 — carrier for the init-blocker fixes',
+    'chore: not a release at all',
+  ];
+  for (const s of subjects) {
+    const counted = bump.laneReleasedVersions([s]).size === 1;
+    assert.equal(counted, bump.isReleaseCommit(s), `disagreement on: ${s}`);
+  }
+});
+
+test('LIVE: the version HEAD declares is one this lane already released', () => {
+  // The steady state the lane depends on: HEAD carries the version set by the
+  // previous release commit, so `taken` is true and the auto-bump fires. If this
+  // ever reads false on a normal main checkout, the lane would try to republish
+  // an existing version.
+  const headVersion = /^const CORE_VERSION = '([0-9.]+)';/m
+    .exec(fs.readFileSync(path.join(ROOT, 'src', 'module-api.js'), 'utf8'))[1];
+  const subjects = execFileSync('git', ['log', '--format=%s', 'HEAD'], { encoding: 'utf8', cwd: ROOT }).split('\n');
+  const released = bump.laneReleasedVersions(subjects);
+  assert.ok(released.size > 100, `expected a long release history, saw ${released.size}`);
+  assert.equal(released.has(headVersion), true,
+    `HEAD declares ${headVersion}, which this lane has no release commit for — the auto-bump would not fire`);
+});

package/tests/goal_category.mjs

@@ -145,6 +145,34 @@ test('an unknown category is a 404, not a silently-created one', async () => {
   assert.equal(res.statusCode, 404);
 });
 
+// ---- the advisory (task 1003277) --------------------------------------------
+
+test('an uncategorised goal earns an advisory that carries the live set and the create path', () => {
+  const adv = gc.adviseCategory({ categoryId: null, categories: [
+    { id: 3, slug: 'security', label: 'Security' },
+    { id: 6, slug: 'economics', label: 'Economics' },
+  ] });
+  assert.equal(adv.reason, 'uncategorised');
+  assert.deepEqual(adv.categories.map((c) => c.slug), ['security', 'economics'],
+    'the live set rides along so a client offers real choices, never hard-coded labels');
+  assert.match(adv.message, /POST \/work-categories/, 'the prompt has somewhere to write into');
+  assert.match(adv.message, /designed prompt, not an error/, 'the criterion\'s own framing travels with the advice');
+  assert.match(adv.message, /gates nothing/, 'and so does the rule that outranks the feature');
+});
+
+test('a categorised goal gets NO advisory — silence, the fail-open posture', () => {
+  assert.equal(gc.adviseCategory({ categoryId: 3, categories: [] }), null);
+});
+
+test('the advisory is advice on a 201, never a refusal', () => {
+  // Pinned in source: POST /goals attaches category_advisory to its SUCCESS body
+  // and never fails the create over it (best-effort, wrapped in try).
+  const routes = read('modules', 'lifecycle', 'routes', 'goals.js');
+  assert.match(routes, /category_advisory = goalCategory\.adviseCategory/);
+  assert.match(routes, /res\.status\(201\)\.json\(\{ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory \}\)/,
+    'it rides the 201 — advice appended to a request that already succeeded');
+});
+
 // ---- decoration ------------------------------------------------------------
 
 test('a goal carries a readable category, and an uncategorised one carries null', () => {

package/tests/profile_nudge_prefs.mjs

@@ -0,0 +1,97 @@
+// tests/profile_nudge_prefs.mjs — the "Complete your profile" nudge shaper
+// (task 1002802 / P06, goal 1000045).
+//
+// The nudge replaced the profile-setup wizard spec Decision 2 rejected: a
+// DISMISSIBLE line item in the hall's needs-attention inbox, shown when bio or
+// preferred_disciplines are empty. These pin the pure decision layer — what
+// counts as missing, when the line shows, and that a dismissal is durable and
+// reversible without disturbing the sibling knobs sharing behavior_prefs.
+//
+// Run:  node --test tests/profile_nudge_prefs.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const p = require('../modules/builder-settings/profile-nudge-prefs.js');
+
+test('missingProfileFields: empty, whitespace, and absent all count as missing', () => {
+  assert.deepEqual(p.missingProfileFields({ bio: '', preferredDisciplines: [] }), ['bio', 'disciplines']);
+  assert.deepEqual(p.missingProfileFields({ bio: '   \n\t ', preferredDisciplines: [] }), ['bio', 'disciplines']);
+  assert.deepEqual(p.missingProfileFields({}), ['bio', 'disciplines']);
+  assert.deepEqual(p.missingProfileFields({ bio: null, preferredDisciplines: null }), ['bio', 'disciplines']);
+});
+
+test('missingProfileFields: a real value on either side drops only that entry', () => {
+  assert.deepEqual(p.missingProfileFields({ bio: 'I build things', preferredDisciplines: [] }), ['disciplines']);
+  assert.deepEqual(p.missingProfileFields({ bio: '', preferredDisciplines: ['engineer'] }), ['bio']);
+  assert.deepEqual(p.missingProfileFields({ bio: 'x', preferredDisciplines: ['engineer'] }), []);
+});
+
+test('missingProfileFields: a non-array disciplines value is missing, not a crash', () => {
+  assert.deepEqual(p.missingProfileFields({ bio: 'x', preferredDisciplines: 'engineer' }), ['disciplines']);
+  assert.deepEqual(p.missingProfileFields({ bio: 'x', preferredDisciplines: {} }), ['disciplines']);
+});
+
+test('nudgeDismissed: defaults to NOT dismissed; only a real boolean overrides', () => {
+  assert.equal(p.nudgeDismissed({}), false);
+  assert.equal(p.nudgeDismissed(null), false);
+  assert.equal(p.nudgeDismissed({ profile_nudge_dismissed: true }), true);
+  assert.equal(p.nudgeDismissed({ profile_nudge_dismissed: false }), false);
+  // Garbage in the blob must not read as dismissed — that would silence the
+  // nudge for a builder who never dismissed it.
+  assert.equal(p.nudgeDismissed({ profile_nudge_dismissed: 'yes' }), false);
+  assert.equal(p.nudgeDismissed({ profile_nudge_dismissed: 1 }), false);
+});
+
+test('shouldNudge: shows only when something is missing AND not dismissed', () => {
+  const missing = { bio: '', preferredDisciplines: [] };
+  const complete = { bio: 'x', preferredDisciplines: ['engineer'] };
+  assert.equal(p.shouldNudge({ behaviorPrefs: {}, ...missing }), true);
+  assert.equal(p.shouldNudge({ behaviorPrefs: { profile_nudge_dismissed: true }, ...missing }), false);
+  assert.equal(p.shouldNudge({ behaviorPrefs: {}, ...complete }), false);
+  assert.equal(p.shouldNudge({ behaviorPrefs: { profile_nudge_dismissed: true }, ...complete }), false);
+});
+
+test('describeForApi: reports what is missing even while dismissed (show is the gate)', () => {
+  const d = p.describeForApi({ profile_nudge_dismissed: true }, { bio: '', preferredDisciplines: [] });
+  assert.equal(d.dismissed, true);
+  assert.equal(d.show, false, 'a dismissed nudge never shows');
+  assert.deepEqual(d.missing, ['bio', 'disciplines'], 'but the API still says what is empty');
+  assert.equal(d.override, true);
+  assert.equal(d.default_dismissed, false);
+});
+
+test('validatePatch: accepts dismissed true/false/null, refuses everything else', () => {
+  assert.deepEqual(p.validatePatch({ dismissed: true }), { ok: true, patch: { profile_nudge_dismissed: true } });
+  assert.deepEqual(p.validatePatch({ dismissed: false }), { ok: true, patch: { profile_nudge_dismissed: false } });
+  assert.deepEqual(p.validatePatch({ dismissed: null }), { ok: true, patch: { profile_nudge_dismissed: null } });
+  assert.deepEqual(p.validatePatch({}), { ok: true, patch: {} }, 'empty body is a valid no-op');
+  assert.equal(p.validatePatch({ dismissed: 'yes' }).ok, false);
+  assert.equal(p.validatePatch({ nope: true }).ok, false);
+  assert.equal(p.validatePatch(null).ok, false);
+  assert.equal(p.validatePatch([]).ok, false);
+});
+
+test('applyPatch: null clears the key; sibling behavior knobs are never disturbed', () => {
+  const existing = { wandering: 'focused', widgets: false, interaction: { technical_level: 'engineer' } };
+  const set = p.applyPatch(existing, { profile_nudge_dismissed: true });
+  assert.equal(set.profile_nudge_dismissed, true);
+  assert.equal(set.wandering, 'focused');
+  assert.equal(set.widgets, false);
+  assert.deepEqual(set.interaction, { technical_level: 'engineer' });
+  // Clearing removes the key entirely (back to the sparse default) and still
+  // leaves the siblings alone — the undismiss path.
+  const cleared = p.applyPatch(set, { profile_nudge_dismissed: null });
+  assert.equal('profile_nudge_dismissed' in cleared, false);
+  assert.equal(cleared.wandering, 'focused');
+  assert.equal(p.nudgeDismissed(cleared), false, 'cleared → the nudge can return');
+  // Pure: the input blob is not mutated.
+  assert.equal('profile_nudge_dismissed' in existing, false);
+});
+
+test('the reserved key is the documented one (behavior_prefs is shared)', () => {
+  assert.equal(p.RESERVED_KEY, 'profile_nudge_dismissed');
+  assert.equal(p.DEFAULT_DISMISSED, false);
+});

package/tests/ship_push_diagnosis.mjs

@@ -0,0 +1,78 @@
+// tests/ship_push_diagnosis.mjs — a terminal push failure must not advise a retry
+// (task 1003293).
+//
+// A failed `git push` in ciLandLocal already parks the task at `confirmed` and
+// opens no PR, which is correct. The ADVICE was the defect: "Fix the push and
+// re-ship" cannot work for the most common cause — a commit touching
+// .github/workflows/ pushed with a credential lacking GitHub's `workflow` scope.
+// Re-shipping fails identically, and the reconciler cannot heal a branch that
+// never reached the remote, so the task sits at `confirmed` looking like an
+// ordinary pending land while its code exists on exactly one machine. That
+// happened twice in one session.
+//
+// These tests pin the distinction the fix turns on: TERMINAL (retrying is
+// pointless — say what actually resolves it) vs transient (retrying is the
+// answer).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+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 { pushDiagnosis, PUSH_DIAGNOSES } = require(path.join(ROOT, 'scripts', 'gds', 'ship-land.js'));
+
+test('THE case that stranded two tasks: the workflow scope rejection', () => {
+  // GitHub's real wording, verbatim from the run that stranded task 1003283.
+  const d = pushDiagnosis(
+    'remote: error: refusing to allow an OAuth App to create or update workflow '
+    + '`.github/workflows/publish.yml` without `workflow` scope\n'
+    + 'To https://github.com/owner/repo.git\n ! [remote rejected] branch -> branch');
+  assert.equal(d.id, 'workflow_scope');
+  assert.equal(d.terminal, true, 'retrying this can never succeed — saying "re-ship" is what stranded the work');
+  assert.match(d.fix, /ssh|workflow/i, 'the advice must name the remedy that actually works');
+});
+
+test('branch protection and a dead credential are terminal too', () => {
+  assert.equal(pushDiagnosis('remote: error: GH006: Protected branch update failed').terminal, true);
+  assert.equal(pushDiagnosis('fatal: Authentication failed for https://github.com/o/r.git/').terminal, true);
+  assert.equal(pushDiagnosis('git@github.com: Permission denied (publickey).').terminal, true);
+});
+
+test('a stale branch IS retryable — the honest "re-ship" case', () => {
+  const d = pushDiagnosis('error: failed to push some refs\nUpdates were rejected because the remote contains work that you do not have locally');
+  assert.equal(d.id, 'stale_branch');
+  assert.equal(d.terminal, false);
+});
+
+test('an unrecognised failure defaults to RETRYABLE, never to terminal', () => {
+  // The safe direction. A wrong "this can never work" sends someone hunting a
+  // problem that does not exist; a wrong "try again" costs one command.
+  const d = pushDiagnosis('fatal: the remote end hung up unexpectedly');
+  assert.equal(d.id, 'unknown');
+  assert.equal(d.terminal, false);
+  assert.equal(pushDiagnosis('').terminal, false);
+  assert.equal(pushDiagnosis(null).terminal, false);
+  assert.equal(pushDiagnosis(undefined).terminal, false);
+});
+
+test('every diagnosis carries both a cause and a remedy', () => {
+  // A classification with no `fix` is just a nicer way of saying "it broke",
+  // which is the state this replaced.
+  for (const d of PUSH_DIAGNOSES) {
+    assert.ok(d.id && d.why && d.fix, `incomplete diagnosis: ${JSON.stringify(d)}`);
+    assert.ok(d.why.length > 20, `${d.id}: "why" must explain, not label`);
+    assert.equal(typeof d.terminal, 'boolean');
+  }
+  const fallback = pushDiagnosis('anything at all');
+  assert.ok(fallback.why && fallback.fix);
+});
+
+test('the patterns do not collide — the first match is the RIGHT match', () => {
+  // A workflow-scope rejection also contains "error:" and often "403"; if the
+  // auth pattern matched it first, the advice would send someone to re-login
+  // instead of to SSH, and the push would fail again.
+  const workflowMsg = 'remote: error: refusing to allow an OAuth App to create or update workflow `.github/workflows/x.yml` without `workflow` scope';
+  assert.equal(pushDiagnosis(workflowMsg).id, 'workflow_scope');
+});

package/tests/sound_player.mjs

@@ -343,3 +343,41 @@ test('playerFor never throws and returns null or a [cmd, args] pair', () => {
     assert.ok(Array.isArray(got[1]));
   }
 });
+
+// ---------------------------------------------------------------------------
+// readPrefs honours the path it was GIVEN (task 1003293).
+//
+// The legacy-path fallback used to fire for any unreadable path, so a caller
+// naming an explicit file silently received a different one — the user's real
+// prefs. That made the two fail-open tests above pass in CI (no prefs on a
+// runner) and fail on any machine where the builder had saved sound settings:
+// green where nobody looks, red where everybody does. The fallback is still
+// right for the DEFAULT call; it is wrong the moment a caller names a file.
+// ---------------------------------------------------------------------------
+
+test('an explicit missing path fails open — it never substitutes another file', () => {
+  // The regression: write a legacy-shaped prefs file at the pre-rename location
+  // and prove an explicit path still ignores it. Skipped if the real file exists,
+  // because this test must never clobber a builder's own settings.
+  const legacy = player.LEGACY_PREFS_PATH;
+  if (!legacy || fs.existsSync(legacy)) {
+    // Nothing to plant, but the invariant is still checkable: an absent explicit
+    // path must yield the fail-open default, whatever the legacy file holds.
+    const p = player.readPrefs(path.join(os.tmpdir(), `otb-absent-${process.pid}.json`));
+    assert.equal(p.volume, 100);
+    assert.equal(p.enabled('ship'), true);
+    return;
+  }
+  fs.mkdirSync(path.dirname(legacy), { recursive: true });
+  fs.writeFileSync(legacy, JSON.stringify({ volume: 11, ship: false }));
+  try {
+    const p = player.readPrefs(path.join(os.tmpdir(), `otb-absent-${process.pid}.json`));
+    assert.equal(p.volume, 100, 'an explicit path must not inherit the legacy file volume');
+    assert.equal(p.enabled('ship'), true, 'an explicit path must not inherit legacy mutes');
+    // …while the DEFAULT call still honours it — the fallback is not removed.
+    const d = player.readPrefs();
+    assert.equal(d.volume, 11, 'the default path must still fall back to the legacy file');
+  } finally {
+    fs.unlinkSync(legacy);
+  }
+});