@bongos/core 1.19.887 → 1.19.889

package/scripts/gds/db-backup-offsite.sh

@@ -17,6 +17,36 @@
 # ADR 0022. The systemd unit injects them via EnvironmentFile; a manual run
 # sources the same file. Required vars:
 #   SPACES_KEY SPACES_SECRET SPACES_BUCKET SPACES_REGION SPACES_ENDPOINT
+#   GDS_OFFSITE_AGE_RECIPIENT
+#
+# ENCRYPTION IS MANDATORY (task 1003372, audit ref A1). Until that task this
+# script uploaded the raw pg_dump to the Space. A database dump is not "a backup"
+# from a security standpoint — it is every secret the platform holds, in one
+# file, on someone else's disk: OAuth credentials, the GitHub App private key,
+# and (before core_249) every builder's live session bearer in plaintext. A
+# breach of the Space, a mis-set bucket ACL, or a leaked read-only S3 key was a
+# total compromise of the instance with no trace in any log the platform keeps.
+#
+# The dump is encrypted to a PUBLIC key (`age`), so this box can produce backups
+# it cannot itself read. That asymmetry is the point: an attacker who owns the
+# droplet gets the live database anyway, but they do not also get the archive of
+# every previous state, and they cannot decrypt what is already in the Space.
+# Keep the private key OFF this machine.
+#
+# One-time setup, on a machine that is NOT the server:
+#   age-keygen -o bongos-backup.key      # store this somewhere safe and offline
+#   # it prints:  Public key: age1xxxxxxxx...
+# Then on the server, add to $ENV_FILE:
+#   GDS_OFFSITE_AGE_RECIPIENT=age1xxxxxxxx...
+#
+# To restore:
+#   age -d -i bongos-backup.key <dump>.sql.gz.age | gunzip | psql <db>
+#
+# WITHOUT A RECIPIENT THIS SCRIPT REFUSES TO RUN. It does not fall back to a
+# plaintext upload: that fallback is the vulnerability, and a silent one, since
+# a backup that "worked" looks identical either way. A failing timer is visible
+# in `systemctl status gds-db-offsite.timer`; an unencrypted dump in a bucket is
+# visible to nobody until it matters.
 #
 # Manual one-shot:
 #   <instance-root>/scripts/gds/db-backup-offsite.sh
@@ -72,13 +102,17 @@ ENV_FILE="${GDS_SPACES_ENV:-${CONFIG_DIR_NAME:+/etc/$CONFIG_DIR_NAME/spaces.env}
 # extract only the five expected KEY=VALUE lines. `read -r k v` with IFS='='
 # splits on the FIRST '=' only, so base64 secrets containing '/', '+' or '='
 # survive intact.
-if [ -z "${SPACES_KEY:-}" ] && [ -f "$ENV_FILE" ]; then
+# Read the file when EITHER the credentials or the encryption recipient is still
+# unset. Keying this on SPACES_KEY alone would skip the file on a box where
+# systemd injects the S3 vars but the recipient was added to the file later —
+# and the script would then refuse to run while the key it needs sat right there.
+if { [ -z "${SPACES_KEY:-}" ] || [ -z "${GDS_OFFSITE_AGE_RECIPIENT:-}" ]; } && [ -f "$ENV_FILE" ]; then
   while IFS='=' read -r _k _v; do
     case "$_k" in
-      SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)
+      SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT|GDS_OFFSITE_AGE_RECIPIENT)
         export "$_k=$_v" ;;
     esac
-  done < <(grep -E '^(SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)=' "$ENV_FILE" || true)
+  done < <(grep -E '^(SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT|GDS_OFFSITE_AGE_RECIPIENT)=' "$ENV_FILE" || true)
 fi
 
 missing=()
@@ -91,8 +125,30 @@ if [ "${#missing[@]}" -gt 0 ]; then
   exit 2
 fi
 
+# The encryption recipient is as required as the credentials — a dump this box
+# can upload but nobody can decrypt is useless, and a dump it uploads in the
+# clear is the finding this refusal exists to close (task 1003372, audit A1).
+if [ -z "${GDS_OFFSITE_AGE_RECIPIENT:-}" ]; then
+  echo "ERROR: GDS_OFFSITE_AGE_RECIPIENT is not set — refusing to ship an unencrypted database dump offsite." >&2
+  echo "       A dump is every secret this platform holds, in one file, on storage the platform does not own." >&2
+  echo "" >&2
+  echo "       Fix, on a machine that is NOT this server:" >&2
+  echo "         age-keygen -o bongos-backup.key     # keep this file safe and OFFLINE — it is the only way back" >&2
+  echo "       then add the age1... public key it prints to $ENV_FILE:" >&2
+  echo "         GDS_OFFSITE_AGE_RECIPIENT=age1..." >&2
+  echo "" >&2
+  echo "       This is deliberately not optional: falling back to a plaintext upload would look identical in the logs." >&2
+  exit 2
+fi
+
+
 # ---- preconditions ----------------------------------------------------------
 
+if ! command -v age >/dev/null 2>&1; then
+  echo "ERROR: 'age' not on PATH — it is what encrypts the dump before it leaves this box." >&2
+  echo "       Install with: apt install age   (or fetch the static binary from https://github.com/FiloSottile/age/releases)" >&2
+  exit 2
+fi
 if ! command -v python3 >/dev/null 2>&1; then
   echo "ERROR: python3 not on PATH (needed for the boto3 S3 client)." >&2
   exit 2
@@ -113,14 +169,38 @@ if [ -z "$LATEST" ]; then
 fi
 
 BASENAME=$(basename "$LATEST")
-KEY="${PREFIX}${BASENAME}"
 BYTES=$(stat -c '%s' "$LATEST")
 
-echo "[$(date -u +%FT%TZ)] gds-db-offsite: archiving ${LATEST} (${BYTES} bytes) → s3://${SPACES_BUCKET}/${KEY}"
+# ---- encrypt before it leaves the box ---------------------------------------
+#
+# To a temp file under the backup dir (same filesystem, so no cross-device copy
+# of plaintext through /tmp) with a 0600 umask, and removed on every exit path
+# including failure — the cleartext dump already lives beside it, so the
+# ciphertext is not sensitive in itself, but leaving files behind on a failing
+# weekly timer fills a disk nobody is watching.
+umask 077
+ENC="$(mktemp "${BACKUP_DIR}/.${BASENAME}.age.XXXXXX")"
+trap 'rm -f "$ENC"' EXIT
+
+if ! age -r "$GDS_OFFSITE_AGE_RECIPIENT" -o "$ENC" "$LATEST"; then
+  echo "ERROR: age refused to encrypt — is GDS_OFFSITE_AGE_RECIPIENT a valid age1... public key?" >&2
+  exit 2
+fi
+
+# A zero-byte or missing ciphertext would upload happily and restore to nothing.
+# Checked here rather than trusted, because the failure is silent for a month.
+ENC_BYTES=$(stat -c '%s' "$ENC")
+if [ "$ENC_BYTES" -lt 1 ]; then
+  echo "ERROR: encryption produced an empty file — refusing to upload it as a backup." >&2
+  exit 2
+fi
+
+KEY="${PREFIX}${BASENAME}.age"
+echo "[$(date -u +%FT%TZ)] gds-db-offsite: archiving ${LATEST} (${BYTES} bytes → ${ENC_BYTES} encrypted) → s3://${SPACES_BUCKET}/${KEY}"
 
 # ---- upload + prune (single boto3 session) ----------------------------------
 
-GDS_OFFSITE_LOCAL="$LATEST" \
+GDS_OFFSITE_LOCAL="$ENC" \
 GDS_OFFSITE_KEY="$KEY" \
 GDS_OFFSITE_KEEP="$KEEP" \
 GDS_OFFSITE_PREFIX="$PREFIX" \
@@ -151,10 +231,25 @@ s3 = boto3.client(
 s3.upload_file(local, bucket, objkey)
 print(f"[gds-db-offsite] uploaded {objkey}")
 
-# Prune: keep the newest `keep` objects under our prefix, delete the rest.
 resp = s3.list_objects_v2(Bucket=bucket, Prefix=prefix)
+contents = resp.get("Contents", [])
+
+# PURGE THE PLAINTEXT ALREADY UP THERE (task 1003372, audit A1). Every `.sql.gz`
+# under this prefix was uploaded unencrypted by an earlier version of this
+# script, and each one is a live copy of every secret the platform held on the
+# day it was taken — including, before core_249, directly replayable session
+# bearers. Encrypting from now on does nothing about them. They are deleted
+# OUTSIDE the retention count, and unconditionally: retaining four of them
+# "for safety" would retain the finding. The local nightly dumps on the droplet
+# are untouched, so this removes copies, never the last copy.
+legacy = [o for o in contents if o["Key"].endswith(".sql.gz")]
+for obj in legacy:
+    s3.delete_object(Bucket=bucket, Key=obj["Key"])
+    print(f"[gds-db-offsite] PURGED unencrypted legacy dump {obj['Key']}")
+
+# Prune: keep the newest `keep` ENCRYPTED objects under our prefix.
 objects = sorted(
-    [o for o in resp.get("Contents", []) if o["Key"].endswith(".sql.gz")],
+    [o for o in contents if o["Key"].endswith(".sql.gz.age")],
     key=lambda o: o["LastModified"],
 )
 to_delete = objects[:-keep] if len(objects) > keep else []
@@ -163,7 +258,8 @@ for obj in to_delete:
     print(f"[gds-db-offsite] pruned {obj['Key']}")
 
 kept = min(len(objects), keep)
-print(f"[gds-db-offsite] ok · {kept} offsite dump(s) retained · pruned {len(to_delete)}")
+print(f"[gds-db-offsite] ok · {kept} offsite dump(s) retained · pruned {len(to_delete)}"
+      + (f" · purged {len(legacy)} unencrypted legacy dump(s)" if legacy else ""))
 PYEOF
 
 echo "[$(date -u +%FT%TZ)] gds-db-offsite: done"

package/scripts/gds/run-unit-tests.js

@@ -171,6 +171,14 @@ const INTEGRATION = new Set([
   // real engine can show the CASE guard leaving a NULL alone on an actual use,
   // which is exactly where the removed timeout would come back.
   'auth_session_expiry_db',
+  // task 1003372 (audit A1, core_249): that hashing the bearer at rest does not
+  // sign anybody out. The DB-free sibling (session_token_hash) stands in front of
+  // the pool and proves the plaintext never reaches a query — the negative that
+  // matters — but it cannot show that Postgres accepts the migration, nor that
+  // the digest the backfill computes in SQL equals the one the kernel computes in
+  // Node. That mismatch would leave every new session working and every migrated
+  // one dead, which is the failure a source-reading test walks straight past.
+  'session_token_hash_db',
   'scouting_rollup_fanout', 'session_records',
   // task 1003217: the cost-row RAISE against real SQL. Every claim in it IS the
   // SQL — an ON CONFLICT DO UPDATE guarded to move a row only upward, and a

package/src/bongos/db-kernel.js

@@ -23,6 +23,7 @@
 
 'use strict';
 
+const crypto = require('node:crypto');
 const { pool } = require('./pool');
 const seams = require('../module-seams');
 
@@ -277,8 +278,37 @@ async function accessStateByLogin(login) {
 // code agree on one number.
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 
+// sessionTokenHash — the ONE place a bearer becomes the value this table stores
+// (task 1003372, audit A1, migration core_249). SHA-256 hex, matching the
+// migration's `encode(sha256(token::bytea), 'hex')` byte for byte, so a row
+// backfilled in SQL and a row minted here resolve identically.
+//
+// WHY A FAST HASH. A session token is 256 bits of CSPRNG, not a password: there
+// is no dictionary to run, so a KDF would buy nothing and cost real latency on
+// every authenticated request. Same reasoning, written out at length, in
+// modules/platform-identity/platform-identity.js (`sha256hex`).
+//
+// WHY NO timingSafeEqual HERE, THOUGH THE TASK NAMED IT. The pattern the task
+// points at compares a presented secret against one it already fetched by
+// client_id, so the comparison happens in JS and must be constant-time. A session
+// has no second identifier — the bearer IS the lookup key — so the comparison is
+// the indexed `WHERE token_hash = $1` below, and there is no JS compare to make
+// constant-time. Adding a timingSafeEqual after that lookup would compare the
+// hash to itself: vacuously true, and worse than nothing, because it would read
+// as a control that is doing something. The property the task wanted — a guessed
+// token leaks no information about how close it was — holds here because the
+// index is probed with a full digest, never a prefix.
+function sessionTokenHash(token) {
+  return crypto.createHash('sha256').update(String(token), 'utf8').digest('hex');
+}
+
 // createSession — mint a builder_sessions row.
 //
+// THE PLAINTEXT BEARER IS NEVER STORED (task 1003372). `token` is hashed on the
+// way in and the column that held it is gone (core_249). The raw value is
+// returned to the caller — it is their input, handed back so the mint response
+// can carry it to the client — and after that it exists only in the client.
+//
 // A null/undefined expiresAt means NO EXPIRY (expires_at NULL), which
 // lookupSession honours as never-expires. That is the CLI's contract (ADR 0294,
 // restoring 003_pms.sql's original one): a `bongos` sign-in lasts until it is
@@ -290,12 +320,15 @@ const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 async function createSession({ builderId, token, source, userAgent, expiresAt }) {
   const effectiveExpiresAt = expiresAt ?? null;
   const { rows } = await pool.query(
-    `INSERT INTO builder_sessions (builder_id, token, source, user_agent, expires_at)
+    `INSERT INTO builder_sessions (builder_id, token_hash, source, user_agent, expires_at)
      VALUES ($1, $2, $3, $4, $5)
-     RETURNING id, builder_id, token, source, created_at, expires_at`,
-    [builderId, token, source, userAgent ?? null, effectiveExpiresAt]
+     RETURNING id, builder_id, source, created_at, expires_at`,
+    [builderId, sessionTokenHash(token), source, userAgent ?? null, effectiveExpiresAt]
   );
-  return rows[0];
+  // `token` is re-attached from the ARGUMENT, never read back from the row — the
+  // row no longer holds it. Callers that pass a token and read one back are
+  // unchanged; what changed is that the database never saw the plaintext.
+  return { ...rows[0], token };
 }
 
 // lookupSession — resolve a live (unrevoked, unexpired) session token to its
@@ -346,8 +379,8 @@ async function lookupSession(token) {
             b.rank, b.status, b.system_role, b.anthropic_user_id${sessionPermsSelect()}
        FROM builder_sessions s
        JOIN builders b ON b.id = s.builder_id
-      WHERE s.token = $1`,
-    [token]
+      WHERE s.token_hash = $1`,
+    [sessionTokenHash(token)]
   );
   const row = rows[0];
   if (!row) return null;
@@ -376,6 +409,9 @@ async function lookupSession(token) {
 module.exports = {
   withTx,
   sessionPermsSelect,
+  // Exported for db.js's revokeSession (which is handed a bearer, not an id) and
+  // for the tests that assert the plaintext never reaches a query parameter.
+  sessionTokenHash,
   getBuilderById,
   getFoundingBuilder,
   listActiveBuilders,

package/src/bongos/db.js

@@ -44,6 +44,9 @@ const {
   // internal uses (setBuilderRank's RANKS.indexOf, etc.) stay byte-identical.
   RANKS, SESSION_TTL_MS, upsertBuilder, seatFirstAdminIfUnclaimed,
   getBuilderByGithubId, hasInvitedAccessRequest, createSession, lookupSession,
+  // The bearer → stored-value transform (task 1003372, core_249). revokeSession
+  // below is the one helper here still handed a raw bearer rather than an id.
+  sessionTokenHash,
 } = require('./db-kernel');
 
 // gradePassCount removed with builderRollingAvgGrade (its only core user) — that
@@ -728,10 +731,14 @@ async function hasCliSession(builderId) {
 // lookupSession — carved to ./db-kernel (ADR 0102). Re-exported above.
 
 
+// Takes the raw bearer (its callers are sign-out paths holding a cookie or an
+// Authorization header, not a session id) and matches on the stored hash —
+// core_249 dropped the plaintext column, so the bearer itself is no longer
+// something this table can be searched by.
 async function revokeSession(token) {
   await pool.query(
-    `UPDATE builder_sessions SET revoked_at = now() WHERE token = $1 AND revoked_at IS NULL`,
-    [token]
+    `UPDATE builder_sessions SET revoked_at = now() WHERE token_hash = $1 AND revoked_at IS NULL`,
+    [sessionTokenHash(token)]
   );
 }
 

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.887'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.889'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/agents_cron_trigger.mjs

@@ -0,0 +1,133 @@
+// tests/agents_cron_trigger.mjs — 'cron' is a trigger type that can EXIST
+// (task 1004008, goal 1000095).
+//
+// Tasks 1002498 (cron-router poller) and 1002501 (cron roster) both select "due
+// cron agents" from a set that was empty by construction: agents_001 pinned
+// trigger_type to ('event','on-demand') on BOTH agents_definitions and
+// agents_runs, and lib/validate.js mirrored it. A poller built against that is
+// correct, tested, and unreachable — green tests over a branch nothing can enter.
+//
+// What this locks:
+//   * the THREE places that must agree (validator, definitions CHECK, runs CHECK)
+//     — the ledger constraint is the one that is easy to forget, and forgetting it
+//     yields the worst shape available: an agent that looks armed, fires, and
+//     then violates a CHECK when it tries to record the run.
+//   * the cadence VOCABULARY, including the sub-hourly divisor rule.
+//   * that validate.js's duplicated CADENCES really match scripts/gds/
+//     routine-schedule.js's, which is the copy this one was made from.
+//   * that widening the enum did not loosen it — an unwired name is still refused.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const v = require('../modules/agents/lib/validate.js');
+const schedule = require('../scripts/gds/routine-schedule.js');
+
+const sql = (f) => fs.readFileSync(path.join(ROOT, 'modules', 'agents', 'migrations', f), 'utf8');
+const mig001 = sql('agents_001_definitions.sql');
+const mig005 = sql('agents_005_cron_trigger.sql');
+
+const def = (over = {}) => ({ name: 'ship-digest', persona: 'x'.repeat(40), ...over });
+const cron = (cadence) => def({ trigger_type: 'cron', trigger_spec: { cadence } });
+
+// ---- 1. the validator ------------------------------------------------------
+
+test("'cron' is a wired trigger type", () => {
+  assert.ok(v.TRIGGER_TYPES.includes('cron'));
+  // Widening is not loosening: the enum is still closed.
+  assert.equal(v.validateAgentDefinition(def({ trigger_type: 'webhook', trigger_spec: {} })).ok, false);
+  assert.deepEqual([...v.TRIGGER_TYPES].sort(), ['cron', 'event', 'on-demand']);
+});
+
+test('a cron definition must say WHEN, or it can never fire', () => {
+  const r = v.validateAgentDefinition(def({ trigger_type: 'cron', trigger_spec: {} }));
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.code === 'trigger_cadence_missing'),
+    'the missing cadence is named as its own error, not folded into a generic spec failure');
+});
+
+test('the cadence vocabulary: named, and sub-hourly where N divides 60', () => {
+  for (const good of ['hourly', 'daily', 'weekly', 'monthly', '15min', '5min', '30min', '1min']) {
+    assert.equal(v.validateAgentDefinition(cron(good)).ok, true, `${good} is a cadence`);
+  }
+  // 7 and 45 do not divide 60: `*/7` fires :00…:56 then waits 4, so the declared
+  // period and the realized period would be different claims.
+  for (const bad of ['7min', '45min', '0min', '60min', 'fortnightly', 'often', '']) {
+    assert.equal(v.validateAgentDefinition(cron(bad)).ok, false, `${bad} is not a cadence`);
+  }
+});
+
+test('an accepted cron definition keeps its cadence through normalization', () => {
+  // The bug class task 1004007 documents one axis over: validate accepted a field
+  // and then DROPPED it, so a definition looked configured and was not.
+  const r = v.validateAgentDefinition(cron('daily'));
+  assert.equal(r.ok, true);
+  assert.equal(r.value.trigger_spec.cadence, 'daily', 'the cadence survives into the normalized value');
+  assert.equal(r.value.trigger_type, 'cron');
+});
+
+test('the event path is untouched', () => {
+  assert.equal(v.validateAgentDefinition(def({ trigger_type: 'event', trigger_spec: { event: 'task.shipped' } })).ok, true);
+  assert.equal(v.validateAgentDefinition(def({ trigger_type: 'event', trigger_spec: {} })).ok, false);
+  assert.equal(v.validateAgentDefinition(def({ trigger_type: 'event', trigger_spec: { event: 'nope' } })).ok, false);
+});
+
+test('a VALID cadence on a non-cron definition is accepted, as a wired event is', () => {
+  // Pinned because the reach is a judgement call and the comment beside the code
+  // claims exactly this. An UNWIRED cadence is still refused wherever it appears.
+  assert.equal(v.validateAgentDefinition(def({ trigger_type: 'on-demand', trigger_spec: { cadence: 'daily' } })).ok, true);
+  assert.equal(v.validateAgentDefinition(def({ trigger_type: 'on-demand', trigger_spec: { cadence: '7min' } })).ok, false);
+});
+
+// ---- 2. the copy that is free to drift -------------------------------------
+
+test('validate.js CADENCES agrees with routine-schedule.js, the copy it came from', () => {
+  // A module may require only src/module-api.js (ADR 0083), so validate.js cannot
+  // import this list — it holds a duplicate. This test is the thing that keeps the
+  // duplicate honest; without it the two are one edit away from disagreeing about
+  // what a cadence is, and nothing would say so until a tick.
+  assert.deepEqual([...v.CADENCES].sort(), [...schedule.CADENCES].sort());
+  for (const n of [1, 5, 7, 15, 30, 45, 60, 0]) {
+    assert.equal(v.isCadence(`${n}min`), schedule.isCadence(`${n}min`),
+      `the two copies agree on ${n}min`);
+  }
+});
+
+// ---- 3. both CHECK constraints ---------------------------------------------
+
+test('BOTH tables widen — the ledger as well as the definition', () => {
+  // agents_001 constrains trigger_type on agents_runs too. Widen only the
+  // definition and a cron agent stores, enables, fires, and THEN fails when the
+  // run insert violates its own CHECK.
+  for (const c of ['agents_definitions_trigger_type_chk', 'agents_runs_trigger_type_chk']) {
+    assert.ok(mig001.includes(c), `${c} exists in agents_001 — this test is about widening it`);
+    assert.match(mig005, new RegExp(`ADD CONSTRAINT ${c}[\\s\\S]{0,200}?'cron'`),
+      `${c} is re-added including 'cron'`);
+    assert.match(mig005, new RegExp(`DROP CONSTRAINT ${c}`),
+      `${c} is dropped before being re-added — ALTER cannot widen a CHECK in place`);
+  }
+});
+
+test('the migration pins the SHAPE of a cron spec, leaving the vocabulary to the validator', () => {
+  assert.match(mig005, /agents_definitions_trigger_spec_cadence_chk/);
+  assert.match(mig005, /trigger_type <> 'cron'/, 'the guard only binds cron rows');
+  assert.match(mig005, /trigger_spec \? 'cadence'/, 'and requires the key');
+  // The sub-hourly divisor rule must NOT be spelled in SQL — that would be a
+  // second copy of isCadence(), free to drift from the one the validator uses.
+  assert.ok(!/% *60|divid/i.test(mig005.replace(/^--.*$/gm, '')),
+    'no arithmetic cadence rule in the executable SQL — the predicate lives in one place');
+});
+
+test('the migration is additive, namespaced and idempotent (ADR 0083 §5)', () => {
+  assert.match(mig005, /IF (NOT )?EXISTS/, 'guarded so a re-run is safe');
+  assert.ok(!/\bDROP TABLE\b|\bDROP COLUMN\b/i.test(mig005), 'nothing is destroyed');
+  for (const stmt of mig005.match(/(CREATE|ALTER)\s+TABLE\s+(\w+)/gi) || []) {
+    assert.match(stmt, /\s(agents_\w+)$/, `${stmt} touches only agents_-namespaced tables`);
+  }
+});

package/tests/agents_validate.mjs

@@ -164,12 +164,20 @@ await test('an on-demand definition carrying a WIRED event is accepted', () => {
 
 // --- THE TRIGGER TYPE -------------------------------------------------------
 
-await test('TRIGGER_TYPES is the v1 pair the DB CHECK also pins', () => {
-  assert.deepEqual(TRIGGER_TYPES, ['event', 'on-demand']);
+await test('TRIGGER_TYPES is the wired set the DB CHECK also pins', () => {
+  // Was the v1 PAIR; task 1004008 added 'cron' so tasks 1002498/1002501 select
+  // from a set that can be non-empty. Kept as an exact list on purpose: widening
+  // this vocabulary must be a deliberate edit here AND in agents_005's CHECK on
+  // both agents_definitions and agents_runs (tests/agents_cron_trigger.mjs pins
+  // that the three agree).
+  assert.deepEqual(TRIGGER_TYPES, ['event', 'on-demand', 'cron']);
 });
 
 await test('an unknown trigger type is refused', () => {
-  for (const bad of ['cron', 'webhook', 'Event', 'on demand', '', null, undefined, 7, {}]) {
+  // 'cron' was this list's first entry until task 1004008 wired it. 'webhook' and
+  // 'schedule' are the plausible-but-unwired names now — the case exists to prove
+  // an unwired name is refused, so it needs names that are actually unwired.
+  for (const bad of ['webhook', 'schedule', 'Event', 'on demand', '', null, undefined, 7, {}]) {
     const r = validateAgentDefinition({ ...OK_DEF, trigger_type: bad }, OPTS);
     assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
     assert.ok(hasCode(r, 'trigger_type_unknown'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
@@ -471,7 +479,7 @@ await test('a hostile getter cannot escape the validator', () => {
 
 await test('EVERY error carries a code, a field and a human message', () => {
   const r = validateAgentDefinition(
-    { name: 'BAD NAME', trigger_type: 'cron', trigger_spec: 'nope', scope_modules: ['government'] },
+    { name: 'BAD NAME', trigger_type: 'webhook', trigger_spec: 'nope', scope_modules: ['government'] },
     { authorRank: 'xenos', allowedModules: ['agents'] },
   );
   assert.equal(r.ok, false);
@@ -485,7 +493,7 @@ await test('EVERY error carries a code, a field and a human message', () => {
 
 await test('validation reports ALL faults at once, not just the first', () => {
   // An author fixing a definition file should not have to re-run four times.
-  const r = validateAgentDefinition({ name: 'X', persona: '', trigger_type: 'cron' }, OPTS);
+  const r = validateAgentDefinition({ name: 'X', persona: '', trigger_type: 'webhook' }, OPTS);
   for (const code of ['name_invalid', 'persona_missing', 'trigger_type_unknown']) {
     assert.ok(hasCode(r, code), `${code} missing from ${JSON.stringify(codes(r))}`);
   }

package/tests/auth_session_expiry_db.mjs

@@ -67,7 +67,7 @@ await pool.query(`
     display_name text, avatar_url text, total_credits int DEFAULT 0, rank text DEFAULT 'archon',
     status text DEFAULT 'active', system_role text, anthropic_user_id text);
   CREATE TABLE builder_sessions (id bigserial PRIMARY KEY, builder_id bigint REFERENCES builders(id),
-    token text UNIQUE, source text, user_agent text, created_at timestamptz DEFAULT now(),
+    token_hash text UNIQUE, source text, user_agent text, created_at timestamptz DEFAULT now(),
     last_used_at timestamptz DEFAULT now(), expires_at timestamptz, revoked_at timestamptz);
   INSERT INTO builders (github_login) VALUES ('probe');
 `);
@@ -86,6 +86,11 @@ const t = async (name, fn) => {
   catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
 };
 const row = async (sql, p) => (await client.query(sql, p)).rows[0];
+// core_249: the bearer is no longer a column, so a probe that wants "the row for
+// this token" has to ask by the stored digest. Uses the kernel's OWN helper, so a
+// change to the hash cannot leave this file quietly matching nothing — a mismatch
+// would make every assertion below read a missing row and fail loudly.
+const h = (token) => kernel.sessionTokenHash(token);
 // refresh-on-use is fire-and-forget: let the UPDATE land before reading it back.
 const settle = () => new Promise((r) => setTimeout(r, 300));
 
@@ -110,67 +115,67 @@ await t('lookupSession resolves a CLI bearer to its builder', async () => {
 await t('after a real use, a CLI session STILL has no expiry (the CASE guard)', async () => {
   await kernel.lookupSession('cli-tok');
   await settle();
-  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token='cli-tok'`)).expires_at, null);
+  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('cli-tok')}'`)).expires_at, null);
 });
 
 await t('refresh-on-use still bumps last_used_at on that same row', async () => {
-  const before = (await row(`SELECT last_used_at FROM builder_sessions WHERE token='cli-tok'`)).last_used_at;
-  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '1 hour' WHERE token='cli-tok'`);
+  const before = (await row(`SELECT last_used_at FROM builder_sessions WHERE token_hash='${h('cli-tok')}'`)).last_used_at;
+  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '1 hour' WHERE token_hash='${h('cli-tok')}'`);
   await kernel.lookupSession('cli-tok');
   await settle();
-  const after = (await row(`SELECT last_used_at FROM builder_sessions WHERE token='cli-tok'`)).last_used_at;
+  const after = (await row(`SELECT last_used_at FROM builder_sessions WHERE token_hash='${h('cli-tok')}'`)).last_used_at;
   assert.ok(after > new Date(Date.now() - 60_000), `last_used_at did not move: ${after} (was ${before})`);
 });
 
 await t('a web session still rolls its expiry forward (refresh-on-use intact)', async () => {
   await kernel.lookupSession('web-tok');
   await settle();
-  const got = (await row(`SELECT expires_at FROM builder_sessions WHERE token='web-tok'`)).expires_at;
+  const got = (await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('web-tok')}'`)).expires_at;
   assert.ok(got !== null && got < thirtyDays, `expected a rolled-forward date below 30d, got ${got}`);
 });
 
 await t('an expired session is still REFUSED (expiry honoured where present)', async () => {
-  await client.query(`INSERT INTO builder_sessions (builder_id, token, source, expires_at)
-                      VALUES (1,'dead-tok','web', now() - interval '1 hour')`);
+  await client.query(`INSERT INTO builder_sessions (builder_id, token_hash, source, expires_at)
+                      VALUES (1,'${h('dead-tok')}','web', now() - interval '1 hour')`);
   assert.equal(await kernel.lookupSession('dead-tok'), null);
 });
 
 await t('a revoked CLI session is still REFUSED', async () => {
-  await client.query(`INSERT INTO builder_sessions (builder_id, token, source, revoked_at)
-                      VALUES (1,'revoked-tok','cli', now())`);
+  await client.query(`INSERT INTO builder_sessions (builder_id, token_hash, source, revoked_at)
+                      VALUES (1,'${h('revoked-tok')}','cli', now())`);
   assert.equal(await kernel.lookupSession('revoked-tok'), null);
 });
 
 // The migration, against rows shaped like the ones live instances actually hold.
 const migrationSql = readFileSync(MIGRATION, 'utf8');
-await client.query(`INSERT INTO builder_sessions (builder_id, token, source, expires_at) VALUES
-  (1,'old-cli','cli', now() + interval '24 hours'),
-  (1,'old-web','web', now() + interval '30 days'),
-  (1,'old-revoked','cli', now() + interval '24 hours')`);
-await client.query(`UPDATE builder_sessions SET revoked_at = now() WHERE token='old-revoked'`);
+await client.query(`INSERT INTO builder_sessions (builder_id, token_hash, source, expires_at) VALUES
+  (1,'${h('old-cli')}','cli', now() + interval '24 hours'),
+  (1,'${h('old-web')}','web', now() + interval '30 days'),
+  (1,'${h('old-revoked')}','cli', now() + interval '24 hours')`);
+await client.query(`UPDATE builder_sessions SET revoked_at = now() WHERE token_hash='${h('old-revoked')}'`);
 await client.query(migrationSql);
 
 await t('core_243 clears a pre-existing CLI expiry', async () => {
-  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-cli'`)).expires_at, null);
+  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-cli')}'`)).expires_at, null);
 });
 
 await t('core_243 leaves a WEB row dated — the source filter is its safety property', async () => {
-  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-web'`)).expires_at, null);
+  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-web')}'`)).expires_at, null);
 });
 
 await t('core_243 leaves a revoked row alone (it is the audit trail)', async () => {
-  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-revoked'`)).expires_at, null);
+  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-revoked')}'`)).expires_at, null);
 });
 
 await t('core_243 is idempotent — a re-run changes nothing', async () => {
   await client.query(migrationSql);
-  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-cli'`)).expires_at, null);
-  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-web'`)).expires_at, null);
+  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-cli')}'`)).expires_at, null);
+  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-web')}'`)).expires_at, null);
 });
 
 // The whole point of the task, stated as a test.
 await t('a CLI session idle for 21 DAYS still authenticates', async () => {
-  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '21 days' WHERE token='cli-tok'`);
+  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '21 days' WHERE token_hash='${h('cli-tok')}'`);
   assert.notEqual(await kernel.lookupSession('cli-tok'), null);
 });
 

package/tests/government_live_proof.mjs

@@ -42,6 +42,9 @@ if (!process.env.DATABASE_URL) {
 }
 
 const { Pool } = require('pg');
+// The kernel's own bearer → stored-digest transform (core_249), so this fixture
+// cannot drift from how production mints a session.
+const { sessionTokenHash } = require('../src/bongos/db-kernel.js');
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
 
 // ── THE READINESS GUARD, AND WHY ITS SHAPE MATTERS (task 1003091) ────────────
@@ -137,9 +140,12 @@ async function seed() {
     [ARCHON, THETES]
   );
   await q(
-    `INSERT INTO builder_sessions (builder_id, token, source)
+    // core_249: the bearer is stored as its SHA-256, so a fixture session has to
+    // be seeded the same way the kernel mints one — otherwise the HTTP calls
+    // below authenticate as nobody.
+    `INSERT INTO builder_sessions (builder_id, token_hash, source)
      VALUES ($1,$2,'web'), ($3,$4,'web')`,
-    [ARCHON, ARCHON_TOKEN, THETES, THETES_TOKEN]
+    [ARCHON, sessionTokenHash(ARCHON_TOKEN), THETES, sessionTokenHash(THETES_TOKEN)]
   );
   const [idea] = await q(
     `INSERT INTO idea_inbox (title, body_md, captured_by)