@bongos/core 1.19.618 → 1.19.620

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.620",
+  "core_contract": "1.19.620",
+  "source_commit": "7e8c8d38a15a24575258eda58829e9120d9ed55f",
   "source_ref": "HEAD",
-  "built_at": "2026-09-09T06:20:10.684Z",
+  "built_at": "2026-09-09T06:53:24.739Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 462,
+    "docs_redacted": 464,
     "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": 2574,
+  "tree_sha256": "8c5d0cef512909da1de5dd90510ca13a74737c8d3b80ec2d8e0a7fc5e1d9451d",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -397,7 +397,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "877ca14cd017c1392fcc5206c2f3603fb24becdc32670aa1e2ad0de9d930dfca"
+      "sha256": "07caf5c1db2cfd16c92713891055b477982aef4dd847af67042b742293e6a9ce"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1864,20 +1864,25 @@
       "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",
       "mode": "0000644",
-      "sha256": "b430ecad01c7458dc893c11d976d3ae35f2dd5b8310e451a38af387908f64659"
+      "sha256": "8adebe11d51d4bbce7e5acacc003ce923e820f0d8532541d3f5a74ed07570ce8"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "81485c0440de636511dc9ee723e18af89f313b175ea626723d0beeeed31bba2f"
+      "sha256": "2059cb9b02d6a20e4b1297c866db9f717bb3514ec49ab2454c776c806775d3da"
     },
     {
       "path": "docs/architecture.md",
@@ -2752,7 +2757,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "ec11a2ed9d50d4558aee3aca03f217dc0dde1f717859eb7a77c706535324fd32"
+      "sha256": "6b3c53cfb31b4bf6963f740bb386c24059ef370af8927b0ececde09e062fff33"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2949,6 +2954,11 @@
       "mode": "0000644",
       "sha256": "f6d2bb1da53f03f54080b8e0aec9f63390d3343c32917b64225ac47ae4ba7b42"
     },
+    {
+      "path": "docs/recipes/reranking-a-goals-board.md",
+      "mode": "0000644",
+      "sha256": "ecd8986c5e4831db53a803dae625e5f1b898b711911e8e6f1c4f1b79a98cbfe8"
+    },
     {
       "path": "docs/recipes/search-index-ingestion.md",
       "mode": "0000644",
@@ -5587,7 +5597,7 @@
     {
       "path": "modules/lifecycle/db-tasks.js",
       "mode": "0000644",
-      "sha256": "e978cadb879a57d8d7e3bb84657a787ac7e83125666fa2d31013ac64b37b0d7a"
+      "sha256": "15c9efea1fb5a8187fe5bae756777ebeb1a214e47e0434d7a8adeb156bd1e093"
     },
     {
       "path": "modules/lifecycle/db-versions.js",
@@ -5597,7 +5607,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "b4b2d6d7890ec67e52fc00718a814bf01a64f4432ed7380a175dca8bc794b0e4"
+      "sha256": "af6af95c05aa6cc76c0e49cb0a99bfb24685b3efb66df0f90883c3301baeede0"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5827,7 +5837,7 @@
     {
       "path": "modules/lifecycle/routes/task-write-routes.js",
       "mode": "0000644",
-      "sha256": "87843c62d8ce7af3d7d6aa5772791bd52823afe5f2c4b9b7427ca9f00dd14c11"
+      "sha256": "cc86b3c05885c733cc28ba6e41f1b08cb8f0fe652e3181c1c88be4caabf18d61"
     },
     {
       "path": "modules/lifecycle/routes/tasks.js",
@@ -7652,12 +7662,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "44a869111a69105fd5f1778cb749ad2c40a067db90fee6e6bbd19fcd76acd2ab"
+      "sha256": "401ae455c8e67d7bf4d622ef7e93fce203948868ae3b07de9770e6d90607249f"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b974dffa8dcde89358258e710e0f0b2c9fbd560ff5ba4c505cc57ced1809ab0e"
+      "sha256": "f6c0e1047dcef4fe6e429e149606d521e0d196ff748bcdeb6de6e1c63d2a60ab"
     },
     {
       "path": "public-docs/index.html",
@@ -7862,7 +7872,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "81ad7fbc99f5c85219f1385cdd6e6954d27a0e2943f285676f060611a4878f4e"
+      "sha256": "de1cdede17761775722509b1e1edb4bb43fbbf336450556f22119b18b93e43d3"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -7922,7 +7932,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "44b8c997a25d9fcc68ba573d33391546ff98a871c7d99e9aa6d982c69a703824"
+      "sha256": "eaa4c3a172009d5ce825e528f5077a480e034658501a7d0c532a7807886beb9e"
     },
     {
       "path": "scripts/gds/client-baseurl-guard.js",
@@ -8302,7 +8312,7 @@
     {
       "path": "scripts/gds/login.js",
       "mode": "0000644",
-      "sha256": "f16497d7eae23657e83f631b420f82a55ed8216480f3cd5488609d3b93274dee"
+      "sha256": "bdc7fcc0876a1185fb15339740793944c755d716d998bb68533ab3a721d39ab2"
     },
     {
       "path": "scripts/gds/main-audit.js",
@@ -9387,7 +9397,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8d4f44cdde9eecac4f1d8294dcd8d1f1283d536c2adab2d9e49b74c8891a40e8"
+      "sha256": "d2b45162be47422810ab7a05c42c9926520df6c1c5ab7e7274386c5a25eb07a3"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9994,6 +10004,11 @@
       "mode": "0000644",
       "sha256": "a57516ed9e904cf1c86fe99688415f834dcae1a19f01b22e986f199fa5473258"
     },
+    {
+      "path": "tests/cli_sessions.mjs",
+      "mode": "0000644",
+      "sha256": "6ec406bf2bcbae261ab37ecaf820cfbe196c11007b0d8d3ee47cf21b6a3919ca"
+    },
     {
       "path": "tests/cli_surface.mjs",
       "mode": "0000644",
@@ -11422,7 +11437,7 @@
     {
       "path": "tests/migration_allocation.mjs",
       "mode": "0000644",
-      "sha256": "e2f03570b76b4d5af7af3c87a2a4989827eb71d1b50c92ab546a456e85c4024e"
+      "sha256": "0d1bc299555d98aa2ad8571e0a5a185776ca727f95577c3308a7e4b36efbfd97"
     },
     {
       "path": "tests/migration_namespace.mjs",
@@ -11662,7 +11677,7 @@
     {
       "path": "tests/patch_gate_ordering.mjs",
       "mode": "0000644",
-      "sha256": "b0690cf28c30bfa4ef1ecc4ceffa7d4be1666dbb09a6605ceb02cc057d2a9cc4"
+      "sha256": "27a3b5023b6857f3f53734966bc7685757383f2b8dadfa3c0bf1aca2e7db5517"
     },
     {
       "path": "tests/path_match.mjs",

package/clients/bongos-client/index.d.ts

@@ -182,7 +182,7 @@ export interface PatchProvisioningInstancesIdDetailResponse { ok: boolean; descr
 export interface PatchProvisioningInstancesIdSettingsResponse { ok: boolean; saved: unknown; planet: unknown; push: unknown }
 export interface PatchTaskRecommendationsIdRequest { status: "declined" | "withdrawn" }
 export interface PatchTaskRecommendationsIdResponse { ok: boolean; recommendation: unknown }
-export interface PatchTasksIdRequest { kind?: string; discipline?: string; requires_rank?: string; module_key?: string; goal_id?: number; parent_task_id?: StringifiableId; parallel_safe?: unknown; newcomer_friendly?: boolean; xenos_claimable?: boolean; security_sensitive?: boolean; automation_tag?: string; needs_migration?: boolean; description?: string; title?: string; status?: unknown }
+export interface PatchTasksIdRequest { kind?: string; discipline?: string; requires_rank?: string; module_key?: string; goal_id?: number; parent_task_id?: StringifiableId; parallel_safe?: unknown; newcomer_friendly?: boolean; xenos_claimable?: boolean; security_sensitive?: boolean; automation_tag?: string; needs_migration?: boolean; description?: string; title?: string; priority?: unknown; status?: unknown }
 export interface PostAccessRequestsInviteRequest { github_login: string }
 export interface PostAccessRequestsInviteResponse { ok: boolean; already_invited?: boolean; github_login?: unknown; request?: unknown }
 export interface PostAccessRequestsRequest { github_login: string; display_name?: string; note?: string }

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/api/openapi.json

@@ -18880,6 +18880,7 @@
             "minLength": 1,
             "maxLength": 200
           },
+          "priority": {},
           "status": {}
         },
         "additionalProperties": false

package/docs/api-reference.md

@@ -591,7 +591,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/tasks` | `any-builder` | — |  |
 | POST | `/api/bongos/tasks` | `metic+archon` | `version_id`, `title`, `description`, `status`, `touches`, `est_minutes`, `est_cost_usd`, `manual_degree`, `priority`, `automation_tag`, `credits_reward`, `source`, `source_ref`, `value_summary`, `kind`, `discipline`, `parallel_safe`, `newcomer_friendly`, `security_sensitive`, `requires_rank`, `auto_detect_touches`, `criterion_ids`, `module_key`, `goal_id` | Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090 (owner decision 2026-06-26): a Metic who can run idea-triage may … |
 | GET | `/api/bongos/tasks/:id` | `any-builder` | — | single-task read; preserved per CRITICAL §4 (supervisor hot path). |
-| PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag`, `needs_migration`, `description`, `title`, `status` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
+| PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag`, `needs_migration`, `description`, `title`, `priority`, `status` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
 | POST | `/api/bongos/tasks/:id/abandon` | `metic+archon` | `reason` | POST /tasks/:id/abandon — terminal "retire this task" transition (task 987). |
 | POST | `/api/bongos/tasks/:id/attest-gate` | `any-builder` | `head_sha` | POST /tasks/:id/attest-gate — body: { head_sha }. |
 | POST | `/api/bongos/tasks/:id/confirm` | `any-builder` | `verified` |  |

package/docs/module-api-changelog.md

@@ -1685,5 +1685,9 @@ 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)
+  1.19.620 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.619 with no explicit bump. run 34321089991. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/reranking-a-goals-board.md

@@ -0,0 +1,93 @@
+# Re-ranking a goal's board — the needed-vs-nice rubric
+
+> Written at task 1003750 (2026-09-09), the first whole-goal re-rank the project ran. Read this before re-ranking any board: the rubric is here so it is applied consistently rather than re-invented per session, and the mechanics section records the two traps that made the first pass cost more than the analysis did.
+
+`tasks.priority` is an integer **1–5, where 1 is most urgent**. Two surfaces read it and both take low-as-urgent:
+
+- version progress is weighted `6 - COALESCE(t.priority, 5)` (`migrations/003_pms.sql`), so an unset priority weighs the same as a P5;
+- the session optimizer orders claimable work `priority ASC NULLS LAST` (`src/bongos/optimizer.js`).
+
+So priority is not a label. It steers what every builder is offered first, and an unset one is not neutral — it sits at the bottom.
+
+## The rubric
+
+The axis is **needed vs nice-to-have**, which is deliberately *not* "is this still true" (that is a relevance audit — see [the goal 1000090 one](../audits/<redacted>.md)) and not "how big is it". A task can be tiny and P1, or large and P5.
+
+| Tier | Test | What earns it |
+|---|---|---|
+| **P1** | Bleeding now | A live path is broken, or **reports success falsely**, or finished paid work is being lost. Fix regardless of what else is queued. |
+| **P2** | Needed, not bleeding | A defect with a workaround that taxes every session; a keystone freezing other tasks; a cost window closing on its own. |
+| **P3** | Should do | Real reliability or legibility gain, no forcing function. |
+| **P4** | Nice to have | Consistency, doc nits, cleanups, and work blocked behind a decision nobody has made yet. |
+| **P5** | Nice to have / speculative | Large refactors and research with no forcing function. Also: tasks whose premise is contested and needs an owner call — park them here rather than guessing. |
+
+Three rules that did the most work in practice:
+
+1. **"Reports success falsely" outranks "is broken".** A broken thing gets noticed; a lying one does not. Three of the five P1s on goal 1000090 were only P1 because a tool printed a success it had not verified.
+2. **Read the body, not the title.** [Task 1001479](https://cloudbongos.com/builders#/task/1001479) sat at P1 from June while its own description read *"Trivial, low priority."* Titles drift from bodies; bodies drift from reality.
+3. **A blocked task is not urgent, but its keystone is.** Where five tasks waited on one unwritten ADR, the ADR moved up and the five moved down. Prioritizing the blocked five would have produced five claims that cannot start.
+
+**Sanity check before writing:** a tier list that is mostly P1 has ranked nothing. Aim for a distribution that narrows sharply at the top — goal 1000090's 63 open rows came out 5 / 8 / 27 / 17 / 6.
+
+## Mechanics
+
+**Now:** `PATCH /api/bongos/tasks/:id` accepts `priority` (integer 1–5, or `null` to clear). It did not before task 1003750 — priority was write-once at create and immutable at every rank, which is why the first re-rank had to be SQL.
+
+```bash
+echo '{"priority":2}' > /tmp/p.json
+node scripts/gds/api.js PATCH /api/gds/tasks/1002884 --body-file /tmp/p.json
+```
+
+Two things to know before you batch this:
+
+- **Bulk PATCH is rate-limited to roughly 30 per minute.** A 63-row pass needs pacing, not a tight loop.
+- **`priority` is not settable at the same time as `status`.** Status moves only through its own transition routes (`/promote`, `/confirm`, …); a body carrying `status` is refused outright with `status_not_patchable`.
+
+**The trap that outlives this recipe: a P1 in `backlog` is inert.** Priority orders the *claimable* feed, and `backlog` rows are not in it. On goal 1000090, four of the five P1s were in `backlog`, so the re-rank changed nothing about what builders saw until they were promoted. **Always re-check status after re-ranking** — `/promote` the ones that should be live, and use [`/backlog-review`](../../.claude/skills/backlog-review/SKILL.md) to walk what is waiting on a person.
+
+And before promoting anything into the claimable pool, **check `requires_rank`.** New tasks floor at `xenos` and the auto-derivation has been inert since ADR 0049, so a task about the deploy or authority surface is newcomer-claimable unless someone raised it by hand. Promoting a P1 without checking that is how a deploy-authority design lands in the newcomer queue.
+
+### When the API cannot reach the live board
+
+Core reaches a live instance only through a release plus a pin move (gate 3, [`core-release-pipeline.md`](core-release-pipeline.md)) — so a *newly shipped* route is not callable against production for as long as the pin lags. In that window the board is only reachable by SQL on the control-plane box, and an agent cannot run it (the permission classifier blocks a mutating `sudo -u lars` over ssh, by design — see [task 1003159](https://cloudbongos.com/builders#/task/1003159), which exists to close exactly this gap).
+
+Generate the statements from a checked map rather than typing ids, keep it in one transaction, and **write the revert first** — the prior values are only recoverable if you captured them before the write:
+
+```bash
+node scripts/gds/api.js GET '/api/gds/tasks?goal_id=<goal>&limit=200' --quiet > before.json
+```
+
+Then group the ids by target tier and emit one `UPDATE` per tier, guarded to the goal and to open statuses so a concurrent ship cannot be clobbered:
+
+```sql
+BEGIN;
+UPDATE tasks SET priority=1, updated_at=now()
+ WHERE goal_id=<goal> AND status IN ('ready','backlog') AND id IN (<ids>);
+-- one statement per tier
+COMMIT;
+```
+
+Build the revert from `before.json` the same way, grouping by each row's *original* priority (including a `NULL` group — unset is a real prior value and restoring it as 5 is not the same thing). Verify every id in the map appears in the emitted SQL before running anything; a silently dropped id leaves a row at a priority nobody chose.
+
+## The goal 1000090 pass, as a worked example
+
+All 63 open rows of [goal 1000090](https://cloudbongos.com/builders#/goal/1000090) (working area 4 — Bongos Core distribution), 2026-09-09. 48 of 63 changed; 24 had no priority at all.
+
+| Tier | Tasks |
+|---|---|
+| **P1** | 1002708, 1002714, 1002884, 1003159, 1003200 |
+| **P2** | 1001431, 1002204, 1002205, 1002863, 1002869, 1003526, 1003537, 1003742 |
+| **P3** | 1000380, 1000861, 1000862, 1001219, 1001429, 1001433, 1001436, 1001930, 1002206, 1002531, 1002532, 1002583, 1002617, 1002622, 1002669, 1002707, 1002854, 1002880, 1002900, 1002903, 1003499, 1003502, 1003564, 1003625, 1003647, 1003648, 1003658 |
+| **P4** | 1001311, 1001441, 1001479, 1001641, 1001927, 1001929, 1002049, 1002208, 1002209, 1002842, 1002844, 1002879, 1002882, 1003563, 1003573, 1003651, 1003657 |
+| **P5** | 1002406, 1002413, 1002839, 1002840, 1002841, 1002843 |
+
+The five P1s all said the same thing, which is the finding the exercise produced: **shipped work does not reliably reach users, and the tooling misreports it.** Task 1002884 health-checked the old still-running process and printed "✓ upgrade complete" while live served the previous version; 1002708 and 1002714 leave the pin uncommitted so the next commit silently downgrades live; 1003159 is the owner having no deploy control at all; 1003200 is that nothing checks whether a claimed artifact ever reached a remote, found after three paid tasks turned out to exist only on laptops.
+
+1002406 and 1002413 sit at P5 as *contested*, not as unimportant — ADR 0062 §7 and task 1003740 now point against their premise, so they need an owner's kill-or-re-argue rather than a builder's guess.
+
+## Related
+
+- [`docs/audits/<redacted>.md`](../audits/<redacted>.md) — the relevance pass on the same board. Run relevance first: there is no point ranking a task whose premise is gone.
+- `/backlog-review` — walks `status='backlog'`, which is where a re-rank's P1s often turn out to be hiding.
+- `/priority-session` — reweights the **idea inbox**, not tasks, and writes no priorities. It ends in a recommendation; this recipe is the write.
+- [`core-release-pipeline.md`](core-release-pipeline.md) — why a shipped route is not a live route.

package/modules/lifecycle/db-tasks.js

@@ -272,7 +272,7 @@ async function findTaskBySourceRef({ source, sourceRef } = {}, deps = {}) {
 
 const TASK_SETTER_COLUMNS = new Set([
   'kind', 'discipline', 'newcomer_friendly', 'security_sensitive', 'parallel_safe', 'automation_tag',
-  'needs_migration', 'module_key', 'description', 'title',
+  'needs_migration', 'module_key', 'description', 'title', 'priority',
 ]);
 
 async function updateTaskColumn(id, column, value) {
@@ -339,6 +339,14 @@ async function updateTaskDescription(id, description) { return updateTaskColumn(
 // 1002791) was permanent. Same permission, same audit trail as the body.
 async function updateTaskTitle(id, title) { return updateTaskColumn(id, 'title', title); }
 
+// task 1003750: the third write-once planning field, and the one that steers
+// what gets claimed — version progress is weighted `6 - COALESCE(priority, 5)`
+// and the session optimizer orders claimable work by `priority ASC NULLS LAST`.
+// Set at create and then immutable at every rank, so re-ranking a goal's board
+// (needed vs nice-to-have) had no route at all and had to be done as raw SQL.
+// 1 = most urgent, 5 = least; null clears it back to unset (weighted as 5).
+async function updateTaskPriority(id, priority) { return updateTaskColumn(id, 'priority', priority); }
+
 
 async function updateTaskDiscipline(id, discipline) { return updateTaskColumn(id, 'discipline', discipline); }
 
@@ -936,6 +944,7 @@ module.exports = {
   updateTaskNeedsMigration,
   updateTaskNewcomerFriendly,
   updateTaskParallelSafe,
+  updateTaskPriority,
   updateTaskRequiresRank,
   updateTaskSecuritySensitive,
   updateTaskStatus,

package/modules/lifecycle/db.js

@@ -127,6 +127,7 @@ const {
   updateTaskNeedsMigration,
   updateTaskNewcomerFriendly,
   updateTaskParallelSafe,
+  updateTaskPriority,
   updateTaskRequiresRank,
   updateTaskSecuritySensitive,
   updateTaskStatus,
@@ -301,6 +302,7 @@ module.exports = {
   disambiguateWorktreeName,
   foldWorktreeName,
   updateTaskParallelSafe,
+  updateTaskPriority,
   updateTaskSecuritySensitive,
   updateTaskAutomationTag,
   updateTaskNeedsMigration,

package/modules/lifecycle/routes/task-write-routes.js

@@ -318,6 +318,14 @@ module.exports = function registerTaskWriteRoutes(router) {
       // briefs naming tables that hard-fail CI). Same shape as create, same
       // task.edit permission, same audit_log trail as a description edit.
       title: { type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
+      // task 1003750: priority was accepted at create and then immutable at every
+      // rank — the same write-once defect title/description carried above. It is
+      // not cosmetic: the DB weights version progress as `6 - COALESCE(priority, 5)`
+      // and the session optimizer orders claimable work by `priority ASC NULLS LAST`,
+      // so a wrong value at create time steers what every builder claims, forever.
+      // A whole-goal re-rank (needed-vs-nice) had no route and had to run as SQL.
+      // null clears it back to unset; the 1..5 bounds mirror tasks_priority_check.
+      priority: {},                                      // 1..5 or null — checked inline
       // task 1002614 (map D-18): DECLARED so strict-mode admits the request far
       // enough to reach the deliberate status_not_patchable hint below (#514) —
       // the hint had been unreachable dead code behind unknown_field since the
@@ -345,6 +353,7 @@ module.exports = function registerTaskWriteRoutes(router) {
     const hasGoalId = Object.prototype.hasOwnProperty.call(body, 'goal_id');
     const hasDescription = Object.prototype.hasOwnProperty.call(body, 'description');
     const hasTitle = Object.prototype.hasOwnProperty.call(body, 'title');
+    const hasPriority = Object.prototype.hasOwnProperty.call(body, 'priority');
     // #514: status is a lifecycle field, not a PATCH-able column — it moves only
     // through the dedicated transition routes. The #506 session tried
     // `PATCH status=ready`, got the generic no_supported_fields error, and had
@@ -356,8 +365,8 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (Object.prototype.hasOwnProperty.call(body, 'status')) {
       return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
     }
-    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, priority, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -374,6 +383,16 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (hasParallelSafe && body.parallel_safe !== null && typeof body.parallel_safe !== 'boolean') {
       return res.fail('bad_parallel_safe', { status: 400, message: 'parallel_safe must be true, false, or null' });
     }
+    // task 1003750: bounds mirror the tasks_priority_check DB constraint via the
+    // shared TASK_FIELD_BOUNDS the create schema uses, so the route and the
+    // column can't drift. Integer or null only — a float or "3" would pass a
+    // bare range test and then fail at the column.
+    if (hasPriority && body.priority !== null) {
+      const p = body.priority;
+      if (!Number.isInteger(p) || p < TASK_FIELD_BOUNDS.priority.min || p > TASK_FIELD_BOUNDS.priority.max) {
+        return res.fail('bad_priority', { status: 400, message: `priority must be an integer ${TASK_FIELD_BOUNDS.priority.min}-${TASK_FIELD_BOUNDS.priority.max} (1 = most urgent), or null to clear` });
+      }
+    }
     if (hasSecuritySensitive) {
       // task 990: explicit Archon-only-broadcast flag. Boolean only (no null) —
       // it gates whether ship.js routes the broadcast to the Archon-only
@@ -528,6 +547,15 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
+    if (hasPriority) {
+      try {
+        updated = await db.updateTaskPriority(id, body.priority ?? null);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        log.error('[gds] PATCH /tasks/:id priority', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
     if (hasGoalId) {
       try {
         updated = await db.updateTaskGoal(id, body.goal_id);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.618",
+  "version": "1.19.620",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.618",
+      "version": "1.19.620",
       "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.620",
   "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.620'; // 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');
+});

package/tests/migration_allocation.mjs

@@ -204,6 +204,7 @@ function shouldReserveMigrationNumber(task) {
         [() => db.updateTaskModuleKey(1, null), 'module_key'],
         [() => db.updateTaskDescription(1, 'edited body'), 'description'], // task 1002647
         [() => db.updateTaskTitle(1, 'corrected title'), 'title'], // task 1002792
+        [() => db.updateTaskPriority(1, 2), 'priority'], // task 1003750
       ];
       for (const [call, column] of setters) {
         const before = seen.length;
@@ -225,10 +226,35 @@ function shouldReserveMigrationNumber(task) {
       'the PATCH schema must declare title with the create-time limits — a title can be rewritten, never blanked'
     );
     assert.ok(/const hasTitle = Object\.prototype\.hasOwnProperty\.call\(body, 'title'\)/.test(routesSrc), 'title is gated like every other field');
-    assert.ok(/&& !hasTitle\) \{/.test(routesSrc), 'a title-only PATCH is a supported request, not no_supported_fields');
+    // Assert !hasTitle is a TERM of the no_supported_fields guard, not that it is
+    // the LAST term: pinning the final position made this red the moment task
+    // 1003750 appended !hasPriority, for a change that kept the stated intent
+    // (a title-only PATCH is supported) perfectly intact.
+    assert.ok(/if \(!hasParent &&[^)]*!hasTitle\b/.test(routesSrc), 'a title-only PATCH is a supported request, not no_supported_fields');
     assert.ok(/db\.updateTaskTitle\(id, body\.title\.trim\(\)\)/.test(routesSrc), 'the write goes through the allowlisted setter');
   });
 
+  // task 1003750: priority was the third write-once planning field (after title
+  // and description above) — accepted at create, then immutable at every rank.
+  // It is the one that steers what gets claimed: version progress is weighted
+  // `6 - COALESCE(priority, 5)` and the optimizer orders by `priority ASC NULLS
+  // LAST`, so re-ranking a goal's board had to be done as raw SQL against prod.
+  await test('PATCH /tasks/:id accepts priority so a board can be re-ranked (task 1003750)', () => {
+    assert.ok(/priority: \{\},\s*\/\/ 1\.\.5 or null/.test(routesSrc), 'the PATCH schema must declare priority so strict-mode admits it');
+    assert.ok(/const hasPriority = Object\.prototype\.hasOwnProperty\.call\(body, 'priority'\)/.test(routesSrc), 'priority is gated like every other field');
+    assert.ok(/if \(!hasParent &&[^)]*!hasPriority\b/.test(routesSrc), 'a priority-only PATCH is a supported request');
+    assert.ok(/db\.updateTaskPriority\(id, body\.priority \?\? null\)/.test(routesSrc), 'the write goes through the allowlisted setter, and null clears');
+    // The bounds must come from the shared TASK_FIELD_BOUNDS the create schema
+    // reads, never a literal 1..5 here — that is how a route and its column drift.
+    assert.ok(/TASK_FIELD_BOUNDS\.priority\.min.*TASK_FIELD_BOUNDS\.priority\.max/s.test(routesSrc), 'priority bounds are shared with the create schema, not re-typed');
+    // Validation must sit ABOVE the first write (the task 1002609 rule this
+    // handler documents): a body mixing a valid field with a bad priority must
+    // commit nothing.
+    const guardAt = routesSrc.indexOf("res.fail('bad_priority'");
+    const firstWriteAt = routesSrc.indexOf('await db.updateTaskKind(');
+    assert.ok(guardAt > 0 && firstWriteAt > 0 && guardAt < firstWriteAt, 'the priority bounds check must run before the first write, not after');
+  });
+
   await test('PATCH /tasks/:id accepts needs_migration so a wrong flag is correctable', () => {
     assert.ok(
       /needs_migration: \{ type: 'boolean' \}/.test(routesSrc),

package/tests/patch_gate_ordering.mjs

@@ -46,6 +46,9 @@ const REFUSALS = [
   // rendered from goalNotOpenRefusal, so the pin looks for the call.
   'goalNotOpenRefusal(goal)',
   "'bad_requires_rank'",
+  // task 1003750: priority joined the PATCH surface; its bounds check is a
+  // validation refusal like the rest, so it must settle before the first write.
+  "'bad_priority'",
   'badKind(res)',
   "'bad_discipline'",
 ];