@bongos/core 1.18.3 → 1.18.19

package/docs/recipes/work-on-a-task-from-your-dev-box.md

@@ -0,0 +1,108 @@
+# Work on a task from your dev box
+
+> Your dev box is **task-scoped**: claim a task and the box pulls **only the code
+> that task needs** — the module(s) its work touches, on top of a small base
+> instance — never the whole repo. Your GitHub token never leaves the server; the
+> box fetches its slice through the control plane. See
+> [ADR 0148](../adr/<redacted>.md) (the scope model) and
+> [ADR 0150](../adr/<redacted>.md) (how the box
+> comes up).
+
+## TL;DR
+
+In your dev box's terminal:
+
+```bash
+/builder-start          # see what you can claim
+/builder-claim <N>      # claim task N (locks it to your session)
+/builder-sync           # pull task N's code onto the box now (re-scopes in place)
+# …work in /workspace…
+/builder-ship           # smoke + review, then land + deploy — awards credits
+```
+
+That's the whole loop. `/builder-sync` is the new step: it materializes the claimed
+task's code within seconds instead of waiting for the box's ~10-minute refresh.
+
+## The model — what's on your box
+
+A task-scoped box carries two layers:
+
+1. **The base instance** — always present, whatever you've claimed: the methodology
+   (`CLAUDE.md`, `.claude/`), the build tooling (`scripts/`, `src/bongos/`),
+   `docs/`, `infra/`, and the **test suite** (`tests/`). Enough for Claude to hold
+   context and run the `/builder-*` CLI, and to run your module's tests.
+2. **Your claimed task's code** — the module directories the task's goal scopes
+   (`goals.scope_modules` → globs, [ADR 0086](../adr/<redacted>.md)). Claim a `dev-box` task → you get
+   `modules/dev-box/`; claim a `game` task → you get the game world too. Nothing
+   else.
+
+What you do **not** get: other builders' modules, the product/game runtime (unless
+your task is game-scoped), and — the point — **no GitHub credential on the box**.
+The box asks the control plane (`GET /box/source-access`) for its slice on each
+fetch; the server holds the token and returns a scoped, cone-mode sparse-checkout
+spec. Lose the claim or a rank, and the next fetch is cut off at the server.
+
+## Step by step
+
+### 1. Connect to your box
+
+If you haven't yet, run **`/builder-connect`** (or follow the
+[dev-box lifecycle recipe](builder-box-lifecycle.md)) to raise and connect to your
+box, then **`/builder-setup`** once on the box to sign the GDS CLI in. The browser
+terminal drops you into `/workspace` — the one working folder.
+
+> **`bongos shell` / `bongos code` re-scope on connect (BV1.R101).** Connecting with
+> either verb runs the sync for you first, so you land in `/workspace` already scoped
+> to your active claim — no manual `/builder-sync` needed just to arrive. (The browser
+> terminal drops you straight into `/workspace`; run `/builder-sync` there if you
+> claimed or switched since your last sync.)
+
+### 2. See what you can claim — `/builder-start`
+
+Lists the tasks that are `ready` and parallel-safe against everyone else's active
+claims. Pick one.
+
+### 3. Claim it — `/builder-claim <N>`
+
+Locks task N to your session. **This is what drives your box's scope:** source
+access is computed from your **active claim** — its task → goal → `scope_modules`.
+
+### 4. Pull the code now — `/builder-sync`
+
+Re-runs the box's source-fetch immediately, so `/workspace` re-scopes to task N's
+modules within seconds. (A ~10-minute cron does this on its own as a backstop — you
+just don't want to wait for it.) Off a box there's nothing to sync — your source is
+your local checkout — and the command tells you so.
+
+### 5. Work — in `/workspace`
+
+`/workspace` now holds the base instance **plus** task N's module code. One folder:
+when you switch tasks it **re-scopes in place**, so there are no per-task folders to
+manage.
+
+### 6. Ship — `/builder-ship`
+
+Runs the smoke tests and the review gate, then lands + deploys and awards credits.
+
+## Switching tasks
+
+One box, one working folder, one active claim at a time (the server enforces
+one-claim-per-session). To move to a different task:
+
+1. `/builder-ship` (or `/builder-release`) the current claim.
+2. `/builder-claim <M>` the new one.
+3. `/builder-sync` — the box re-scopes to task M in place.
+
+## Notes + gotchas
+
+- **`tests/` is always in the base** — so a module's tests run on the box (they
+  live in the top-level `tests/`, not inside `modules/<key>/`).
+- **Idle boxes rest.** A box with no activity is reclaimed after ~10–15 min; the
+  next connect re-provisions a fresh one and re-fetches your scope. **Uncommitted
+  work on a reaped box is lost** — ship or commit before you step away.
+- **`/builder-sync` is idempotent** — safe to re-run; it just does, on demand, what
+  the cron does on its schedule.
+- **A fresh box comes up with the base already cloned.** If a box ever comes up
+  *bare* (no code, no terminal), that's the packaging bug
+  [ADR 0150](../adr/<redacted>.md) fixed on the
+  control plane — flag it rather than working around it.

package/migrations/003_pms.sql

@@ -223,17 +223,16 @@ CREATE INDEX IF NOT EXISTS idx_session_logs_builder ON session_logs (builder_id)
 CREATE INDEX IF NOT EXISTS idx_session_logs_ended ON session_logs (ended_at);
 
 -- =========================================================================
--- Seed: the two known versions
+-- Seed: the platform PMS-V1 version
 -- =========================================================================
--- Instance-seed guard (task 1704 / ADR 0105): these are OTB product versions —
--- scope-truth that must NOT seed onto a vanilla / non-owning DB. scripts/migrate.sh
--- sets app.seed_instance_data='off' on such a boot; unset (direct psql / OTB) = seed.
+-- Instance-seed guard (task 1704 / ADR 0105): OTB platform scope-truth that must
+-- NOT seed onto a vanilla / non-owning DB. scripts/migrate.sh sets
+-- app.seed_instance_data='off' on such a boot; unset (direct psql / OTB) = seed.
+-- (Game V1 was product/primea scope; relocated to the amazonprimea instance's
+--  migrations/instance/ per task 1002423 — the neutral core carries no game seed.)
 DO $seed$ BEGIN IF current_setting('app.seed_instance_data', true) IS DISTINCT FROM 'off' THEN
 INSERT INTO versions (id, name, track, status, scope_doc_path, started_at, done_when)
 VALUES
-  ('V1', 'Game V1 — first playable purchase loop', 'product', 'building',
-   'limitations/current-version.md', '2026-05-08'::timestamptz,
-   'A visitor can land in the world, walk to the vendor, buy a real item, and Hermeslines fulfills it.'),
   ('PMS-V1', 'PMS V1 — project management system, parallel internal track', 'internal', 'building',
    'limitations/pms-v1.md', '2026-05-09'::timestamptz,
    'Builders auth via GitHub. Slash commands claim/ship tasks atomically. Backlog migrated. Public status page live.')

package/migrations/006_pms_v2.sql

@@ -337,38 +337,10 @@ ON CONFLICT (version_id, criterion_id) DO UPDATE
 END IF; END $seed$;
 
 -- =========================================================================
--- 6. Seeds: V1 done-when criteria (mirrors limitations/current-version.md)
+-- (Game V1 done-when criteria removed — product/primea scope, not core.)
+-- Relocated to the amazonprimea instance's migrations/instance/ per task
+-- 1002423; the neutral core seeds no game scope-truth.
 -- =========================================================================
--- The V1 done-when (CLAUDE.md §9): "the experience supports the full
--- purchase loop: land in the world → walk to the vendor → buy a real
--- item → Hermeslines fulfills it." Decomposed into checkable criteria.
-
--- Instance-seed guard (task 1704 / ADR 0105): OTB V1 game scope-truth. FK-references
--- the V1 version guarded above, so this must skip on a vanilla DB too.
-DO $seed$ BEGIN IF current_setting('app.seed_instance_data', true) IS DISTINCT FROM 'off' THEN
-INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order) VALUES
-  ('V1', 'world-land',
-   'Visitor lands in the persistent world from amazonprimea.com',
-   10),
-  ('V1', 'walk-to-vendor',
-   'Visitor can walk to Hyperion at the shipping container with WASD',
-   20),
-  ('V1', 'auth-magic-link',
-   'Visitor authenticates via Stripe-tied magic link before purchase',
-   30),
-  ('V1', 'vendor-purchase',
-   'Vendor dialog supports real-product purchase via Stripe',
-   40),
-  ('V1', 'hermeslines-fulfill',
-   'Order intake reaches Hermeslines fulfillment system (whatever the format)',
-   50),
-  ('V1', 'order-confirmation',
-   'Visitor receives order confirmation in-world',
-   60)
-ON CONFLICT (version_id, criterion_id) DO UPDATE
-  SET criterion_md = EXCLUDED.criterion_md,
-      sort_order   = EXCLUDED.sort_order;
-END IF; END $seed$;
 
 -- =========================================================================
 -- 7. Migration record

package/migrations/core_193_task_needs_rebase.sql

@@ -0,0 +1,28 @@
+-- core_193_task_needs_rebase.sql — ADR 0120 part 2: the `needs_rebase` flag.
+--
+-- A confirmed task whose land the publish-reconciler cannot complete after the
+-- normal auto-land grace (its retries + the ADR 0082 generated-file self-heal)
+-- is flagged needs_rebase=true. It is a SIGNAL, not a status change: the task
+-- stays 'confirmed' (its work is done) — it is simply marked as awaiting *its
+-- builder's* rebase. Attribution to the builder who did the work is derived from
+-- tasks.shipped_by (confirmTask/applyGrade/decideOverrideRequest all COALESCE it
+-- to the claim holder), so no separate owner column is needed.
+--
+-- The claim gate (core claimTask, ADR 0120 part 3) refuses that builder's NEW
+-- claims while any of their tasks is needs_rebase; landing the task (shipTask)
+-- or releasing it clears the flag. This is a CORE migration (not a lifecycle
+-- module migration) because it ALTERs the core `tasks` table — the module
+-- migration namespacing rule forbids a module migration touching non-namespaced
+-- core objects (the discord precedent).
+--
+-- Safe DDL: ADD COLUMN ... NOT NULL DEFAULT <constant> does not rewrite the
+-- table on Postgres 11+ (the default is stored in the catalog).
+
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS needs_rebase boolean NOT NULL DEFAULT false;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS needs_rebase_reason text;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS needs_rebase_at timestamptz;
+
+-- The claim gate + hall/CLI ask "does builder B own any needs_rebase task?",
+-- keyed on shipped_by. Partial index keeps that lookup cheap (only the handful
+-- of flagged rows are indexed).
+CREATE INDEX IF NOT EXISTS idx_tasks_needs_rebase ON tasks (shipped_by) WHERE needs_rebase;

package/migrations/core_194_confirmed_backlog_clawback.sql

@@ -0,0 +1,63 @@
+-- core_194_confirmed_backlog_clawback.sql — ADR 0120 part 4: one-time clawback
+-- + re-gate of the confirmed backlog that accrued under the OLD pay-on-confirm
+-- rule (parts 1-3 moved BOTH the pay and the queue gate to the LAND).
+--
+-- For every task still at status='confirmed' (verified but NOT yet merged to
+-- main) this migration:
+--   1. Reverses its task.confirmed per-task credit — a compensating NEGATIVE
+--      credit_log row (reason='task.confirmed_reversal') per (task, builder), so
+--      the builders.total_credits trigger nets it back to 0. The reward is fully
+--      RE-EARNABLE: when the task finally lands, part 1a books a fresh
+--      'task.shipped' credit. Achievements already unlocked are LEFT INTACT
+--      (reversing gamification is punitive + messy — ADR 0120 §Consequences).
+--   2. Flags the task needs_rebase=true (reason 'clawback:confirmed_backlog') so
+--      the part-3 claim gate applies the new incentive to the work that stranded
+--      under the old rule, rather than grandfathering it.
+--
+-- Idempotent: a task already carrying a task.confirmed_reversal row is skipped,
+-- and needs_rebase is only set where still false — a re-run is a no-op. It runs
+-- ONCE per DB (schema_migrations), at the deploy that first carries it; that is
+-- WHERE the retroactive sting lands, so it hits real builders (the owner
+-- included) only when this version is actually deployed.
+--
+-- Deliberately NOT reversed: the idea-promotion bonus and the net-negative
+-- bonus. The ADR names only the 'task.confirmed' delta; the idea bonus stays
+-- with its capturer (it is not double-paid on re-land — maybeAwardIdeaPromotion
+-- Bonus guards on the existing 'idea_promotion_bonus' row), and the net-negative
+-- bonus derives from grade-time signals that never moved off confirm.
+--
+-- DML only (no schema change): safe to run inside one transaction.
+
+BEGIN;
+
+-- 1. Compensating reversal of the task.confirmed credit for still-confirmed tasks.
+INSERT INTO credit_log (builder_id, task_id, delta, reason, description)
+SELECT cl.builder_id,
+       cl.task_id,
+       -SUM(cl.delta),
+       'task.confirmed_reversal',
+       'ADR 0120 clawback: reverse premature task.confirmed credit for still-confirmed (unlanded) task ' || cl.task_id
+  FROM credit_log cl
+  JOIN tasks t ON t.id = cl.task_id
+ WHERE t.status = 'confirmed'
+   AND cl.reason = 'task.confirmed'
+   AND NOT EXISTS (
+     SELECT 1 FROM credit_log r
+      WHERE r.task_id = cl.task_id
+        AND r.builder_id = cl.builder_id
+        AND r.reason = 'task.confirmed_reversal'
+   )
+ GROUP BY cl.builder_id, cl.task_id
+HAVING SUM(cl.delta) <> 0;
+
+-- 2. Re-gate: flag every still-confirmed task needs_rebase for its builder
+--    (attribution via tasks.shipped_by), so the claim gate (part 3) bites.
+UPDATE tasks
+   SET needs_rebase = true,
+       needs_rebase_reason = 'clawback:confirmed_backlog',
+       needs_rebase_at = COALESCE(needs_rebase_at, now()),
+       updated_at = now()
+ WHERE status = 'confirmed'
+   AND needs_rebase = false;
+
+COMMIT;

package/migrations/core_195_idea_triage_provenance.sql

@@ -0,0 +1,57 @@
+-- core_195_idea_triage_provenance.sql — give a triage VERDICT somewhere to
+-- record what it decided (task 1002447).
+--
+-- Triage has three verbs; only two of them had storage. `status` records THAT an
+-- idea was discarded or merged, and `promoted_to_task_id` records the task a
+-- promotion produced — but nothing recorded WHICH idea a merge folded into, or
+-- WHY a discard happened. `promoted_to_task_id` cannot stand in for the merge
+-- target: it is `REFERENCES tasks(id)`, so writing an idea id there either trips
+-- the FK or silently points at an unrelated task. BOTH callers that documented
+-- or performed that write are corrected alongside this migration — the
+-- /idea-triage skill doc and the interactive walker `scripts/gds/triage.js`.
+-- Without a target, "merge" is just "discard" wearing a different label.
+--
+-- CORE, not modules/ideas/migrations/, even though the ideas module owns every
+-- query against this table: `idea_inbox` is a CORE table, and a module migration
+-- may only touch its own <key>_-prefixed objects — `fitness.js`
+-- checkModuleMigrationsAdditive hard-fails an `ALTER TABLE idea_inbox` from a
+-- module (ADR 0083 §Decision #5). The module's "new ideas migration goes in
+-- modules/ideas/migrations/" note applies to objects the module OWNS, and it
+-- owns none.
+--
+-- Two additive, nullable columns. Forward-safe by construction: every existing
+-- reader SELECTs an explicit column list, so old code on the new schema neither
+-- sees nor needs these (tests/migrations_forward_safe.mjs).
+
+BEGIN;
+
+ALTER TABLE idea_inbox
+  ADD COLUMN IF NOT EXISTS merged_into_idea_id bigint REFERENCES idea_inbox(id);
+
+ALTER TABLE idea_inbox
+  ADD COLUMN IF NOT EXISTS triage_note text;
+
+-- A target exists IFF the idea is merged. Without this, two ordinary PATCHes
+-- build a merge CHAIN: set A's target while leaving A open, then merge C into A
+-- — whose status still reads 'open', so a status-based no-chains check waves it
+-- through. One direction only (`target IS NULL OR status='merged'`), because
+-- every pre-existing merged row has a NULL target and must stay valid.
+-- 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 = 'idea_inbox'::regclass
+       AND conname = 'idea_inbox_merge_target_needs_merged_status'
+  ) THEN
+    ALTER TABLE idea_inbox
+      ADD CONSTRAINT idea_inbox_merge_target_needs_merged_status
+      CHECK (merged_into_idea_id IS NULL OR status = 'merged');
+  END IF;
+END $$;
+
+INSERT INTO schema_migrations (version) VALUES ('core_195_idea_triage_provenance')
+  ON CONFLICT DO NOTHING;
+
+COMMIT;

package/migrations/core_196_session_reward_topup.sql

@@ -0,0 +1,69 @@
+-- core_196_session_reward_topup.sql
+-- Let a multi-ship session be paid for ALL of its cost, not just its first ship.
+--
+-- WHY THIS IS A CORE MIGRATION, NOT modules/economy/. credit_log is a CORE table — the
+-- economy module owns the queries against it, not the table itself (ADR 0083 §Decision #5;
+-- modules/economy/CLAUDE.md "Tables: None owned"). A module migration may only touch its own
+-- economy_-namespaced objects, so this shipped as economy_002_* and reddened the fitness gate
+-- three ways (destructive DDL + index + alter on a non-namespaced table). The real defect was
+-- placement, not DDL: as a module migration these columns only existed when the economy module
+-- happened to be ENABLED, which makes core schema depend on module enablement — the exact
+-- coupling the rule forbids. Relocated per the core_195 precedent (task 1002447).
+--
+-- schema_migrations is stem-keyed, so this re-applies once under its new stem. That is safe
+-- BECAUSE every statement below is IF [NOT] EXISTS — the re-run is a no-op on any database
+-- that already had it as economy_002.
+--
+-- THE DEFECT. Migration 091 made the cost-plus session reward idempotent with a
+-- PARTIAL UNIQUE INDEX on credit_log (session_id) WHERE reason='session.token_reward'
+-- — "the hard DB-level backstop against a double payout". That is correct and stays.
+-- But it was the ONLY control, so once a session booked its first reward row, every
+-- later ship in the same session was a hard no-op. A session's cost keeps growing
+-- after its first ship, and that increment had nowhere to land.
+--
+-- Measured: three tasks shipped from one session, priced $14.30 / $27.76 / $40.32,
+-- paid 17 drachmae where the whole session was worth round(40.32 × 1.20) = 48.
+-- Roughly 65% of real, shipped, graded work went unrewarded. Multi-ship sessions are
+-- normal — one claim at a time, but ship -> new worktree -> claim again.
+--
+-- THE FIX is watermark accounting: each landed ship books the DIFFERENCE between what
+-- the whole session is now worth and what it has already been paid. That needs more
+-- than one row per session, so uniqueness moves from (session_id) to
+-- (session_id, reward_basis) — still scoped to the same reason.
+--
+-- WHY A CUMULATIVE BASIS AND NOT THE DELTA. Two concurrent uploads at the SAME cost
+-- level must still collide and DO NOTHING. reward_basis is the CUMULATIVE owed total
+-- at the moment of the row, so it is monotonic and identical for a racing pair. A bare
+-- delta would be wrong: two genuine increments that happened to be equal would
+-- collide and one payment would be silently lost.
+--
+-- Additive and non-destructive. No historical row changes value.
+
+-- (a) The cumulative cost-plus total this session was owed when the row was written.
+--     NOT NULL DEFAULT 0 (rather than nullable) so the unique index below has clean
+--     semantics: Postgres treats NULLs as DISTINCT in a unique index, so a nullable
+--     basis would let two legacy rows share a session_id and would WEAKEN the very
+--     backstop 091 added.
+--
+--     Existing rows therefore land on reward_basis = 0, which is the marker for
+--     "booked before top-ups existed". The application refuses to top those up: doing
+--     so would be an uncontrolled retroactive payout across every historical session.
+--     Reconstructing what past sessions are owed is a deliberate, owner-signed-off
+--     backfill, tracked separately.
+ALTER TABLE credit_log
+  ADD COLUMN IF NOT EXISTS reward_basis integer NOT NULL DEFAULT 0;
+
+-- (b) Swap the uniqueness key. CREATE the replacement BEFORE dropping the original so
+--     the double-pay backstop is never absent, not even inside this transaction.
+--
+--     For legacy rows (all at basis 0) the new index is exactly as strict as the old
+--     one — (session_id, 0) is unique per session — so nothing already paid can be
+--     paid twice.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_credit_session_token_reward_basis
+  ON credit_log (session_id, reward_basis)
+  WHERE reason = 'session.token_reward';
+
+DROP INDEX IF EXISTS uniq_credit_session_token_reward;
+
+-- Counter hygiene: as a core migration this consumes core number 196 (next free after
+-- core_195), so the core allocator floor advances with it.

package/modules/autonomy/pollers/routine-timers.js

@@ -8,10 +8,12 @@
 // contributes.pollers:["routine-timers"]; the loader (src/module-loader/loader.js
 // startModulePollers) requires THIS file and calls start(deps) at boot, stop() at
 // shutdown — the module-agnostic successor to the hardcoded `routineTimers.start()`
-// block server.js used to carry. server.js (the game/droplet entrypoint) is the
-// ONLY caller of startModulePollers, never src/platform-server.js, so a future
-// second always-on instance on the same DB can't double-run (and the FOR UPDATE
-// row lock in tallyPeerVotes is the hard guard if one ever does).
+// block server.js used to carry. src/platform-server.js is now the ONLY caller of
+// startModulePollers (task 1002419) — server.js, the retired game/droplet
+// entrypoint, was the previous one, and while it was gone NO module poller ran at
+// all. It runs as a single process (docker-entrypoint.sh `exec`s it, no cluster),
+// so a second always-on instance on the same DB still can't double-run — and the
+// FOR UPDATE row lock in tallyPeerVotes is the hard guard if one ever does.
 //
 // WHY THIS EXISTS
 // ADR 0078 demoted peer-vote-tally to `mode: deterministic` and built an EXTERNAL
@@ -100,10 +102,9 @@ async function runPeerVoteTally(deps = {}) {
 
 // Start the timer(s). Idempotent. Kill-switched by ROUTINE_TIMERS_DISABLED=1.
 // Unref'd so it never holds the process open on a systemd restart. Started by the
-// loader's startModulePollers ONLY on the game/droplet entrypoint (server.js),
-// never in src/platform-server.js, so a future second always-on instance on the
-// same DB can't double-run (and the FOR UPDATE row lock in tallyPeerVotes is the
-// hard guard if one ever does).
+// loader's startModulePollers from src/platform-server.js — the single always-on
+// entrypoint (task 1002419) — so a second instance on the same DB can't double-run
+// (and the FOR UPDATE row lock in tallyPeerVotes is the hard guard if one ever does).
 function start(deps = {}) {
   if (process.env.ROUTINE_TIMERS_DISABLED === '1') {
     console.log('[routine-timers] disabled (ROUTINE_TIMERS_DISABLED=1)');

package/modules/builder-settings/wandering-prefs.js

@@ -18,13 +18,14 @@
 // blob; future behavior knobs add their own reserved keys. A missing key falls
 // back to the rank-derived default below, so the column stays sparse.
 //
-// Resolution = default-by-rank, capped-by-rank, server-enforced.
+// Resolution = default-by-role, capped-by-role, server-enforced (see the ROLE
+// METADATA block below for why a ceiling is metadata and not a permission).
 //   - DEFAULT level rides the trust ladder (Xenos→Locked … Archon→Exploratory).
-//   - MAX (ceiling) per rank: Xenos and Thetes are capped at their default (they
-//     may dial DOWN for more focus, never UP); Metic and Archon may set any
-//     level (their rank is a starting default, not a ceiling). Owner decision
+//   - CEILING per role: Xenos and Thetes are capped at their default (they may
+//     dial DOWN for more focus, never UP); Metic and Archon may set any level
+//     (their rank is a starting default, not a ceiling). Owner decision
 //     2026-06-19: "Thetes is gated; Metic is just a starting default."
-//   - effectiveLevel = clamp(override ?? default, 0, maxForRank). So a Xenos who
+//   - effectiveLevel = clamp(override ?? default, 0, ceiling). So a Xenos who
 //     stores Exploratory is still resolved to Locked — opening the setting up
 //     for self-service later stays safe because the clamp is the enforcement,
 //     not the UI.
@@ -98,15 +99,54 @@ const LEVEL_CONTRACT = Object.freeze({
     + 'investigations worth the user\'s attention as you go, while still landing the claimed task.',
 });
 
-// Default level per rank (the array index in LEVELS). Rides the live rank
-// ladder (xenos<thetes<metic<archon — db.RANKS / boxes.RANK_ORDER). A rank not
-// listed (e.g. a reserved/penalty rank, or an unknown string) falls back to the
-// safest floor: Locked.
-const RANK_DEFAULT = Object.freeze({ xenos: 0, thetes: 1, metic: 2, archon: 3 });
+// ---- the wandering ceiling as ROLE METADATA (BV1.R107, ADR 0151) ----
+//
+// The governance model makes a permission a BOOLEAN atom and a rank a seeded
+// ROLE. A wandering ceiling is neither: it is a NUMBER in 0..3. Spelling it as
+// permissions would need one catalog key per level (`me.wandering.level.0..3`) —
+// four keys no route consumes individually, against the catalog's first rule
+// ("a permission no route consumes does not exist") and multiplying the key count
+// to encode a quantity that was never a yes/no capability.
+//
+// So the ceiling is ROLE METADATA: a property carried BY the role, alongside —
+// not inside — the permission that authorizes the write. The two compose:
+//   • the PERMISSION `me.wandering.set` (catalog: floor xenos, scope 'own',
+//     resource 'builder_prefs') answers MAY this builder set their OWN level. It
+//     is ownership-scoped, so it is answered by resolver.authorizeOwned(), never
+//     by an unconditional "do they hold it" — that is the route gate's business.
+//   • the ROLE METADATA below answers HOW HIGH they may set it. Holding the
+//     permission is never sufficient on its own: effectiveLevel() clamps to the
+//     role's ceiling server-side, so the ceiling is enforcement, not UI copy.
+//
+// Keyed by ROLE KEY. The four seeded rank-roles are named for the ranks they seed
+// (governance_002), so a role key and a rank string coincide — which is why the
+// rank-keyed helpers below still resolve correctly, and why BV1.R108 can fold this
+// table onto the one live ladder without changing a value. A role this table does
+// not name carries NO wandering metadata and resolves to the safest floor
+// (Locked), the same fail-closed posture the resolver takes for a rank with no
+// seeded role.
+const ROLE_WANDERING = Object.freeze({
+  xenos: Object.freeze({ default: 0, ceiling: 0 }),
+  thetes: Object.freeze({ default: 1, ceiling: 1 }),
+  metic: Object.freeze({ default: 2, ceiling: 3 }),
+  archon: Object.freeze({ default: 3, ceiling: 3 }),
+});
+const NO_ROLE_WANDERING = Object.freeze({ default: 0, ceiling: 0 });
+
+function roleWandering(roleKey) {
+  return Object.prototype.hasOwnProperty.call(ROLE_WANDERING, roleKey)
+    ? ROLE_WANDERING[roleKey]
+    : NO_ROLE_WANDERING;
+}
 
-// Ceiling per rank. Below Metic the default IS the ceiling (dial down only);
-// Metic+ may pick any level. Unknown rank → floor (0).
-const RANK_MAX = Object.freeze({ xenos: 0, thetes: 1, metic: 3, archon: 3 });
+// DERIVED projections of the metadata above, kept because scripts/gds/session-eval.js
+// and the /me payload read them by rank. Deriving them means the two views cannot drift.
+const RANK_DEFAULT = Object.freeze(
+  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.default])),
+);
+const RANK_MAX = Object.freeze(
+  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.ceiling])),
+);
 
 const TOP_LEVEL = LEVELS.length - 1; // 3
 const RESERVED_KEY = 'wandering';
@@ -120,9 +160,10 @@ for (const key of LEVELS) {
 for (let i = 0; i < LEVELS.length; i++) {
   if (LEVEL_META[LEVELS[i]].n !== i) throw new Error(`wandering-prefs: LEVEL_META.${LEVELS[i]}.n must equal its index ${i}`);
 }
-for (const rank of Object.keys(RANK_DEFAULT)) {
-  if (!(rank in RANK_MAX)) throw new Error(`wandering-prefs: RANK_DEFAULT has '${rank}' but RANK_MAX does not`);
-  if (RANK_DEFAULT[rank] > RANK_MAX[rank]) throw new Error(`wandering-prefs: default > max for rank '${rank}'`);
+for (const [role, meta] of Object.entries(ROLE_WANDERING)) {
+  if (!isLevelInt(meta.default)) throw new Error(`wandering-prefs: role '${role}' has a non-level default`);
+  if (!isLevelInt(meta.ceiling)) throw new Error(`wandering-prefs: role '${role}' has a non-level ceiling`);
+  if (meta.default > meta.ceiling) throw new Error(`wandering-prefs: default > ceiling for role '${role}'`);
 }
 
 // ---- pure helpers ----
@@ -141,11 +182,11 @@ function levelIndex(key) {
 }
 
 function defaultLevelForRank(rank) {
-  return Object.prototype.hasOwnProperty.call(RANK_DEFAULT, rank) ? RANK_DEFAULT[rank] : 0;
+  return roleWandering(rank).default;
 }
 
 function maxLevelForRank(rank) {
-  return Object.prototype.hasOwnProperty.call(RANK_MAX, rank) ? RANK_MAX[rank] : 0;
+  return roleWandering(rank).ceiling;
 }
 
 // The override a builder has stored (the raw 'wandering' key off behavior_prefs),
@@ -262,6 +303,8 @@ module.exports = {
   LEVELS,
   LEVEL_META,
   LEVEL_CONTRACT,
+  ROLE_WANDERING,
+  roleWandering,
   RANK_DEFAULT,
   RANK_MAX,
   TOP_LEVEL,

package/modules/dev-box/app/README.md

@@ -0,0 +1,73 @@
+# OTB Dev Box — the desktop switch for a builder's hosted box
+
+A menu-bar (macOS) / system-tray (Windows) app that turns a builder's hosted
+dev box on and off with one switch. Built for the newcomer who should never
+see a terminal: sign in with browser clicks (app pairing, ADR 0045), flip the
+switch, and connect from Claude Desktop or the browser terminal.
+
+What it does beyond the switch — each fixing a failure observed in the
+2026-06-10 onboarding sessions that killed the old `curl | bash` flow:
+
+- **Pairing sign-in** — opens the builders' hall, one Approve click, token
+  delivered over the app's own secret channel (`/api/gds/auth/app-pair/*`).
+  The session is written to `~/.config/otb/gds-session.json`, the same file
+  the `/builder-*` CLI uses — pairing the app signs in the CLI too.
+- **SSH key done right** — generates `~/.ssh/otb_builder` (ed25519) with real
+  600 perms (icacls ACL on Windows) and registers it via `POST /box/ssh-key`.
+- **known_hosts kept fresh** — Claude Desktop's embedded ssh2 reads ONLY
+  `~/.ssh/known_hosts`, and host keys change on every re-provision; the app
+  re-scans and replaces entries each time the box turns active.
+- **Claude Desktop connection file** — installs the managed-settings file to
+  the system path with a native elevation prompt (osascript / UAC), the step
+  the agent-driven flow could never finish.
+- **Native notifications** — box ready, rested while idle.
+- **No heartbeats** — the app never sends `claude_active`; the droplet's idle
+  sweep stays authoritative so an unused box still reclaims itself (~10 min).
+
+## Layout
+
+- `src/main.js` — Electron main: tray, window, IPC, wiring.
+- `src/brand.js` — every brand string (ADR 0004: the civ name lives here only).
+- `src/{pairing,box-controller,gds-client,session-store,ssh-setup,updater}.js` — the
+  logic, Electron-free and unit-tested in `test/unit.mjs`.
+- `src/updater.js` — in-app update check (#924): semver compare + platform→target
+  resolution. `main.js` polls `GET /downloads/devbox/version` on open + every 12h
+  and, when the published release is strictly newer, shows the Update banner; the
+  Update button downloads the installer and hands it to the OS (browser-download
+  fallback on any error). **Bumping `config/devbox-app.json` version is what makes
+  the banner appear in the field** — see [`docs/recipes/devbox-app-release.md`](../docs/recipes/devbox-app-release.md).
+- `renderer/` — the panel UI (sandboxed, contextIsolated; preload exposes
+  named verbs only).
+- `scripts/gen-icons.js` — regenerates all icons from pixel grids (`npm run
+  icons`; borrows `sharp` from the repo root's node_modules).
+
+## Develop
+
+```
+cd devbox-app
+npm install
+npm test          # hermetic unit tests, no Electron needed
+npm start         # run against prod (or OTB_DEVBOX_API_BASE=http://… npm start)
+```
+
+Dev/test env hooks: `OTB_DEVBOX_API_BASE` (point at a stub/staging GDS),
+`OTB_DEVBOX_NO_ELEVATE=1` (skip the managed-settings elevation prompt),
+`OTB_DEVBOX_SCREENSHOT_DIR` (write a PNG of the panel on every state change —
+how CI/verification captures proof).
+
+## Build & release
+
+```
+npm run dist:mac   # dmg, arm64 + x64 (unsigned → ad-hoc)
+npm run dist:win   # NSIS one-click installer, x64 + arm64
+```
+
+CI builds both on every push that touches `devbox-app/**`
+(`.github/workflows/build-devbox-app.yml`) and uploads them as artifacts.
+Publishing = attach the artifacts to a release on the PUBLIC releases repo
+named in `config/devbox-app.json`, then bump that config and ship — the
+branded `/downloads/devbox/*` redirects follow the config. Full recipe:
+`docs/recipes/devbox-app-release.md`.
+
+This subproject is self-contained on purpose: its `package.json` never feeds
+the droplet's `npm ci`, and nothing under `devbox-app/` runs server-side.