@bongos/core 1.18.18 → 1.19.2

package/docs/recipes/core-release-pipeline.md

@@ -0,0 +1,179 @@
+# Recipe — the core release pipeline: how a change to Cloud Bongos reaches a live instance
+
+> **The map.** Three sibling recipes each cover one leg — [packaging-the-core](packaging-the-core.md) (build the artifact), [private-npm-distribution](private-npm-distribution.md) (publish it), [upgrading-the-core](upgrading-the-core.md) (consume it). This file is the thing that connects them, and it exists to state one fact loudly:
+>
+> ## **Merging to `main` ships nothing.**
+>
+> A change that has landed on `main` is running on **zero** instances. It reaches users only after someone bumps `CORE_VERSION`, cuts an artifact, and moves an instance's pin. Those are three separate acts by design ([ADR 0137](../adr/<redacted>.md)) — and every layer around them reports success in the meantime.
+
+## Why this file exists
+
+Between 2026-07-24 and 2026-08-03, **93 work commits (171 counting merges) — including the entire governance permission system — sat on `main` unreleased for ten days** while the live platform served the previous version. Nothing was broken. `/builder-ship` printed success, the publish-reconciler flipped `confirmed → shipped`, credits paid out. Every signal a builder could see said "delivered"; nothing compared live against `main` (blocker 1000097, task [1002521](https://example.com/builders#/task/1002521)).
+
+A second failure followed from the same gap: a builder filed a careful, well-evidenced "prod has been serving stale code for days" report whose central measurement was taken against **the wrong instance**, and which prescribed the npm `--registry` upgrade path for an instance that pins a **vendored tarball** — where it would have moved nothing at all.
+
+Both were documentation failures, not code failures. This is the missing document.
+
+---
+
+## The three gates
+
+A change crosses three independent gates. **None of them implies the next**, and each has its own actor, action, and proof.
+
+| # | Gate | What it means | Who | Proof it happened |
+|---|---|---|---|---|
+| **0** | **Included** | your change is inside the publishable subtree at all | the allowlist | `isPublishable('<path>')` → `true` |
+| **1** | **Landed** | the commit is on core `main` | any builder, via `/builder-ship` | task status `shipped` |
+| **2** | **Released** | a `CORE_VERSION` exists that *contains* the commit, and an artifact was cut from it | a builder bumps + packages; **the owner publishes** | the version is published / a `.tgz` exists |
+| **3** | **Deployed** | a specific instance moved its pin to that version | per instance | that instance's `/version` reports the new `coreVersion` |
+
+The GDS vocabulary collides with gate 1 in a way worth naming: **task status `shipped` means "merged to `main`"** — it does not mean released, and it does not mean live. `ship.js` says so in its own comment and, since task 1002521, prints a divergence warning at the end of every ship.
+
+---
+
+## Gate 0 — does your change ship at all?
+
+The core is not "this repo." It is exactly the subtree [`isPublishable()`](../../scripts/gds/publish-manifest.js) selects ([ADR 0098](../adr/<redacted>.md)) — a **default-deny, two-layer** gate:
+
+```
+isPublishable(p)  ==  matchesDeny(p) ? false : matchesAllow(p)
+```
+
+A path publishes only if it falls in `PUBLISH_ALLOWLIST` **and** escapes `PUBLISH_DENYLIST`. A new, unclassified top-level surface therefore never leaks by omission — it is simply not published.
+
+**A change under a denied path reaches no instance at any version.** The four denial rationales:
+
+| Rationale | Examples |
+|---|---|
+| **Topology** — prod infra, deploy machinery, CI, local gate hooks | `infra/`, `scripts/deploy/`, `.github/`, `.claude/hooks/` |
+| **Read-sensitive docs** — the security/audit corpus | `docs/security/`, `docs/audits/` |
+| **Content / copyright** — the instance's product layer and all art | `modules/game/`, `modules/art-pipeline/`, `public/`, `brand/` |
+| **Host-module tests** — tests that statically import an excluded module | see the list in `publish-manifest.js` |
+
+Note the deliberate non-exclusion: the rank / trust-boundary / ship-grade machinery **is published** — it is the open-source methodology ([ADR 0065 §4](../adr/<redacted>.md)). Only the *topology* subset of the protected surfaces is held back.
+
+Check a path before you assume:
+
+```bash
+node -e "console.log(require('./scripts/gds/publish-manifest').isPublishable('docs/recipes/core-release-pipeline.md'))"
+```
+
+## Gate 1 — land it on `main`
+
+The ordinary claim→ship loop: `/builder-claim N` → build → `/builder-ship`. That chains `completed` → `confirmed` → `shipped`, and credits land at `shipped` ([ADR 0120](../adr/<redacted>.md)).
+
+Landing is CI-gated (tasks 1002610/1002611/1002619, ADR 0159): every PR runs the **`unit`** check — the DB-free suite plus the fitness gates, via `npm test` — and branch protection **requires** it, so a red suite blocks the merge. PRs touching the hard-floor safety surfaces ([`CODEOWNERS`](../../CODEOWNERS)) additionally need the owner's review. The owner kill-switch is `node scripts/gds/gating.js on|off|status` — reversible by construction, snapshot-restored.
+
+**Stop here and nothing happens to any user.** This is the gate that feels like the finish line and is not.
+
+## Gate 2 — cut a release
+
+Three steps. The first two are ordinary claimed work; only the publish (2c) is owner-gated — and 2c is skipped entirely for a vendored-tarball instance.
+
+### 2a. Bump `CORE_VERSION` — the step with no automation behind it
+
+`CORE_VERSION` lives in [`src/module-api.js`](../../src/module-api.js) and is bumped **by hand, inside a claimed task**, with a changelog line in the same file. It is never auto-bumped: the version's provenance stays in git history + changelog ([ADR 0137](../adr/<redacted>.md) §2).
+
+Semver here is not decoration — it decides **who receives the change automatically** ([ADR 0136](../adr/<redacted>.md)):
+
+| Bump | Reaches `patch` subscribers (the default) | Reaches `minor` subscribers |
+|---|---|---|
+| **patch** — a fix; the doorway surface is byte-identical | ✅ | ✅ |
+| **minor** — an added export / additive surface | ❌ **invisible to them** | ✅ |
+| **major** — never automatic for anyone | ❌ | ❌ |
+
+The practical trap: a **MINOR is silently withheld from every patch-only instance**, which is the default channel. If a fix must reach the fleet, it belongs behind a *patch* bump — so an additive export shipped alongside a needed fix will strand that fix. The changelog convention is to justify the level explicitly ("the doorway surface is byte-identical to X, so despite the volume this is → PATCH").
+
+**A bump is mandatory even for a one-file fix.** `bongos upgrade` refuses an equal version, and npm rejects a duplicate — a natural guard, and the reason "carrier bumps" exist to sweep up commits that landed with no bump behind them.
+
+### 2b. Build the artifact
+
+```bash
+node scripts/gds/package-core.js --ref main            # → dist/bongos-core-<v>.tgz + .manifest.json
+node scripts/gds/package-core.js --ref main --self-verify
+```
+
+`package-core` archives the **committed** tree at `--ref`, never your working tree, and stamps the version from `CORE_VERSION` *at that ref*. Full mechanics — the fail-closed no-leak gate, the `tree_sha256` integrity pin, the pruned lockfile — in [packaging-the-core](packaging-the-core.md).
+
+> ⚠️ **Packaging a mid-flight `main` produces a stale version number.** If `CORE_VERSION` at your ref is still the previous value, your tarball is stamped with a version the fleet may already have. `bongos upgrade` refuses only the **equal** case (`already on <v>`, and `--force` bypasses even that) — it has **no downgrade guard**, so a target *below* what is installed proceeds and silently installs older code. Confirm the bump is actually in your ref before packaging.
+
+### 2c. Publish — only for the registry path
+
+Publishing to npm is a **manual, owner-gated step**; merges do not auto-publish and **no npm write token exists in CI or the repo** ([ADR 0137](../adr/<redacted>.md) §3).
+
+```bash
+node scripts/gds/package-core.js --publish          # DRY-RUN — runs the no-leak gate, previews
+node scripts/gds/package-core.js --publish --live   # permanent
+```
+
+**`--publish` is not needed for a vendored-tarball instance** — see gate 3. Chasing an npm publish to move a `file:`-pinned instance is a documented dead end.
+
+## Gate 3 — move the instance's pin
+
+Each instance decides, independently, when to take a release. **Which mechanism it uses is a per-instance fact you must establish before prescribing anything** — read its `package.json`:
+
+| Pin in `package.json` | Path | How it updates |
+|---|---|---|
+| `"@bongos/core": "file:vendor/bongos-core-<v>.tgz"` | **vendored tarball** | ship the `.tgz` to the instance and run `bongos upgrade --from <tgz>`; npm's published version is irrelevant |
+| `"@bongos/core": "^<v>"` | **npm registry** | `bongos upgrade --to <v> --registry`; requires the version to be published and a token to read it |
+
+The mechanics of the bump itself — pre-flight, pin-verify, migrate, `.claude/` materialize, restart, the mandatory health check, and auto-rollback — are in [upgrading-the-core](upgrading-the-core.md). Two portable traps that bite hardest here:
+
+- **`PGDATABASE` is load-bearing.** `migrate.sh` has a default; on a co-tenant host that default is *someone else's database*. Always set `PGDATABASE=<instance-db>` explicitly or you migrate the wrong DB (the usual outcome is a clean auto-rollback, which then reads as "the upgrade failed").
+- **Never hand-edit `package-lock.json`'s `@bongos/core` entry.** Editing `version` + `resolved` while leaving `integrity` at the old tarball's hash makes `npm ci` resolve the *old* content from the content-addressable cache — the deploy reports healthy and runs old code. Run `npm install file:vendor/bongos-core-<v>.tgz` instead, and verify after: `node -e "console.log(require('./node_modules/@bongos/core/package.json').version)"`.
+
+Also: an instance can have **more than one plane to update** (e.g. a web instance plus a control plane that resolves its tooling from its own vendored core). Updating one does not update the other.
+
+---
+
+## Detecting divergence
+
+[`scripts/gds/deploy-divergence.js`](../../scripts/gds/deploy-divergence.js) is the comparison that was missing during the ten-day incident. It runs **warn-only at the end of every ship** and can be run by hand any time:
+
+```bash
+node scripts/gds/deploy-divergence.js --url https://<instance-host>
+```
+
+It reports the two gaps **separately**, because they have different fixes:
+
+- **UNRELEASED** — commits on `main` past the last `CORE_VERSION` bump. *No instance can take these at any pin* — no version contains them. Fix: bump + land (gate 2a).
+- **UNDEPLOYED** — the live instance's `coreVersion` is behind `main`'s. A release exists; this instance has not moved its pin. Fix: gate 3.
+
+Exit codes: `0` aligned, `1` diverged, `2` undetermined.
+
+> ### ⚠️ Do not trust its numbers without checking the anchor
+>
+> The tool has a **known anchor defect** — reproduced live on 2026-08-08, where it named `1.18.19` as the last bump while printing `origin/main 1.19.0` two lines above, then counted 70 UNRELEASED commits from that wrong anchor.
+>
+> The mechanism is one compound failure. It locates the bump with `git log <ref> -1 -G"^const CORE_VERSION = "`. `git log` shows no diff for merge commits, so `-G` **cannot match the merge** that lands a bump on `main` — the only candidate is the original commit on the branch, carrying that branch's earlier **commit date**. `-1` then picks the newest *by date*, so a bump authored earlier on a long-lived branch loses to a later-authored one, even when the earlier one is the higher version. Every count downstream inherits the wrong anchor.
+>
+> Separately and by design, it measures from the last *bump commit*, not from what was actually **packaged** — so work landing between the bump and `package-core` reads as UNRELEASED even though the tarball contains it. Comparing against the `core-v*` release tag would be more accurate.
+>
+> Treat a divergence warning as **"look closer"**, never as a precise commit count. The direction is reliable; the arithmetic is not.
+
+**Before acting on any "prod is stale" report, establish which instance was measured.** `curl` the `/version` endpoint of each candidate host yourself. Instances that serve different products are pinned at different versions *correctly* — a game-only instance needs no platform release. A report that names the wrong host will read as authoritative regardless of how carefully it was written.
+
+---
+
+## Who can do what
+
+| Act | Gate | Who |
+|---|---|---|
+| Land a change on `main` | 1 | any builder holding a claim, behind the required `unit` check (protected paths are Metic+; hard-floor paths need owner review per [`CODEOWNERS`](../../CODEOWNERS); [canonical-permissions](../canonical-permissions.md)) |
+| Bump `CORE_VERSION` | 2a | a builder, inside a claimed task |
+| Build the artifact | 2b | any builder — `package-core` is tokenless and network-free |
+| Publish to npm | 2c | **owner only** — needs `npm login` + 2FA; no write token exists anywhere else |
+| Move an instance's pin | 3 | whoever operates that instance |
+
+Automating gate 2c (a tag-triggered CI publish) is deliberately deferred until a real fleet makes the manual step a bottleneck — see [ADR 0137](../adr/<redacted>.md) "When to revisit".
+
+## Where to go next
+
+| You want to… | Read |
+|---|---|
+| build / verify / inspect the artifact | [packaging-the-core](packaging-the-core.md) |
+| publish it, or set up private npm access | [private-npm-distribution](private-npm-distribution.md) |
+| move an instance from N → N+1, or subscribe it to updates | [upgrading-the-core](upgrading-the-core.md) |
+| know *why* publishing is manual | [ADR 0137](../adr/<redacted>.md) |
+| know *what* an unattended upgrade is allowed to take | [ADR 0136](../adr/<redacted>.md) |
+| know what counts as "the core" | [ADR 0098](../adr/<redacted>.md) · [ADR 0103](../adr/<redacted>.md) |

package/docs/recipes/packaging-the-core.md

@@ -1,5 +1,7 @@
 # Recipe — packaging the Cloud Bongos core as a pinned, installable artifact
 
+> **This is one leg of three.** For how a change to Cloud Bongos actually reaches a live instance — and why merging to `main` ships nothing on its own — start at [the core release pipeline](core-release-pipeline.md).
+>
 > Implements [ADR 0100 §1](../adr/<redacted>.md) (the two-repo instance model). This is **R84**, the first step of the `R84 → R85 → R86` spine: package the core → stand a downstream instance up on a pinned core → make `bongos upgrade` a real update channel. Tooling: [`scripts/gds/package-core.js`](../../scripts/gds/package-core.js) (`bongos package-core`).
 >
 > **Real installable npm package ([ADR 0108](../adr/<redacted>.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@bongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.

package/docs/recipes/parallel-goal-waves.md

@@ -59,9 +59,7 @@ Worked example from goal 1000030:
 
 ## 3. Claiming a parallel set
 
-`claim.js` **cannot hold concurrent claims from one machine.** The app-layer guard permits one claim per *worktree*, but `uniq_active_claim_per_session` (`migrations/180`) is keyed on `creator_session_id` alone — worktree-blind — and the stricter of the two wins. Every worktree on a box shares one CLI session token, so the second `claim.js` fails.
-
-Worse, it fails with a **misleading** message: `claimTask` maps any Postgres `23505` to `ALREADY_CLAIMED`, so you are told *"Task #N was just claimed by another session"* when nothing is claimed and no retry will ever succeed. Two separate agents burned a full investigation each on this before the cause was found. (Filed as idea 1000617.)
+Concurrent bound claims from one machine **used to be impossible**: the app-layer guard permits one claim per *worktree*, but migration 180's `uniq_active_claim_per_session` was keyed on `creator_session_id` alone — worktree-blind — and the stricter of the two won, so the second `claim.js` failed. Worse, it failed with a misleading message: `claimTask` mapped any Postgres `23505` to `ALREADY_CLAIMED` — *"Task #N was just claimed by another session"* when nothing was claimed (filed as idea 1000617; two agents burned a full investigation each). Both halves are fixed now: task 1002589 made the refusal honest (`session_already_has_bound_claim`, naming the in-flight claim), and task 1002570 (`core_204`) re-keyed the index to `(session, worktree)` — **one bound claim per worktree just works**, matching the guard. The batch endpoint below remains a fine way to claim a whole wave in one call.
 
 **Use the batch endpoint**, which was built for exactly this:
 

package/docs/recipes/private-npm-distribution.md

@@ -1,5 +1,7 @@
 # Recipe — private-first npm distribution (core + client)
 
+> **This is one leg of three.** For the whole path from a change on core `main` to a live instance — and for when publishing to npm is *not* what moves an instance — start at [the core release pipeline](core-release-pipeline.md).
+>
 > Implements [ADR 0134](../adr/<redacted>.md). Pre-launch, `@bongos/core` and `@bongos/client` publish as **private, scoped** npm packages on the owner's paid `bongos` npm org (the canonical brand); at launch they flip to public. The daily command is `bongos` regardless of package name.
 >
 > **Why private must be scoped:** on npm, *unscoped* names are always public — only *scoped* names (`@bongos/…`) can be private, and only on a paid plan. So the packages publish under the `@bongos` scope, which maps to the paid `bongos` org.

package/docs/recipes/upgrading-the-core.md

@@ -1,5 +1,7 @@
 # Recipe — upgrading a consumer instance's Cloud Bongos core (`bongos upgrade`)
 
+> **This is one leg of three.** For the whole path from a change on core `main` to a live instance — including how to tell whether *this* instance takes a vendored tarball or a registry version — start at [the core release pipeline](core-release-pipeline.md).
+>
 > The R86 update-consumption channel ([ADR 0100](../adr/<redacted>.md) §2, [ADR 0103](../adr/<redacted>.md) §4, task [#1690](https://example.com/builders#/task/1690)). How a **two-repo consumer instance** — one that installs `@bongos/core` as a vendored-tarball dependency — pulls the core from version N → N+1. Tooling: [`scripts/gds/upgrade.js`](../../scripts/gds/upgrade.js) (`bongos upgrade`). First proven live on emersonian-circles 1.15.0 → 1.16.0 (task [#1976](https://example.com/builders#/task/1976)).
 
 ## What the channel does

package/migrations/core_197_display_name_source.sql

@@ -0,0 +1,56 @@
+-- core_197_display_name_source.sql — "your name wins, always" (task 1002568).
+--
+-- THE DEFECT. `upsertBuilder` (src/bongos/db-kernel.js) runs on EVERY sign-in,
+-- not just at account creation, and its ON CONFLICT (github_id) DO UPDATE
+-- unconditionally re-set `display_name = EXCLUDED.display_name` — where EXCLUDED
+-- carries the GitHub-derived name. So a builder who renamed themselves in hall
+-- Settings (PATCH /me/display-name) saw the value save, then silently revert at
+-- the next authentication. All four login paths clobber it (pollDeviceFlow,
+-- completeWebFlow, completeIdpFlow, completeDeviceExchange).
+--
+-- THE FIX needs one bit of state the row does not currently carry: WHO last set
+-- this name. With it, the upsert keeps seeding + re-syncing GitHub's name for
+-- builders who never renamed (a GitHub rename still propagates), and stops
+-- overwriting the name of anyone who set their own. See ADR 0156.
+--
+-- WHY THIS IS A CORE MIGRATION, NOT modules/builder-settings/migrations/. The
+-- column sits on the CORE `builders` table and is read by CORE code — the guard
+-- lives inside db-kernel.js's upsert, on the auth path. A module migration may
+-- only touch its own <key>-namespaced objects (ADR 0083 §Decision #5), and core
+-- schema must never depend on whether a module happens to be enabled. Same
+-- placement as the other builders-table preference columns (037, 075, 119, 164).
+--
+-- 'github' is the correct default for every existing row: before this migration
+-- there was no durable user-set name — whatever is stored survived the last
+-- sign-in, which means it IS the GitHub-derived value. A builder who wants their
+-- own name re-saves it once and it sticks from then on.
+--
+-- Safe DDL: ADD COLUMN ... NOT NULL DEFAULT <constant> does not rewrite the
+-- table on Postgres 11+ (the default is stored in the catalog). Forward-safe:
+-- every existing reader SELECTs an explicit column list, so old code on the new
+-- schema neither sees nor needs this column.
+-- Idempotent: safe to re-run.
+
+ALTER TABLE builders
+  ADD COLUMN IF NOT EXISTS display_name_source text NOT NULL DEFAULT 'github';
+
+-- Only two values are meaningful, and the upsert guard keys on 'user' exactly —
+-- a typo'd third value would silently fall through to "GitHub wins", which is
+-- the bug this migration exists to close. CHECK constraints have no
+-- ADD ... IF NOT EXISTS, so guard the add (the migration 042 idiom) and keep the
+-- file replay-safe.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conrelid = 'builders'::regclass
+       AND conname = 'builders_display_name_source_check'
+  ) THEN
+    ALTER TABLE builders
+      ADD CONSTRAINT builders_display_name_source_check
+      CHECK (display_name_source IN ('github', 'user'));
+  END IF;
+END $$;
+
+INSERT INTO schema_migrations (version) VALUES ('core_197_display_name_source')
+  ON CONFLICT DO NOTHING;

package/migrations/core_204_rekey_active_claim_per_session_worktree.sql

@@ -0,0 +1,77 @@
+-- core_204_rekey_active_claim_per_session_worktree.sql
+-- Applied under claim 1002172 (task 1002570 -- parallel worktrees can't claim:
+-- migration 180's index still keys on the auth session). Number 204 reserved by
+-- the claim. A CORE migration, not a lifecycle_ module one, by rule: it drops
+-- an index on the shared pre-module `claims` table, and module migrations must
+-- stay additive within their own <key>_ tables (ADR 0083 section Decision #5 -- the
+-- fitness gate enforces both).
+-- Idempotent on re-run.
+--
+-- THE PROBLEM. The authoritative app guard (shouldRefuseSessionClaim,
+-- modules/lifecycle/routes/claims.js) keys the one-active-claim rule on the
+-- WORKING TREE: one auth session may hold several active bound claims as long
+-- as each lands in its own worktree (one worktree = one branch = one HEAD; only
+-- same-tree claims commingle a ship). Migration 180's backstop index was never
+-- updated to match -- keyed on creator_session_id ALONE, it refused at the DB
+-- layer the parallel second-worktree claim the app layer had just approved, so
+-- the documented worktree-per-task parallel workflow was broken.
+--
+-- THE FIX. Re-key the partial unique index to
+-- (creator_session_id, COALESCE(worktree_name, '')). COALESCE rather than
+-- PG15's NULLS NOT DISTINCT, and it is load-bearing: in a plain multi-column
+-- unique index NULLs are DISTINCT, so two worktree-less claims (worktree_name
+-- NULL -- one shared clone whose single branch genuinely commingles) would BOTH
+-- insert and re-open the hole task 1642 closed. Folding NULL to '' keeps the
+-- shared-clone case self-colliding on every supported Postgres. (Degenerate
+-- corner: a claim named '' collides with the NULL group -- the same "no worktree
+-- info, assume one shared clone" answer the app guard gives.)
+--
+-- The predicate is unchanged from 180: released_at IS NULL is the claims-table
+-- "active" convention (there is no status column), and NULL sessions
+-- (bind_session=false web claims -- many may coexist, adoptable by any of the
+-- builder's CLI sessions) stay excluded.
+--
+-- The error surface survives the swap: claimUniqueViolationError
+-- (modules/lifecycle/db.js, task 1002589) matches the OLD and NEW index names,
+-- so a 23505 from either generation renders as session_already_has_bound_claim,
+-- never the false ALREADY_CLAIMED.
+
+BEGIN;
+
+-- Step 1 -- heal before CREATE (the migration 174/180 shape): a unique index
+-- fails to create if existing rows already violate it, which would block
+-- deploy. Under the old session-only index no session can hold two bound
+-- active claims at all, so this normally closes nothing -- it only bites on a
+-- DB whose old index was dropped by hand. Keep the EARLIEST active bound claim
+-- per (session, folded worktree) and close the rest, exactly as 180 did.
+WITH ranked AS (
+  SELECT c.id,
+         ROW_NUMBER() OVER (
+           PARTITION BY c.creator_session_id, COALESCE(c.worktree_name, '')
+           ORDER BY c.claimed_at, c.id
+         ) AS rn
+    FROM claims c
+   WHERE c.released_at IS NULL
+     AND c.creator_session_id IS NOT NULL
+)
+UPDATE claims c
+   SET released_at = now(),
+       outcome     = COALESCE(c.outcome, 'abandoned')
+  FROM ranked r
+ WHERE c.id = r.id
+   AND r.rn > 1;
+
+-- Step 2 -- swap the index. The old name goes away entirely rather than staying
+-- alongside: keeping it would re-refuse exactly what the guard (and the new
+-- index) deliberately allow.
+DROP INDEX IF EXISTS uniq_active_claim_per_session;
+
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_active_claim_per_session_worktree
+  ON claims (creator_session_id, (COALESCE(worktree_name, '')))
+  WHERE released_at IS NULL AND creator_session_id IS NOT NULL;
+
+-- (The index name in claimUniqueViolationError's SESSION_CLAIM_INDEXES set and
+-- this file must stay in lockstep -- tests/one_active_claim_per_session.mjs pins
+-- both sides.)
+
+COMMIT;

package/modules/autonomy/routes/autonomy.js

@@ -20,7 +20,7 @@ const autonomyGate = require('../../../scripts/gds/autonomy-gate');
 module.exports = function buildAutonomyRouter() {
   const router = express.Router();
 
-  router.get('/autonomy/precheck', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.get('/autonomy/precheck', auth.requireBuilder, auth.requirePermission('autonomy.precheck'), async (req, res) => {
     const routine = String(req.query.routine || '').slice(0, 64);
     if (!routine) return res.fail('routine_required', { status: 400, message: 'pass ?routine=<name>' });
     try {

package/modules/builder-settings/db.js

@@ -143,10 +143,16 @@ async function getBuilderDisplayName(builderId) {
 // writes it verbatim and returns the saved string. Own-scoped: the route only
 // ever passes the AUTHENTICATED builder's id. display_name is `text NOT NULL`
 // (migration 003), so a validated non-empty string is always a legal write.
+//
+// Also stamps display_name_source='user' (core migration 197): that flag is what
+// makes the name durable — core's upsertBuilder re-syncs the GitHub name on
+// every sign-in and skips any row marked 'user'. Without the stamp the save
+// reverts at the next authentication (task 1002568, ADR 0156).
 async function setBuilderDisplayName(builderId, displayName) {
   const { rows } = await pool.query(
     `UPDATE builders
-        SET display_name = $2
+        SET display_name = $2,
+            display_name_source = 'user'
       WHERE id = $1
       RETURNING display_name`,
     [builderId, displayName]