@bongos/core 1.19.373 → 1.19.374

package/modules/builder-settings/routes/settings.js

@@ -28,6 +28,7 @@ const wanderingPrefs = require('../wandering-prefs');
 const interactionPrefs = require('../interaction-prefs');
 const modelAllocPrefs = require('../model-alloc-prefs');
 const renderPrefs = require('../render-prefs');
+const profileNudgePrefs = require('../profile-nudge-prefs');
 const displayName = require('../display-name');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('builder-settings');
@@ -378,6 +379,53 @@ module.exports = function buildBuilderSettingsRouter() {
     }
   });
 
+  // The "Complete your profile" nudge dismissal (task 1002802 / P06). The nudge
+  // itself is a DISMISSIBLE line item in the hall's needs-attention inbox — the
+  // replacement for the profile-setup wizard Decision 2 rejected. These two
+  // routes own only the dismissal FLAG; whether anything is actually missing is
+  // composed by the caller, which already holds both inputs (preferred_disciplines
+  // from GET /me, bio from GET /me/cross-project — bio lives on the platform
+  // identity account, and this module must never reach across to that one).
+  //
+  // rank: any-builder — own profile config; same posture as /me/render.
+  router.get('/me/profile-nudge', api.requireBuilder, async (req, res) => {
+    try {
+      // preferred_disciplines is NOT on req.builder (requireBuilder attaches an
+      // identity+rank subset), so read the row through the doorway — the same
+      // getBuilderById the wandering/interaction routes above use.
+      const [stored, builder] = await Promise.all([
+        db.getBuilderBehaviorPrefs(req.builder.id),
+        api.getBuilderById(req.builder.id),
+      ]);
+      res.json(profileNudgePrefs.describeForApi(stored, {
+        preferredDisciplines: builder && builder.preferred_disciplines,
+      }));
+    } catch (err) {
+      log.error('GET /me/profile-nudge', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH the dismissal. Body: { dismissed: <bool> | null } — null clears the
+  // override so the nudge can come back (the undismiss path). Sibling behavior
+  // keys are preserved by applyPatch.
+  router.patch('/me/profile-nudge', api.requireBuilder, async (req, res) => {
+    try {
+      const v = profileNudgePrefs.validatePatch(req.body || {});
+      if (!v.ok) return res.fail('invalid_patch', 422, { errors: v.errors });
+      const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
+      const next = profileNudgePrefs.applyPatch(existing, v.patch);
+      const saved = await db.setBuilderBehaviorPrefs(req.builder.id, next);
+      const builder = await api.getBuilderById(req.builder.id);
+      res.json(profileNudgePrefs.describeForApi(saved, {
+        preferredDisciplines: builder && builder.preferred_disciplines,
+      }));
+    } catch (err) {
+      log.error('PATCH /me/profile-nudge', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // Per-builder DISPLAY NAME (task 1669). The free label shown next to a
   // builder's work in the hall (header, leaderboard, work feed — all already read
   // display_name, so a DB update propagates). Seeded once from GitHub at account

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -500,6 +500,10 @@ function createClient(opts = {}) {
       patchMeModelAllocation: (args) => request("PATCH", "/me/model-allocation", { hasBody: true }, args),
       // PATCH /me/profile — rank: any-builder — PATCH /me/profile
       patchMeProfile: (args) => request("PATCH", "/me/profile", { hasBody: true }, args),
+      // GET /me/profile-nudge — rank: any-builder — GET /me/profile-nudge
+      getMeProfileNudge: (args) => request("GET", "/me/profile-nudge", { hasBody: false }, args),
+      // PATCH /me/profile-nudge — rank: any-builder — PATCH /me/profile-nudge
+      patchMeProfileNudge: (args) => request("PATCH", "/me/profile-nudge", { hasBody: true }, args),
       // GET /me/recent-ships — rank: any-builder — GET /me/recent-ships
       getMeRecentShips: (args) => request("GET", "/me/recent-ships", { hasBody: false }, args),
       // GET /me/render — rank: any-builder — GET /me/render

package/modules/hall-ui/public/goal-inbox.js

@@ -273,6 +273,13 @@
     host.innerHTML =
       '<h2 id="attention-h" class="scroll__h">Needs your attention<span class="count-pill" id="attention-count" hidden></span></h2>' +
       '<div id="attention-goals"></div>' +
+      // task 1002802 (P06): "Complete your profile" — a DISMISSIBLE nudge when
+      // bio or preferred_disciplines are empty. Rendered by builders.js (which
+      // already holds the /me state the condition reads), exactly like the
+      // ideas slice. Placement rule: an action awaiting the builder is an inbox
+      // LINE, never a new Home card — that is why the rejected profile wizard
+      // (task 1002783) became this.
+      '<div id="attention-profile"></div>' +
       '<div id="attention-ideas"></div>' +
       // task 1003066 (BV1.R05): routed filings that SOFT-LANDED — a reported bug
       // now sitting at 'backlog' in a real goal, one Metic+ nod from claimable.
@@ -284,6 +291,9 @@
     host.addEventListener('click', onClick);
     load();
     loadNodQueue();
+    // task 1002802 (P06): the profile slice lives in its own file (builders.js is
+    // over the size budget); this card owns its div, so it boots it here.
+    window.OTBProfileNudge?.load();
   }
 
   // The card's shared visibility contract: any slice renderer calls refresh()

package/modules/hall-ui/public/index.html

@@ -123,6 +123,10 @@
      hall-widget tags the server injects still anchor on builders.js's tag
      below (it matches by filename), so they land between the two. -->
 <script src="/builders/hall-render.js?v=2026-08-24-hallrender1" defer></script>
+<!-- task 1002802 (P06): the profile-completion nudge slice. Exposes
+     window.OTBProfileNudge; goal-inbox.js's mount() calls it once it has
+     created the #attention-profile div, so load order is not load-bearing. -->
+<script src="/builders/profile-nudge.js?v=2026-08-25-profile-nudge" defer></script>
 <script src="/builders/builders.js?v=2026-06-27-r75" defer></script>
 <script src="/builders/copy-on-click.js?v=2026-06-01-copy-1" defer></script>
 </body>

package/modules/hall-ui/public/profile-nudge.js

@@ -0,0 +1,122 @@
+// profile-nudge.js — the "Complete your profile" slice of the hall's
+// "Needs your attention" card (task 1002802 / P06, goal 1000045).
+//
+// Its own file rather than a block inside builders.js: the slice needs no state
+// from that file (both its inputs come from its own two fetches), and builders.js
+// is already far over the 1,500-line budget the quality ratchets enforce.
+//
+// goal-inbox.js owns the CARD (id 'attention-scroll') and creates this slice's
+// div (#attention-profile); card visibility + the headline count derive from
+// every slice via window.OTBAttention.refresh().
+(function () {
+  'use strict';
+  if (!window.OTB) return;
+  const { escapeHtml } = window.OTB;
+  const API = '/api/bongos';
+  // Result-mode client: a 401/404 must be inspectable control flow, never a throw
+  // that breaks a sibling slice (the goal-inbox.js pattern).
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+
+  async function getJSON(path) {
+    const res = await api.request('GET', path);
+    if (!res.ok) { const e = new Error(`${path} → ${res.status}`); e.status = res.status; throw e; }
+    return res.data;
+  }
+  async function patchJSON(path, body) {
+    const res = await api.request('PATCH', path, { body: body || {} });
+    if (!res.ok) { const e = new Error(`${path} → ${res.status}`); e.status = res.status; throw e; }
+    return res.data;
+  }
+
+
+  // Renders the PROFILE slice of the "Needs your attention" card. goal-inbox.js
+  // owns the card (id 'attention-scroll') + the slice div; visibility and the
+  // headline count derive from every slice via OTBAttention.
+  //
+  // WHY A LINE AND NOT A CARD OR A WIZARD: spec Decision 2 rejected a
+  // profile-setup wizard (profiles are auto-created and enriched
+  // progressively; an interstitial after sign-in adds friction at the drop-off
+  // point). The hall's placement rule then puts an action awaiting the builder
+  // in the inbox as a LINE, never a new Home card.
+  //
+  // The two inputs live in different places — preferred_disciplines on the
+  // builder row (already in the /me payload this file holds) and bio on the
+  // platform-identity account (GET /me/cross-project) — so the SHOW decision is
+  // composed here. The server owns only the dismissal flag.
+  // Uses .ginbox__item so OTBAttention.refresh() counts it with no selector change.
+  function renderProfileNudge(state) {
+    const box = document.getElementById('attention-profile');
+    if (!box) return;
+    if (!state || !state.show) {
+      box.innerHTML = '';
+      window.OTBAttention?.refresh();
+      return;
+    }
+    // Name what is actually missing: "add a bio" is actionable, "complete your
+    // profile" is a chore of unknown size.
+    const missing = Array.isArray(state.missing) ? state.missing : [];
+    const parts = [];
+    if (missing.includes('bio')) parts.push('a short bio');
+    if (missing.includes('disciplines')) parts.push('the kinds of work you want');
+    const what = parts.length === 2 ? `${parts[0]} and ${parts[1]}` : (parts[0] || 'a detail or two');
+    box.innerHTML = '<h3 class="ginbox__sec-h">Complete your profile</h3>'
+      + '<ul class="ginbox">'
+      + '<li class="ginbox__item">'
+      // .ginbox__body / .ginbox__actions are the classes style.css actually
+      // defines (the body is the flex column that stacks label over sub-line).
+      + '<div class="ginbox__body">'
+      + `<a class="ginbox__goal" href="/settings">Add ${escapeHtml(what)}</a>`
+      + '<span class="ginbox__sub">Shown on your public profile — it helps others know what you work on.</span>'
+      + '</div>'
+      + '<div class="ginbox__actions">'
+      + '<button class="btn-ghost" type="button" data-profile-nudge-dismiss="1">Dismiss</button>'
+      + '</div>'
+      + '</li></ul>';
+    window.OTBAttention?.refresh();
+  }
+
+  // Fetch the dismissal flag + the bio in parallel, then compose. Any failure
+  // renders NOTHING (a nudge is the most skippable thing on the page — it must
+  // never surface an error card or break a sibling slice).
+  async function loadProfileNudge() {
+    try {
+      const [nudge, cross] = await Promise.all([
+        getJSON(`${API}/me/profile-nudge`),
+        getJSON(`${API}/me/cross-project`).catch(() => null),
+      ]);
+      if (!nudge) return;
+      // The server computed `missing` from preferred_disciplines only (bio is not
+      // its to read — different module). Fold the bio in here.
+      const missing = Array.isArray(nudge.missing) ? nudge.missing.slice() : [];
+      const bio = cross && typeof cross.bio === 'string' ? cross.bio : '';
+      const bioMissing = bio.trim() === '';
+      // A null cross-project (older server, or a principal with no platform
+      // identity) means "cannot tell" — do not invent a missing bio from it.
+      if (bioMissing && cross && !missing.includes('bio')) missing.push('bio');
+      if (!bioMissing) { const i = missing.indexOf('bio'); if (i !== -1) missing.splice(i, 1); }
+      renderProfileNudge({ ...nudge, missing, show: !nudge.dismissed && missing.length > 0 });
+    } catch (_) {
+      /* signed out, older server, or a hiccup: the nudge simply does not appear */
+    }
+  }
+
+  // task 1002802 (P06): dismiss the profile nudge. Delegated for the same reason
+  // as the triage verb above — the slice re-renders. Optimistic: the line goes
+  // away immediately (a dismissal that appears to fail is worse than one that
+  // silently retries), and the server flag makes it stay gone on every device.
+  document.addEventListener('click', (e) => {
+    const btn = e.target.closest('[data-profile-nudge-dismiss]');
+    if (!btn) return;
+    btn.disabled = true;
+    renderProfileNudge({ show: false });
+    patchJSON(`${API}/me/profile-nudge`, { dismissed: true })
+      .catch(() => loadProfileNudge()); // write failed → put the line back, honestly
+  });
+
+  // The CARD OWNER boots its slices: goal-inbox.js's mount() creates
+  // #attention-profile and then calls this, exactly as it calls its own load()
+  // and loadNodQueue(). No DOMContentLoaded race and no polling for the div —
+  // the widget registry mounts asynchronously after /me resolves, so a
+  // load-time call would reliably find nothing.
+  window.OTBProfileNudge = { load: loadProfileNudge, render: renderProfileNudge };
+})();

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.373",
+  "version": "1.19.374",
   "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/scripts/gds/fitness-checks-write-validation.js

@@ -41,6 +41,7 @@ const WRITE_VALIDATION_EXEMPT = new Set([
   'PATCH /me/model-allocation',   // per-slot tiers                — modelAllocPrefs.validatePatch
   'PATCH /me/render',             // { widgets: <bool>|null }      — renderPrefs.validatePatch
   'PATCH /me/display-name',       // { display_name }              — displayName.validate
+  'PATCH /me/profile-nudge',      // { dismissed: <bool>|null }    — profileNudgePrefs.validatePatch
 ]);
 
 // KNOWN GAPS, NOT EXEMPTIONS (task 1002551 / BV1.R109b → tracked by task 1002552).

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

@@ -1176,8 +1176,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.373'; // 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/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);
+  }
+});