@bongos/core 1.19.618 → 1.19.619

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.618",
-  "core_contract": "1.19.618",
-  "source_commit": "1e344743e60d4921a3e5d73b32817388928e62a0",
+  "core_version": "1.19.619",
+  "core_contract": "1.19.619",
+  "source_commit": "b3a494e84958a264492cf55b3525d70680f7bbda",
   "source_ref": "HEAD",
-  "built_at": "2026-09-09T06:20:10.684Z",
+  "built_at": "2026-09-09T06:39:30.103Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 462,
+    "docs_redacted": 463,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2085,
+    "functional_verbatim": 2086,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2571,
-  "tree_sha256": "725579642848cf49184292a5271ac418e2ea288cac2beaaa80b49468625abc14",
+  "file_count": 2573,
+  "tree_sha256": "f0ad9c8d1e70405ab669163d2d2153cd7f6ae97a699036bb8e4278f1e3a435d5",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -1864,10 +1864,15 @@
       "mode": "0000644",
       "sha256": "cec61252a02d5da416c77088dbf2adf99c138cb10b654fa9fef949a0848a7964"
     },
+    {
+      "path": "docs/adr/0269-the-cli-session-store-is-host-keyed-at-a-fixed-anchor.md",
+      "mode": "0000644",
+      "sha256": "cc44045ea59f76dabc62fe43993ffab6004add88c7f6142bfe9215f7f2c33c99"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "7ab74c04d47b89328aedfe3fca3f2fd18c049c2fe5aa6c98bc1072d26bc12c68"
+      "sha256": "d660b4bc0bc3306f5fcf583118ca9149ba3deafe82dfe3894fe0b1c11b60cc2f"
     },
     {
       "path": "docs/api-reference.md",
@@ -2752,7 +2757,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "ec11a2ed9d50d4558aee3aca03f217dc0dde1f717859eb7a77c706535324fd32"
+      "sha256": "1fe02fc79e2952efb61450bbd45e6b09e41e8cf73453c6e0a2fbbf2944c1cdab"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7652,12 +7657,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "44a869111a69105fd5f1778cb749ad2c40a067db90fee6e6bbd19fcd76acd2ab"
+      "sha256": "41aca5e97b1cb72e389656c14ddd1bb35a3d5fdce8145f05e294c3fa3f52dc15"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b974dffa8dcde89358258e710e0f0b2c9fbd560ff5ba4c505cc57ced1809ab0e"
+      "sha256": "2084b4c59fd9b3857bb83b5a4198d43c308f0180edc0e21a698e4285809323fd"
     },
     {
       "path": "public-docs/index.html",
@@ -7862,7 +7867,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "81ad7fbc99f5c85219f1385cdd6e6954d27a0e2943f285676f060611a4878f4e"
+      "sha256": "de1cdede17761775722509b1e1edb4bb43fbbf336450556f22119b18b93e43d3"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -7922,7 +7927,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "44b8c997a25d9fcc68ba573d33391546ff98a871c7d99e9aa6d982c69a703824"
+      "sha256": "eaa4c3a172009d5ce825e528f5077a480e034658501a7d0c532a7807886beb9e"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8302,7 +8307,7 @@
     {
       "path": "scripts/gds/login.js",
       "mode": "0000644",
-      "sha256": "f16497d7eae23657e83f631b420f82a55ed8216480f3cd5488609d3b93274dee"
+      "sha256": "bdc7fcc0876a1185fb15339740793944c755d716d998bb68533ab3a721d39ab2"
     },
     {
       "path": "scripts/gds/main-audit.js",
@@ -9387,7 +9392,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8d4f44cdde9eecac4f1d8294dcd8d1f1283d536c2adab2d9e49b74c8891a40e8"
+      "sha256": "983d456cff4042137990a5baacb002919c3d213a33f663d6e8fcc7e9f5945ae6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9994,6 +9999,11 @@
       "mode": "0000644",
       "sha256": "a57516ed9e904cf1c86fe99688415f834dcae1a19f01b22e986f199fa5473258"
     },
+    {
+      "path": "tests/cli_sessions.mjs",
+      "mode": "0000644",
+      "sha256": "6ec406bf2bcbae261ab37ecaf820cfbe196c11007b0d8d3ee47cf21b6a3919ca"
+    },
     {
       "path": "tests/cli_surface.mjs",
       "mode": "0000644",

package/docs/adr/0269-the-cli-session-store-is-host-keyed-at-a-fixed-anchor.md

@@ -0,0 +1,104 @@
+# ADR 0269 — The CLI's session store is host-keyed at a fixed anchor; the per-brand file stays the active pointer
+
+- **Status:** accepted
+- **Date:** 2026-09-09
+- **Task:** [task 1003741](https://cloudbongos.com/builders#/task/1003741) (BONGOS-V2, goal 1000090 — *Working area 4, Bongos Core distribution*)
+- **Deciders:** Claude, under the Archon's standing scope
+- **Related:** [ADR 0258](<redacted>.md) (the public CLI, which is where this bites) · [ADR 0108](<redacted>.md) (each instance its own checkout) · [ADR 0083](<redacted>.md) (why the store directory may not be called `sessions`)
+
+---
+
+## Context
+
+The CLI resolved its session path from the **branding pack**, which is read out of whatever
+checkout the process happens to be standing in. That gave it exactly **one session slot**, and the
+slot moved depending on where you ran from:
+
+- **Standalone** — the public `@cloudbongos/cli`'s entire situation — no checkout means no brand,
+  so every instance shared `~/.config/cloudbongos/gds-session.json`. Signing into a second
+  instance **destroyed** the first. Measured on the published 0.1.1: `configHome()` resolved to
+  `<HOME>/.config/cloudbongos` whichever instance was named.
+- **In-repo** the brand resolved and the session landed in `~/.config/<slug>/`, where the
+  standalone CLI could never find it. `npx @cloudbongos/cli api GET /api/gds/me` from a bare
+  directory returned the cloudbongos.com builder while a valid hermeslines session sat on the same
+  machine.
+
+This was not theoretical. The owner's own config dir carries a hand-made
+`gds-session.<redacted>.bak.json`, alongside four more rescues of the same
+shape. For a newcomer with one project it is invisible; it bites precisely the people running more
+than one, which is the direction the platform is going.
+
+## Decision
+
+**Keep one session file per instance, keyed by the instance's host, under a FIXED anchor —
+`~/.config/<FALLBACK_DIR>/instances/<host>.json` — and leave the per-brand `gds-session.json`
+exactly where it is, as the ACTIVE pointer.**
+
+Four parts are load-bearing.
+
+### 1. The anchor is fixed, never brand-derived
+
+A brand-derived anchor is the bug. `sessionStoreDir()` is built from `FALLBACK_DIR` and must not
+read `configHome()`, `configDirName()` or the pack — so the same instance resolves to the same file
+whether you run from a checkout or from `npx`. A test asserts the function body names none of them,
+because "helpfully" routing it back through the brand would silently reinstate the split.
+
+It lives in `scripts/gds/cli-lib.js`, **not** `src/instance-config.js`. That module is generic
+config-path machinery shared with the server, and a CLI session store is not its concern; cli-lib
+already owns `SESSION_PATH` and `SESSION_READ_PATHS`, so one file now describes where a session
+lives. (The first cut put it in instance-config and the knip dead-code ratchet caught it: knip
+cannot trace that module's `require()` consumers, so every export it gains counts as dead — three
+new ones broke the gate. The right answer was better placement, not a bigger baseline.)
+
+### 2. The active pointer does not move
+
+Every existing reader — in-repo skills, the card hook, the dev box, `readSessionToken` — looks at
+`gds-session.json` in the configured dir. The store is **additive**: `saveSession` still writes that
+file last and unchanged. Moving it would have been the tidier design and would have broken every one
+of those readers at once, for no gain a builder can see.
+
+### 3. The OUTGOING session is archived before the incoming one lands
+
+Order matters, and this step is the one that is easy to omit. A session written *before* the store
+existed is not in it; without archiving the session being replaced, the very first login after
+upgrading would still lose it — the exact bug, surviving its own fix. Archiving is best-effort and
+never blocks a real sign-in.
+
+### 4. A stored token is verified before it is trusted
+
+`bongos login <url>` now switches back to an instance you are already signed into with no browser
+flow — but it calls `/api/gds/me` with the stored token first. Reinstating an expired or revoked
+token unchecked would leave a builder "signed in" to a session every later command then fails on.
+An unverified token falls straight through to the real device flow; `--force` signs in as somebody
+else.
+
+Because sessions are now kept rather than overwritten, `login` also names the other instances this
+machine knows and how to move between them — silence would leave them unfindable.
+
+## Consequences
+
+- Signing into a second instance is non-destructive, and moving between two projects costs no
+  browser round-trip.
+- Session files are `0600` in a `0700` directory: they hold bearer tokens.
+- An `api_base` that names no host is **not stored** rather than stored under a guessed name, so a
+  malformed or hostile base cannot write outside the store directory.
+- **The directory is `instances/`, not `sessions/`.** `sessions` is a live module key, and
+  ADR 0083 §Decision #4 forbids kernel machinery from naming one — `src/instance-config.js` is a
+  kernel file and the fitness gate caught it. `instances/` is also the truer name: one file per
+  instance is exactly what it holds.
+- A corrupt entry in the store is skipped, never fatal.
+- Still open: the store is per-machine and holds no notion of which instance a *directory* belongs
+  to, so running in an instance repo does not automatically select that instance — the active
+  pointer is whatever you last signed into. That is a smaller, separable question.
+
+## Rejected
+
+- **Moving the active pointer into the store** — breaks every existing reader at once for no
+  visible gain.
+- **One file holding a map of instances** — changes the on-disk format that in-repo readers,
+  hooks and the dev box all parse today.
+- **Keying the store under `configHome()`** — brand-derived, which is the bug being fixed.
+- **Restoring a stored session without verifying it** — hands the builder a dead session that
+  looks live.
+- **A new `bongos switch` verb** — `login <url>` is the command a builder already reaches for, and
+  the public CLI's verb surface is deliberately small (ADR 0258).

package/docs/adr/README.md

@@ -360,3 +360,4 @@ This keeps the decision history honest and traceable.
 | 0266 | [**The Board Room is its own surface, reachable by whoever may vote** ([task 1003734](https://cloudbongos.com/builders#/task/1003734) · goal 1000111 — *Working area 7, Government*, criterion `wa7-government`; owner decision 2026-09-08). The hall's only **upward-pointing** gate ([ADR 0175](<redacted>.md)) shipped as a hash tab inside `/government`, and two things about that did not survive inspection. **The nav never followed the page:** R16 correctly widened the PAGE gate from `government.manage` (archon) to `page.view.government` (metic+) when the page became three rooms — its own comment says *"the shell follows the widest legitimate audience"* — but `shell.js` still declares that item as label Permissions with gate archon, so a Metic who SITS on the board has no nav link at all and the only word in the nav is Permissions. Watch, Harbor, Gate and Sessions each own a nav item; the voting room was reachable only by knowing a URL fragment. **The surface was narrower than the franchise:** `board.vote.cast` floors at XENOS deliberately (`board.js:149` — the floor is low *so that widening the board works*) while the shell demands metic+, so the moment a constitution widens membership below Metic — the exact act [ADR 0175](<redacted>.md) §6 exists to make a CONFIG change — those members may vote by API and cannot load the page they would vote on, reintroducing the code-path change §6 removed. Decision: **its own page at `/board-room`, gated on the same atom the vote route checks.** The floor stays coarse — membership is still checked in-handler per item against that item's own snapshotted constitution — so a builder who clears the floor but sits on no board sees the room and no ballot, which is honest (§9 made the ballot open on purpose). **The migration is client-side because a fragment never reaches the server:** `#board-room` cannot be caught by any server route, so `government.js` redirects on load, preserving `?item=N` — recorded as a decision because adding a regex to `serve-internal.js` looks like the obvious fix and silently never fires. Three writers move (Discord `board-broadcast.js`, the `board_votes` need href, docs), and the redirect stays a release regardless because announcements already in channel history carry the old link forever. A **waiting-vote count** goes on the nav item: the data already exists (`boardVotesNeed` carries a live count pre-filtered to what the vote route would accept, served on `GET /me`), but `shell.js` has NO badge/bell/dot mechanism at all, so one is built once, generically, zero-is-silent, visible to exactly whoever the item is. Found while scoping and filed separately ([task 1003738](https://cloudbongos.com/builders#/task/1003738)): the hall renders needs as a SINGLE slot and `computeNeeds` sorts only by state with a stable sort, so registry order decides inside the `action_needed` bucket and `boardVotesNeed` sits fourth behind `artKeyNeed` — any builder with an unresolved image key never sees the board notice, which was live for this decision's own owner at the moment they asked for the bell. Rejected: a nav item merely deep-linking to the existing tab (cheaper, keeps the hash links free, but leaves the voting room inside a page whose gate answers a different question); a bell in the global header (a second inbox, needing its own read/unread and dismissal semantics); and a SOUND (`alert.wav`/`chime.wav` already ship, so it would be easy — it was not asked for).](<redacted>.md) | government / the board / hall nav |
 | 0267 | [**Unanimity, and the revise-and-re-sit loop** ([task 1003733](https://cloudbongos.com/builders#/task/1003733) · goal 1000111 — *Government*, owner decision 2026-09-08). A Full Idea is ratified by **unanimous** agreement from round one; a sitting that does not carry RETURNS to its author, who revises and re-sits it, unbounded, until the board is unanimous. `unanimous` joins `PASS_RULES` as a fourth answer on the axis these rules actually differ on — **what silence means**: it is two conditions, not one, because "nobody objected" is true of an empty room. Everyone who spoke must have said yes AND somebody must have spoken, so an unvoted sitting RETURNS, which is exactly what makes the clock the owner asked for safe under it ([ADR 0191](<redacted>.md) §4: a deadline may only be given to a rule whose expiry means return). **There is deliberately no membership denominator** — that is the whole difference from `majority`, and it is the owner's "silence does not block" as code: an absent member is not in the reckoning, so one yes out of four carries. The stated cost is that an attentive minority can ratify on a distracted board; the alternative is one person on holiday stopping the pipeline. Trigger changes follow from the rule: a single yes does NOT close it (a later member must still be able to object — the sitting runs its clock, full turnout closes early), while a reasoned objection closes it AT ONCE (no vote-changing in v1 fixes the outcome, and the author needs the feedback to revise). ADR 0191 §3's author rule rides both unchanged. **`BOARD_DEFAULTS` is NOT moved**: a fresh instance stays the day-one monarchy, because under any non-author-yes rule a solo founder can never ratify their own ideas (0191 §5) — adoption is a board amendment, and no env var can change a constitution. The revise-and-re-sit loop already existed (`POST /inbox/:id/resubmit` re-grades and re-fires the window hook); what the board owes it is now pinned by test — a return CLOSES the item so the next window may open, and pays nothing. Named limits: a zero-vote return carries no human objection (the author gets the mechanical weakest-section flag), and this changes nothing live until the separate defect where a ratified amendment does not survive to the next read is fixed.](<redacted>.md) | government / board room |
 | 0268 | [**The constitution comes from two roots, and a decision that did not take must say so** ([task 1003739](https://cloudbongos.com/builders#/task/1003739) · goal 1000111 — *Government*). On 2026-08-25 cloudbongos.com's board RATIFIED an amendment (rank:metic+ · consent · a 1440-minute sitting) and the constitution never changed — for two weeks `GET /government/constitution` answered the day-one monarchy with the passed amendment sitting in its own `history` array directly beneath the contradicting `board` block. Every sitting since was decided under a rule the board had voted to replace, and it silently un-shipped [ADR 0191](<redacted>.md) (majority) and would have un-shipped [ADR 0267](<redacted>.md) the same way. **Cause:** `modules/government/config.js` resolved BOTH its neutral starter and its instance pack from one `path.resolve(__dirname, '..', '..')`, under a comment saying the roots coincided *today* — true in a single checkout, false on a STANDALONE instance ([ADR 0108](<redacted>.md) §1), where the server runs `node_modules/@cloudbongos/core` with `WorkingDirectory=<instance repo>`. The neutral path stayed right (it really is core content); the INSTANCE path resolved inside the core package, so the host's own `config/government.json` was never read and `applyBoardAmendment` wrote the ratified amendment into `node_modules`, where the nightly core upgrade ([ADR 0161](<redacted>.md) cuts a release per merge) erased it within a day. **Nothing threw and nothing could have** — both paths exist, both are writable, and an absent instance pack is a legal state, so the read fell through to the neutral monarchy exactly as designed. `src/branding.js` had the pattern right three files away. **Fix:** neutral from `resolveCoreRoot()`, instance from `resolveInstanceRoot()`, reached through `src/module-api` — which had exposed NEITHER resolver, and that absence is precisely why the module re-derived the wrong one ([ADR 0083](<redacted>.md) forbids requiring a core internal). Resolved at load, not per call, because `resolveInstanceRoot()` falls back to `process.cwd()` and a lazy resolve would let a `chdir` move the constitution; `applyBoardAmendment` now mkdirs, since the write targets a directory the core does not own. Single-checkout behaviour is byte-identical, asserted rather than claimed. **The detector, which is the durable half:** `constitutionView` carries a `divergence` block comparing the newest PASSED amendment (sanitized as an apply would write it) field-by-field against what is in force, rendered above the hall's dials in words rather than config keys. It REPORTS and never HEALS — the instance pack is also the file a human editing the constitution touches, so a silent re-apply would revert a legitimate hand edit with no way to tell the two apart. A RETURNED amendment is never compared (that is what *returned* means). Does NOT put the 2026-08-25 amendment back in force — that is a board act. Sibling sweep RUN, not promised: one real hit filed as [task 1003745](https://cloudbongos.com/builders#/task/1003745) (quarantine.js's repo-containment refusal is blind to the instance repo).](<redacted>.md) | government / instance roots |
+| 0269 | [**The CLI session store is host-keyed at a fixed anchor; the per-brand file stays the active pointer** ([task 1003741](https://cloudbongos.com/builders#/task/1003741) · goal 1000090 — *Working area 4, Bongos Core distribution*). The CLI resolved its session path from the BRANDING PACK, read out of whatever checkout the process stood in — one slot, that moved. Standalone (the public CLI's whole situation) no checkout means no brand, so every instance shared `~/.config/cloudbongos/gds-session.json` and signing into a second DESTROYED the first; in-repo it landed in `~/.config/<slug>/` where the standalone CLI could never find it (`npx … api GET /me` from a bare dir returned the cloudbongos builder while a valid hermeslines session sat on the same machine). Not theoretical — the owner's config dir carries a hand-made `gds-session.<redacted>.bak.json` and four more of the same shape. **Decision: one file per instance keyed by HOST at a FIXED anchor (`~/.config/<FALLBACK_DIR>/instances/<host>.json`), with the per-brand `gds-session.json` left exactly where it is as the ACTIVE pointer.** Four load-bearing parts. (1) The anchor must never read `configHome()`/`configDirName()`/the pack — a test asserts the function body names none, since routing it back through the brand silently reinstates the split. (2) The active pointer does NOT move: every existing reader (in-repo skills, the card hook, the dev box, `readSessionToken`) looks there, and the store is purely additive. (3) The OUTGOING session is archived BEFORE the incoming one lands — a session written before the store existed is not in it, so without this the first login after upgrading still loses it, the bug surviving its own fix. (4) A stored token is VERIFIED against `/api/gds/me` before being reinstated; unverified falls through to the real device flow, `--force` signs in as somebody else. `login` also names the other instances and how to switch, since sessions are now kept rather than overwritten. Files 0600 in a 0700 dir; an `api_base` naming no host is not stored rather than stored under a guess, so nothing can write outside the store. The dir is `instances/` NOT `sessions/` — `sessions` is a live module key and [ADR 0083](<redacted>.md) §Decision #4 forbids kernel machinery naming one; the fitness gate caught it. Rejected: moving the active pointer (breaks every reader for no visible gain); one file holding a map (changes a format hooks and the dev box parse today); keying under `configHome()` (the bug); restoring without verifying (hands over a dead session that looks live); a new `bongos switch` verb (login is the command already reached for, and the public CLI's surface is deliberately small).](<redacted>.md) | cli / auth / distribution |

package/docs/module-api-changelog.md

@@ -1685,5 +1685,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.616 with no explicit bump. run 34317034024. (task 1002620)
   1.19.618 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.617 with no explicit bump. run 34318552090. (task 1002620)
+  1.19.619 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.618 with no explicit bump. run 34320024204. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.618",
+  "version": "1.19.619",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/build-cli-package.js

@@ -35,7 +35,7 @@ const REPO_ROOT = path.join(__dirname, '..', '..');
 
 // The package's OWN version — deliberately independent of the core's. The core moves many times
 // a day (CI auto-patch, ADR 0161); the CLI's public contract should not.
-const PACKAGE_VERSION = '0.1.2';
+const PACKAGE_VERSION = '0.1.3';
 const PACKAGE_NAME = '@cloudbongos/cli';
 
 // ── What the package carries ────────────────────────────────────────────────────────────────

package/scripts/gds/cli-lib.js

@@ -229,12 +229,117 @@ async function loadSession() {
   return null;
 }
 
+// ---- the shared session store (task 1003741, ADR 0269) ---------------------
+// ONE FILE PER INSTANCE, at a FIXED anchor — deliberately NOT configHome().
+//
+// WHY A FIXED ANCHOR. configHome() is brand-derived, and the brand is read out of whatever checkout
+// the process is standing in. That gave the CLI exactly one session slot, and the slot MOVED: run
+// standalone (the public @cloudbongos/cli's whole situation) the brand cannot resolve, so every
+// instance shared one gds-session.json and signing into a second DESTROYED the first; run from
+// inside an instance repo and the session landed in ~/.config/<slug>/ where the standalone CLI
+// could never find it. The owner's own config dir carries a hand-made `hermeslines-clobber` backup
+// from the first mode.
+//
+// WHY HERE AND NOT instance-config.js. That module is generic config-path machinery shared with the
+// server; a CLI session store is not its concern, and cli-lib already owns SESSION_PATH and
+// SESSION_READ_PATHS. Keeping the two together means one file describes where a session lives.
+function sessionStoreDir() {
+  // Directory name deliberately NOT 'sessions': that is a live module key, and ADR 0083
+  // §Decision #4 forbids naming one in shared machinery. 'instances' is the truer name anyway —
+  // one file per instance is exactly what this holds.
+  return path.join(os.homedir(), '.config', ic.FALLBACK_DIR, 'instances');
+}
+
+// The store's filename for an instance, derived from its api_base host. Returns null when the base
+// names no host — an unkeyable session is simply not stored, never stored under a guessed name.
+function sessionHostKey(apiBase) {
+  const raw = String(apiBase || '').trim();
+  if (!raw) return null;
+  let host = null;
+  try { host = new URL(raw).host; } catch (_) { host = null; }
+  if (!host) return null;
+  // Filename-safe, and collision-free for real hosts: ':' (a port) is the only character a valid
+  // host adds beyond the safe set, and it maps to '_' which cannot otherwise appear in one.
+  const safe = host.replace(/[^A-Za-z0-9._-]/g, '_');
+  return safe && safe !== '.' && safe !== '..' ? safe : null;
+}
+
+function sessionStorePath(apiBase) {
+  const key = sessionHostKey(apiBase);
+  return key ? path.join(sessionStoreDir(), `${key}.json`) : null;
+}
+
+// Write one session into the shared, host-keyed store. No-op when the session names no host —
+// an unkeyable session is skipped, never filed under a guessed name.
+async function writeSessionToStore(session) {
+  const target = session && sessionStorePath(session.api_base);
+  if (!target) return null;
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  await fsp.chmod(path.dirname(target), 0o700).catch(() => {});
+  await fsp.writeFile(target, JSON.stringify(session, null, 2), { mode: 0o600 });
+  return target;
+}
+
+// Every instance's session is kept, not just the last one (task 1003741).
+//
+// This used to write ONE file, so `bongos login <another-instance>` silently DESTROYED the session
+// you already had — the owner's own config dir carries a hand-made `hermeslines-clobber` backup
+// from exactly that. Three steps now, and the order matters:
+//
+//   1. archive the OUTGOING session first. That is what rescues a session written before the store
+//      existed: it was never in the store, so without this step the very first login after
+//      upgrading would still lose it.
+//   2. store the incoming one under its own host.
+//   3. write the ACTIVE pointer exactly where it has always gone, so every existing reader —
+//      in-repo skills, hooks, the dev box — behaves identically.
 async function saveSession(session) {
   const dir = path.dirname(SESSION_PATH);
   await fsp.mkdir(dir, { recursive: true });
+
+  try {
+    const prev = await loadSession();
+    const prevKey = prev && prev.token ? sessionHostKey(prev.api_base) : null;
+    const nextKey = sessionHostKey(session && session.api_base);
+    if (prevKey && prevKey !== nextKey) await writeSessionToStore(prev);
+  } catch (_) {
+    // Archiving is best-effort — a lost previous session must never block a real sign-in.
+  }
+
+  await writeSessionToStore(session).catch(() => null);
   await fsp.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
 }
 
+// The stored session for one instance, or null. Used by `bongos login` to switch back to an
+// instance you are already signed into without a fresh device flow.
+async function loadStoredSession(apiBase) {
+  const target = sessionStorePath(apiBase);
+  if (!target) return null;
+  return readSessionFile(target);
+}
+
+// Every instance this machine has a stored session for — so the CLI can say which one it is
+// targeting and what else it remembers. Sorted for a stable listing; never throws.
+function listStoredSessions() {
+  let names = [];
+  try { names = fs.readdirSync(sessionStoreDir()); } catch (_) { return []; }
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(sessionStoreDir(), name), 'utf8'));
+      if (j && j.token) {
+        out.push({
+          host: name.slice(0, -5),
+          api_base: j.api_base || null,
+          login: (j.builder && j.builder.github_login) || null,
+          instance: (j.instance && j.instance.name) || null,
+        });
+      }
+    } catch (_) { /* a corrupt entry is skipped, never fatal */ }
+  }
+  return out.sort((a, b) => a.host.localeCompare(b.host));
+}
+
 function loadSessionSync() {
   for (const p of SESSION_READ_PATHS) {
     if (!fs.existsSync(p)) continue;
@@ -1006,6 +1111,11 @@ module.exports = {
   loadSession,
   loadSessionSync,
   saveSession,
+  sessionStoreDir,
+  sessionHostKey,
+  sessionStorePath,
+  loadStoredSession,
+  listStoredSessions,
   arg,
   argText,
   hasFlag,

package/scripts/gds/login.js

@@ -22,7 +22,7 @@
 
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
-const { saveSession } = require('./cli-lib');
+const { saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
 const { branding } = require('../../src/branding');
 
 // --- pure helpers (unit-tested) ---------------------------------------------
@@ -204,6 +204,30 @@ async function main() {
   const idp = (man.data.auth && man.data.auth.idp) || null;
   log(`  Signing in to ${instanceName}${doorWord}${idp ? ' — via Cloud Bongos platform sign-in' : ''}`);
 
+  // 1b. Already signed in to THIS instance? Switch back instead of re-running a browser flow
+  //     (task 1003741). Sessions are now kept per instance, so moving between two projects should
+  //     cost nothing. The stored token is VERIFIED against the instance before it is trusted — an
+  //     expired or revoked one falls straight through to the real flow below.
+  if (!process.argv.includes('--force')) {
+    let stored = null;
+    try { stored = await loadStoredSession(base); } catch (_) { stored = null; }
+    if (stored && stored.token) {
+      const me = await fetchJson(`${base}/api/gds/me`, { headers: { Authorization: `Bearer ${stored.token}` } });
+      if (me.ok && me.data && me.data.builder) {
+        await saveSession({ ...stored, builder: me.data.builder, api_base: base,
+          instance: { name: instanceName, origin: base } });
+        const back = me.data.builder.github_login || me.data.builder.display_name || 'you';
+        log('');
+        log(`  ✓ Already signed in to ${instanceName} as ${back} — switched, no browser needed.`);
+        logOtherInstances(base, log);
+        log('  Next:  bongos start  (see what you can claim)');
+        log('  (Re-run with --force to sign in as somebody else.)');
+        return;
+      }
+      log('  Your saved session for this instance has expired — signing in again.');
+    }
+  }
+
   // 2. Device flow.
   let flow = await runDeviceFlow(base, { log, idp });
 
@@ -280,9 +304,23 @@ async function main() {
   const who = (flow.builder && (flow.builder.github_login || flow.builder.display_name)) || 'you';
   log('');
   log(`  ✓ Signed in to ${instanceName} as ${who}.`);
+  logOtherInstances(base, log);
   log('  Next:  bongos start  (see what you can claim)  ·  bongos code / bongos shell  (get on your dev box)');
 }
 
+// Name the OTHER instances this machine is signed into, and how to move between them (task
+// 1003741). Signing in used to destroy the session you already had, so there was never anything
+// to say; now that every instance is kept, silence would leave a builder unable to find them.
+function logOtherInstances(base, log) {
+  let others = [];
+  try {
+    others = listStoredSessions().filter((s) => s.api_base && s.api_base !== base);
+  } catch (_) { return; }
+  if (!others.length) return;
+  const names = others.map((s) => s.instance || s.host);
+  log(`  Also signed in to ${names.join(', ')} — switch with \`bongos login <url>\` (no browser needed).`);
+}
+
 if (require.main === module) {
   main().catch((err) => {
     console.error(`✖ ${err.message}`);
@@ -290,4 +328,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { normalizeInstanceBase, pollDecision, runDeviceFlow };
+module.exports = { normalizeInstanceBase, pollDecision, runDeviceFlow, logOtherInstances };

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.618'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.619'; // 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

@@ -0,0 +1,168 @@
+// tests/cli_sessions.mjs — one session slot became one per instance (task 1003741).
+//
+// THE BUG. The CLI resolved its session path from the BRANDING PACK, which is read out of whatever
+// checkout you happen to be standing in. That gave it exactly one slot, with two failure modes:
+//
+//   • standalone (the public @cloudbongos/cli's whole situation) the brand cannot resolve, so every
+//     instance shared ~/.config/cloudbongos/gds-session.json and `bongos login <other>` DESTROYED
+//     the session you already had. The owner's own config dir carries a hand-made
+//     `gds-session.hermeslines-clobber-2026-08-12.bak.json` from exactly this.
+//   • 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,
+// so every existing reader behaves identically — that back-compat is asserted here too.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+const ic  = require(path.join(REPO_ROOT, 'src', 'instance-config.js'));
+const lib = require(path.join(REPO_ROOT, 'scripts', 'gds', 'cli-lib.js'));
+
+// SESSION_PATH is frozen at module load from os.homedir(), so anything touching the real save path
+// runs in a child with its own HOME.
+function inSandbox(body) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-sess-'));
+  try {
+    const code = `const R=${JSON.stringify(REPO_ROOT)};
+      const lib=require(R+'/scripts/gds/cli-lib.js');
+      const ic=require(R+'/src/instance-config.js');
+      const fs=require('node:fs'), path=require('node:path');
+      (async()=>{ ${body} })().catch((e)=>{ console.error('ERR '+e.message); process.exit(1); });`;
+    const r = spawnSync(process.execPath, ['-e', code], { encoding: 'utf8', env: { ...process.env, HOME: home } });
+    return { home, out: `${r.stdout || ''}${r.stderr || ''}`, status: r.status };
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+}
+
+// ── 1. The key and the anchor ───────────────────────────────────────────────────────────────
+
+test('a session is keyed by the instance host', () => {
+  assert.equal(lib.sessionHostKey('https://cloudbongos.com'), 'cloudbongos.com');
+  assert.equal(lib.sessionHostKey('https://hermeslines-marketing.cloudbongos.com'), 'hermeslines-marketing.cloudbongos.com');
+  assert.equal(lib.sessionHostKey('http://localhost:3000'), 'localhost_3000');
+});
+
+test('an unkeyable base is stored nowhere, never under a guess', () => {
+  for (const bad of ['', null, undefined, 'not a url', '/etc/passwd', '../../escape']) {
+    assert.equal(lib.sessionHostKey(bad), null, `should refuse ${JSON.stringify(bad)}`);
+    assert.equal(lib.sessionStorePath(bad), null);
+  }
+});
+
+test('no host can escape the store directory', () => {
+  // The key becomes a filename, so a traversal in a hostile api_base must not reach outside.
+  for (const b of ['https://cloudbongos.com', 'http://localhost:3000']) {
+    const p = lib.sessionStorePath(b);
+    assert.equal(path.dirname(p), lib.sessionStoreDir(), `${b} escaped the store dir`);
+    assert.ok(!path.basename(p).includes('/') && !path.basename(p).includes('\\'));
+  }
+});
+
+test('the store anchor is FIXED, not brand-derived — that is the whole fix', () => {
+  // A brand-derived anchor is what split in-repo from standalone in the first place. If someone
+  // "helpfully" routes this through configHome() again, the two diverge and the bug is back.
+  assert.equal(lib.sessionStoreDir(), path.join(os.homedir(), '.config', ic.FALLBACK_DIR, 'instances'));
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'cli-lib.js'), 'utf8');
+  const body = src.slice(src.indexOf('function sessionStoreDir()'));
+  const fn = body.slice(0, body.indexOf('\n}') + 2);
+  assert.ok(!/configHome|configDirName|safeBrand/.test(fn), `sessionStoreDir must not read the brand:\n${fn}`);
+});
+
+// ── 2. A login never destroys another instance's session ────────────────────────────────────
+
+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');
+    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 });
+
+    await lib.saveSession({ token:'TOKEN-B', api_base:'https://b.example.com', builder:{github_login:'someone'} });
+
+    const rescued = await lib.loadStoredSession('https://a.example.com');
+    const stored  = await lib.loadStoredSession('https://b.example.com');
+    const pointer = JSON.parse(fs.readFileSync(active,'utf8'));
+    console.log(JSON.stringify({
+      firstSurvived: !!(rescued && rescued.token === 'TOKEN-A'),
+      secondStored:  !!(stored  && stored.token  === 'TOKEN-B'),
+      activeIsSecond: pointer.api_base === 'https://b.example.com',
+      hosts: lib.listStoredSessions().map(s => s.host),
+    }));`);
+  const r = JSON.parse(out.trim().split('\n').pop());
+  assert.equal(r.firstSurvived, true, 'the first instance\'s session was destroyed — the bug is back');
+  assert.equal(r.secondStored, true);
+  assert.equal(r.activeIsSecond, true, 'the active pointer must follow the newest sign-in');
+  assert.deepEqual(r.hosts, ['a.example.com', 'b.example.com']);
+});
+
+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
+  // 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')) }));`);
+  assert.equal(JSON.parse(out.trim().split('\n').pop()).wroteActive, true);
+});
+
+test('re-saving the SAME instance is idempotent and files nothing extra', () => {
+  const { out } = inSandbox(`
+    const s = { token:'T1', api_base:'https://a.example.com', builder:{github_login:'x'} };
+    await lib.saveSession(s);
+    await lib.saveSession({ ...s, token:'T2' });   // e.g. fetch-art-key rewriting one field
+    const cur = await lib.loadStoredSession('https://a.example.com');
+    console.log(JSON.stringify({ hosts: lib.listStoredSessions().map(h=>h.host), token: cur.token }));`);
+  const r = JSON.parse(out.trim().split('\n').pop());
+  assert.deepEqual(r.hosts, ['a.example.com'], 'a same-instance re-save must not fan out');
+  assert.equal(r.token, 'T2');
+});
+
+test('session files are owner-only', () => {
+  const { out } = inSandbox(`
+    await lib.saveSession({ token:'T', api_base:'https://a.example.com', builder:{github_login:'x'} });
+    const f = fs.statSync(lib.sessionStorePath('https://a.example.com')).mode & 0o777;
+    const d = fs.statSync(lib.sessionStoreDir()).mode & 0o777;
+    console.log(JSON.stringify({ file: f.toString(8), dir: d.toString(8) }));`);
+  const r = JSON.parse(out.trim().split('\n').pop());
+  assert.equal(r.file, '600', 'a session file holds a bearer token');
+  assert.equal(r.dir, '700');
+});
+
+test('a corrupt store entry is skipped, never fatal', () => {
+  const { out } = inSandbox(`
+    await lib.saveSession({ token:'T', api_base:'https://a.example.com', builder:{github_login:'x'} });
+    fs.writeFileSync(path.join(lib.sessionStoreDir(),'broken.json'), '{ not json');
+    console.log(JSON.stringify({ hosts: lib.listStoredSessions().map(h=>h.host) }));`);
+  assert.deepEqual(JSON.parse(out.trim().split('\n').pop()).hosts, ['a.example.com']);
+});
+
+// ── 3. Switching back ───────────────────────────────────────────────────────────────────────
+
+test('login VERIFIES a stored token before trusting it, and can be forced past', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'login.js'), 'utf8');
+  // A stored token may be expired or revoked. Reinstating one unchecked would leave the builder
+  // "signed in" to a session every later command then fails on.
+  assert.match(src, /loadStoredSession\(base\)/);
+  assert.match(src, /\/api\/gds\/me`, \{ headers: \{ Authorization/);
+  assert.match(src, /if \(me\.ok && me\.data && me\.data\.builder\)/);
+  assert.match(src, /--force/, 'there must be a way to sign in as somebody else');
+});
+
+test('login names the other instances and how to move between them', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'login.js'), 'utf8');
+  assert.match(src, /function logOtherInstances/);
+  assert.match(src, /Also signed in to/);
+  // Terminal reader: no slash command may appear in that guidance (task 1003730's rule).
+  const fnStart = src.indexOf('function logOtherInstances');
+  assert.ok(!/\/builder-/.test(src.slice(fnStart, fnStart + 700)), 'no slash command in terminal guidance');
+});