@bongos/core 1.17.0

package/migrations/060_access_requests.sql

@@ -0,0 +1,46 @@
+-- 060_access_requests.sql — onboarding cold-start (2026-05-30).
+--
+-- A brand-new person who wants to build has a chicken-and-egg problem: the code
+-- lives in a PRIVATE GitHub repo, so they can't do anything until an Archon adds
+-- them as a collaborator. Until now there was no way to ask — the welcome copy
+-- said "an Archon will give thee the link" with no mechanism behind it, and the
+-- Archon was never notified. This table is the request queue that closes that gap.
+--
+-- It is written by an UNAUTHENTICATED visitor (POST /api/gds/access-requests is
+-- the one public write on the GDS) — by definition the requester is outside the
+-- system and has no builder row yet. The only thing we capture is what an Archon
+-- needs to send the GitHub collaborator invite: the GitHub username, an optional
+-- display name, and an optional note. The global IP rate-limiter guards the
+-- endpoint against spam; a partial unique index stops a username from piling up
+-- duplicate open requests.
+--
+-- Lifecycle: pending → invited | dismissed (terminal; the row stays as the audit
+-- trail). 'invited' = an Archon sent the GitHub invite. 'dismissed' = declined /
+-- spam / duplicate. resolved_by_builder_id records which Archon acted.
+
+CREATE TABLE IF NOT EXISTS access_requests (
+  id                       bigserial PRIMARY KEY,
+  github_login             text NOT NULL,
+  display_name             text,
+  note                     text,
+  status                   text NOT NULL DEFAULT 'pending'
+                             CHECK (status IN ('pending', 'invited', 'dismissed')),
+  resolved_by_builder_id   bigint REFERENCES builders(id),
+  resolved_at              timestamptz,
+  created_at               timestamptz NOT NULL DEFAULT now()
+);
+
+-- Archon queue lookup: "open requests, newest first."
+CREATE INDEX IF NOT EXISTS idx_access_requests_pending
+  ON access_requests (created_at DESC)
+  WHERE status = 'pending';
+
+-- At most one OPEN request per GitHub login (case-insensitive). Historical
+-- rows (invited/dismissed) don't conflict, so a username can re-request after
+-- a dismissal.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_access_requests_open_per_login
+  ON access_requests (lower(github_login))
+  WHERE status = 'pending';
+
+INSERT INTO schema_migrations (version) VALUES ('060_access_requests')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/061_backfill_override_ship_attribution.sql

@@ -0,0 +1,29 @@
+-- 061_backfill_override_ship_attribution.sql — fix #538 misattribution (2026-06-02).
+--
+-- Before #538, decideOverrideRequest set tasks.shipped_by = COALESCE(shipped_by,
+-- archonId) when an Archon APPROVED a grader-false-negative override, so the SHIP
+-- was attributed to the approving Archon (driving the builders' hall + peer-vote
+-- feed) instead of the builder who actually did the work — even though the CREDIT
+-- was routed to the requester correctly. The code is fixed; this backfills the
+-- rows the old code already mis-stamped.
+--
+-- Re-point shipped_by to the original requester for every task that an APPROVED
+-- override left attributed to its approving Archon. Idempotent: once
+-- shipped_by = requester (which is DISTINCT FROM the decider) the WHERE no longer
+-- matches, so re-running is a no-op.
+--
+-- Known instance at write time: task #477 (fisher NPC, LarsCode #3), already
+-- corrected by hand on prod under the #538 claim. This migration makes that
+-- correction reproducible in every environment (staging, restored backups) and
+-- auditable in the diff — addressing the grader's blocker that the backfill was
+-- otherwise invisible outside a side-channel psql command.
+
+UPDATE tasks t
+   SET shipped_by = r.requested_by_builder_id,
+       updated_at = now()
+  FROM task_override_requests r
+ WHERE r.task_id = t.id
+   AND r.status = 'approved'
+   AND r.requested_by_builder_id IS NOT NULL
+   AND t.shipped_by = r.decided_by_builder_id
+   AND t.shipped_by IS DISTINCT FROM r.requested_by_builder_id;

package/migrations/062_session_records.sql

@@ -0,0 +1,34 @@
+-- 062_session_records.sql — BFG session-inefficiency evaluator, sub-phase 6D.1
+-- (ADR 0027). Stores a compact, secret-scrubbed digest of each shipped Claude
+-- Code session so the BFG (a LOCAL Claude Code routine — 6D.3) can search the
+-- corpus (6D.2) and deep-dive the wasteful ones.
+--
+-- Design note (privacy + size): the heavy transcript CONTENT is never uploaded.
+-- Each row holds per-turn METADATA (role, tool name, error flag, token usage,
+-- content length) + short secret-scrubbed snippets + token aggregates. That
+-- keeps rows small (KB, not MB) and the secret surface minimal — ADR 0027's
+-- "scrubbed, retention-bounded" posture.
+--
+-- Write path: scripts/gds/ship.js uploads via POST /api/gds/sessions on a
+-- successful ship (best-effort, non-blocking). Deduped per session_id — a
+-- session that ships multiple tasks upserts once, accumulating task_ids.
+-- Read path (6D.2, separate task): self-serve read of one's OWN sessions + an
+-- Archon-gated (BFG-principal when 6C.1 lands) cross-builder search.
+
+CREATE TABLE IF NOT EXISTS session_records (
+  id               bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  session_id       text NOT NULL UNIQUE,             -- Claude Code CLAUDE_CODE_SESSION_ID
+  builder_id       bigint NOT NULL REFERENCES builders(id),
+  task_ids         bigint[] NOT NULL DEFAULT '{}',   -- tasks shipped from this session
+  drachmae_earned  integer NOT NULL DEFAULT 0,       -- credit_log delta attributable to the session
+  total_tokens     bigint NOT NULL DEFAULT 0,        -- summed transcript usage (in + out + cache)
+  duration_seconds integer,                           -- transcript first -> last timestamp
+  started_at       timestamptz,
+  ended_at         timestamptz,
+  uploaded_at      timestamptz NOT NULL DEFAULT now(),
+  detail           jsonb NOT NULL DEFAULT '[]'::jsonb, -- per-turn metadata + short scrubbed snippets
+  metrics          jsonb NOT NULL DEFAULT '{}'::jsonb  -- derived aggregates (turns, tool errors, token buckets)
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_records_builder  ON session_records (builder_id);
+CREATE INDEX IF NOT EXISTS idx_session_records_uploaded ON session_records (uploaded_at DESC);

package/migrations/063_session_records_tool_errors_idx.sql

@@ -0,0 +1,11 @@
+-- 063_session_records_tool_errors_idx.sql — BFG session evaluator 6D.2 (ADR 0027).
+--
+-- searchSessions sorts AND filters on COALESCE((metrics->>'tool_error_count')::int, 0)
+-- (the "interesting session" signal). Postgres only uses an expression index
+-- when the indexed expression EXACTLY matches the query's — so the index must
+-- include the same COALESCE wrapper db.js uses, or it's inert (#541 grade).
+--
+-- Harmless + fast at current scale (the table is tiny); this is forward cover.
+
+CREATE INDEX IF NOT EXISTS idx_session_records_tool_errors
+  ON session_records ((COALESCE((metrics->>'tool_error_count')::int, 0)));

package/migrations/064_grade_attempts.sql

@@ -0,0 +1,18 @@
+-- 064_grade_attempts.sql — BFG session evaluator 6D.6 (ADR 0027).
+--
+-- task_grades has task_id UNIQUE — it keeps only the LATEST grade, so the number
+-- of grade ATTEMPTS (re-grade thrash) is lost. This append-only log records every
+-- grader run so that thrash is countable (the #506-class signal: a task graded
+-- 3+ times burned a lot of tokens). Written best-effort + post-commit by
+-- db.applyGrade — a logging failure never affects the grade that just committed.
+
+CREATE TABLE IF NOT EXISTS grade_attempts (
+  id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  task_id      bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  builder_id   bigint REFERENCES builders(id),
+  passed       boolean NOT NULL,
+  score        numeric(3,1),
+  attempted_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_grade_attempts_task ON grade_attempts (task_id);

package/migrations/065_bfg_principal.sql

@@ -0,0 +1,58 @@
+-- 065_bfg_principal.sql — BFG service principal + cross-builder memory WRITE
+-- substrate (MAS Phase 6 sub-phase 6C.1, ADR 0026 §6C).
+--
+-- THE trust-boundary exception (extends ADR 0016): this lands the IDENTITY half
+-- of the first cross-builder memory WRITE capability in the system. The write
+-- endpoint (src/bongos/routes/memory.js) gates on the EXACT principal identity
+-- (builders.system_role = 'bfg'), NOT on rank — so an Archon token, or any
+-- rank-escalated / stolen token, is rejected at the write endpoint (ADR 0026:
+-- "gate on the exact principal identity, not on rank"). The principal:
+--   * cannot claim work — status='inactive' reuses the existing db.claimTask
+--     guard (BUILDER_INACTIVE), so no new claim-path code is needed;
+--   * cannot earn drachmae — it never claims/ships, so credit_log never grows
+--     for it (and it's rank='xenos', which carries no authority anyway);
+--   * is not loginable — github_id 'system:bfg' is non-numeric, so the GitHub
+--     OAuth upsert path (numeric ids) can never produce or authenticate it.
+--
+-- karma_log.reason is free-text (migration 040) — no schema change is needed to
+-- "add" a reason. This migration DOCUMENTS the new BFG vocabulary so the value
+-- is discoverable in one place:
+--   karma_log.reason  'bfg_correction'        — a transparent, attributed
+--                       negative karma delta the BFG applies ALONGSIDE a visible
+--                       corrective memory note (wired in 6C.2). granted_by = the
+--                       BFG principal id.
+--   audit_log action  'bfg_dream_write' /     — recorded per cross-builder write
+--                     'bfg_correction_write'    by the write endpoint (the
+--                       audit_log.method CHECK only allows write verbs, so the
+--                       true semantics live in request_body_redacted.action,
+--                       mirroring the Archon forensic-read pattern).
+
+-- 1. system_role marker: NULL for every human builder, 'bfg' for the principal.
+--    The write endpoint's identity gate keys on this exact value.
+ALTER TABLE builders ADD COLUMN IF NOT EXISTS system_role text;
+
+-- At most one row per system role (a second 'bfg' row is a bug, not a feature).
+CREATE UNIQUE INDEX IF NOT EXISTS idx_builders_system_role
+  ON builders (system_role) WHERE system_role IS NOT NULL;
+
+-- Defense-in-depth allowlist: system_role may only be NULL or a KNOWN system
+-- role. The app-layer gate (requireBfgPrincipal) checks exact equality, but a
+-- DB-level CHECK means even raw SQL or a future careless update route cannot
+-- mint an arbitrary system_role and ride a (hypothetically relaxed) gate. A new
+-- system principal in the future widens this CHECK in its own migration — an
+-- intentional, reviewable act, not an accident. Idempotent via pg_constraint.
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'builders_system_role_check') THEN
+    ALTER TABLE builders
+      ADD CONSTRAINT builders_system_role_check
+      CHECK (system_role IS NULL OR system_role IN ('bfg'));
+  END IF;
+END $$;
+
+-- 2. The BFG service principal. Idempotent via NOT EXISTS (the #476 guard for
+--    hardcoded natural keys — re-running this migration is a no-op). All three
+--    NOT NULL columns without defaults (github_id, github_login, display_name)
+--    are provided; rank/status are set explicitly though they have defaults.
+INSERT INTO builders (github_id, github_login, display_name, rank, status, system_role)
+SELECT 'system:bfg', 'bfg-system', 'The BFG (system)', 'xenos', 'inactive', 'bfg'
+WHERE NOT EXISTS (SELECT 1 FROM builders WHERE system_role = 'bfg');

package/migrations/066_live_notify_triggers.sql

@@ -0,0 +1,69 @@
+-- #569 — Builders-hall live updates: Postgres NOTIFY triggers.
+--
+-- The builders hall (public-builders/) fetched every panel ONCE at page load
+-- and then froze until a manual refresh — so an onboarding step that ticks
+-- server-side (e.g. after /builder-ship) never showed until the page reloaded.
+-- See docs/adr/0030-builders-hall-live-updates.md for the full design.
+--
+-- This migration is the "something changed" signal source. A single
+-- statement-level AFTER trigger on each table that backs a live panel emits a
+-- pg_notify on the 'gds_live' channel carrying a minimal {table, op} payload.
+-- The GDS process holds one persistent LISTEN connection (src/bongos/live-channel.js)
+-- and relays each notification to the Colyseus BuildersHallRoom
+-- (src/rooms/BuildersHallRoom.js), which broadcasts a nudge over the existing
+-- game WebSocket so the hall re-pulls the affected panels.
+--
+-- Why statement-level (FOR EACH STATEMENT), not row-level:
+--   * The payload carries NO row data — only the table name + op — so we don't
+--     need OLD/NEW. A bulk UPDATE therefore needs exactly one nudge, not one
+--     per row. Statement-level coalesces it for free and keeps write overhead
+--     on these tables negligible.
+--   * The browser de-bounces nudges and re-fetches whole panels regardless, so
+--     per-row granularity would buy nothing.
+--
+-- Why pg_notify (not row data over the wire): it catches EVERY write path —
+-- API routes, background routines, AND direct psql writes (the methodology's
+-- "direct DB writes are work too" reality) — because the trigger lives in the
+-- database, below the application. That direct-write coverage is the whole
+-- point: the original staleness often came from changes the app never saw.
+
+-- Generic notifier. Used by every trigger below. TG_OP / TG_TABLE_NAME are
+-- available in statement-level triggers; OLD/NEW are not, and we don't use them.
+CREATE OR REPLACE FUNCTION gds_notify_live() RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify(
+    'gds_live',
+    json_build_object('table', TG_TABLE_NAME, 'op', TG_OP)::text
+  );
+  RETURN NULL;  -- AFTER STATEMENT triggers ignore the return value
+END;
+$$ LANGUAGE plpgsql;
+
+-- One trigger per table backing a live hall panel:
+--   tasks                    — claimable list, recent ships, the "ship" step
+--   claims                   — claimable list churn, the "claim" step
+--   builders                 — standing (credits/karma cached counters), rank, disciplines
+--   builder_onboarding_state — the onboarding checklist itself (the reported bug)
+--   credit_log / karma_log   — drachmae + karma feeds (and the leaderboard)
+--
+-- DROP-then-CREATE keeps the migration idempotent (CREATE TRIGGER has no
+-- IF NOT EXISTS form before PG 17; the droplet runs PG 16).
+DO $$
+DECLARE t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY[
+    'tasks', 'claims', 'builders',
+    'builder_onboarding_state', 'credit_log', 'karma_log'
+  ] LOOP
+    EXECUTE format('DROP TRIGGER IF EXISTS trg_%s_notify_live ON %I', t, t);
+    EXECUTE format(
+      'CREATE TRIGGER trg_%s_notify_live
+         AFTER INSERT OR UPDATE OR DELETE ON %I
+         FOR EACH STATEMENT EXECUTE FUNCTION gds_notify_live()',
+      t, t
+    );
+  END LOOP;
+END $$;
+
+INSERT INTO schema_migrations (version) VALUES ('066_live_notify_triggers')
+  ON CONFLICT DO NOTHING;

package/migrations/067_builder_boxes.sql

@@ -0,0 +1,117 @@
+-- 067_builder_boxes.sql — #598 (ADR 0031 §2 / §5): per-builder cloud dev box lifecycle.
+--
+-- Context
+-- -------
+-- ADR 0031 decided the worker (the part of Claude Code that opens files and
+-- runs commands) lives on an org-controlled, containerized DigitalOcean box —
+-- ONE per builder (§2). #596 shipped the box-as-code (.devcontainer/). This
+-- migration is the STATE LEDGER for the box LIFECYCLE that #598 builds on top:
+-- provision → run → auto-suspend when idle → reclaim when dormant.
+--
+-- Why a DB table and not just DO's own droplet list: the GDS is the project's
+-- complete ledger (CLAUDE.md hard rule). The lifecycle sweeps (idle-suspend,
+-- dormant-reclaim) need a builder→box mapping, an activity heartbeat, and a
+-- per-builder compute-cost tally that DO's API does not give us. DO holds the
+-- live droplet; this table holds the lifecycle truth we reason over.
+--
+-- §9.3 resolution (recorded in ADR 0031): auto-suspend is SNAPSHOT-AND-PARK,
+-- not a Coder control-plane. DO has no native suspend and a *powered-off*
+-- droplet still bills, so "park" snapshots then DESTROYS the droplet (keeping
+-- only the cheap snapshot, ~$0.30/mo) and "wake" recreates from the snapshot.
+-- That is why `droplet_id`/`ip` are NULLable (gone while parked) but
+-- `snapshot_id` persists across a park.
+--
+-- Idempotent: safe to re-run.
+
+-- ---------------------------------------------------------------------------
+-- builder_boxes — one row per builder, the lifecycle state of their box.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS builder_boxes (
+  id               bigserial PRIMARY KEY,
+  -- One box per builder (ADR 0031 §2: a shared box collides on files/ports/DB).
+  builder_id       bigint NOT NULL UNIQUE REFERENCES builders(id) ON DELETE CASCADE,
+
+  -- Lifecycle state machine (mirrored in src/bongos/boxes.js BOX_STATES):
+  --   none        — no box yet (default; a row may exist pre-provision)
+  --   provisioning— create-droplet in flight
+  --   active       — droplet running, billing compute
+  --   parking      — snapshot+destroy in flight
+  --   parked       — droplet destroyed, only the snapshot remains (cheap)
+  --   waking       — recreate-from-snapshot in flight
+  --   destroyed    — fully de-provisioned (droplet + snapshot gone). The
+  --                  dormant-reclaim sweep moves a long-parked box straight here.
+  --   error        — a lifecycle op failed; needs operator attention
+  state            text NOT NULL DEFAULT 'none'
+    CHECK (state IN ('none','provisioning','active','parking','parked',
+                     'waking','destroyed','error')),
+
+  -- Source-access scope recorded at provision time. CONSUMED by #600 (rank-gated
+  -- source access): 'starter' = a Xenos's scoped surface (art/docs/good-first),
+  -- 'full' = a Metic+'s full private-repo credential. #598 records it; #600
+  -- enforces what the box's GitHub credential can actually reach.
+  scope            text NOT NULL DEFAULT 'starter'
+    CHECK (scope IN ('starter','full')),
+  -- The live rank the builder held when the box was provisioned (audit + #600).
+  provisioned_rank text,
+
+  -- DigitalOcean handles. droplet_id/ip are NULL while parked (droplet gone);
+  -- snapshot_id is the durable residual that a wake restores from.
+  droplet_id       text,
+  droplet_name     text,
+  snapshot_id      text,
+  region           text NOT NULL DEFAULT 'nyc3',
+  size_slug        text NOT NULL DEFAULT 's-2vcpu-4gb',
+  ip               text,
+  -- Stable per-builder DNS (e.g. box-<login>.dev.amazonprimea.com). The droplet
+  -- IP churns on every wake; the hostname is what #599's Desktop managed-settings
+  -- pin to. #598 records it + exposes a DNS hook; #599 owns the cutover.
+  hostname         text,
+
+  -- Activity + lifecycle timestamps.
+  last_activity_at timestamptz, -- bumped by POST /box/heartbeat; drives idle sweep
+  provisioned_at   timestamptz, -- first ever provision
+  active_since     timestamptz, -- when the CURRENT live droplet started billing
+  parked_at        timestamptz, -- when it last entered 'parked' (drives dormant sweep)
+  destroyed_at     timestamptz,
+
+  -- Running tally of compute cost charged to this box (USD). Accrued at park /
+  -- deprovision as (active hours × size hourly rate); also mirrored to cost_log
+  -- (category 'compute', builder-attributed) so the status dashboard sees it.
+  compute_cost_usd numeric(10,4) NOT NULL DEFAULT 0,
+
+  error_note       text,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now()
+);
+
+-- Both sweeps select by state (listBoxes: WHERE state = $1) and then refine by
+-- recency in memory (selectIdleBoxes / selectDormantBoxes), so a single index on
+-- `state` serves every read path. Partial indexes on last_activity_at/parked_at
+-- were deliberately NOT added: they would add write overhead on the hot heartbeat
+-- UPDATE (which touches last_activity_at every ~5 min per active box) without
+-- accelerating any query. If filtering ever moves into SQL at scale, add the
+-- matching index in that same migration.
+CREATE INDEX IF NOT EXISTS idx_builder_boxes_state ON builder_boxes (state);
+
+-- ---------------------------------------------------------------------------
+-- box_events — append-only lifecycle ledger. Direct infra mutations (CLI/sweep)
+-- are project state changes too, so they get an audit row (CLAUDE.md hard rule).
+-- The HTTP audit_log only captures API mutations; lifecycle ops run on the
+-- control-plane CLI, so they record here.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS box_events (
+  id          bigserial PRIMARY KEY,
+  box_id      bigint NOT NULL REFERENCES builder_boxes(id) ON DELETE CASCADE,
+  builder_id  bigint REFERENCES builders(id) ON DELETE SET NULL,
+  -- provision | park | wake | deprovision | heartbeat | cost | error
+  event       text NOT NULL,
+  detail      text,
+  cost_usd    numeric(10,4),
+  -- Who/what triggered it: 'cli:<login>' | 'sweep:idle' | 'sweep:dormant' | 'api'
+  actor       text,
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_box_events_box ON box_events (box_id, created_at DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('067_builder_boxes')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/067_discord_bot_foundation.sql

@@ -0,0 +1,69 @@
+-- 067_discord_bot_foundation.sql — Discord bot service principal + account
+-- linking + cosmetic applause + audit surface (Discord Phase 3 F1, ADR 0033).
+--
+-- Foundation for the Phase 3 bot. The bot is a SERVICE PRINCIPAL, gated by
+-- identity (builders.system_role='discord_bot'), NEVER by rank — the same
+-- pattern as the BFG principal (migration 065 / ADR 0026 §6C). It is trusted
+-- only to assert "this Discord user, who reacted/posted, is linked builder X";
+-- every write it triggers re-checks X's live rank server-side (ADR 0033 §1).
+--
+-- Decision-independent substrate: needs no live bot. Account linking (F2), the
+-- bot process (F3), upvoting (F4), role-sync (F5) and inbound (F6) build on top.
+
+-- 1. Widen the system_role allowlist to admit the discord_bot principal. The
+--    CHECK was introduced by migration 065 ('bfg' only); adding a new system
+--    principal widens it in its own migration — an intentional, reviewable act
+--    (065's own note). Drop-then-add is idempotent on re-run, and every existing
+--    row (NULL for humans, 'bfg' for the BFG) already satisfies the wider set.
+ALTER TABLE builders DROP CONSTRAINT IF EXISTS builders_system_role_check;
+ALTER TABLE builders
+  ADD CONSTRAINT builders_system_role_check
+  CHECK (system_role IS NULL OR system_role IN ('bfg', 'discord_bot'));
+
+-- 2. The Discord bot service principal. Mirrors the BFG principal exactly:
+--    * cannot claim work — status='inactive' trips the db.claimTask guard;
+--    * cannot earn drachmae — it never claims/ships, and rank='xenos' carries
+--      no authority anyway;
+--    * is not loginable — github_id 'system:discord_bot' is non-numeric, so the
+--      GitHub OAuth upsert (numeric ids) can never produce or authenticate it.
+--    The bot authenticates via a session token minted out-of-band (F3); the
+--    requireDiscordBot gate keys on system_role='discord_bot', not rank.
+--    Idempotent via NOT EXISTS (the #476 hardcoded-natural-key guard).
+INSERT INTO builders (github_id, github_login, display_name, rank, status, system_role)
+SELECT 'system:discord_bot', 'discord-bot-system', 'Discord Bot (system)', 'xenos', 'inactive', 'discord_bot'
+WHERE NOT EXISTS (SELECT 1 FROM builders WHERE system_role = 'discord_bot');
+
+-- 3. Account links: builder <-> Discord user, 1:1 both ways. A row exists only
+--    because the builder PERSONALLY linked their Discord via the UI-first OAuth
+--    flow (F2) — the bot never invents a mapping (ADR 0033 §2). PRIMARY KEY
+--    (builder_id) = at most one Discord per builder; UNIQUE (discord_user_id) =
+--    at most one builder per Discord. ON DELETE CASCADE: offboarding drops it.
+CREATE TABLE IF NOT EXISTS discord_links (
+  builder_id       bigint      NOT NULL PRIMARY KEY REFERENCES builders(id) ON DELETE CASCADE,
+  discord_user_id  text        NOT NULL UNIQUE,
+  linked_at        timestamptz NOT NULL DEFAULT now()
+);
+
+-- 4. Cosmetic applause — the "everyone" half of both-mode upvoting (ADR 0033
+--    §3). A reaction by anyone (player, Xenos, unlinked, self) lands here and
+--    NEVER touches karma_log. One applause per Discord user per target task;
+--    re-reacting is a harmless no-op (ON CONFLICT DO NOTHING in the helper).
+--    discord_user_id is stored raw (no FK to discord_links) precisely because
+--    applause does NOT require a link — that is the point of the cosmetic tier.
+CREATE TABLE IF NOT EXISTS discord_applause (
+  id               bigserial   PRIMARY KEY,
+  target_task_id   bigint      NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  discord_user_id  text        NOT NULL,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (target_task_id, discord_user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_discord_applause_task ON discord_applause (target_task_id);
+
+-- 5. Audit surface (ADR 0033 §1 + the grader's forensic note). NULL for direct
+--    human web/CLI writes; set to the system-principal id (e.g. 'discord_bot')
+--    for principal-originated writes, so "all bot-originated writes" is a clean
+--    WHERE clause for forensic review. Populated by the bot endpoints (F4);
+--    additive + nullable, so existing audit rows are unaffected.
+ALTER TABLE audit_log ADD COLUMN IF NOT EXISTS surface text;
+COMMENT ON COLUMN audit_log.surface IS
+  'Originating surface: NULL for direct human web/CLI writes, or a system principal id (e.g. discord_bot, bfg). Lets forensic review distinguish principal-originated writes (ADR 0033).';

package/migrations/068_thetes_requires_rank.sql

@@ -0,0 +1,27 @@
+-- 068_thetes_requires_rank.sql — #692 / ADR 0034: make `thetes` a 4th LIVE rank.
+--
+-- Context: `thetes` is the GRADUATED-newcomer rank, sitting between `xenos`
+-- (sandboxed entry) and `metic` (trusted working rank): ladder is
+--   archon > metic > thetes > xenos.
+-- A Thetes escapes the newcomer_friendly sandbox and claims the whole general
+-- queue (any task with requires_rank='xenos', the default) but is blocked from
+-- tasks raised to requires_rank='metic'/'archon'. A Xenos auto-graduates here
+-- after 3 confirmed tasks (server-side, in the confirm transaction — db.js
+-- maybeAutoGraduateToThetes).
+--
+-- `thetes` is ALREADY allowed by builders.rank's CHECK (migration 023 reserved
+-- the full ladder up front), so this migration only widens the INVERSE gate:
+-- tasks.requires_rank, whose CHECK (migration 044) currently allows just
+-- xenos/metic/archon. Without this, an Archon could never raise a task's floor
+-- to 'thetes', and rankAllowsTask's tier comparison would have no schema-backed
+-- domain for the value.
+--
+-- Idempotent: drops + re-adds the named constraint, safe to re-run.
+
+ALTER TABLE tasks DROP CONSTRAINT IF EXISTS tasks_requires_rank_enum;
+ALTER TABLE tasks
+  ADD CONSTRAINT tasks_requires_rank_enum
+  CHECK (requires_rank IN ('xenos', 'thetes', 'metic', 'archon'));
+
+INSERT INTO schema_migrations (version) VALUES ('068_thetes_requires_rank')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/069_builder_ssh_keys.sql

@@ -0,0 +1,66 @@
+-- 069_builder_ssh_keys.sql — #685 (ADR 0031 §1/§6): server-side SSH-key distribution.
+-- (Renumbered 068→069 at ship time: main had meanwhile merged 068_thetes_requires_rank.)
+--
+-- Context
+-- -------
+-- Today, connecting a builder's Claude Desktop to their dev box requires the
+-- operator to SSH into the box and hand-append the builder's public key to
+-- ~/.ssh/authorized_keys — a manual round-trip across two machines (the builder
+-- ssh-keygens, pastes the public half back, the operator installs it). #685
+-- removes that round-trip: the builder registers their OWN public key with the
+-- GDS (POST /box/ssh-key), and the box PULLS its authorized_keys from the GDS at
+-- boot + on a cron (GET /box/authorized-keys), exactly like it already pulls
+-- rank-gated source (#600 / box-source-fetch.sh).
+--
+-- This table is the registry that backs both. A public SSH key is NOT a secret
+-- (it is, by design, the half you hand out), so it lives in the DB in the clear —
+-- unlike the box source CREDENTIAL, which stays in the prod env (ADR 0022). The
+-- security property is the SAME as source access: GET /box/authorized-keys is
+-- gated on the builder's LIVE rank+status (box-access.decideSourceAccess), so a
+-- demoted/deactivated builder's keys stop being served on the box's very next
+-- fetch — instant, credential-layer offboarding (the droplet teardown is the
+-- slower control-plane half via `box.js reconcile`). Empty served file = no SSH
+-- login = the box is locked even before it is destroyed.
+--
+-- Idempotent: safe to re-run.
+
+-- ---------------------------------------------------------------------------
+-- builder_ssh_keys — public SSH keys a builder authorizes for their dev box.
+-- Many keys per builder (laptop + desktop + a re-key); de-duped by fingerprint.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS builder_ssh_keys (
+  id            bigserial PRIMARY KEY,
+  builder_id    bigint NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+
+  -- The full authorized_keys line as the builder presented it, already
+  -- validated + normalized server-side to "<type> <base64> [comment]" (a single
+  -- line, no shell metacharacters) by src/bongos/box-onboard.validateSshPublicKey.
+  -- Stored verbatim so GET /box/authorized-keys can emit it unchanged.
+  public_key    text NOT NULL,
+  -- Algorithm token (ssh-ed25519 | ssh-rsa | ecdsa-sha2-* | sk-*). Recorded for
+  -- the roster/audit and so a future policy ("ed25519 only") is a pure filter.
+  key_type      text NOT NULL,
+  -- SHA256 fingerprint (base64, no padding — the `SHA256:...` form ssh-keygen
+  -- prints). The natural de-dupe key: re-registering the same key is a no-op,
+  -- not a duplicate authorized_keys line on the box.
+  fingerprint   text NOT NULL,
+  -- Human label for the roster ("box-connect macOS 2026-06-05"); never trusted
+  -- input on the box side (it is a comment, not part of the key material).
+  label         text,
+
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  -- Bumped when GET /box/authorized-keys serves this key to a live box, so the
+  -- roster can show "last seen on a box" without a separate events table.
+  last_used_at  timestamptz,
+
+  -- One row per (builder, key). Re-registering the same key updates the label /
+  -- last_used_at via ON CONFLICT rather than inserting a duplicate.
+  UNIQUE (builder_id, fingerprint)
+);
+
+-- The hot read path is "every key for THIS builder" (GET /box/authorized-keys,
+-- GET /box/ssh-key). A single index on builder_id serves both.
+CREATE INDEX IF NOT EXISTS idx_builder_ssh_keys_builder ON builder_ssh_keys (builder_id);
+
+INSERT INTO schema_migrations (version) VALUES ('069_builder_ssh_keys')
+  ON CONFLICT (version) DO NOTHING;