@bongos/core 1.19.120 → 1.19.122

package/modules/provisioning/routes/provisioning.js

@@ -55,6 +55,16 @@ function mothershipOrigin() {
   catch { return ''; }
 }
 
+// The apex under which new projects get their auto-assigned <slug>.<apex> address
+// (task 1002704). A dedicated branding key — NOT publicOrigin, which on a control
+// plane that co-hosts a game is the GAME's domain (see mothershipOrigin above), so
+// deriving from it would assign customers under the wrong zone. Blank/absent →
+// no auto-assign: self-host and unconfigured instances keep creating domainless.
+function instanceApex() {
+  try { return (api.branding().domains || {}).instanceBase || ''; }
+  catch { return ''; }
+}
+
 // The provisioning mothership's product brand (e.g. "Cloud Bongos" on the control plane),
 // used to brand-qualify the auto GitHub App name so a common project slug ("demo") does
 // not collide with an existing GitHub App (task 2093). Portable — reads THIS instance's
@@ -311,6 +321,7 @@ module.exports = function provisioningRoutes() {
       target_ref: { type: 'string', maxLength: 200 },
       hosting_shape: { type: 'string', maxLength: 20 },
       domain: { type: 'string', maxLength: 253 },
+      no_address: { type: 'boolean' },
       tier: { type: 'string', maxLength: 40 },
       onboard_mode: { type: 'string', maxLength: 20 },
       // the declared project Type (task 1002772) — optional, closed vocabulary
@@ -337,10 +348,57 @@ module.exports = function provisioningRoutes() {
       });
     }
     try {
+      // A re-request must not re-litigate the address: createInstance never updates
+      // an existing row's domain, so for one the guards below could only misfire —
+      // a "Try again" on a pre-existing reserved-label row, or domain_taken fired
+      // against the row's own address. Birth-time rules run at birth only.
+      const existing = await provisioning.getInstanceBySlug(pool, slug);
+      // Resolve the address (task 1002704 — auto-assign, opt-out). An explicit
+      // domain (bring-your-own) wins; `no_address: true` is the deliberate opt-out;
+      // otherwise default to <slug>.<instanceBase> so an API-first caller inherits
+      // the same day-one address the wizard promises. An omitted domain is NOT an
+      // opt-out. Explicit domains are normalized + refused when malformed — the
+      // same bar the attach route has always applied (create inserted them raw).
+      let domain;
+      const assignedDefault = provisioning.defaultDomainForSlug(slug, instanceApex());
+      if (!existing) {
+        if (String(body.domain || '').trim()) {
+          domain = provisioning.normalizeHostname(body.domain);
+          if (!domain) {
+            return res.fail('bad_domain', 400, { reason: 'not a plausible hostname (letters/digits/dashes, at least two labels)' });
+          }
+        } else if (!body.no_address) {
+          domain = assignedDefault || undefined;
+        }
+        if (domain && provisioning.isReservedHostname(domain, instanceApex())) {
+          return res.fail('domain_reserved', {
+            status: 400,
+            message: `${domain} is a platform-reserved address — pick a different handle or bring your own domain.`,
+          });
+        }
+        // Inside the platform apex, the only address a project can hold is its own
+        // <slug>.<apex> — any other label under the apex is a squat on another
+        // handle's address space. Domains outside the apex are the real BYO path.
+        const apexZone = provisioning.normalizeHostname(instanceApex());
+        if (domain && apexZone && domain.endsWith(`.${apexZone}`) && domain !== assignedDefault) {
+          return res.fail('domain_reserved', {
+            status: 400,
+            message: `Inside ${apexZone}, a project's address is its own <handle>.${apexZone} — bring a domain you own instead.`,
+          });
+        }
+        // The same uniqueness bar as the attach route: one owner's address can
+        // never silently shadow another's.
+        if (domain) {
+          const holder = await provisioning.getInstanceByDomain(pool, domain);
+          if (holder && holder.slug !== slug) {
+            return res.fail('domain_taken', { status: 409, message: 'That address is already held by another instance.' });
+          }
+        }
+      }
       const { instance, created } = await provisioning.createInstance(pool, {
         ownerBuilderId: req.builder.id, slug,
         targetRef: body.target_ref, hostingShape: shape,
-        domain: body.domain, tier: body.tier, onboardMode,
+        domain, tier: body.tier, onboardMode,
         type: body.type,
       });
       // Slug already taken by ANOTHER builder — refuse (never reassign ownership).
@@ -360,7 +418,7 @@ module.exports = function provisioningRoutes() {
       if (created) {
         await provisioning.recordEvent(pool, {
           instanceId: instance.id, ownerBuilderId: req.builder.id, event: 'request',
-          detail: `provision requested (shape=${shape}, mode=${onboardMode}${body.domain ? `, domain=${body.domain}` : ''})`,
+          detail: `provision requested (shape=${shape}, mode=${onboardMode}${domain ? `, domain=${domain} (${domain === assignedDefault ? 'assigned' : 'byo'})` : ', no address'})`,
           actor: 'api:self',
         }).catch(() => {});
       }
@@ -376,6 +434,15 @@ module.exports = function provisioningRoutes() {
           };
         }
       }
+      // …and a re-request cannot REMOVE one either (task 1002704's opt-out only
+      // applies at birth) — same honesty, opposite direction.
+      let noAddressIgnored;
+      if (!created && body.no_address && instance.domain) {
+        noAddressIgnored = {
+          current: instance.domain,
+          hint: "a re-request never removes an existing instance's address",
+        };
+      }
       // Same honesty for a changed Type (task 1002772): a re-request keeps the
       // original declaration, and unlike domain there is no mutation route yet —
       // say so rather than silently dropping the new answer.
@@ -392,6 +459,7 @@ module.exports = function provisioningRoutes() {
         queued: intentCreated,
         created,
         ...(domainIgnored ? { domain_ignored: domainIgnored } : {}),
+        ...(noAddressIgnored ? { no_address_ignored: noAddressIgnored } : {}),
         ...(typeIgnored ? { type_ignored: typeIgnored } : {}),
       });
     } catch (err) {
@@ -497,16 +565,38 @@ module.exports = function provisioningRoutes() {
       if (!domain) {
         return res.fail('bad_domain', 400, { reason: 'a real multi-label hostname (e.g. myproject.example.com) — no scheme, path, or bare TLD' });
       }
+      // The runner's DNS write is an UPSERT, so an attach may not claim a
+      // platform-reserved name any more than a create may (task 1002704).
+      if (provisioning.isReservedHostname(domain, instanceApex())) {
+        return res.fail('domain_reserved', {
+          status: 400,
+          message: `${domain} is a platform-reserved address — bring a domain of your own instead.`,
+        });
+      }
       const inst = await provisioning.getInstanceById(pool, id);
       if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
         return res.fail('instance_not_found', 404);
       }
+      // Same rule as create: inside the platform apex the only address an instance
+      // can hold is its own <slug>.<apex> — anything else is a squat (task 1002704).
+      const apexZone = provisioning.normalizeHostname(instanceApex());
+      const assignedDefault = provisioning.defaultDomainForSlug(inst.slug, instanceApex());
+      if (apexZone && domain.endsWith(`.${apexZone}`) && domain !== assignedDefault) {
+        return res.fail('domain_reserved', {
+          status: 400,
+          message: `Inside ${apexZone}, an instance's address is its own <handle>.${apexZone} — bring a domain you own instead.`,
+        });
+      }
       const current = provisioning.normalizeHostname(inst.domain);
       if (current && current === domain) {
         return res.json({ ok: true, changed: false, queued: false, domain: inst.domain,
           message: 'This instance already has that address.' });
       }
-      if (current) {
+      // A platform-ASSIGNED address may be upgraded away to a bring-your-own
+      // domain — that upgrade path is half the task-1002704 decision (the old
+      // record lingers in DNS, the idea-1000710 class). A genuine BYO address
+      // stays un-re-pointable, as before.
+      if (current && current !== assignedDefault) {
         return res.fail('domain_already_set', { status: 409,
           message: `This instance is already addressed as '${inst.domain}' — re-pointing an existing address is not supported here.`,
           details: { current: inst.domain } });

package/package-lock.json

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

package/package.json

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

@@ -5,6 +5,10 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{productName}} — projects</title>
 <meta name="description" content="{{tagline}} Browse the map of what is being built, manage your own projects, and start a new one.">
+<!-- the apex new projects are addressed under (server-stamped, task 1002704) —
+     the wizard's address preview reads this so it matches what the server will
+     actually assign; blank/unstamped → fall back to guessing from the host -->
+<meta name="instance-base" content="{{instanceBase}}">
 <!-- Fonts: the production instance also injects these from the branding pack
      (config/branding.json theme.ui.fonts.links); kept here so the page reads
      correctly when viewed standalone. -->
@@ -2054,6 +2058,12 @@ h1[tabindex="-1"]:focus{outline:none;}
        dotless/local host (localhost, an IP) there is nothing sane to assign, so
        the step degrades to the old optional-domain form. ── */
     function apexBase() {
+      /* the server-stamped apex wins — it is what POST /provisioning/instances
+         will actually assign; the host guess below can disagree on a subdomain
+         hub (e.g. get.<apex>) and would then preview an address that 400s */
+      var meta = document.querySelector('meta[name="instance-base"]');
+      var stamped = meta ? String(meta.content || '').toLowerCase() : '';
+      if (stamped && stamped.indexOf('{{') < 0 && stamped.indexOf('.') > 0) return stamped;
       var h = String(location.hostname || '').toLowerCase().replace(/^www\./, '');
       if (!h || h.indexOf('.') < 0) return null;
       if (/^(localhost|127\.|\d+\.\d+\.\d+\.\d+$|\[)/.test(h)) return null;
@@ -2479,6 +2489,9 @@ h1[tabindex="-1"]:focus{outline:none;}
       var code = err && err.data && err.data.error && (err.data.error.code || '');
       if (code === 'slug_taken') return 'That handle is already taken by another project. Pick a different one.';
       if (code === 'bad_slug') return 'The handle didn’t pass the server’s checks — 2–40 lowercase letters, numbers, or dashes.';
+      if (code === 'domain_reserved') return 'That address is reserved for the platform itself. Pick a different handle, or bring a domain you own.';
+      if (code === 'domain_taken') return 'That address is already held by another project. Pick a different handle or domain.';
+      if (code === 'bad_domain') return 'The domain didn’t parse as a real hostname — use something like myproject.example.com.';
       return 'Couldn’t file the request: ' + (err && err.message ? err.message : 'something went sideways. Try again.');
     }
 
@@ -2532,6 +2545,10 @@ h1[tabindex="-1"]:focus{outline:none;}
             type: state.projType || undefined,
             hosting_shape: 'standalone',
             domain: resolvedDomain() || undefined,
+            /* The server now defaults an omitted domain to the assigned address
+               (task 1002704), so the opt-out must travel explicitly — an absent
+               domain no longer means "none". */
+            no_address: state.noAddress ? true : undefined,
             target_ref: state.owner + '/' + state.repo,
             /* LOAD-BEARING for the control-plane runner, not just for the checklist we
                render (task 1002562): 'adopt' makes it clone + layer onto the repo's
@@ -2554,6 +2571,7 @@ h1[tabindex="-1"]:focus{outline:none;}
         try {
           sessionStorage.setItem(CREATED_KEY, JSON.stringify({
             id: data.instance && data.instance.id, slug: state.slug, domain: resolvedDomain(),
+            noaddr: !!state.noAddress,
             mode: state.mode, name: state.name, at: Date.now()
           }));
           sessionStorage.removeItem(DRAFT_KEY);
@@ -2973,6 +2991,9 @@ h1[tabindex="-1"]:focus{outline:none;}
            blank wizard */
         state.name = created.name || created.slug; state.slug = created.slug || '';
         state.domain = created.domain || ''; state.mode = created.mode || 'greenfield';
+        /* restore the opt-out too — without it resolvedDomain() re-derives the
+           assigned address and the done panel promises one that doesn't exist */
+        state.noAddress = !!created.noaddr;
         renderDone();
         show(6, !!focus);
         startProgress(created.id);
@@ -3155,7 +3176,21 @@ h1[tabindex="-1"]:focus{outline:none;}
     return inst.status === 'provisioning' || inst.status === 'active';
   }
   /* client mirror of provisioning.DOMAIN_ATTACH_FROM */
-  function canAttachDomain(inst) { return !inst.domain && (inst.status === 'requested' || inst.status === 'error' || inst.status === 'active'); }
+  /* the platform-assigned <slug>.<apex> for this instance, from the server-stamped
+     apex only — no host guessing here: the upgrade door below must never show for
+     an address the server would refuse to re-point (task 1002704) */
+  function assignedDefaultFor(inst) {
+    var meta = document.querySelector('meta[name="instance-base"]');
+    var base = meta ? String(meta.content || '').toLowerCase() : '';
+    if (!base || base.indexOf('{{') >= 0 || base.indexOf('.') <= 0) return null;
+    return inst.slug + '.' + base;
+  }
+  /* domainless instances get their first address; an assigned default may be
+     upgraded to a bring-your-own domain (the server allows exactly that re-point) */
+  function canAttachDomain(inst) {
+    return (!inst.domain || inst.domain === assignedDefaultFor(inst)) &&
+      (inst.status === 'requested' || inst.status === 'error' || inst.status === 'active');
+  }
   /* re-enqueue doors: Try again on snagged, Bring it back on torn down —
      both re-POST the slug (the server's PROVISION_ENQUEUE_FROM gate) */
   function canRetry(inst) { return inst.status === 'error' && !inst.open_intent; }
@@ -3292,7 +3327,8 @@ h1[tabindex="-1"]:focus{outline:none;}
     if (canAttachDomain(inst)) {
       body += '<div class="attach">' +
         '<input type="text" id="dom-' + iid + '" placeholder="myproject.example.com" autocomplete="off" spellcheck="false" maxlength="253">' +
-        '<button type="button" class="btn small" data-attach="' + iid + '">Give it an address</button></div>';
+        '<button type="button" class="btn small" data-attach="' + iid + '">' +
+        (inst.domain ? 'Use your own domain' : 'Give it an address') + '</button></div>';
     }
     if (inst.status === 'error' && !inst.open_intent) {
       /* once a retry is queued the strip tells the story — the stale error

package/scripts/gds/api.js

@@ -18,12 +18,15 @@
 // on a 2xx, 1 on any non-2xx or transport error, 2 on bad invocation.
 
 const fs = require('node:fs');
-const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit, cliExit } = require('./cli-lib');
+const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit, cliExit, repairMsysMangledPath } = require('./cli-lib');
 
 
 (async () => {
   const method = (process.argv[2] || '').toUpperCase();
-  const urlPath = process.argv[3];
+  // task 1002809: Git Bash converts the leading-slash path arg into a Windows
+  // path under the Git install root before node sees it; undo that so builders
+  // don't need the MSYS_NO_PATHCONV=1 prefix.
+  const urlPath = repairMsysMangledPath(process.argv[3]);
   if (!method || !urlPath || !urlPath.startsWith('/')) {
     console.error("usage: node scripts/gds/api.js <METHOD> <path> [--body '<json>' | --body-file <file|->] [--quiet]");
     process.exit(2);
@@ -46,6 +49,13 @@ const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanc
     if (raw != null && raw.trim()) body = JSON.parse(raw);
   } catch (e) {
     console.error(`api: could not read/parse JSON body: ${e.message}`);
+    // task 1002809: inline --body is the usual culprit — shells (especially on
+    // Windows) strip or re-split the quotes before node sees them. Teach the
+    // durable pattern instead of leaving a bare parse error.
+    if (bodyFile == null && bodyInline != null) {
+      console.error('  Inline --body often loses its quoting through the shell. Durable pattern:');
+      console.error('  write the JSON to a file and pass --body-file <path>, or pipe it via --body-file -');
+    }
     process.exit(2);
   }
 

package/scripts/gds/cli-lib.js

@@ -771,6 +771,34 @@ function parseSessionRequest(text) {
   return { timeBudgetMin, mode, parallel };
 }
 
+// task 1002809: Git Bash (MSYS) rewrites a leading-slash argument into a Windows
+// path under the Git install root BEFORE node sees it — `/tasks/123` arrives as
+// `C:/Program Files/Git/tasks/123` — unless the builder remembers
+// MSYS_NO_PATHCONV=1. Undo it here so no one needs the env prefix. EXEPATH (set
+// by Git Bash) points INSIDE the install (`…\Git\bin`), while the mangled prefix
+// is the install root (`…\Git`), so we strip the LONGEST ancestor of EXEPATH
+// that prefixes the arg — never the bare drive root (that would "repair"
+// arbitrary Windows paths). Case-insensitive, both slash styles. Pure + exported
+// for tests/api_msys_path_repair.mjs; no-op off win32 or without EXEPATH.
+function repairMsysMangledPath(raw, { exepath = process.env.EXEPATH, platform = process.platform } = {}) {
+  if (!raw || raw.startsWith('/')) return raw;
+  if (platform !== 'win32' || !exepath) return raw;
+  const rawFwd = String(raw).replace(/\\/g, '/');
+  const rawLower = rawFwd.toLowerCase();
+  let ancestor = String(exepath).replace(/\\/g, '/').replace(/\/+$/, '');
+  let best = null;
+  while (ancestor.includes('/')) {
+    // Stop before the bare drive root ("C:" after the last slice).
+    if (/^[a-z]:$/i.test(ancestor)) break;
+    if (rawLower.startsWith(ancestor.toLowerCase() + '/') && (best === null || ancestor.length > best.length)) {
+      best = ancestor;
+    }
+    ancestor = ancestor.slice(0, ancestor.lastIndexOf('/'));
+  }
+  if (best === null) return raw;
+  return rawFwd.slice(best.length);
+}
+
 module.exports = {
   API_BASE,
   hallBase,
@@ -784,6 +812,7 @@ module.exports = {
   arg,
   hasFlag,
   stripBom,
+  repairMsysMangledPath,
   resolveQuiet,
   readSessionToken,
   apiCall,

package/scripts/gds/init.js

@@ -521,7 +521,7 @@ async function interview({ adopt = false } = {}) {
     const wantProv = (await ask(rl, '  Provision production hosting now? (y/N)', 'N')).toLowerCase();
     if (wantProv === 'y' || wantProv === 'yes') {
       const shape = (await ask(rl, '  Hosting shape? (co-tenant = share an existing box, $0 / dedicated = its own droplet / standalone = its own repo + pinned @bongos/core, ADR 0108)', 'co-tenant')).toLowerCase();
-      const domain = await ask(rl, '  Domain you own — bring-your-own (blank = none yet)?');
+      const domain = await ask(rl, '  Domain you own — bring-your-own (blank = the platform assigns <slug>.<its apex> when configured)?');
       const targetRef = await ask(rl, '  Target credential ref? (which control-plane creds the runner should use; optional)');
       let tier = '';
       if (shape === 'dedicated') tier = await ask(rl, '  Droplet tier? (e.g. s-1vcpu-2gb; optional)');
@@ -780,7 +780,13 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
       provisioned = true;
       const inst = (pres.data && pres.data.instance) || {};
       const cost = Number(inst.cost_estimate_usd || 0);
-      log(`  ✓ requested provisioning of instance "${pr.slug}" (${pr.hosting_shape}${pr.domain ? `, ${pr.domain}` : ''})` +
+      // Report the ROW's domain, not the request's: the server may have
+      // auto-assigned <slug>.<instanceBase> to a domainless request (task
+      // 1002704) — the operator must hear the address they actually got.
+      const addr = inst.domain
+        ? `, ${inst.domain}${pr.domain ? '' : ' (auto-assigned — attach your own domain any time to replace it)'}`
+        : ', no address yet';
+      log(`  ✓ requested provisioning of instance "${pr.slug}" (${pr.hosting_shape}${addr})` +
           `${cost ? ` — est. $${cost}/mo` : ''} — a provision intent is queued for the control-plane runner`);
     } else {
       const why = pres.status === 404

package/scripts/gds/onboard.js

@@ -88,7 +88,7 @@ async function run() {
     a.repoName = await ask(rl, 'GitHub repo name?');
     a.firstAdmin = await ask(rl, 'First admin (GitHub login — the founding Archon)?', a.repoOwner);
     a.slug = await ask(rl, 'Instance slug? (DNS/db-safe, e.g. mercury)');
-    a.domain = await ask(rl, 'Domain you own (bring-your-own; blank = decide later)?');
+    a.domain = await ask(rl, 'Domain you own (bring-your-own; blank = the platform assigns <slug>.<its apex> when configured)?');
 
     // Step 2 — human: the GitHub repo (create empty for greenfield; use existing for adopt)
     if (adopt) {

package/scripts/gds/ship.js

@@ -3122,6 +3122,40 @@ function playShipBell() {
   playSound(shipWav);
 }
 
+// task 1002809: normalize an API error body across BOTH wire shapes — the live
+// ADR 0116 (R01) envelope `{ error: { code, message } }` and the legacy flat
+// `{ error: 'code' }`. Same normalization as claim.js:formatClaimFailure and
+// cli-lib:isBoxScope; pure + exported for tests/ship_post_land_verify.mjs.
+function normalizeApiError(data) {
+  const errRaw = data ? data.error : undefined;
+  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
+  return {
+    code: isEnvelope ? errRaw.code : errRaw,
+    message: isEnvelope ? errRaw.message : undefined,
+  };
+}
+
+// task 1002809: classify a FAILED post-land POST /tasks/<id>/ship. The merge
+// already succeeded, so the server may simply have landed the task first
+// (reconcile-on-read — task 1049 — or the ~5-min reconciler racing this call).
+// The old check compared `data.error === 'task_not_confirmed'` — dead against
+// the envelope shape, so the already-landed SUCCESS rendered as a failure with
+// an "[object Object]" reason (the HANDOFF-apex-ui "400 after a successful
+// land" gotcha). liveStatus is the task's status from a verify GET (null when
+// that GET itself failed): 'shipped' is authoritative success whatever the
+// error said; task_not_confirmed with no live status keeps the task-1049
+// benefit of the doubt; any KNOWN non-shipped status stays a loud failure.
+// Pure + exported for tests/ship_post_land_verify.mjs.
+function postLandShipOutcome({ code, liveStatus }) {
+  if (liveStatus === 'shipped') {
+    return { alreadyShipped: true, why: 'the server landed it first — the failed ship call lost that race, nothing to fix' };
+  }
+  if (liveStatus == null && code === 'task_not_confirmed') {
+    return { alreadyShipped: true, why: 'the server reconciled it from the merged PR' };
+  }
+  return { alreadyShipped: false };
+}
+
 // Step 3 of the lifecycle: confirmed → shipped. Merge the branch into main,
 // deploy, flip the task to shipped, and fire the Discord broadcast (only when
 // the change actually deploys — #94 / ADR 0032; best-effort). Side-effecting;
@@ -3146,17 +3180,26 @@ async function mergeAndDeploy({ taskId, summary, advanceToMerge, skipMerge, dbOn
 
   const ship = await (await cliClient()).tasks.postTasksIdShip({ id: taskId, body: {} });
   if (!ship.ok) {
-    // task 1049: the server's publish-status reconcile-on-read may have already
-    // flipped this task to shipped (a concurrent status read saw merge+deploy).
-    // That's a SUCCESS — don't print it as a failure.
-    if (ship.status === 409 && ship.data && ship.data.error === 'task_not_confirmed') {
-      console.log(`Task #${taskId} is now: shipped (the server reconciled it from the merged PR).`);
+    // task 1049 / 1002809: the server may have already flipped this task to
+    // shipped (reconcile-on-read, or the reconciler racing this call). Verify
+    // the LIVE status before treating the refusal as a failure — the old
+    // flat-shape string check never matched the R01 envelope, so this success
+    // path was dead and every reconciled land reported as a failed ship.
+    const { code, message } = normalizeApiError(ship.data);
+    let liveStatus = null;
+    try {
+      const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
+      if (t.ok && t.data && t.data.task) liveStatus = t.data.task.status;
+    } catch (_) { /* verify is best-effort; fall back to the code-based call */ }
+    const outcome = postLandShipOutcome({ code, liveStatus });
+    if (outcome.alreadyShipped) {
+      console.log(`Task #${taskId} is now: shipped (${outcome.why}).`);
     } else {
-      console.error(`  /tasks/${taskId}/ship failed:`, ship.data);
+      const e = message || code || `HTTP ${ship.status}`;
+      console.error(`  /tasks/${taskId}/ship failed: ${e}${liveStatus ? ` (task is at '${liveStatus}')` : ''}`);
       // The merge itself succeeded — only the status flip failed, so a re-run
       // resumes cleanly (task 941). Report it rather than letting the card claim
       // the land is in progress.
-      const e = (ship.data && (ship.data.message || ship.data.error)) || `HTTP ${ship.status}`;
       return landBailed(`merged, but the ship call failed — ${e}`, `node scripts/gds/ship.js ${taskId}`);
     }
   } else {
@@ -4418,6 +4461,8 @@ module.exports = {
   // task 1049 (B): pure CI-land outcome classifier — a timed-out-but-armed PR is
   // 'pending' (success), not failure. Exported so the semantics are unit-tested.
   classifyLandOutcome,
+  normalizeApiError,
+  postLandShipOutcome,
   // task 1718: pure poll-path decision — enable-failure polls the SERVER (not a
   // dead-end strand at confirmed), enable-success watches GitHub. Exported so the
   // regression test locks in that a worktree enable-failure still waits for the land.