@bongos/core 1.19.373 → 1.19.375

package/modules/onboarding/routes/access-requests.js

@@ -10,11 +10,21 @@
 //   POST /api/bongos/access-requests          PUBLIC (the one unauthenticated GDS
 //                                          write) — a stranger submits their
 //                                          GitHub username; a pending row lands
-//                                          in the queue.
+//                                          in the queue. Refused outright on an
+//                                          invite-only project, and on an open
+//                                          one (sign in — you're in already).
 //   GET  /api/bongos/access-requests          Archon-only — the pending queue (and
 //                                          ?status=invited|dismissed history).
 //   PATCH /api/bongos/access-requests/:id     Archon-only — resolve a request:
 //                                          { status: 'invited' | 'dismissed' }.
+//   POST /api/bongos/access-requests/invite   Archon-only — invite a GitHub
+//                                          username before any request exists:
+//                                          the way in on an invite-only project.
+//
+// Which door a project runs — open / apply / invite_only — is the owner's
+// joinability setting, read through the doorway's joinabilityMode() (task
+// 1003044, ADR 0194): the same reader the sign-in gate uses, so this route and
+// the gate never disagree about whether a stranger may ask.
 //
 // The global IP rate-limiter (mounted in routes.js before every router) guards
 // the public POST against spam. A partial unique index on lower(github_login)
@@ -30,6 +40,14 @@ const auth = { requireBuilder: api.requireBuilder, requirePermission: api.requir
 const { pool } = api;
 const { validateOrRespond, parseId } = api;
 const approvalBroadcast = require('../approval-broadcast');
+const log = api.logger('onboarding');
+
+// The public refusal each door gives a would-be applicant — plain sentences,
+// shown as written by the hall, the CLI, and the hub's join relay.
+const DOOR_REFUSAL = {
+  invite_only: { code: 'invite_only', status: 403, message: 'This project is invite-only — it doesn’t take applications. If you’ve been invited, or already have an account, sign in with GitHub to enter.' },
+  open: { code: 'open_enrollment', status: 409, message: 'This project is open — no request needed. Sign in with GitHub and you’re in.' },
+};
 
 // GitHub usernames: 1–39 chars, alphanumeric or single hyphens, no leading/
 // trailing hyphen. We accept a leading '@' and strip it (people paste "@name").
@@ -46,6 +64,12 @@ module.exports = function buildAccessRequestsRouter() {
   // rank: public — the requester is by definition outside the system (no
   // builder row yet); this is the one public write on the GDS.
   router.post('/access-requests', async (req, res) => {
+    // The door answers first — before validation and before any lookup — so a
+    // refusal costs no query and reveals nothing about who already exists.
+    const refusal = DOOR_REFUSAL[api.joinabilityMode()];
+    if (refusal) {
+      return res.fail(refusal.code, { status: refusal.status, message: refusal.message });
+    }
     if (validateOrRespond(req, res, {
       github_login: { required: true, type: 'string', minLength: 1, maxLength: 60 },
       display_name: { type: 'string', maxLength: 100 },
@@ -204,5 +228,67 @@ module.exports = function buildAccessRequestsRouter() {
     }
   });
 
+  // POST /access-requests/invite — an Archon admits a GitHub username BEFORE any
+  // request exists (task 1003044): the only way in on an invite-only project,
+  // where the public POST refuses, and a shortcut on an apply one. It writes the
+  // same access_request row the sign-in gate reads (status 'invited' —
+  // hasInvitedAccessRequest), so nothing new is consulted at sign-in; a pending
+  // request for that login is resolved in place rather than duplicated. Two
+  // Archons inviting the same login at once can each insert a row (the unique
+  // index covers pending only): harmless — the gate reads "any invited row" —
+  // and it shows as two lines in the invited history, so no lock is taken.
+  // body: { github_login }. 201 with a new row; 200 with the row when a pending
+  // request was resolved; 200 already_invited when an invite already stands;
+  // 409 already_member when they have an account.
+  // rank: archon — the same gate as resolving a request.
+  router.post('/access-requests/invite', auth.requireBuilder, auth.requirePermission('access_request.review'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      github_login: { required: true, type: 'string', minLength: 1, maxLength: 60 },
+    })) return;
+    const login = normalizeLogin(req.body.github_login);
+    if (!GITHUB_LOGIN_RE.test(login)) {
+      return res.fail('bad_github_login', { status: 400, message: 'That does not look like a GitHub username.' });
+    }
+    try {
+      const member = await pool.query(
+        `SELECT 1 FROM builders WHERE lower(github_login) = lower($1) LIMIT 1`,
+        [login]
+      );
+      if (member.rows.length > 0) {
+        return res.fail('already_member', { status: 409, message: 'They already have an account here — no invite needed.' });
+      }
+      const standing = await pool.query(
+        `SELECT 1 FROM access_requests
+          WHERE lower(github_login) = lower($1) AND status = 'invited' LIMIT 1`,
+        [login]
+      );
+      if (standing.rows.length > 0) {
+        return res.json({ ok: true, already_invited: true, github_login: login });
+      }
+      const resolved = await pool.query(
+        `UPDATE access_requests
+            SET status = 'invited',
+                resolved_by_builder_id = $1,
+                resolved_at = now()
+          WHERE lower(github_login) = lower($2) AND status = 'pending'
+          RETURNING id, github_login, status, resolved_at`,
+        [req.builder.id, login]
+      );
+      if (resolved.rows.length > 0) {
+        return res.json({ ok: true, request: resolved.rows[0] });
+      }
+      const { rows } = await pool.query(
+        `INSERT INTO access_requests (github_login, status, resolved_by_builder_id, resolved_at)
+         VALUES ($1, 'invited', $2, now())
+         RETURNING id, github_login, status, resolved_at`,
+        [login, req.builder.id]
+      );
+      return res.status(201).json({ ok: true, request: rows[0] });
+    } catch (err) {
+      log.error('[gds] POST /access-requests/invite', err);
+      return res.fail('invite_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };

package/modules/platform-identity/routes/my-projects.js

@@ -16,6 +16,34 @@ const pi = require('../platform-identity');
 
 const { pool, requireBuilder, validateOrRespond, userAgent } = api;
 
+// joinRelayOutcome — what the project's own admission surface answered, said in
+// the HUB's words (task 1003044). The project decides; the hub relays and must
+// never paint a refusal as "requested" — nor as "unreachable". A 2xx is a filed
+// request; 409 already_member a standing membership; the door refusals (403
+// invite_only, 409 open_enrollment) name the door; a 401 is the project's
+// member-only visibility door (ADR 0192) refusing the ask itself. The project's
+// own sentence is deliberately NOT relayed: a registered project is trusted to
+// build, not to write prose into the platform's UI. Anything else is "not
+// relayed" (null) → the caller's 502.
+const RELAY_SENTENCE = {
+  requested: 'Requested access. The project’s owner admits new builders; once approved, sign in to enter.',
+  already_member: 'You already build on this project — sign in to it to see it here.',
+  invite_only: 'This project is invite-only — it doesn’t take requests. Ask its owner for an invite; once invited, sign in to it.',
+  open_enrollment: 'This project is open — no request needed. Sign in to it and you’re in.',
+  members_only: 'This project is only visible to its members right now, so it can’t take a request from here — ask its owner.',
+};
+function joinRelayOutcome(status, body) {
+  const err = (body && body.error) || null;
+  const code = err && (err.code || err);
+  let outcome;
+  if (status >= 200 && status < 300) outcome = 'requested';
+  else if (code === 'invite_only' || code === 'open_enrollment') outcome = code;
+  else if (status === 409) outcome = 'already_member';
+  else if (status === 401) outcome = 'members_only';
+  else return null;
+  return { status: outcome, message: RELAY_SENTENCE[outcome] };
+}
+
 module.exports = function myProjectsRoutes() {
   const router = express.Router();
 
@@ -56,27 +84,24 @@ module.exports = function myProjectsRoutes() {
       // Relay an access request to the project's OWN (public) admission endpoint —
       // the project decides (open-join, or request/invite per ADR 0112). We post to
       // the registry-trusted origin, never the caller's raw input.
-      let relayed = false;
-      let alreadyMember = false;
+      let outcome = null;
       try {
         const r = await fetch(`${client.origin}/api/gds/access-requests`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
           body: JSON.stringify({ github_login: req.builder.github_login, note: 'via platform My Projects' }),
         });
-        alreadyMember = r.status === 409;
-        relayed = r.ok || r.status === 200 || r.status === 201 || alreadyMember;
+        const body = await r.json().catch(() => null);
+        outcome = joinRelayOutcome(r.status, body);
       } catch (e) {
         console.log('[platform-identity] join relay failed (non-fatal):', e.message);
       }
-      if (!relayed) return res.fail('join_relay_failed', { status: 502, message: 'the project could not be reached to request access' });
+      if (!outcome) return res.fail('join_relay_failed', { status: 502, message: 'the project could not be reached to request access' });
       res.json({
         ok: true,
-        status: alreadyMember ? 'already_member' : 'requested',
+        status: outcome.status,
         project: { name: client.name, origin: client.origin },
-        message: alreadyMember
-          ? 'You already build on this project — sign in to it to see it here.'
-          : 'Requested access. The project’s owner admits new builders; once approved, sign in to enter.',
+        message: outcome.message,
       });
     } catch (err) {
       console.error('[platform-identity] POST /my-projects/join', err);
@@ -138,3 +163,4 @@ module.exports = function myProjectsRoutes() {
 
   return router;
 };
+module.exports.joinRelayOutcome = joinRelayOutcome;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.373",
+  "version": "1.19.375",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.373",
+      "version": "1.19.375",
       "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.375",
   "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/public-landing/projects.html

@@ -678,11 +678,19 @@ summary{min-height:24px;padding:3px 0;}
         </details>
       </div>
 
-      <!-- the setting the sibling task (1003044) fills in — placed BELOW the
-           sections that work, so a founder meets controls before promises -->
+      <!-- live since task 1003044: how people join — the membership door. The
+           visibility section's two reads, key for key: the choice shown is
+           the platform's REQUEST (its settings row); what the project actually
+           RUNS is read back from its own public manifest (brand.project.
+           joinability) — never from the save's reply, which is a receipt. The
+           fold is a SIBLING of the volatile slot so no re-render can drop it. -->
       <div class="card" id="mJoinability">
         <h2 style="font-family:var(--font-display);font-size:19px;margin-bottom:12px;">How people join</h2>
-        <div class="empty"><p>Choosing how new people join — walk right in, apply first, or invite only — isn’t wired up here yet. For now, people apply to join and you invite them.</p></div>
+        <div id="mJoin"><p class="finePrint">Reading the project’s settings…</p></div>
+        <details class="finePrint" id="mJoinWhat">
+          <summary>What each choice changes</summary>
+          <p><b>Anyone can join</b> — whoever signs in with GitHub becomes a member at once, at the newcomer rank. <b>Apply to join</b> — people ask from the project’s hall, you approve each one from the hall’s Watch page, and then they sign in. <b>Invite only</b> — no one can apply: the project’s hall and its sign-in say so, and you invite people by GitHub username from the hall’s Watch page; only an invited person’s sign-in gets in — and people who asked before you switched stay in your queue, to approve or dismiss. Whichever you pick, people who are already members stay members. Changing it restarts the project to pick it up — the line under the choice says what the project is running right now.</p>
+        </details>
       </div>
 
       <!-- live since task 1003042: the teardown control, for a project in ANY
@@ -4379,6 +4387,7 @@ summary{min-height:24px;padding:3px 0;}
     /* same contract: the visibility section's in-flight line reads open_intent
        only, so a queued settings push shows up on the tick without a reload */
     renderVisState(inst);
+    renderJoinState(inst);
     /* the page names its project — in the heading and in the tab */
     $('mTitle').textContent = inst.slug || 'Manage';
     document.title = (inst.slug ? inst.slug + ' — ' : '') + BASE_TITLE;
@@ -4484,6 +4493,7 @@ summary{min-height:24px;padding:3px 0;}
         /* the settings row + the project's own manifest — the same cadence as
            the GitHub read: entry + tab return, never the in-flight tick */
         if (!keepRepo) loadVisibility(inst);
+        if (!keepRepo) loadJoinability(inst);
       })
       .catch(function (err) {
         var m = String(err && err.message);
@@ -4805,6 +4815,162 @@ summary{min-height:24px;padding:3px 0;}
     if (t && t.hasAttribute('data-vis-save')) doVisSave();
   });
 
+  /* ── how people join (task 1003044): the joinability toggle — the visibility
+     section's shape, key for key: the CHOICE from the platform's settings row,
+     what the project RUNS from its own manifest (brand.project.joinability),
+     the save's push.message shown verbatim and never painted as the live
+     state. visPushOpen() is shared: one settings push carries every key. ── */
+
+  var JOIN_OPTIONS = {
+    open: { label: 'Anyone can join', blurb: 'Whoever signs in with GitHub becomes a member right away, at the newcomer rank.' },
+    apply: { label: 'Apply to join', blurb: 'People ask to join from the project’s hall; you approve each one, then they sign in.' },
+    invite_only: { label: 'Invite only', blurb: 'No one can apply. You invite people by GitHub username from the hall, and only an invited person can sign in.' }
+  };
+  var mJoinSettings = null;  /* the platform row's last answer: { value, options } */
+  var mJoinRunsHtml = '';    /* what the project's manifest last said it runs */
+  var mJoinPushSeen = false; /* a settings push was open — re-read the manifest once it settles */
+
+  function joinMsg(html) { $('mJoin').innerHTML = html; }
+
+  function renderJoin() {
+    var s = mJoinSettings;
+    if (!s) return;
+    var opts = (s.options || []).filter(function (v) { return !!JOIN_OPTIONS[v]; });
+    joinMsg('<div role="radiogroup" aria-label="How people join">' + opts.map(function (v) {
+      var o = JOIN_OPTIONS[v];
+      return '<label class="visOpt"><input type="radio" name="mJoinPick" value="' + esc(v) + '"' +
+        (v === s.value ? ' checked' : '') + '><span><b>' + esc(o.label) + '</b>' + esc(o.blurb) + '</span></label>';
+    }).join('') + '</div>' +
+      '<div class="actions"><button type="button" class="btn small" data-join-save>Save</button></div>' +
+      '<div class="projMsg" id="mJoinMsg" role="status" aria-live="polite"></div>' +
+      '<p class="finePrint" id="mJoinRuns">' + mJoinRunsHtml + '</p>');
+    renderJoinState(manageInst);
+  }
+
+  function joinRuns(html) {
+    mJoinRunsHtml = html;
+    var el = $('mJoinRuns');
+    if (el) el.innerHTML = html;
+  }
+
+  /* fetch-free, from open_intent only (renderManage calls it on every repaint) */
+  function renderJoinState(inst) {
+    if (!inst || !$('mJoinRuns')) return;
+    if (visPushOpen(inst)) {
+      mJoinPushSeen = true;
+      joinRuns(inst.open_intent.state === 'running'
+        ? 'Restarting the project to apply a settings change…'
+        : 'A settings change is queued — the project restarts to pick it up. Until then it keeps its current setting.');
+      return;
+    }
+    if (mJoinPushSeen) { mJoinPushSeen = false; loadJoinRuns(inst); }
+  }
+
+  /* what the project RUNS: its own public manifest, read cross-origin */
+  function loadJoinRuns(inst) {
+    if (!inst || inst.status !== 'active' || !inst.domain) { joinRuns(''); return; }
+    var asked = manageId;
+    joinRuns('Checking what the project is running…');
+    var ctl = typeof AbortController === 'function' ? new AbortController() : null;
+    var timer = ctl ? setTimeout(function () { ctl.abort(); }, 8000) : null;
+    fetch('https://' + inst.domain + '/api/gds/instance', { mode: 'cors', signal: ctl ? ctl.signal : undefined })
+      .then(function (res) {
+        if (!res.ok) throw new Error('http:' + res.status);
+        return res.json();
+      })
+      .then(function (m) {
+        if (asked !== manageId) return;
+        var p = m && m.brand && m.brand.project;
+        var v = p && p.joinability;
+        if (!p || typeof p !== 'object') {
+          joinRuns('This project’s server doesn’t report this setting yet — it runs an older platform version, so the setting can’t take effect until the project is updated.');
+          return;
+        }
+        var o = JOIN_OPTIONS[v];
+        if (!o) { joinRuns('This project’s server reports a setting this page doesn’t recognise (' + esc(String(v)) + ').'); return; }
+        var want = mJoinSettings && mJoinSettings.value;
+        joinRuns('Right now the project runs as <b>' + esc(o.label) + '</b>' +
+          (want && want !== v && JOIN_OPTIONS[want] ? ' — the saved choice (' + esc(JOIN_OPTIONS[want].label) + ') hasn’t taken effect there yet.' : '.'));
+      })
+      .catch(function (err) {
+        if (asked !== manageId) return;
+        var http = /^http:(\d+)$/.exec(String(err && err.message));
+        joinRuns(http
+          ? 'The project answered but didn’t share what it’s running (it replied ' + esc(http[1]) + ').'
+          : 'Couldn’t reach the project to check what it’s running right now.');
+      })
+      .then(function () { if (timer) clearTimeout(timer); });
+  }
+
+  function loadJoinability(inst) {
+    mJoinSettings = null; mJoinRunsHtml = ''; mJoinPushSeen = false;
+    joinMsg('<p class="finePrint">Reading the project’s settings…</p>');
+    var asked = manageId; /* a stale answer must never describe a newer project */
+    fetch(API + '/provisioning/instances/' + encodeURIComponent(manageId) + '/settings', { credentials: 'same-origin' })
+      .then(function (res) {
+        if (asked !== manageId) throw new Error('stale');
+        return jsonOrEmpty(res).then(function (data) {
+          if (res.ok) {
+            mJoinSettings = {
+              value: (data.settings || {}).joinability,
+              options: (data.options || {}).joinability || Object.keys(JOIN_OPTIONS)
+            };
+            renderJoin();
+            if (!visPushOpen(inst)) loadJoinRuns(inst);
+            return;
+          }
+          joinMsg('<p class="finePrint">' + (res.status === 401 ? signInAgain() : 'Couldn’t read this project’s settings right now — refresh in a moment.') + '</p>');
+        });
+      })
+      .catch(function (err) {
+        if (String(err && err.message) === 'stale') return;
+        joinMsg('<p class="finePrint">Couldn’t read this project’s settings right now — refresh in a moment.</p>');
+      });
+  }
+
+  /* the save sends the CHOICE and shows the platform's receipt verbatim */
+  function doJoinSave() {
+    if (!manageInst || !mJoinSettings) return;
+    var picked = document.querySelector('#mJoin input[name="mJoinPick"]:checked');
+    if (!picked) return;
+    var value = picked.value;
+    var box = $('mJoinMsg');
+    var btn = document.querySelector('#mJoin [data-join-save]');
+    if (btn) btn.disabled = true;
+    box.className = 'projMsg'; box.textContent = 'Saving…';
+    fetch(API + '/provisioning/instances/' + encodeURIComponent(manageId) + '/settings', {
+      method: 'PATCH', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ joinability: value })
+    }).then(function (res) {
+      return jsonOrEmpty(res).then(function (data) {
+        if (res.ok) {
+          /* the row now holds the choice — the radio follows it; the "runs"
+             line does NOT, until the project's own manifest says so */
+          mJoinSettings.value = (data.saved || {}).joinability || value;
+          if (data.push && data.push.queued) mJoinPushSeen = true;
+          box.className = 'projMsg ok';
+          box.textContent = (data.push && data.push.message) || 'Saved.';
+          return;
+        }
+        var e = apiError(data, res.status);
+        if (res.status === 401) { box.className = 'projMsg err'; box.innerHTML = signInAgain(); return; }
+        box.className = e.code === 'intent_conflict' ? 'projMsg' : 'projMsg err';
+        box.textContent = e.message || 'The change could not be saved — try again in a moment.';
+      });
+    }).catch(function () {
+      box.className = 'projMsg err';
+      box.textContent = 'Couldn’t reach the platform — check your connection and try again.';
+    }).then(function () {
+      if (btn) btn.disabled = false;
+      loadManage(true, true);
+    });
+  }
+
+  $('mJoin').addEventListener('click', function (ev) {
+    var t = ev.target.closest && ev.target.closest('button');
+    if (t && t.hasAttribute('data-join-save')) doJoinSave();
+  });
+
   /* ── delete the project (task 1003042): the manage page's teardown control.
      It renders from status + open_intent only — no second request — so the
      minute tick can repaint it and a queued teardown appears without a reload.

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/login.js

@@ -189,11 +189,20 @@ async function main() {
   }
   const instanceName = man.data.name || base;
   const admission = (man.data.admission && man.data.admission.policy) || 'invite-only';
+  // The project's door (task 1003044): brand.project.joinability names which of
+  // open / apply / invite_only it runs; an older core reports none, and then the
+  // binary admission.policy above is all there is to say.
+  // admission.policy 'open' wins over a pushed 'apply': a self-hosted instance on
+  // the legacy open-enrolment flag reports the pack's default while its door is open.
+  const joinability = admission === 'open' ? 'open'
+    : (man.data.brand && man.data.brand.project && man.data.brand.project.joinability) || null;
+  const DOOR_WORD = { open: '', apply: ' (apply to join)', invite_only: ' (invite-only)' };
+  const doorWord = joinability in DOOR_WORD ? DOOR_WORD[joinability] : (admission === 'invite-only' ? ' (invite-only)' : '');
   // Federation (ADR 0141 §1): a hosted instance advertises auth.idp = { origin,
   // client_id } — sign-in then runs through the Cloud Bongos hub, not a local
   // GitHub app. null → the direct-GitHub path, unchanged.
   const idp = (man.data.auth && man.data.auth.idp) || null;
-  log(`  Signing in to ${instanceName}${admission === 'invite-only' ? ' (invite-only)' : ''}${idp ? ' — via Cloud Bongos platform sign-in' : ''}`);
+  log(`  Signing in to ${instanceName}${doorWord}${idp ? ' — via Cloud Bongos platform sign-in' : ''}`);
 
   // 2. Device flow.
   let flow = await runDeviceFlow(base, { log, idp });
@@ -202,6 +211,12 @@ async function main() {
   //    then finish sign-in with a fresh device flow (the first code is spent).
   if (flow.state === 'not_approved') {
     log('');
+    // An invite-only project takes no applications — say so instead of
+    // collecting a username for a request the project would refuse.
+    if (joinability === 'invite_only') {
+      console.error(`✖ ${instanceName} is invite-only — it doesn’t take applications. Ask its owner for an invite, then re-run \`bongos login ${base}\`.`);
+      process.exit(1);
+    }
     log(`  You're not admitted to ${instanceName} yet.`);
     const ghLogin = (await prompt('  Your GitHub username: ')).replace(/^@/, '');
     if (!ghLogin) {
@@ -212,12 +227,18 @@ async function main() {
       method: 'POST',
       body: JSON.stringify({ github_login: ghLogin, note: 'via bongos login' }),
     });
-    if (reqRes.status === 409 && reqRes.data && reqRes.data.error === 'already_member') {
+    // The refusal envelope is { error: { code, message } } (ADR 0116); an older
+    // instance answered a flat { error: 'code' } — read both.
+    const reqErr = (reqRes.data && reqRes.data.error) || null;
+    const reqCode = reqErr && (reqErr.code || reqErr);
+    const reqMessage = reqErr && reqErr.message;
+    if (reqRes.status === 409 && reqCode === 'already_member') {
       log('  You already have an account — retrying sign-in…');
     } else if (reqRes.ok || reqRes.status === 200 || reqRes.status === 201) {
       log(`  ✓ Requested access to ${instanceName}. An Archon approves you with a 👍 in Discord (#member-approvals).`);
     } else {
-      console.error(`✖ could not file an access request (HTTP ${reqRes.status}).`);
+      // the project's own sentence when it gave one (an invite-only or open door)
+      console.error(reqMessage ? `✖ ${reqMessage}` : `✖ could not file an access request (HTTP ${reqRes.status}).`);
       process.exit(1);
     }
     log('  Waiting for approval (safe to leave running)…');

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,