@bongos/core 1.19.665 → 1.19.667

package/scripts/gds/conductor-dispatch.js

@@ -44,6 +44,9 @@
 // 0 when a task was selected (a directive was emitted), 1 on a NO-GO / no work.
 
 const { execFileSync } = require('node:child_process');
+// basename(cwd) is the worktree name a claim is bound to (task 1003834) — the
+// same value claim.js records via --worktree.
+const path = require('node:path');
 const { cliClient } = require('./cli-lib');
 const grader = require('../../modules/grading/grader');
 // Phase 4.5: reuse the $0 deterministic autonomy precheck (the same gate the
@@ -195,11 +198,58 @@ function diffStatsSince(base, untracked) {
   };
 }
 
+// THE WORKTREE IS THE ANSWER, when there is one (task 1003834).
+//
+// A claim BINDS to a dedicated worktree — one claim per session, one worktree
+// per claim (task 1642, ADR 0097) — and `claim.js --worktree` records that
+// worktree's leaf-folder name on the claim row, which is exactly
+// `path.basename(process.cwd())`. So when this dispatch runs inside a claimed
+// worktree there is no inference to do: that worktree's claim IS the task being
+// worked on. Everything below it is a heuristic; this is a fact.
+//
+// Claims from before the column existed carry a null worktree_name and are
+// simply not matched here — the heuristic still covers them.
+function claimForWorktree(claims, worktreeName) {
+  if (!Array.isArray(claims) || !worktreeName) return null;
+  return claims.find((c) => c && c.worktree_name && c.worktree_name === worktreeName) || null;
+}
+
 // Pick the active claim whose touches[] best overlap the changed files — the
 // claim the current diff most plausibly belongs to. With multiple (possibly
 // stale) claims, blindly taking claims[0] grades the diff against the wrong
 // task: the Phase 4 dogfood's Narc FAILed because it graded Conductor code
 // against an unrelated stale offsite-backup claim. Best-overlap fixes that.
+//
+// SPECIFICITY, NOT VOLUME (task 1003834). A raw count of matched files rewards
+// BREADTH, so the more honestly a claim declares its touches[] the more likely
+// it loses. Observed 2026-09-10: reviewing task 1003829's diff, its own claim
+// declared three exact files (`modules/hall-ui/public/studio.{js,html,css}`) and
+// could therefore score at most 3, while a concurrent rename claim declaring
+// `scripts/gds/`, `src/bongos/`, `modules/`, `clients/` matched most of the
+// same diff and won — so the reviewer was briefed on an unrelated task. A
+// pattern like `modules/` covers almost any diff in this repo and must not
+// out-vote an exact path.
+//
+// So each matched file is worth the SPECIFICITY of the pattern that matched it:
+// its path-segment depth, plus a bonus when the pattern is the file itself.
+// Volume still counts — a genuinely broad claim matching fifty files beats a
+// narrow one sharing a single file — but depth breaks the tie the right way.
+function patternWeight(pattern, file) {
+  const p = String(pattern || '');
+  const depth = p.replace(/\/+$/, '').split('/').filter(Boolean).length;
+  return depth + (p === file ? EXACT_MATCH_BONUS : 0);
+}
+const EXACT_MATCH_BONUS = 1;
+
+function claimOverlapScore(claim, files) {
+  let score = 0;
+  for (const f of files) {
+    const hit = matchOne(f, (claim && claim.touches) || []);
+    if (hit !== null) score += patternWeight(hit, f);
+  }
+  return score;
+}
+
 function bestMatchingClaim(claims, changedFiles) {
   if (!Array.isArray(claims) || claims.length === 0) return null;
   const files = Array.isArray(changedFiles) ? changedFiles : [];
@@ -207,12 +257,29 @@ function bestMatchingClaim(claims, changedFiles) {
   let bestScore = -1;
   for (const c of claims) {
     // Use the canonical matcher; ties keep the earlier claim (strict >).
-    const score = files.filter((f) => matchOne(f, c.touches || []) !== null).length;
+    const score = claimOverlapScore(c, files);
     if (score > bestScore) { bestScore = score; best = c; }
   }
   return best;
 }
 
+// The claim this diff belongs to, and HOW that was decided — because the two
+// answers deserve very different trust. 'worktree' is a fact; 'overlap' is a
+// guess, and a guess that must be visible so a reader can discount a review
+// that argues from the brief rather than from the diff.
+//
+// A claim with an EMPTY touches[] scores zero against any diff, which is most
+// tasks in this repo — another reason the worktree signal leads rather than
+// merely breaking ties.
+function attributeClaim(claims, changedFiles, worktreeName) {
+  const byWorktree = claimForWorktree(claims, worktreeName);
+  if (byWorktree) return { claim: byWorktree, signal: 'worktree', worktree: worktreeName };
+  const byOverlap = bestMatchingClaim(claims, changedFiles);
+  if (!byOverlap) return { claim: null, signal: 'none', worktree: worktreeName || null };
+  const score = claimOverlapScore(byOverlap, Array.isArray(changedFiles) ? changedFiles : []);
+  return { claim: byOverlap, signal: score > 0 ? 'overlap' : 'fallback', worktree: worktreeName || null };
+}
+
 // --- task context (best-effort) ---
 // Workers grade a diff against a task. For a mid-flight review we use the
 // best-matching active claim's task; otherwise we synthesize a minimal
@@ -224,7 +291,12 @@ async function resolveTaskContext(changedFiles) {
     if (me.ok) {
       const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
       if (claims.length > 0) {
-        const c = bestMatchingClaim(claims, changedFiles);
+        // The worktree this dispatch was invoked in decides it when it can
+        // (task 1003834); the touches[] heuristic is the fallback, and which
+        // one answered is reported to the reader rather than hidden.
+        const attribution = attributeClaim(claims, changedFiles, path.basename(process.cwd()));
+        const c = attribution.claim;
+        if (!c) throw new Error('no claim attributed');
         // Pull the full description for richer context (best-effort). Coerce
         // task_id to an integer before interpolating it into the URL path —
         // it's a trusted internal value, but a guard costs nothing and closes
@@ -243,6 +315,11 @@ async function resolveTaskContext(changedFiles) {
           description: description || '(no description fetched — mid-flight review; judge the diff on its own merits)',
           kind: 'unclassified',
           version_id: c.version_id,
+          // How this task was attributed to this diff, carried so the header can
+          // say it (task 1003834). 'worktree' is a fact; anything else is a
+          // guess the reader should weigh.
+          attribution: attribution.signal,
+          claim_count: claims.length,
         };
       }
     }
@@ -257,6 +334,22 @@ async function resolveTaskContext(changedFiles) {
 
 // --- rendering ---
 
+// Say how the task context was chosen, but only when saying it changes what a
+// reader should do (task 1003834). Attribution by WORKTREE is certain, and a
+// single claim leaves nothing to confuse, so both stay silent. A guess made
+// while several claims were open is the case that misled a reader before, and
+// it says so out loud.
+function attributionNote(task) {
+  if (!task || !task.id) return '';
+  const n = Number(task.claim_count) || 0;
+  if (task.attribution === 'worktree' || n < 2) return '';
+  const how = task.attribution === 'overlap'
+    ? 'guessed from touches[] overlap'
+    : 'no signal at all — first claim taken';
+  return `\n   ⚠ attribution: ${how}, across ${n} open claims. This worktree is bound to no claim, so the brief`
+    + '\n     may belong to different work: weigh findings about the FILES, discount findings about intent.';
+}
+
 function renderWorker(w) {
   const lines = [];
   const status = w.error ? `ERROR (${w.error})` : w.verdict.toUpperCase();
@@ -382,7 +475,7 @@ async function main() {
   const routeRank = grader.routeRankPrePass(files);
 
   console.log(`🎼 Conductor dispatch → ${kinds.join(', ')}  (model=${model}, ${files.length} changed file(s), base=${base.slice(0, 8)})`);
-  console.log(`   task context: ${task.id ? '#' + task.id + ' ' + task.title : task.title}`);
+  console.log(`   task context: ${task.id ? '#' + task.id + ' ' + task.title : task.title}${attributionNote(task)}`);
   if (routeRank) console.log('   + deterministic route-rank check (route file in diff)');
   console.log('');
 
@@ -423,4 +516,9 @@ if (require.main === module) {
   });
 }
 
-module.exports = { pickSpecialists, bestMatchingClaim, selectAutonomousDispatch, autoDispatch };
+module.exports = {
+  pickSpecialists, bestMatchingClaim, selectAutonomousDispatch, autoDispatch,
+  // task 1003834 — the attribution layer, exported so its decisions are pinned
+  // rather than only observed through a dispatch run.
+  claimForWorktree, claimOverlapScore, attributeClaim, attributionNote,
+};

package/scripts/gds/fetch-art-key.js

@@ -5,7 +5,7 @@
 // The art pipeline (modules/art-pipeline/pipeline/gen_api.py) runs LOCALLY and can't call the API
 // per generation, so SessionStart runs this once: GET /api/gds/me/art-key and,
 // based on the builder's live rank, write or remove the `shared_gemini_api_key`
-// field in ~/.config/otb/gds-session.json. gen_api.py reads that field as a
+// field in ~/.config/otb/bongos-session.json. gen_api.py reads that field as a
 // fallback BELOW the builder's own key — so own key always wins, and a newcomer
 // with no own key falls back to the shared one we pay for.
 //

package/scripts/gds/init.js

@@ -254,7 +254,7 @@ function buildBrandingConfig(spec) {
     // Every instance gets its OWN session/config dir (task 1002626). Without
     // this, instance-config.js falls back to the shared 'cloudbongos' dir, so
     // every un-branded instance on a machine reads/writes the SAME
-    // ~/.config/cloudbongos/gds-session.json — signing in to one silently
+    // ~/.config/cloudbongos/bongos-session.json — signing in to one silently
     // evicts the CLI session of every other, including the hub. Same slug
     // family as the package name + provisioning slug.
     configDir: spec.configDir ? String(spec.configDir).trim() : slugify(productName, 'instance'),

package/scripts/gds/paste-token.js

@@ -2,7 +2,7 @@
 // scripts/gds/paste-token.js — V3.R91 / #401.
 //
 // Accept a CLI bearer minted by the builders' hall (POST /api/gds/auth/cli-token/issue)
-// and write it into ~/.config/otb/gds-session.json. Preserves any existing
+// and write it into ~/.config/otb/bongos-session.json. Preserves any existing
 // fields (notably gemini_api_key registered via /builder-setup) so a token
 // paste never silently un-registers a builder's Gemini key.
 //
@@ -24,10 +24,13 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const ic = require('../../src/instance-config');
+// Destructured for the same reason as cli-lib: a namespace-only `ic.X` read is
+// invisible to knip, which then calls the export dead code.
+const { SESSION_FILENAMES, readSessionConfigSync } = require('../../src/instance-config');
 
 // WRITE the session to the configured instance dir (OTB → ~/.config/otb,
 // unchanged; a fresh instance → its neutral dir). R61 / task 1200.
-const SESSION_PATH = ic.configPath('gds-session.json');
+const SESSION_PATH = ic.configPath(SESSION_FILENAMES[0]);
 // env → the EXISTING session's api_base → this instance's branding default.
 // On a RE-auth a session file already exists, and its api_base is the best signal
 // of which instance the builder is on — this file used to hardcode the founder
@@ -91,9 +94,11 @@ async function main() {
   //    way, treat as a fresh write.
   let existing = {};
   try {
-    // Read across config dirs (configured + legacy otb) so a session written the
-    // old way still has its fields preserved on the next paste.
-    const raw = ic.readConfigFileSync('gds-session.json');
+    // Read across config dirs (configured + legacy otb) AND across every accepted
+    // filename, so a session written the old way still has its fields preserved on
+    // the next paste. This is the re-auth path: a miss here does not fail loudly,
+    // it silently drops the builder's gemini_api_key (task 1003704).
+    const raw = readSessionConfigSync();
     if (raw) existing = JSON.parse(raw);
   } catch (_) {
     /* fresh session; nothing to merge */

package/scripts/gds/portability-smoke-memory.sh

@@ -95,7 +95,7 @@ if [ -z "$REMOTE" ]; then bad "could not resolve origin remote for fresh-clone t
     # --- 2. the fresh clone leaks NO secrets / NO builder memory ------------
     LEAKS=0
     CFG_DIR=$(gds_node "process.stdout.write(require('../../src/instance-config').configDirName())" 2>/dev/null) || CFG_DIR=""
-    for p in ".env.local" "spaces.env" ".config/${CFG_DIR:-otb}/gds-session.json" "etc/${CFG_DIR:-otb}"; do
+    for p in ".env.local" "spaces.env" ".config/${CFG_DIR:-otb}/bongos-session.json" ".config/${CFG_DIR:-otb}/gds-session.json" "etc/${CFG_DIR:-otb}"; do
       if [ -e "$TMP/clone/$p" ]; then echo "  leak: $p present in clone"; LEAKS=$((LEAKS+1)); fi
     done
     # builder_memory is server-side only — no memory dir should ship in-repo

package/scripts/gds/setup.js

@@ -14,7 +14,7 @@
 //
 // Prints the user_code and verification_uri, then polls until the user
 // completes auth (or expires/denies). On success, writes
-// ~/.config/otb/gds-session.json (resolved from os.homedir(), so this works for
+// ~/.config/otb/bongos-session.json (resolved from os.homedir(), so this works for
 // any user on any machine; no path is hardcoded to a particular developer's
 // home directory) and prints the builder profile.
 
@@ -49,7 +49,7 @@ function dryRunStep(msg) {
 // pixel-art pipeline (gen_api.py). V3.R11 (#91): each builder pays their own
 // Gemini bill, so spend is attributable per-builder on the public dashboard.
 //
-// Stored as gemini_api_key in ~/.config/otb/gds-session.json (mode 600, same
+// Stored as gemini_api_key in ~/.config/otb/bongos-session.json (mode 600, same
 // file as the GitHub session token). gen_api.py reads this location before
 // falling back to ~/.config/otb/env or .env.local.
 //
@@ -476,7 +476,7 @@ async function main() {
 
       // A valid session already exists on this machine. Don't silently adopt
       // it. The session file is a single global path
-      // (~/.config/otb/gds-session.json), so a second person setting up on a
+      // (~/.config/otb/bongos-session.json), so a second person setting up on a
       // shared device — or the same person onboarding a different account,
       // e.g. for testing — would otherwise be invisibly bound to whoever set
       // up first. On an interactive shell, confirm before continuing; the gate
@@ -513,7 +513,7 @@ async function main() {
         console.log('');
         console.log('Setting up as a different builder — the saved session will be replaced once you finish signing in...');
         // Fall through to the Device Flow below, which calls saveSession() and
-        // overwrites ~/.config/otb/gds-session.json with the new identity.
+        // overwrites ~/.config/otb/bongos-session.json with the new identity.
       } else {
         console.log(`Continuing as ${who}.`);
         process.exit(0);

package/scripts/gds/smoke-write.sh

@@ -2,7 +2,8 @@
 # GDS write-path smoke test (production). Renamed from PMS in V3.R01.
 #
 # Exercises the full claim → ship round-trip against the live API:
-#   1. Read session token from ~/.config/otb/gds-session.json (or legacy pms-session.json)
+#   1. Read session token from ~/.config/otb/bongos-session.json (or the legacy
+#      gds-session.json / pms-session.json names, all still accepted on read)
 #   2. POST /api/gds/tasks → create a synthetic task titled '__smoke__ <ts>'
 #   3. POST /api/gds/claims → claim it
 #   4. POST /api/gds/claims/:id/resolve outcome=shipped

package/scripts/hall-preview/refresh-fixtures.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // scripts/hall-preview/refresh-fixtures.js — snapshot real API responses into
 // the preview harness's fixtures/ (task 2167). Run with a valid GDS CLI session
-// (~/.config/otb/gds-session.json) whenever the fixtures drift from the live
+// (~/.config/otb/bongos-session.json) whenever the fixtures drift from the live
 // API shapes:  node scripts/hall-preview/refresh-fixtures.js
 //
 // Read-only: GETs only. Endpoints that 403/404 for the caller's rank are

package/src/bongos/auth.js

@@ -62,6 +62,15 @@ const { addDiscordGuildMember, buildDiscordAuthorizeUrl, discordAuthorizeUrl, di
 
 const MAX_AUTH_TOKEN_CANDIDATES = 6;
 
+// Every name the session cookie has ever had, NEWEST FIRST. A rename APPENDS to
+// this list, it never replaces: at the instant the new code deploys, every
+// signed-in browser is still sending the OLD name, so dropping a name signs that
+// builder out mid-session. `pms_session` predates the gds_ rename and is still
+// in the wild, so the list is three long, not two (task 1003704). The server
+// SETS only the head; routes/auth.js clears the tail on the next write. Part 4
+// (task 1003706) retires the tail behind a test of its absence.
+const SESSION_COOKIE_NAMES = Object.freeze(['bongos_session', 'gds_session', 'pms_session']);
+
 function extractTokens(req) {
   const out = [];
   const push = (t) => {
@@ -70,18 +79,30 @@ function extractTokens(req) {
   const auth = req.headers['authorization'] || '';
   const m = /^Bearer\s+([a-zA-Z0-9]+)$/.exec(auth);
   if (m) push(m[1]);
-  // Cookie parsing: minimal, no dep. Prefer new name, fall back to legacy.
+  // Cookie parsing: minimal, no dep. Group by NAME, then emit in
+  // SESSION_COOKIE_NAMES order, so a browser carrying both a fresh
+  // `bongos_session` and a stale `gds_session` tries the fresh name first
+  // instead of depending on header order.
+  //
+  // EVERY value under a name is kept, in header order — never just the first.
+  // One name can legitimately appear TWICE: a stale host-only cookie plus the
+  // current apex-scoped one (#851, #726/#734). Returning only the first let the
+  // stale duplicate shadow the live session and 401 the builder, so the grouping
+  // must be name → LIST. push() dedupes identical values and caps the total.
   const cookieHeader = req.headers['cookie'] || '';
-  const legacy = [];
+  const found = new Map();
   for (const part of cookieHeader.split(';')) {
     const idx = part.indexOf('=');
     if (idx < 0) continue;
     const k = part.slice(0, idx).trim();
     const v = part.slice(idx + 1).trim();
-    if (k === 'gds_session' && v) push(v);
-    else if (k === 'pms_session' && v) legacy.push(v);
+    if (!v || !SESSION_COOKIE_NAMES.includes(k)) continue;
+    if (!found.has(k)) found.set(k, []);
+    found.get(k).push(v);
+  }
+  for (const name of SESSION_COOKIE_NAMES) {
+    for (const v of found.get(name) || []) push(v);
   }
-  for (const v of legacy) push(v);
   return out;
 }
 
@@ -887,6 +908,7 @@ module.exports = {
   completeDeviceExchange,
   membershipKind,
   extractTokens,
+  SESSION_COOKIE_NAMES,
   resolveSession,
   allowBoxScope,
   sessionScope,

package/src/bongos/middleware/rate-limit.js

@@ -122,6 +122,19 @@ function pruneAndCount(bucket, now, windowMs) {
   return bucket.length;
 }
 
+// Every name the session cookie has ever had, newest first, precompiled.
+//
+// One regex PER NAME rather than a single alternation: an alternation matches in
+// COOKIE-HEADER order, not preference order, so a browser mid-rename — carrying
+// both the new and the old name — would key on whichever the browser happened to
+// send first. Precompiled at module load because this runs on every request.
+//
+// Deliberately duplicated from SESSION_COOKIE_NAMES in src/bongos/auth.js rather
+// than imported: this middleware is dependency-free by design. The copy is pinned
+// against the real list by tests/session_rename_fallback.mjs (task 1003704).
+const SESSION_COOKIE_RES = ['bongos_session', 'gds_session', 'pms_session']
+  .map((n) => new RegExp('(?:^|;\\s*)' + n + '=([^;]+)'));
+
 function extractSessionKey(req) {
   // Bearer token first (CLI flow); cookie second (web flow). We use the
   // token AS-IS as the limiter key — it's already opaque + cheap to hash to
@@ -132,8 +145,10 @@ function extractSessionKey(req) {
   }
   const cookie = req.headers && req.headers.cookie;
   if (cookie) {
-    const m = /(?:^|;\s*)(?:gds_session|pms_session)=([^;]+)/.exec(cookie);
-    if (m) return 'c:' + m[1];
+    for (const re of SESSION_COOKIE_RES) {
+      const m = re.exec(cookie);
+      if (m) return 'c:' + m[1];
+    }
   }
   return null;
 }

package/src/bongos/routes/auth.js

@@ -204,12 +204,41 @@ function renderAccessPendingPage(login, startHref) {
 </body></html>`;
 }
 
-// Cookie names. The web flow writes the new `gds_session` (+ `gds_oauth_state`)
-// names; both flows accept either the new or the legacy `pms_session` /
-// `pms_oauth_state` cookies on read so a builder mid-flow doesn't have to
-// re-auth at the rename rollout.
-const SESSION_COOKIE = 'gds_session';
-const SESSION_COOKIE_LEGACY = 'pms_session';
+// Cookie names. The web flow writes the new `bongos_session` (+ `gds_oauth_state`)
+// names; both flows accept every older session name on read so a builder
+// mid-flow doesn't have to re-auth at the rename rollout.
+//
+// The session read-list is NOT declared here. It lives in ../auth.js as
+// SESSION_COOKIE_NAMES, because the request-level token extractor there has to
+// accept exactly the names this router sets and clears: two lists would drift,
+// and the only symptom of the drift is a builder being silently signed out.
+// Head = the one name we SET. Tail = the names we accept and clear on write.
+const SESSION_COOKIE = auth.SESSION_COOKIE_NAMES[0];
+const SESSION_COOKIE_OLD = auth.SESSION_COOKIE_NAMES.slice(1);
+
+// The session token off a request's cookies, trying each accepted name newest
+// first. Replaces the hand-written `parseCookie(new) || parseCookie(legacy)`
+// pairs, which accepted only two of the three live names.
+function sessionCookieToken(req) {
+  for (const name of auth.SESSION_COOKIE_NAMES) {
+    const v = parseCookie(req, name);
+    if (v) return v;
+  }
+  return null;
+}
+
+// Clear every SUPERSEDED session cookie, in both the host-only and apex-scoped
+// forms (a clearCookie only matches the cookie whose domain attribute it names).
+// Called wherever we set the current cookie, so a browser that arrived with a
+// `gds_session` leaves holding only `bongos_session` — otherwise the stale name
+// lingers until its own expiry and every later request carries two tokens.
+function clearSupersededSessionCookies(req, res) {
+  const domainOpts = sessionCookieDomainOpts(req);
+  for (const name of SESSION_COOKIE_OLD) {
+    res.clearCookie(name);
+    if (domainOpts.domain) res.clearCookie(name, domainOpts);
+  }
+}
 const STATE_COOKIE = 'gds_oauth_state';
 const STATE_COOKIE_LEGACY = 'pms_oauth_state';
 const DISCORD_STATE_COOKIE = 'gds_discord_state';
@@ -650,6 +679,10 @@ module.exports = function buildAuthRouter() {
         // amazonprimea.com + builders. + status. (#726); host-only elsewhere.
         ...sessionCookieDomainOpts(req),
       });
+      // A browser arriving with an older session name must not keep it: two
+      // session cookies means every later request carries two candidate tokens,
+      // and the stale one outlives this sign-in.
+      clearSupersededSessionCookies(req, res);
       // Persist the wizard's repo token (task 1002099 / ADR 0143): encrypted at rest,
       // short-TTL, keyed to the builder — the repo picker/creator reads it back over
       // the next few minutes. Gated on secret-box being configured (upsertGithubToken
@@ -916,19 +949,17 @@ module.exports = function buildAuthRouter() {
   // rank: any-builder — own session, no rank gate (a Xenos can log themselves out).
   router.post('/auth/logout', auth.requireBuilder, async (req, res) => {
     const token = (req.headers['authorization'] || '').replace(/^Bearer\s+/, '')
-      || parseCookie(req, SESSION_COOKIE)
-      || parseCookie(req, SESSION_COOKIE_LEGACY);
+      || sessionCookieToken(req);
     if (token) await db.revokeSession(token);
     // Clear BOTH the host-only form (older sessions) and the apex-scoped form
     // (#726) — a clearCookie only matches the cookie whose domain attribute it
     // names, so sign-out on a production host must target the apex domain too.
     res.clearCookie(SESSION_COOKIE);
-    res.clearCookie(SESSION_COOKIE_LEGACY);
     const domainOpts = sessionCookieDomainOpts(req);
-    if (domainOpts.domain) {
-      res.clearCookie(SESSION_COOKIE, domainOpts);
-      res.clearCookie(SESSION_COOKIE_LEGACY, domainOpts);
-    }
+    if (domainOpts.domain) res.clearCookie(SESSION_COOKIE, domainOpts);
+    // …and every superseded name, or a sign-out leaves the older cookie behind
+    // and the next request re-authenticates on it.
+    clearSupersededSessionCookies(req, res);
     // Federated single-logout (ADR 0144, task 1002238): announce the logout so the
     // hub (platform-identity, enabled only on cloudbongos.com) can fan a signed
     // back-channel logout out to every federated project this builder entered. A
@@ -1002,7 +1033,7 @@ module.exports = function buildAuthRouter() {
   // (a leaked CLI token shouldn't be able to extend its own lifetime; the
   // httpOnly browser cookie is the harder-to-steal credential).
   router.post('/auth/cli-token/issue', auth.requireBuilder, async (req, res) => {
-    const cookieToken = parseCookie(req, SESSION_COOKIE) || parseCookie(req, SESSION_COOKIE_LEGACY);
+    const cookieToken = sessionCookieToken(req);
     if (!cookieToken) {
       // Name the instance's own sign-in host (from the branding pack), not a
       // hardcoded "amazonprimea.com" (ADR 0062 §3/§5).
@@ -1144,7 +1175,7 @@ module.exports = function buildAuthRouter() {
   // CLI bearer must not be able to approve pairings and mint itself siblings;
   // only the httpOnly browser cookie — the click in the hall — can.
   router.post('/auth/app-pair/approve', auth.requireBuilder, async (req, res) => {
-    const cookieToken = parseCookie(req, SESSION_COOKIE) || parseCookie(req, SESSION_COOKIE_LEGACY);
+    const cookieToken = sessionCookieToken(req);
     if (!cookieToken) {
       return res.fail('cookie_required', { status: 403, message: 'Pairings are approved from an authenticated browser session in the builders’ hall, not from a bearer token.' });
     }

package/src/instance-config.js

@@ -104,7 +104,7 @@ function resolveApiBase({ session, env = process.env, b = safeBrand() } = {}) {
   let s = session;
   if (s === undefined) {
     try {
-      const raw = readConfigFileSync('gds-session.json', { b });
+      const raw = readSessionConfigSync({ b });
       s = raw ? JSON.parse(raw) : null;
     } catch (_) {
       s = null; // unreadable/corrupt session must never break base resolution
@@ -135,8 +135,32 @@ function configPath(name, b = safeBrand()) {
   return path.join(configHome(b), name);
 }
 
+// Every name the CLI session file has ever had, NEWEST FIRST.
+//
+// Lives here, not in cli-lib.js which owns the session STORE, because this module
+// is the lowest one that has to read the file (resolveApiBase below) and cli-lib
+// imports this — so this is the only place both can share. A rename APPENDS a
+// name; dropping one signs out every builder machine and every live dev box at
+// once. Part 4 (task 1003706) retires the tail. (task 1003704)
+const SESSION_FILENAMES = Object.freeze([
+  'bongos-session.json',
+  'gds-session.json',
+  'pms-session.json',
+]);
+
+// The first readable session file across every config dir and every accepted
+// name, or null. FILENAME-major: the newest name in ANY read dir beats an older
+// name in the configured dir, which is the precedence a rename wants.
+function readSessionConfigSync({ b = safeBrand() } = {}) {
+  for (const name of SESSION_FILENAMES) {
+    const raw = readConfigFileSync(name, { b });
+    if (raw) return raw;
+  }
+  return null;
+}
+
 // Every candidate path for a named config file, configured dir first then legacy
-// dirs — for read-with-fallback (the gds-session.json / cost_ledger pattern).
+// dirs — for read-with-fallback (the session-file / cost_ledger pattern).
 function configReadPaths(name, b = safeBrand()) {
   return configReadDirs(b).map((d) => path.join(d, name));
 }
@@ -298,6 +322,8 @@ module.exports = {
   configPath,
   configReadPaths,
   readConfigFileSync,
+  SESSION_FILENAMES,
+  readSessionConfigSync,
   resolveEnv,
   resolveCoreRoot,
   resolveInstanceRoot,

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.665'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.667'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/cli_sessions.mjs

@@ -10,7 +10,8 @@
 //   • in-repo the session landed in ~/.config/<slug>/ where the standalone CLI could never find it.
 //
 // The store is keyed by instance host at a FIXED anchor, so the same instance resolves to the same
-// file from either direction. The per-brand gds-session.json stays the ACTIVE pointer, untouched,
+// file from either direction. The per-brand session file (SESSION_FILENAMES[0]) stays the ACTIVE
+// pointer, untouched,
 // so every existing reader behaves identically — that back-compat is asserted here too.
 
 import test from 'node:test';
@@ -157,7 +158,7 @@ test('the sandbox actually relocates os.homedir() — on THIS platform', () => {
 });
 
 test('a session store path resolved inside the sandbox stays inside it', () => {
-  const { out, status, home } = inSandbox(`console.log(JSON.stringify({ p: ic.configPath('gds-session.json'), d: lib.sessionStoreDir() }));`);
+  const { out, status, home } = inSandbox(`console.log(JSON.stringify({ p: ic.configPath(ic.SESSION_FILENAMES[0]), d: lib.sessionStoreDir() }));`);
   assert.equal(status, 0, `sandbox child failed: ${out}`);
   const { p, d } = JSON.parse(out.trim().split('\n').pop());
   assert.ok(p.startsWith(home), `the active session pointer resolved OUTSIDE the sandbox: ${p}`);
@@ -176,7 +177,7 @@ test('sandboxEnv overrides every home variable a platform might read', () => {
 test('signing into a second instance PRESERVES the first — including one written before the store existed', () => {
   const { out } = inSandbox(`
     // A session from before this feature: an active pointer, nothing in the store.
-    const active = ic.configPath('gds-session.json');
+    const active = ic.configPath(ic.SESSION_FILENAMES[0]);
     fs.mkdirSync(path.dirname(active), { recursive: true });
     fs.writeFileSync(active, JSON.stringify({ token:'TOKEN-A', api_base:'https://a.example.com',
       builder:{github_login:'someone'} }), { mode: 0o600 });
@@ -200,11 +201,11 @@ test('signing into a second instance PRESERVES the first — including one writt
 });
 
 test('the ACTIVE pointer still lands exactly where every existing reader looks', () => {
-  // In-repo skills, hooks and the dev box all read gds-session.json in the configured dir. The
+  // In-repo skills, hooks and the dev box all read the active session file in the configured dir. The
   // store is additive; if this moved, every one of them would silently stop finding a session.
   const { out } = inSandbox(`
     await lib.saveSession({ token:'T', api_base:'https://a.example.com', builder:{github_login:'x'} });
-    console.log(JSON.stringify({ wroteActive: fs.existsSync(ic.configPath('gds-session.json')) }));`);
+    console.log(JSON.stringify({ wroteActive: fs.existsSync(ic.configPath(ic.SESSION_FILENAMES[0])) }));`);
   assert.equal(JSON.parse(out.trim().split('\n').pop()).wroteActive, true);
 });