@bongos/core 1.17.0 → 1.17.2

package/public-landing/create.html

@@ -62,10 +62,24 @@ body{
   text-transform:lowercase;color:var(--ink);text-decoration:none;
 }
 .top .mark span{color:var(--accent);}
+.top-right{display:flex;align-items:center;gap:clamp(10px,2vw,18px);}
+/* exit the wizard — Esc, or this button (task 2098). Nothing is created until the
+   final step, so leaving simply drops the in-progress project. */
+.exit-wizard{
+  display:inline-flex;align-items:center;gap:7px;cursor:pointer;
+  background:transparent;border:1px solid rgba(42,31,23,0.16);border-radius:999px;
+  padding:7px 14px;font-family:var(--font-body);font-weight:600;font-size:13px;color:var(--ink-soft);
+  transition:background .14s ease,border-color .14s ease,color .14s ease;
+}
+.exit-wizard:hover{background:rgba(42,31,23,0.05);color:var(--ink);border-color:rgba(42,31,23,0.28);}
+.exit-wizard kbd{font-family:var(--font-mono);font-size:10px;line-height:1;background:rgba(42,31,23,0.08);border-radius:4px;padding:2px 5px;color:var(--ink-faint);}
 .who{display:flex;align-items:center;gap:10px;font-size:14px;font-weight:600;color:var(--ink-soft);min-height:34px;}
 .who img{width:30px;height:30px;border-radius:50%;border:2px solid #fff;box-shadow:0 2px 8px rgba(42,31,23,0.12);}
 .who a{color:var(--accent-deep);text-decoration:none;font-weight:700;}
 .who a:hover{text-decoration:underline;}
+/* switch to a different GitHub account from inside the wizard (task 2098) */
+.who .switch-acct{font-size:12px;font-weight:600;color:var(--ink-faint);padding-left:10px;margin-left:2px;border-left:1px solid rgba(42,31,23,0.16);}
+.who .switch-acct:hover{color:var(--accent-deep);}
 
 /* ── layout ── */
 .wrap{
@@ -304,7 +318,10 @@ input[type=text].bad{border-color:var(--err);}
 
 <header class="top">
   <a class="mark" href="/"><span data-brand-product>cloud bongos</span></a>
-  <div class="who" id="who" aria-live="polite"></div>
+  <div class="top-right">
+    <button type="button" class="exit-wizard" id="exitWizard" title="Leave the wizard — nothing is created">Exit <kbd>esc</kbd></button>
+    <div class="who" id="who" aria-live="polite"></div>
+  </div>
 </header>
 
 <div class="wrap">
@@ -445,7 +462,8 @@ input[type=text].bad{border-color:var(--err);}
   var API = '/api/bongos';
   var b = (typeof window !== 'undefined' && window.__BRANDING__) || {};
   var productName = (b.identity && b.identity.productName) || 'Cloud Bongos';
-  var buildersOrigin = (b.domains && b.domains.buildersOrigin) || 'https://builders.cloudbongos.com';
+  // (task 2094: the wizard no longer links into cloud bongos's own builders hall,
+  //  so the buildersOrigin it used to render is gone.)
   document.querySelectorAll('[data-brand-product]').forEach(function (n) { n.textContent = productName.toLowerCase(); });
   document.querySelectorAll('[data-brand-product-inline]').forEach(function (n) { n.textContent = productName; });
 
@@ -697,24 +715,24 @@ input[type=text].bad{border-color:var(--err);}
     var oa = state.domain ? oauthAppValues(state.domain) : null;
     $('doneLede').innerHTML = 'Provisioning is requested for <strong>' + esc(state.name || state.slug) + '</strong>' +
       (adopt ? ' — adopting your existing repo' : '') +
-      '. The platform stands up the server, database, and address on its own; you’ll find its live status under <a href="' + esc(buildersOrigin) + '" style="color:var(--accent-deep);font-weight:700;">Instances in your hall</a>.';
+      '. The platform stands up the server, database, and address on its own — you can watch its live status right here.';
 
     var steps = [];
     var repoLabel = state.owner && state.repo ? '<strong>' + esc(state.owner + '/' + state.repo) + '</strong>' : 'your new repository';
     steps.push(adopt
-      ? '<li><b>Layer onto your existing repo</b><p>In your repo run <code style="font-family:var(--font-mono)">bongos init --adopt</code>. It shows a conflict pre-flight and writes <em>nothing</em> until you accept — your files and history stay yours, and your existing backlog is imported. Commit and push.</p></li>'
-      : '<li><b>Create the empty GitHub repo</b><p>On github.com: New repository → ' + repoLabel + ' → leave it completely empty.</p></li>');
+      ? '<li data-onboard-step="github-repo"><b>Layer onto your existing repo</b><p>In your repo run <code style="font-family:var(--font-mono)">bongos init --adopt</code>. It shows a conflict pre-flight and writes <em>nothing</em> until you accept — your files and history stay yours, and your existing backlog is imported. Commit and push.</p></li>'
+      : '<li data-onboard-step="github-repo"><b>Create the empty GitHub repo</b><p>On github.com: New repository → ' + repoLabel + ' → leave it completely empty.</p></li>');
     if (!state.domain) {
       steps.push('<li><b>Add a domain you own</b><p>Sign-in on your new instance needs a real domain. When you have one, come back here or ask your hall — the address gets wired in minutes.</p></li>');
     }
     if (oa) {
-      steps.push('<li><b>Create the GitHub OAuth app</b><p>GitHub → <em>your account’s</em> Settings → Developer settings → OAuth Apps → New OAuth App. (Developer settings live under your account, not the repo.)</p>' +
+      steps.push('<li data-onboard-step="oauth-app"><b>Create the GitHub OAuth app</b><p>GitHub → <em>your account’s</em> Settings → Developer settings → OAuth Apps → New OAuth App. (Developer settings live under your account, not the repo.)</p>' +
         '<div class="kv"><span class="kk">Homepage URL</span><code>' + esc(oa.homepageUrl) + '</code>' + copyBtn(oa.homepageUrl) + '</div>' +
         '<div class="kv"><span class="kk">Callback URL</span><code>' + esc(oa.callbackUrl) + '</code>' + copyBtn(oa.callbackUrl) + '</div></li>');
       var cmd = 'bongos oauth-secret place ' + state.slug + ' --client-id <id> --client-secret <secret> --apply';
       steps.push('<li><b>Place the secret — verified</b><p>Never hand-edit the env file. On the control plane run the placement command; it checks the value is real and confirms sign-in works.</p>' +
         '<div class="kv"><code>' + esc(cmd) + '</code>' + copyBtn(cmd) + '</div></li>');
-      steps.push('<li><b>First sign-in</b><p>Open <code style="font-family:var(--font-mono)">' + esc(oa.homepageUrl) + '</code> and sign in with GitHub once. That seats you as the owner — the founding Archon.</p></li>');
+      steps.push('<li data-onboard-step="first-sign-in"><b>First sign-in</b><p>Open <code style="font-family:var(--font-mono)">' + esc(oa.homepageUrl) + '</code> and sign in with GitHub once. That seats you as the owner — the founding Archon.</p></li>');
       steps.push('<li><b>Verify</b><p><code style="font-family:var(--font-mono)">' + esc(oa.homepageUrl) + '/healthz</code> should report <code style="font-family:var(--font-mono)">auth_configured: true</code>. Then the hall is yours.</p></li>');
     }
     $('humanSteps').innerHTML = steps.join('');
@@ -760,7 +778,7 @@ input[type=text].bad{border-color:var(--err);}
     } else if (s === 'error') {
       el.innerHTML = progressMarkup(1, 1,
         'The standup hit a snag' + (inst.error_note ? ': ' + esc(inst.error_note) : '') +
-        '. The platform keeps retrying; details live under <a href="' + esc(buildersOrigin) + '">Instances in your hall</a>.', 'isErr');
+        '. The platform keeps retrying — this page updates as it recovers.', 'isErr');
     } else if (s === 'tearing_down' || s === 'torn_down') {
       el.innerHTML = progressMarkup(-1, 0, 'This instance was torn down. You can start another project below.', 'isErr');
       return true;
@@ -781,7 +799,7 @@ input[type=text].bad{border-color:var(--err);}
       fetch(API + '/provisioning/instances/' + encodeURIComponent(id), { credentials: 'same-origin' })
         .then(function (res) {
           if (res.status === 401) { throw new Error('gone:Your session expired — <a href="' + API + '/auth/web/start?return=/create">sign in again</a> to keep watching.'); }
-          if (res.status === 404) { throw new Error('gone:Can’t see this instance any more — check <a href="' + esc(buildersOrigin) + '">Instances in your hall</a>.'); }
+          if (res.status === 404) { throw new Error('gone:Can’t see this instance any more — it may have been torn down.'); }
           if (!res.ok) throw new Error('soft');
           return res.json();
         })
@@ -821,15 +839,43 @@ input[type=text].bad{border-color:var(--err);}
   }
   wireAgain();
 
-  /* ── boot: who am I? ── */
+  /* ── exit the wizard (task 2098) ── Esc, or the header button. Nothing is
+     provisioned until the final Create step, and the named orb is client-only
+     on the gate, so leaving simply means the project is not created. The form
+     draft persists in sessionStorage, so an accidental exit loses no typing. */
+  function exitWizard() { window.location.assign('/gate/'); }
+  $('exitWizard').addEventListener('click', exitWizard);
+  document.addEventListener('keydown', function (e) {
+    if (e.key === 'Escape') { e.preventDefault(); exitWizard(); }
+  });
+
+  /* ── switch GitHub account from inside the wizard (task 2098) ── you are not
+     locked to the account you entered with: sign out of the Cloud Bongos session,
+     then restart GitHub sign-in so the wizard reloads under whichever account you
+     pick. (To land on a *different* GitHub account, switch accounts on GitHub's
+     side; this un-locks our session so the next sign-in is honored.) */
+  function switchAccount(e) {
+    if (e) e.preventDefault();
+    var back = API + '/auth/web/start?return=/create';
+    fetch(API + '/auth/logout', { method: 'POST', credentials: 'same-origin' })
+      .then(function () { window.location.assign(back); })
+      .catch(function () { window.location.assign(back); });
+  }
+
+  /* ── boot: who am I? ── (task 2094: the wizard shows the signed-in identity
+        ONLY — never a link into cloud bongos's own builders hall. A project
+        creator enters a hall from their own project's landing, not from here.
+        task 2098: + a "switch account" action so you're not locked in.) ── */
   function renderWho() {
     var w = $('who');
     if (me) {
       w.innerHTML = (me.avatar_url ? '<img src="' + esc(me.avatar_url) + '" alt="">' : '') +
         '<span>' + esc(me.github_login || 'signed in') + '</span>' +
-        '<a href="' + esc(buildersOrigin) + '">your hall →</a>';
+        '<a href="#" class="switch-acct" id="switchAcct">switch account</a>';
+      var sw = $('switchAcct');
+      if (sw) sw.addEventListener('click', switchAccount);
     } else {
-      w.innerHTML = '<a href="' + esc(buildersOrigin) + '">the hall →</a>';
+      w.innerHTML = '';
     }
   }
 

package/public-landing/index.html

@@ -50,12 +50,15 @@ body{
 /* a soft white glow behind the mascot so a white- or transparent-bg PNG blends */
 .hero-mascot{
   position:relative;width:min(540px,86vw);margin-bottom:6px;
+  /* cap by height on short viewports so the hall CTA + sign-in hint always clear
+     the fixed footer (task 2094); on tall desktops the width cap wins, unchanged */
+  max-height:50vh;display:flex;justify-content:center;
 }
 .hero-mascot::before{
   content:"";position:absolute;inset:-6% -10%;z-index:-1;border-radius:50%;
   background:radial-gradient(ellipse at center, rgba(255,255,255,0.95) 0%, rgba(255,255,255,0.7) 45%, rgba(255,255,255,0) 72%);
 }
-.hero-mascot img{display:block;width:100%;height:auto;}
+.hero-mascot img{display:block;width:100%;height:auto;max-height:50vh;object-fit:contain;}
 /* fallback shown if buddha.png is not present yet */
 .mascot-fallback{
   width:min(540px,86vw);aspect-ratio:1.6/1;border-radius:28px;
@@ -95,6 +98,9 @@ body{
   font-size:14px;font-weight:600;color:var(--ink-soft);min-height:30px;
 }
 .who img{width:28px;height:28px;border-radius:50%;border:2px solid #fff;box-shadow:0 2px 8px rgba(42,31,23,0.14);}
+.who a{color:var(--accent-deep);text-decoration:none;font-weight:700;}
+.who a:hover{text-decoration:underline;}
+.who .who-act{padding-left:10px;margin-left:2px;border-left:1px solid rgba(42,31,23,0.18);}
 .foot{
   position:fixed;bottom:18px;left:0;right:0;z-index:1;text-align:center;
   color:var(--ink-soft);font-size:13px;opacity:0.8;
@@ -114,10 +120,9 @@ body{
   <div class="wordmark" data-brand-product>cloud bongos</div>
   <p class="tagline" data-brand-tagline>Building software is laying down a beat.</p>
   <div class="cta-row">
-    <a class="btn resting" id="createBtn" href="/api/bongos/auth/web/start?return=/create">Create a project</a>
-    <a class="btn ghost" data-link-hall href="https://builders.cloudbongos.com">Enter the Hall →</a>
+    <a class="btn" id="hallBtn" data-link-hall href="https://builders.cloudbongos.com">Enter the Hall →</a>
   </div>
-  <p class="signin-hint" id="signinHint" aria-live="polite"><a href="/api/bongos/auth/web/start?return=/create">Sign in with GitHub</a> to create a project — one click, and it's yours.</p>
+  <p class="signin-hint" id="signinHint" aria-live="polite"></p>
 </main>
 <div class="who" id="who" aria-live="polite"></div>
 
@@ -138,30 +143,44 @@ body{
     if (dom.buildersOrigin) document.querySelectorAll('[data-link-hall]').forEach(function(n){ n.setAttribute('href', dom.buildersOrigin); });
   }
 
-  /* Platform sign-in state (goal 35, task 2084). Signed out: the create door
-     rests grayed and clicking it starts GitHub sign-in, returning straight into
-     /create. Signed in: it wakes to the full accent door to /create, and the
-     builder chip appears top-right. The session cookie is apex-scoped, so
-     sign-in here carries into the hall too. Degrades to the signed-out visual
-     when the API is unreachable (static preview / standalone viewing). */
+  /* Membership-aware hall access (goal 35, task 2094). This is a PROJECT's own
+     landing page. Signed in as an admitted builder here → "Enter the Hall".
+     Otherwise → "Request access" (this project's own hall shows the request-
+     access card), with a quiet "already a builder? sign in" for returning
+     builders. Sign-in is itself gated to approved builders (auth.js), so a
+     newcomer who tries it is routed to request access anyway. The identity +
+     action live top-right. Degrades to the request-access visual when the API
+     is unreachable (static preview / standalone viewing). */
+  var hallHref = (b && b.domains && b.domains.buildersOrigin) || 'https://builders.cloudbongos.com';
+  var signInHref = '/api/bongos/auth/web/start?return=' + encodeURIComponent('/');
   function esc(s) {
     return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
       return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
     });
   }
+  var hallBtn = document.getElementById('hallBtn');
+  var signinHint = document.getElementById('signinHint');
+  var who = document.getElementById('who');
+
+  function showSignedOut() {
+    if (hallBtn) { hallBtn.textContent = 'Request access'; hallBtn.setAttribute('href', hallHref); }
+    if (signinHint) signinHint.innerHTML = 'Already a builder here? <a href="' + signInHref + '">Sign in with GitHub</a>.';
+    if (who) who.innerHTML = '<a href="' + signInHref + '">Sign in with GitHub</a>';
+  }
+  function showMember(me) {
+    if (hallBtn) { hallBtn.textContent = 'Enter the Hall →'; hallBtn.setAttribute('href', hallHref); }
+    if (signinHint) signinHint.textContent = '';
+    if (who) who.innerHTML =
+      (me.avatar_url ? '<img src="' + esc(me.avatar_url) + '" alt="">' : '') +
+      '<span>' + esc(me.github_login || 'signed in') + '</span>' +
+      '<a class="who-act" href="' + hallHref + '">Enter hall →</a>';
+  }
+
+  showSignedOut();   // default until /me resolves (and the no-JS request-access intent)
   fetch('/api/bongos/me', { credentials: 'same-origin' })
     .then(function (res) { if (!res.ok) throw new Error(String(res.status)); return res.json(); })
-    .then(function (data) {
-      var me = data.builder || data.me || data;
-      var btn = document.getElementById('createBtn');
-      btn.classList.remove('resting');
-      btn.setAttribute('href', '/create');
-      document.getElementById('signinHint').textContent = '';
-      document.getElementById('who').innerHTML =
-        (me.avatar_url ? '<img src="' + esc(me.avatar_url) + '" alt="">' : '') +
-        '<span>' + esc(me.github_login || 'signed in') + '</span>';
-    })
-    .catch(function () { /* signed out or unreachable: keep the resting door + hint */ });
+    .then(function (data) { showMember(data.builder || data.me || data); })
+    .catch(function () { /* signed out / not a member / unreachable: request-access visual stands */ });
 })();
 </script>
 </body>

package/scripts/discord/README.md

@@ -1,6 +1,6 @@
 # Discord integration (outbound)
 
-Posts Off the Boats build updates into the team Discord. This replaced the
+Posts Example build updates into the team Discord. This replaced the
 Google Chat outbound broadcast (Discord Phase 2, GDS task [#607](https://example.com/builders#/task/607)).
 
 Discord is a **one-way window into the GDS** — these scripts only POST. No

package/scripts/gds/CLAUDE.md

@@ -1,144 +1,15 @@
-# scripts/gds/ — builder CLI (agent notes)
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> Nested CLAUDE.md — loads on demand when you work here. Root [CLAUDE.md](../../CLAUDE.md) is the index. See [ADR 0061](../../docs/adr/<redacted>.md) for why these exist.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-**Purpose.** Cross-platform Node CLI behind the `/builder-*` slash commands (`.claude/skills/builder-*`). Every script talks to `/api/gds/*` on `example.com` (override `GDS_API_BASE` for local dev). `node` is the one guaranteed runtime — no bash/python/jq in the JS path ([#686](https://example.com/builders#/task/686)), so the skills shell out to `node scripts/gds/*.js`. Session token lives in the instance config dir — `~/.config/<configDir>/gds-session.json`, resolved via `src/instance-config.js` (R61/[#1200](https://example.com/builders#/task/1200)); OTB pins `configDir=otb` so it stays `~/.config/otb`, with read-fallback to the legacy dir + `pms-session.json`. Env vars resolve `<envPrefix>_<SUFFIX>` (OTB → `OTB_`) then legacy `OTB_`/`GDS_`/`PMS_`.
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-**Shared kit.** `cli-lib.js` — `apiCall(method, path, body)` (adds auth header, resolves token+base), `requireSession`, `arg`/`hasFlag` (argv parsing), `readSessionToken`, plus terminal format helpers + onboarding/cost nudges. `api.js` — generic `node api.js METHOD /path [--body | --body-file -]` caller; status→STDERR, JSON→STDOUT.
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-**Entry points (→ slash command).**
-- `start.js` → `/builder-start` — list claimable tasks (parallel-safe vs active claims); `--fit`, `--discipline`, `--version`, `--track`, `--json`.
-- `claim.js` → `/builder-claim N` — atomically claim a task; prints claim id + touches[] + relevant learnings/context-pack.
-- `ship.js` → `/builder-ship` — **the big one (~151KB)**; 3-step lifecycle completed→confirmed (credits, smoke)→shipped (merge+deploy). Flags: `--no-merge`, `--skip-grade`, `--regrade`, `--force`, `--allow-empty`. The empty-diff/phantom-ship guard runs **regardless of `--skip-grade`** (task 1365 closed the task-1363 hole where `--skip-grade` bypassed it and a never-committed deliverable confirmed + reconciler-shipped with no artifact on main); a no-artifact/DB-only ship now needs explicit `--allow-empty`, which is still **refused if the working tree is dirty/untracked** (that means you forgot to commit).
-- `release.js` → `/builder-release N` — cancel a claim (no credits); task returns to `ready`.
-- `capture.js` → idea_inbox — file an idea (`--kind`, `--body-file`, `--version`); `recall.js` → `/recall` — lexical (FTS+trigram/RRF) rank-scoped knowledge search; `learning-capture.js` — durable short-form learning into the DB.
-- `gen-diagrams.js` — regenerate the 5 onboarding `.mmd`/`.svg`/`.png` + `assertions.json` from live facts; `gen-repo-map.js` — regenerate the code symbol skeleton (`docs/repo-map.md` + the generated factual block in each nested CLAUDE.md; ADR 0063); `gen-session-index.js` — regenerate the session-log index (`docs/session-log-index.md` + the bounded CLAUDE.md §13 snippet) from `docs/session-logs/*.md` (ADR 0062 §8, task 1226); `gen-file-map.js` — regenerate the `.claude/skills/` + `.claude/scheduled-tasks/` sections of `docs/file-map.md` from disk, notes sourced from `docs/file-map.notes.json` (ADR 0066, task 1276; `--check` fails on drift or an undescribed skill/routine); `fitness.js` — architecture fitness gate (core↔host boundary, CLAUDE.md budget, nested-doc presence, rank-guard, generated-artifact freshness; ADR 0062 §9, enforced via `tests/fitness.mjs`); `architect-audit.js` — MAS Phase 5 bounded first-principles `--scope` audit → `docs/audits/`; `linkify-refs.js` — rewrite bare `#NNN` refs into hall links so GitHub doesn't mis-autolink.
-- `box.js` — operator/control-plane dev-box lifecycle (`provision`/`park`/`wake`/`deprovision`/`sweep-*`/`status`); rank-gated against live DB rank. **Runs on the control plane, never inside a box.**
-- `provision.js` — the **instance-provisioning** control-plane runner (ADR 0111 §2/§3, [#1944](https://example.com/builders#/task/1944)); a sibling of `box.js`. Sole holder of the DO/Cloudflare tokens; drains `provisioning_intents` (the web tier only enqueues) and composes the [`cloudbongos-standup`](../../docs/recipes/cloudbongos-standup.md) runbook — server (co-tenant port OR dedicated droplet) → `createdb` + GDS-only migrate → per-instance `/etc/<slug>/web.env` → systemd unit → per-instance Caddy snippet + reload → `/healthz` — **idempotent, dry-run-default** (nothing mutates without `--apply`), drift-reconciling. Driven by `infra/provision-intent-runner.timer`. Commands: `run-intents`/`provision <slug>`/`teardown <slug>`/`reconcile`/`status`/`dns-check <domain>` (the task-[#1980](https://example.com/builders#/task/1980) DNS token-scope PREFLIGHT — read-only, verifies the CF token reaches the domain's zone before the address step; provisioning also fail-fasts on it up front). Reuses `do-api.js` + `modules/provisioning/provisioning.js`. **Runs on the control plane, never inside the web tier.** The runner is `User=lars` (non-root), so the privileged steps (write `/etc`, `systemctl`, `createdb`/`migrate`) escalate via `sudo` (temp-file + `sudo install`, `sudo systemctl`, `sudo -u postgres`) **only under `PROVISION_SUDO=1`** — the runner unit sets it ([ADR 0128](../../docs/adr/<redacted>.md)); default OFF keeps CLI/test runs bare. The unit must NOT set `NoNewPrivileges=true` (it blocks `sudo`). With `PROVISION_REMOTE_HOST` set it also runs the box-mutating steps on a remote co-hosting box over `ssh` (control plane orchestrates co-tenants that live elsewhere → zero cloud tokens on that box), while the Cloudflare DNS hook stays local via `controlExec` ([ADR 0130](../../docs/adr/<redacted>.md), task 2065); default OFF = all-local, unchanged. The `cohost-*` control-plane runner units + the SSH DB tunnel that read the co-hosting box's queues over `127.0.0.1:5433` to activate this end-to-end are [ADR 0132](../../docs/adr/<redacted>.md) / task 2071.
-- `oauth-secret.js` — **verified, shell-independent OAuth-secret placement** for a provisioned instance (ADR 0111, [#1979](https://example.com/builders#/task/1979)); the onboarding step every form (skill/CLI/hall) drives. `place <slug> --client-id --client-secret [--apply]`: VALIDATES the creds (length/charset — catches the silent 26-char truncation `authConfigured()` misses, since it only checks presence), rewrites `/etc/<slug>/web.env` via Node (never a fragile `read -s`/`sed -i`), restarts the unit, then PROBES `/healthz` for `auth_configured:true`. Dry-run-default; control-plane only.
-- `do-api.js` · `cf-tunnel.js` · `http-api-client.js` — the **shared control-plane network clients** (DigitalOcean v2 · Cloudflare named-tunnel · their JSON-HTTP skeleton). Operator-CLI-only (never the web tier), injectable-transport + **dry-run-by-default**. Moved here from `modules/dev-box/` in BV1 task [#1943](https://example.com/builders#/task/1943) ([ADR 0111](../../docs/adr/<redacted>.md) §2) so both `box.js` AND the instance-provisioning runner `provision.js` (task #1944) reuse the DO client without a module→module import. (The Cloudflare **DNS-record** hook stays at `infra/box-dns-cloudflare.sh`, invoked by path via `BOX_DNS_HOOK`.)
-- `seed-v3-tasks.js` / `seed-gds-v4-tasks.js` — idempotent planning-session task seeders (skip on existing `source_ref`); `newcomer-floor.*` — deterministic copy-stamp replenisher for newcomer chores (`.js` + `.config.json` + `.templates.json` + `.test.js`).
-
-**Gotchas / invariants.**
-- `ship.js` is huge — search by phase keyword, don't read end-to-end. Every change here still needs a claimed GDS task (no admin loophole).
-- Cross-platform = no bash-isms in the `.js` path; keep `process.execPath`/`os.homedir()` patterns.
-- Never hand-edit generated `.mmd`/`assertions.json` — run `gen-diagrams.js`. Never hand-edit `linkify-refs.js`'s output by adding bare `#NNN`.
-- **The guardrails are two-root aware ([ADR 0108](../../docs/adr/<redacted>.md) §Consequences #4).** `fitness.js`, `gen-repo-map.js`, `gen-file-map.js` resolve `resolveCoreRoot()` (core code + the src/bongos·scripts/gds nested docs) vs `resolveInstanceRoot()` (the root CLAUDE.md, `.claude/`, instance modules + migrations); modules are scanned across both. Today both roots are the one checkout (byte-identical); post-split each inspects the right tree. **Do not reintroduce a hardcoded `path.resolve(__dirname,'..','..')`** in these files — it re-fuses the boundary and would point into `node_modules` post-split. `tests/fitness_two_root.mjs` diverges the roots to prove it.
-- **Migration filenames are namespaced by source ([ADR 0108](../../docs/adr/<redacted>.md) §5, `migration-namespace.js`).** A NEW core migration is `migrations/core_NNN_slug.sql`; a NEW module migration is `modules/<key>/migrations/<key>_NNN_slug.sql`; instance seeds stay bare `migrations/instance/NNN_slug.sql`. This is what lets the core repo and the instance repo version independently without their migrations colliding on the stem-keyed `schema_migrations`. Existing bare files are grandfathered (never rename one — it re-runs on prod). `fitness.js` Check 11b + `tests/migration_namespace.mjs` enforce it; `claim.js`/`next-number.js` suggest the namespaced form. `migrate.sh` merges three roots (core-package / instance / module) resolved via `resolveCoreRoot()`/`resolveInstanceRoot()`.
-- Many other files here are not slash-command entry points: smoke tests (`smoke-*.sh`/`smoke-gds.js`), audits (`audit-*`, `main-audit.js`, `gate-review.js`), session tooling (`session*.js`, `pulse.js`), and systemd units (`gds-db-*.{service,timer}`).
-
-<!-- BEGIN GENERATED REPO-MAP (scripts/gds/gen-repo-map.js — do not hand-edit) -->
-**Symbol skeleton (generated from the code — do not hand-edit; refresh: `node scripts/gds/gen-repo-map.js`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](../../docs/adr/<redacted>.md)).
-
-- `adopt-detect.js` — `detectStack({ dir, fs = nodeFs, path = nodePath } = {})`, `formatStackSummary(s)`, `detectPackageManager(exists, hasPkg)`
-- `adopt-import.js` — `DEFAULT_MAX`, `parseBacklogFile(text)`, `resolveBacklogTasks({ dir, repo = {}, githubToken, backlogFile, fetchImpl, fs = nodeFs, path = nodePath, max =…)`, `BACKLOG_FILENAMES`, `fetchGitHubIssues({ owner, repo, token, fetchImpl = globalThis.fetch, max = DEFAULT_MAX, onWarn = ()`, `findBacklogFile(dir, fs = nodeFs, path = nodePath)`, `parseGitHubIssues(issues)`
-- `adopt-preflight.js` — `SEV`, `formatPreflight(report)`, `INCOMING_PATHS`, `preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {})`, `checkCiCollisions(workflows = [])`, `checkFitnessBoundary({ topLevelDirs = [], hasSrcBongos = false } = {})`, `checkMigrationNamespace(basenames = [])`, `checkProtectedPaths(incoming = INCOMING_PATHS)`, `CORE_EXPECTED_CHECKS`
-- `architect-audit.js` — `slug(scope)`, `buildPrompt({ scope, fileList, fileBlocks, version })`, `PROMPT_HEADER`, `pickValidKind(kind)`, `validateSeedIdeas(raw)`
-- `art-stage.js` — `waitHealthy(healthUrl, deps = {})`, `affectedTiles(explicit, deps = {})`, `copyAtlasToServed(deps = {})`, `rebuildAtlas(deps = {})` _(+1 more)_
-- `audit-deps.js` — `classify(tTouches, oTouches)`, `OPEN`, `findMissingDeps(tasks, { open = OPEN, isBlocker = isUnshippedBlocker } = {})`, `HOTSPOTS`, `isUnshippedBlocker(s)`
-- `audit-exports.js` — `TARGETS`, `buildCorpus()`, `classifyExports(targetAbsPath, exportNames, corpus)` _(+1 more)_
-- `audit-ships.js` — `findCommitForTask(taskId)`, `gitDiffStatsForCommit(sha)`, `filesTouchedByCommit(sha)`, `downstreamImpact(sha, files)`, `fetchShipped(days)`, `fetchFullTask(id)`, `fetchLearning(taskId)`
-- `autonomy-gate.js` — `decide({ enabled, routine = '', claimableCount = 0, openIdeasCount = 0, mtdSpendUsd = 0, ceiling …)`, `precheck(routine, deps = {})`, `isEnabled(env = process.env)`, `gatherSignals(routine, deps = {})`, `AUTONOMY_FLAG`, `DEFAULT_CEILING_USD`, `ceilingUsd(env = process.env)`, `autofixAllowed({ enabled = false, graderBypassOn = true, isProtected = true, confidence = 'low', fileCoun…)`
-- `backfill-cost.js` — `findLedger(argPath)`, `parseLedger(filePath)`, `postCost(row, sourceRef)`
-- `backfill-sessions.js` — `entryText(entry)`, `extractTaskIds(entries)`, `inScope(dirName)`, `PROJECT_TOKENS`, `TASK_MARKERS`
-- `backfill-task-rewards.js` — `BACKFILL_REASON`, `backfillKey(taskId)`, `computeTaskReward(taskId, rawCredits, kind)`, `netForBuilder(wouldBeTotal, costPlusAlreadyPaid)`, `planForBuilder(builderId, taskRewards, costPlusAlreadyPaid, alreadyBackfilled = new Set()`, `TOKEN_REWARD_REASON`
-- `backup.js` — `fmtBytes(n)`, `fetchStatus()`, `printStatus(data)`, `trigger()`
-- `box-auth-check.js` — `onBox()`, `decideBoxAuth({ onBox, hasToken, isBoxScoped, meStatus })`, `printReauth({ boxScoped })`, `printSetup()`
-- `box-connect-lib.js` — `RANK_ORDER`, `WORKSPACE`, `binPresent(bin, versionArgs = ['--version'])`, `buildKnownHostsUpsert(existing, hostname, hostKeysRaw)`, `buildRemoteShellCommand({ firstRun = false, workdir = WORKSPACE } = {})`, `buildSshAliasBlock({ hostname, identityFile })`, `CLAUDE_VSCODE_EXTENSION`, `fetchRank()`, `isFirstLogin(hostname)`, `parseEnsure(data)` _(+8 more)_
-- `box.js` — `deprovisionOne(pool, boxes, doApi, box, { actor, login, sleepFn } = {})`, `cmdProvision(pool, boxes, boxOnboard, ref, { apply })`, `markErrorUnlessDestroyed(pool, boxes, builderId, errNote)`, `runDnsHook(hostname, ip, hook = CONFIG.dnsHook)`, `deleteWithRetry(fn, { tries = 3, sleepMs = 2000, sleepFn } = {})`, `runDnsHookBlackhole(hostname, hook = CONFIG.dnsHook)`, `cmdReconcileDrift(pool, boxes, { apply })`
-- `build-bongos.js` — `VERSION`, `TARGETS`
-- `capture.js` — `resolveDefaultVersion()`
-- `cf-tunnel.js` — `class CfTunnelApi`, `terminalHostname(login, zone)`, `CfApiError`, `previewHostname(login, zone)`, `CF_API_BASE`, `CACHE_BYPASS_RULE_DESC`, `tunnelName(login)`, `CACHE_BYPASS_EXPRESSION`, `CFARGO_SUFFIX`, `GAME_SERVICE` _(+1 more)_
-- `ci-grade.js` — `git(args)`
-- `claim-recall.js` — `printClaimRecall(task, { excludeKeys = [] } = {})`, `RECALL_LIMIT`, `claimRecallQuery(task)`, `formatRecallSources(results, { limit = RECALL_LIMIT, excludeKeys = [], currentTaskId = null } = {})`, `rowKeys(row)`
-- `claim.js` — `printRelevantLearnings(task)`, `printDisciplineMode(task)`, `captureHeadSha()`, `warnIfToolingStale()`, `printClaimCard(task, widgetsEnabled = true)`
-- `classify-discipline.js` — `pad(s, n)`, `emoji(d)`
-- `claude-materialize.js` — `bongosify(text, verbs = VERBS)`, `materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = ()`, `copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true } = {})`, `GDS_INVOCATION_RE`, `scriptToVerb(verbs = VERBS)`, `transformSettings(srcPath)`
-- `cli-lib.js` — `cliClient(opts = {})`, `arg(name, args = process.argv.slice(2)`, `requireSession()`, `API_BASE`, `hasFlag(name, args = process.argv.slice(2)`, `SESSION_PATH`, `apiCall(method, urlPath, body = null, opts = {})`, `loadSession()`, `fmtUsd(n)`, `fmtMinutes(m)` _(+13 more)_
-- `code.js` — `repoRoot()`, `runCode(args, { inherit = true } = {})`, `runLocal({ log })`
-- `codemod-rename-src-gds.js` — `segReplace(s)`, `isSrcTopLevel(rel)`, `gitMv()`, `isBinary(buf)`
-- `conductor-dispatch.js` — `autoDispatch(deps = {})`, `bestMatchingClaim(claims, changedFiles)`, `pickSpecialists(changedFiles)`, `selectAutonomousDispatch(gate, claimable)`
-- `context-pack.js` — `contextPack({ activeClaims = [], currentTaskId = null } = {})`, `formatContextPack(pack)`, `buildContextPack({)`, `formatContextPackCompact(pack)`, `apiContract()`, `formatClaims(claims)`, `formatOs(os)`, `normalizeClaims(activeClaims, currentTaskId)`, `osFacts({ platform, runWhich })`, `resolveWorktreeRoot({ runGit, cwd })`
-- `design-sync.js` — `arg(flag, args)`, `collectFiles(dir, root)`
-- `diagnose-achievements.js` — `backfill()`
-- `diagram-facts.js` — `repoSlug(repo)`, `gatherFacts({ repo })`, `defaultRank(migs)`, `readMigrations(repo)`, `CONCEPTUAL_TASK_IDS`, `conceptualFacts({ repo, migs })`, `DEV_BOX_TASK_IDS`, `liveVersions()`, `rankEnum(migs)`, `readGdsSource(repo)` _(+5 more)_
-- `do-api.js` — `class DoApi`, `DoApiError`, `DO_API_BASE`
-- `docs-entropy.js` — `parseFile(absPath)`, `collectMarkdownFiles()`, `scanStaleLinks(relFiles)`, `scanDuplicateProse(relFiles)`, `toSlug(heading)`
-- `doctor.js` — `section(title)`, `gitOut(cmd, opts = {})`, `checkSession()`, `checkToolchain()`, `checkGitPlumbing()`, `checkRepoState()`, `checkEnvironment()`, `checkDeployTooling()`
-- `feedback-latest.js` — `parseArgs(argv)`
-- `fetch-sound-prefs.js` — `writeAtomic(targetPath, contents)`
-- `figma-design-sync.js` — `arg(flag, args)`, `collectFiles(dir, root)`
-- `fitness.js` — `KERNEL_FILES`, `discoveredModuleKeys(modulesDir)`, `scanScopeMapSource(src)`, `checkCoreHostBoundary()`, `checkScopeMapImportsProtected()`, `moduleImportViolation(fromAbsFile, spec)`, `moduleNamespace(key)`, `moduleOwnerOf(absFile)`, `checkClaudeMdBudget(opts = {})`, `checkCoreCarriesNoModuleCode()` _(+20 more)_
-- `gate-review.js` — `classifyChanges({ files, blobAt, diffBytes = 0 } = {})`, `matchesHardFloor(f)`, `HARD_FLOOR_GLOBS`, `isCanonicalPath(p)`, `resolveAction({ verdict, trusted, ownerApproved })`, `certifyAllowlistNarrowing(base, head)`, `certifyRunUnitTestsNarrowing(base, head)`
-- `gating.js` — `repoSlug()`, `getProtection(repo)`, `toPutBody(p)`, `putProtection(repo, putBody)`, `deleteProtection(repo)`, `workflowState(repo, wf)`, `setWorkflow(repo, wf, enable)`, `readSnapshot()`, `writeSnapshot(obj)`, `summarize(putBody)` _(+3 more)_
-- `gen-api-client.js` — `build()`, `buildModel(spec)`, `camel(s)`, `groupByTag(ops)`, `renderClientJs(spec, ops)`, `renderTypes(spec, ops)`, `pascal(s)`
-- `gen-api-docs.js` — `build()`, `pathParams(route)`, `resolveScalar(expr, constants = {})`, `captureBalanced(str, from)`, `splitTopLevel(inner)`, `extractModel()`, `extractResponse(lines, i)`, `pascalCase(s)`, `requestSchemaFor(r)`, `resolveArray(expr, constants = {})` _(+18 more)_
-- `gen-atlas.js` — `buildContextView()`, `buildModuleView()`
-- `gen-diagrams.js` — `brand()`, `cap(s)`, `lifecycleMmd(f)`, `rankLadderMmd(f)`, `versioningMmd(f)`, `drachmaeKarmaMmd(f)`, `architectureMmd(f)`, `rebuildAssertions(prev, f)`
-- `gen-file-map.js` — `end(id)`, `buildModel()`, `begin(id)`, `SECTIONS`, `renderSection(model)`, `computeWrites()`, `injectSection(existing, model)`, `buildSection(section, notes)`
-- `gen-repo-map.js` — `BEGIN`, `END`, `buildModel()`, `NESTED_DIRS`, `injectBlock(existing, block)`, `renderNestedBlock(model, dir)`, `renderRepoMap(model)`
-- `gen-session-index.js` — `BEGIN`, `END`, `computeWrites()`, `collectEntries(dir = LOGS_DIR)`, `injectSnippet(existing, snippet)`, `renderIndex(entries)`, `SESSION_FILE_RE`, `cleanTitle(rawHeading)`, `parseEntry(filename, content)`, `renderSnippet(entries, count = SNIPPET_COUNT)` _(+1 more)_
-- `git-merge-regen.js` — `REGENERABLE`, `regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {})`, `resolveInWorktree(relpath)`, `hasMarkers(s)`, `threeWayMerge(base, ours, theirs)`, `MARKER_RE`
-- `grade-smoke.js` — `summarize(result, label)`
-- `http-api-client.js` — `class JsonHttpApi`, `makeApiError(name, code)`
-- `init.js` — `CORE_PKG`, `slugify(s, fallback = 'goal')`, `interview({ adopt = false } = {})`, `HOSTING_SHAPES`, `KNOWN_MODULES`, `coreVersionSafe()`, `coreDepRange()`, `provisioningRequest(spec)`, `seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {})`, `writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })` _(+15 more)_
-- `install-git-hooks.js` — `activate()`, `registerMergeDriver(root)`, `MERGE_DRIVER_NAME`, `configuredHooksDir()`
-- `key-card.js` — `wrap(text, width)`, `esc(s)`, `safeBrand()`, `emitKeyCard(model, { log = console.log, widgetsEnabled = true } = {})`, `buildKeyCardModel(input = {})`, `renderKeyCardHtml(model)`, `renderMonospaceKeyCard(model)`
-- `key-status.js` — `KEYS`, `KEY_LIKE_RE`, `refuseIfKeyPasted(argv)`
-- `land-watch.js` — `watch({ nowMs = Date.now()`, `PENDING_DIR`, `readBreadcrumbs()`, `classifyLand(task, ageMs, { staleMs = DEFAULT_STALE_MS } = {})`, `DEFAULT_STALE_MS`, `writeBreadcrumb(taskId, data = {})`, `buildShippedEnvelope(crumb, task)`, `removeBreadcrumb(fileOrId)`
-- `learning-capture.js` — `csv(v)`, `readStdin()`, `autoDetectFiles()`
-- `linkify-refs.js` — `RESOLVER_BASE`, `linkifyText(text, ids, stats)`, `discoverDocs()`, `classifyKind(left, carried, prevKind)`, `linkifySegment(segment, ids, leftContext, stats)`, `RESOLVER_BASE_BLOCKER`, `RESOLVER_BASE_IDEA`, `upgradeLineCodeSpans(line, ids, stats)`, `normalizeIdSets(ids)`, `unlinkEntitySegment(segment, leftContext, stats)`
-- `local-preview-lib.js` — `start(deps = {})`, `REPO_ROOT`, `stop(deps = {})`, `restart(deps = {})`, `health(deps = {})`, `healthUrl(deps = {})`, `HOST`, `onBox(deps = {})`, `BOX_ENV_PATH`, `localUrl(deps = {})` _(+11 more)_
-- `local-preview.js` — `pollHealthy(ms = 20_000)`, `warnIfOnBox()`
-- `login.js` — `runDeviceFlow(base, { log })`, `normalizeInstanceBase(raw)`, `pollDecision(body)`
-- `main-audit.js` — `analyzeCommits(commits, rankByIdentity, { strict = false } = {})`, `parseCommits(range)`, `resolveRank(c, rankByIdentity)`
-- `memory-map.js` — `entries(text)`, `estTokens(bytes)`, `measure(text)`, `applyCompaction(mapPath, expectedText, newText, deps = {})`, `keepAlways(meta)`, `metaOf(file, memoryDir, deps = {})`, `parseLines(text)`, `planCompaction(text, opts = {})`, `WARN_BYTES`, `isRule(type)` _(+4 more)_
-- `merge-lock.js` — `mainWorktreeRoot()`
-- `migration-namespace.js` — `CORE_NS`, `INSTANCE_NS`, `filenameViolation(source, basename, { moduleKey } = {})`, `migrationNumberOf(basename)`, `stemCollisions(files)`, `nextInNamespace(basenames)`, `parseMigrationName(basename)`, `LEGACY_BARE_CORE_MAX`, `LEGACY_BARE_MODULES`, `sqlNamespace(moduleKey)` _(+2 more)_
-- `mirror-lineage-check.js` — `MIGRATION_BASENAME_RE`, `migrationNumbersFromPaths(paths)`, `parseEnumChecks(sql)`, `proveLineage({ publishableFiles, privateMigrationNumbers, ctx })`, `buildRedactionContext()`, `enumDrift(files)`, `numberingDivergence(privateSet, mirrorSet)`, `runSimulation()`
-- `mirror-redact.js` — `findLeaks(text, sensitiveLiterals)`, `buildRedactionRules(branding = {}, extra = {})`, `collectSensitiveLiterals(branding = {}, extra = {})`, `findSecretLeak(text, extraSecrets = [])`, `REDACTED_IP`, `escapeRegExp(s)`, `redactText(text, rules)`, `NEUTRAL_TOKEN`, `deriveInstanceLiterals(branding = {}, extra = {})`, `firstPublicIP(text)` _(+7 more)_
-- `module.js` — `coreVersion()`, `MODULES_DIR`, `camel(key)`, `printHelp(out = console.log)`, `cmdUpgrade(_args, { log = console.log, errlog = console.error, gather = gatherUpgrade } = {})`, `evaluateUpgrade({ rows = [], errors = [], core } = {})`, `gatherUpgrade({ modulesDir = MODULES_DIR, core = coreVersion()`, `buildManifest(key, { core = coreVersion()`, `checkModulePublishability(key, { modulesDir = MODULES_DIR } = {})`, `claudeMdTemplate(key, manifest)` _(+8 more)_
-- `newcomer-floor.js` — `VALID_DISCIPLINES`, `computeTemplateDeficits(supply, templatesByDisc, floorDefaults, { only = null } = {})`, `templateFloor(template, discipline, floorDefaults)`, `buildProposalFromTemplate(template, seq, { discipline } = {})`, `HARD_MAX_MINUTES`, `parseSeq(ref, discipline, templateId)`, `SOURCE_TAG`, `loadTemplates(templatesPath)`, `nextSeq(existingRefs, discipline, templateId)`, `parseRef(ref)` _(+3 more)_
-- `newcomer-floor.test.js` — `test(name, fn)`, `deficitFor(rows, templateId)`
-- `next-number.js` — `padMig(n)`, `nextFree(numberSet, start = 1)`, `padAdr(n)`, `nextNumbers({ runGit = defaultRunGit, readDir = defaultReadDir } = {})`, `computeNextNumbers({ committedPaths = [], localPaths = [], startAdr = 1, startMigration = 1 } = {})`, `gitTreePaths(ref, dirs, runGit)`, `parseNumbers(basenames, re)`
-- `oauth-secret.js` — `webEnvPath(slug, { etcBase = ETC_BASE } = {})`, `provisionedEnvPrefix()`, `validateClientId(id)`, `validateClientSecret(secret)`, `CLIENT_ID_MIN_LEN`, `parseHealthzAuth(stdout)`, `SECRET_MIN_LEN`, `fillOAuthEnv(body, { prefix, clientId, clientSecret })`, `portFromEnv(body)`
-- `onboard.js` — `oauthAppInstructions(domain)`, `buildInitSpec(a = {})`, `healthzUrl(domain)`, `onboardPlan(mode = 'greenfield')`
-- `onboarding-analyze.js` — `acquireLock()`, `releaseLock()`, `analyzeOne(name, entry)`
-- `onboarding-config.js` — `encodeProjectPath(absPath)`, `ensureDir(dir)`, `SPOOL_DIR`, `windowDays()`, `CONFIG_DIR`, `CONSENT_PATH`, `listTranscripts(dir)`, `readConsent()`, `MANIFEST_PATH`, `needsSpool(manifest, file)` _(+7 more)_
-- `package-core.js` — `coreVersion()`, `octal(n, width)`, `TAR_ROOT`, `normalizeMode(mode)`, `ARTIFACT_NAME`, `MANIFEST_SCHEMA`, `processCoreFile({ pathRel, raw, rules, sensitiveLiterals, envSecrets })`, `sha256hex(buf)`, `buildPackageJson({ version, sourceDeps, sourceOverrides })`, `ustarHeader({ name, prefix = '', mode, size, typeflag })` _(+14 more)_
-- `provision.js` — `CONFIG`, `standaloneRoot(inst, { base = CONFIG.standaloneBase } = {})`, `MAX_INTENT_ATTEMPTS`, `checkDnsTokenScope(domain, { token = <redacted>, zoneOverride = process.env.CLOUDFLARE_…)`, `webEnvPath(inst, { etcBase = CONFIG.etcBase } = {})`, `cmdRunIntents(deps)`, `cmdStatus(deps)`, `coreVersionSafe()`, `dnsUpsertEnv(inst, { publicIp, zone, proxied = false } = {})`, `provisionInstance(inst, deps)` _(+26 more)_
-- `publish-manifest.js` — `isPublishable(relPath)`, `normalize(p)`, `matchesDeny(relPath)`, `PUBLISH_ALLOWLIST`, `PUBLISH_DENYLIST`, `PROTECTED_TOPOLOGY_EXCLUDE`, `INSTANCE_EXCLUDE`, `matchesAllow(relPath)`, `CONTENT_EXCLUDE`, `SENSITIVE_DOC_EXCLUDE` _(+1 more)_
-- `pulse.js` — `loadDeps()`, `parseThresholdHours(args)`, `postDiscordPing(text)`, `releaseStale({ thresholdHours, dryRun })`
-- `push-main.js` — `pushMain(extra = [])`
-- `read-session-export.js` — `render(data, opts)`, `reduce(records)`, `loadExport(zipPath)`, `openZip(filePath)`, `readEntry(fd, entry)`
-- `reauth.js` — `openInBrowser(url)`, `printGuidance({ opened })`
-- `recall.js` — `parseArgs(argv)`, `truncate(s, n)`
-- `render-ideas.js` — `fmtTimestamp(iso)`, `daysAgo(iso)`, `renderIdea(idea)`, `renderSection(heading, ideas, emptyMsg)`, `fetchAllIdeas()`, `partition(ideas)`, `render(ideas)`
-- `repo-metrics.js` — `gatherFileSizes()`, `summarizeSizes(sizes)`, `scanDeadCode()`, `scanBranchHygiene()`, `countConfirmedUnshipped(pool)`, `upsertSnapshot(pool, snap)`
-- `run-routine.js` — `VALID_MODES`, `parseRoutineFrontmatter(skillMd)`, `VALID_SINKS`, `tokenize(cmd)`
-- `run-unit-tests.js` — `discoverModuleTests({ modulesDir = MODULES_DIR, isEnabled = isModuleEnabled } = {})`
-- `sandbox-stage.js` — `stage({ taskId } = {}, deps = {})`, `BOX_ENV_PATH`, `BOX_SERVED_ROOT`, `resolvePreviewContext(deps = {})`, `computeTreeStamp(deps = {})`, `PREVIEWABLE_PATHSPECS`, `markerPath(deps = {})`, `previewUrl(deps = {})`, `runShipGate({ taskId, files, skipStage, tty, approved }, deps = {})`, `verifyServedFresh(deps = {})` _(+11 more)_
-- `search-ingest-db.js` — `buildRows({ sourceRef, title, body, minRank = 'xenos', ownerBuilderId = null, scrub = false })`, `requirePool()`, `SOURCES`, `recentCommitRows(limit = 80)`
-- `search-ingest-md.js` — `SENSITIVE_DOC_GLOBS`, `requirePool()`, `collectMarkdown(dir, root, out = [])`, `minRankForDoc(rel)`, `chunkFile(abs)`, `ingestFile(client, rows, sourceRef)`
-- `<redacted>.js` — `post(path, body)`
-- `<redacted>.js` — `post(path, body)`
-- `seed-module-upstreaming.js` — `findOrCreateGoal()`
-- `seed-provisioning-tasks.js` — `post(path, body)`
-- `seed-v2-world-tasks.js` — `withRetry(fn)`
-- `session-cost.js` — `addTiers(acc, t)`, `emptyTiers()`, `newestTranscriptFor(cwd)`, `priceTranscript(transcriptPath)`, `roundTiers(t)`, `listJsonlRecursive(dir)`, `looksLikeGraderTranscript(file)`, `priceSubagents(sessionDir)`, `addComponents(acc, components)`
-- `session-digest.js` — `parseHookInput(stdinRaw, opts = {})`
-- `session-eval.js` — `computeOverhead(detail)`, `evaluateSession(record)`, `detectFootguns(detail, overhead = {}, opts = {})`, `FINDING_TEMPLATES`, `findingsByBuilder(evaluated)`, `verdictFor(overheadRatio)`, `classifyTurn(turn, opts = {})`, `interpretCorpusSearch(count, opts = {})`, `summarizeSystemicFindings(evaluated, opts = {})`
-- `session.js` — `readArgv(argv)`, `builderLocalHour(timezone)`, `isOvernightHour(hour)`, `recentShipsAllOvernightSafe(me)`, `suggestDefaults(me)`, `ask(rl, q, fallback)`, `interactive(defaults)`, `callOptimizer({ timeBudgetMin, mode, parallel })`, `fitsMode(task, mode)`, `disjointTouches(a, b)` _(+5 more)_
-- `setup.js` — `dryRunStep(msg)`, `promptGeminiKey()`, `readLocalAnthropicAccount()`, `promptAnthropicLink()`, `promptDisciplines()`, `promptOnboardingConsent()`
-- `shell.js` — `repoRoot()`, `runLocal({ remoteCmd, log })`
-- `ship.js` — `buildSessionDigest(entries, opts = {})`, `computeChangedFiles(baseline)`, `sanitizeGitHubRefs(text)`, `computeGraderBaseline(claim)`, `recordUploadSkip(taskId, { code, reason }, opts = {})`, `runSubagentGrader({ task, valueSummary, baseline, changedFiles: precomputedChanged })`, `buildMergeArgv(branch, valueSummary)`, `gradeAndRecord({ taskId, task, summary, baseline, committedFiles })`, `snippetOf(text, extraSecrets, max = 160)`, `buildGradePayload(gradeResult, committedFiles = null)` _(+9 more)_
-- `smoke-gds.js` — `isLocalTarget(hostname)`, `probeListener(host, port, timeoutMs = 1500)`
-- `start.js` — `progressBar(percent, width = 10)`, `formatVersionsRow(progress)`, `formatCostRow(cost)`, `formatRecentRow({ recentShipped, inboxCount, blockerCount })`, `statusParts({ progress, recentShipped, inboxCount, blockerCount })`, `quietStatusLine(header)`, `estimateShort(t)`, `clip(s, n)`, `cell(s)`, `disciplineLabel(t)` _(+10 more)_
-- `status.js` — `parseArgs(argv)`, `renderStatusWidget(data, criterion)`, `renderStatusMarkdown(data, criterion)`
-- `triage.js` — `formatDevelopment(block)`, `loadDevelopment(path)`, `parseDevelopment(text)`, `resolveDevelopmentPath(argv = process.argv, env = process.env)`
-- `upgrade.js` — `parseArgs(argv)`, `CORE_PKG`, `ARTIFACT`, `npmInstall(instanceDir, run = spawnSync)`, `readInstalledCoreVersion(instanceDir, fsImpl = fs)`, `regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsImpl = fs)`, `vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs)`, `versionFromTgzPath(p)`, `gitTreeClean(instanceDir, run = spawnSync)`, `pollHealth(healthUrl, deps = {})` _(+8 more)_
-- `validate-design.js` — `readJson(filePath, label)`, `deepMerge(base, override)`, `isUri(s)`, `dirExists(p)`, `fileExists(p)`, `listDirs(p)`
-- `version-close.js` — `parseArgs(argv)`, `buildCommitMessage({ versionId, nextVersionId, shippedCount, carryCount })`, `buildManualSql({ versionId, versionName, nextVersionId, nextScopeDocPath, carryOverTasks, nextVersionExis…)`, `buildNextVersionStub({ nextVersionId, prevVersionId, carryOverTasks })`, `buildShippedArchive({ versionId, versionName, scopeDocPath, shippedTasks, originalScopeBody, shippedAt })`, `deriveNextScopePath(currentPath, nextVersionId)`, `deriveNextVersionId(currentId)`, `deriveShippedPath(currentPath, versionId)`
-<!-- END GENERATED REPO-MAP -->
-
-**See also.** `.claude/skills/builder-*` skill docs · [ADR 0061](../../docs/adr/<redacted>.md) · [docs/recipes/ops-gotchas.md](../../docs/recipes/ops-gotchas.md) · [src/bongos/](../../src/bongos/) (the server side these call).
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/scripts/gds/claim.js

@@ -143,7 +143,88 @@ function printClaimCard(task, widgetsEnabled = true) {
   } catch (_) { /* never block a claim on the card */ }
 }
 
-(async () => {
+// task 1476: render a failed claim as GUIDANCE, not a raw object dump. The API
+// returns the R01 error envelope (ADR 0116): { error: { code, message, details } }.
+// Older paths returned a flat { error: 'CODE', ...fields } shape. This normalizes
+// BOTH — without it `r.data.error` is now an object (never === a string), so every
+// branch below silently missed and the refusal printed as `[object Object]`. Pure
+// (no console / no process.exit) + exported so it can be unit-tested against the
+// real envelope shapes. Returns { lines, exit }.
+function formatClaimFailure(r, taskId) {
+  const lines = [];
+  const errRaw = r && r.data ? r.data.error : undefined;
+  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
+  const code = isEnvelope ? errRaw.code : errRaw;
+  const message = isEnvelope ? errRaw.message : undefined;
+  // Structured fields live under .details in the envelope; fall back to the
+  // top-level body for the legacy flat shape (so both keep working).
+  const d = { ...(r && r.data ? r.data : {}), ...((isEnvelope && errRaw.details) || {}) };
+
+  // #766: a generic onboarding stage gate (kept rendering cleanly, not as raw JSON).
+  if (code === 'stage_required') {
+    lines.push(`Task #${taskId} can't be claimed yet.`);
+    lines.push(`  ${d.what_to_do || `Clear "${d.required_stage_label || d.required_stage}" first.`}`);
+    return { lines, exit: 1 };
+  }
+  // task 1476 (the core case): a session may hold at most ONE active claim
+  // (task 1642 / ADR 0097). This is the most common refusal and previously fell
+  // straight through to the raw dump — the exact "reads like you can't hold more
+  // than one task" complaint from idea 218. Surface it as guidance AND teach how
+  // to parallelize (a separate worktree/session per task, or the hall bulk-claim).
+  if (code === 'session_already_has_active_claim' || code === 'session_claim_check_failed') {
+    const n = d.active_task_id;
+    lines.push(n
+      ? `This session already holds task #${n}${d.active_task_title ? `: ${d.active_task_title}` : ''}.`
+      : 'This session already holds an active claim.');
+    lines.push(`  ${d.what_to_do || (n
+      ? `Run /builder-ship ${n} (or /builder-release ${n}) first, or open a fresh worktree/session for this task.`
+      : 'Ship or release the in-flight claim, or start a fresh worktree/session.')}`);
+    lines.push('  One claim per session keeps each ship isolated (task 1642). To work tasks in PARALLEL, open a separate worktree/session per task — each holds its own single claim — or use the hall work board’s multi-select bulk-claim.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'newcomer_must_ship_first') {
+    lines.push(`Task #${taskId} can't be claimed yet — your first work isn't shipped.`);
+    lines.push(`  You're holding an active claim on #${d.active_task_id}: ${d.active_task_title}`);
+    lines.push(`  ${d.what_to_do || 'Ship or release the current claim first.'}`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'ALREADY_CLAIMED') {
+    lines.push(`Task #${taskId} was just claimed by another session. Try a different task.`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'MODULE_CONFLICT') {
+    lines.push(`Task #${taskId} has module_key='${d.module_key}', but another active claim already owns that module:`);
+    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
+    lines.push('Two tasks in the same module cannot run concurrently. Ship or release the in-flight claim first.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'TOUCHES_CONFLICT') {
+    lines.push(`Task #${taskId} touches files currently in flight on another claim:`);
+    for (const t of d.conflictTaskTitles || []) lines.push(`  - ${t}`);
+    lines.push('Pick a task with disjoint touches[], or run it in a separate session once the other ships.');
+    return { lines, exit: 1 };
+  }
+  if (code === 'TASK_NOT_READY') {
+    lines.push(`Task #${taskId} is not ready (current status: ${d.currentStatus}).`);
+    if (d.hint) lines.push(`  ${d.hint}`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'TASK_NOT_FOUND') {
+    lines.push(`Task #${taskId} not found — check the id (run /builder-start to list claimable tasks).`);
+    return { lines, exit: 1 };
+  }
+  if (code === 'DEPS_NOT_SHIPPED') {
+    lines.push(`Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
+    for (const dep of d.deps || []) lines.push(`  - #${dep.id}  [${dep.status}]  ${dep.title}`);
+    lines.push('Ship those first (or release them) and try again.');
+    return { lines, exit: 1 };
+  }
+  // Fallback — still readable: the message + code, never a raw [object Object].
+  lines.push(`Claim failed (${r ? r.status : '?'})${code ? ` [${code}]` : ''}${message ? `: ${message}` : ''}.`);
+  return { lines, exit: 1 };
+}
+
+async function main() {
   await requireSession();
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
@@ -283,51 +364,20 @@ function printClaimCard(task, widgetsEnabled = true) {
     printClaimCard(task, widgetsEnabled);
     return;
   }
-  // #766: the newcomer claim gate is now just the one-claim-at-a-time rule
-  // below. A generic stage_required (any future onboarding gate) still renders
-  // cleanly rather than as a raw API error.
-  if (r.data?.error === 'stage_required') {
-    console.error(`Task #${taskId} can't be claimed yet.`);
-    console.error(`  ${r.data.what_to_do || `Clear "${r.data.required_stage_label || r.data.required_stage}" first.`}`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'newcomer_must_ship_first') {
-    console.error(`Task #${taskId} can't be claimed yet — your first work isn't shipped.`);
-    console.error(`  You're holding an active claim on #${r.data.active_task_id}: ${r.data.active_task_title}`);
-    console.error(`  ${r.data.what_to_do || 'Ship or release the current claim first.'}`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'ALREADY_CLAIMED') {
-    console.error(`Task #${taskId} was just claimed by another session. Try a different task.`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'MODULE_CONFLICT') {
-    console.error(`Task #${taskId} has module_key='${r.data.module_key}', but another active claim already owns that module:`);
-    for (const t of r.data.conflictTaskTitles || []) console.error(`  - ${t}`);
-    console.error('Two tasks in the same module cannot run concurrently. Ship or release the in-flight claim first.');
-    process.exit(1);
-  }
-  if (r.data?.error === 'TOUCHES_CONFLICT') {
-    console.error(`Task #${taskId} touches files currently in flight on another claim:`);
-    for (const t of r.data.conflictTaskTitles || []) console.error(`  - ${t}`);
-    console.error('Pick a task with disjoint touches[].');
-    process.exit(1);
-  }
-  if (r.data?.error === 'TASK_NOT_READY') {
-    console.error(`Task #${taskId} is not ready (current status: ${r.data.currentStatus}).`);
-    process.exit(1);
-  }
-  if (r.data?.error === 'DEPS_NOT_SHIPPED') {
-    console.error(`Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
-    for (const d of r.data.deps || []) {
-      console.error(`  - #${d.id}  [${d.status}]  ${d.title}`);
-    }
-    console.error('Ship those first (or release them) and try again.');
+  // Any non-201 comes here. formatClaimFailure normalizes the R01 error envelope
+  // and renders the refusal as guidance (task 1476) — one place, unit-tested.
+  const failure = formatClaimFailure(r, taskId);
+  for (const line of failure.lines) console.error(line);
+  process.exit(failure.exit);
+}
+
+// Only auto-run when invoked directly (`node claim.js …`); a `require()` (the
+// unit test) just imports formatClaimFailure without executing the claim flow.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
     process.exit(1);
-  }
-  console.error(`Claim failed (${r.status}):`, r.data);
-  process.exit(1);
-})().catch((err) => {
-  console.error('fatal:', err);
-  process.exit(1);
-});
+  });
+}
+
+module.exports = { formatClaimFailure };