@bongos/core 1.19.791 → 1.19.793

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.791",
+  "version": "1.19.793",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/box-auth-check.js

@@ -93,7 +93,7 @@ async function probeMe(tokenInfo) {
 function printReauth({ boxScoped }) {
   const why = boxScoped
     ? 'This box holds the BOX-SCOPED bootstrap token (source=box, ADR 0053) — it can bootstrap the box but is refused (403) on claim / ship / publish.'
-    : 'This session token is EXPIRED or revoked (CLI tokens carry a 24h idle TTL).';
+    : 'This session token is REVOKED or otherwise rejected (CLI tokens do not expire on their own — ADR 0294).';
   console.log('[otb] ── dev box: RE-AUTH BEFORE YOU WORK ──');
   console.log(`[otb] ${why}`);
   console.log('[otb] ⚠ FIRST STEP this session: get the builder onto a real CLI session BEFORE claiming or shipping —');

package/scripts/gds/cli-lib.js

@@ -521,9 +521,9 @@ function printUnauthGuidanceAndExit() {
   }
   console.error('');
   console.error('  Possible causes:');
-  console.error('    - Your session token expired (24h idle TTL, auto-refreshes on each request)');
-  console.error('    - Your token was revoked by an Archon');
+  console.error('    - Your token was revoked — by you ("Sign out everywhere") or by an Archon');
   console.error('    - A recent deploy applied an auth-changing migration (see deploy banner)');
+  console.error('    - This instance is older than ADR 0294 and still expires idle CLI sessions');
   console.error('');
   console.error('  Once re-authed, re-run whichever command you were trying.');
   // `doctor` is checkout-only — it is not one of the public CLI's verbs (ADR 0258).

package/scripts/gds/paste-token.js

@@ -7,7 +7,8 @@
 // paste never silently un-registers a builder's Gemini key.
 //
 // Usage:
-//   node scripts/gds/paste-token.js <token>
+//   bongos paste-token <token>          # what the hall hands you (task 1003961)
+//   node scripts/gds/paste-token.js <token>   # equivalent, inside a core checkout
 //
 // The portal returns the exact invocation as the "paste_command" field, so a
 // builder can copy + paste a single line.
@@ -42,7 +43,8 @@ const API_BASE = ic.resolveApiBase();
 function usage(extra) {
   if (extra) console.error(extra);
   console.error('');
-  console.error('Usage: node scripts/gds/paste-token.js <token>');
+  console.error('Usage: bongos paste-token <token>');
+  console.error('   (inside a core checkout: node scripts/gds/paste-token.js <token>)');
   console.error('');
   console.error('Get a token on your Settings page: ' + API_BASE + '/builders/settings');
   console.error('— under "CLI Access" click "Re-issue CLI token" (you must be signed in).');

package/scripts/gds/reauth.js

@@ -3,11 +3,13 @@
 //
 // The fast, UI-first path to refresh an expired/invalid GDS CLI session.
 //
-// Why this exists: CLI bearer tokens carry a 24h idle TTL (refresh-on-use) for
-// auth-token hygiene (GDS-V3 criterion C9) — a leaked or abandoned token in the
-// plaintext session file dies on its own instead of living forever. That's a
-// keeper. The friction it caused (re-auth via the slow Device Flow, terminal
-// codes, Gemini-key prompts) is NOT a keeper. This script is the fix:
+// Why this exists: a CLI session can stop working — revoked from the hall's
+// "Sign out everywhere", swept by a demotion, or invalidated by an auth-changing
+// deploy. (It no longer stops working from mere disuse: ADR 0294 removed the idle
+// expiry, because the timer only ever signed out the legitimate holder while
+// refresh-on-use kept a thief's copy alive.) Whatever killed it, the friction of
+// getting back in — the slow Device Flow, terminal codes, Gemini-key prompts — is
+// not something to keep. This script is the fix:
 //
 //   1. Detect — is the current session still valid? (GET /api/gds/me)
 //        valid   → print who you are + exit 0. Nothing to do.
@@ -15,7 +17,7 @@
 //   2. Guide — open the builder's Settings page in the default browser (where
 //      the builder is already signed in via the httpOnly cookie) and print the
 //      exact click-path: Settings → CLI Access → Re-issue CLI token → Copy.
-//      The page hands back a one-liner: `node scripts/gds/paste-token.js
+//      The page hands back a one-liner: `bongos paste-token
 //      <token>`. The builder pastes that one line back into Claude; the
 //      /builder-reauth skill runs it (paste-token.js verifies + writes safely).
 //
@@ -94,7 +96,7 @@ function printGuidance({ opened }) {
   console.log("        you're already signed in there via your browser cookie)");
   console.log('  2. Under the "CLI Access" section, click "Re-issue CLI token".');
   console.log('  3. Click "Copy" — it copies a one-line command that looks like:');
-  console.log('       node scripts/gds/paste-token.js <token>');
+  console.log('       bongos paste-token <token>');
   console.log('  4. Paste that one line back to Claude. It will run it for you,');
   console.log('     verify the token, and write your new session.');
   console.log('');
@@ -133,8 +135,8 @@ async function main() {
     const b = (res.data && res.data.builder) || {};
     console.log(`Your GDS CLI session is valid — no re-auth needed.`);
     console.log(`  Signed in as ${b.github_login || '?'}${b.rank ? ` (rank: ${b.rank})` : ''}.`);
-    console.log('  (Sessions carry a 24h idle TTL and refresh on every use, so an');
-    console.log('   actively-used session stays alive.)');
+    console.log('  (CLI sessions do not expire — they last until revoked. Kill one from');
+    console.log('   Settings → Active sessions, or "Sign out everywhere".)');
     process.exit(0);
   }
 

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

@@ -145,6 +145,13 @@ const INTEGRATION = new Set([
   // prove the CHECK actually refuses a stored fourth state, that the backfill lands on a
   // pre-migration row, and that publishableSql and projectPublishability agree.
   'project_visibility_db',
+  // task 1003956 (ADR 0294): that CLI sessions really never expire. The DB-free
+  // sibling (auth_session_ttl) pins the constant, createSession's value against a
+  // stub pool, and the TEXT of the refresh statement — but a regex over source
+  // proves the characters are there, not that Postgres does what they mean. Only a
+  // 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',
   '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/auth-github.js

@@ -218,6 +218,8 @@ async function pollDeviceFlow(deviceCode, userAgent) {
       source: 'cli',
       userAgent: userAgent ?? null,
       // CLI tokens have no expiry (manually revocable). Web tokens expire.
+      // True again as of ADR 0294: migration 035 made this line a lie for two years
+      // by defaulting a null to a TTL, and removing that default restored it.
       expiresAt: null,
     });
     // V3.R75 (#294): tick the onboarding state machine. Best-effort — auth

package/src/bongos/db-kernel.js

@@ -262,16 +262,25 @@ async function accessStateByLogin(login) {
 
 // --- Auth sessions (kernel: the builder_sessions token store auth.js drives) ----
 
-// SESSION_TTL_MS — session TTL on create/refresh. Centralized so the migration's
-// grace formula, the tests, and the code agree on one number.
+// SESSION_TTL_MS — the roll-forward window for a session that HAS an expiry.
+// It is no longer a default: a caller that names no expiry gets none (ADR 0294).
+// What still reads it is refresh-on-use below, which rolls an already-dated row
+// (the web flow's) forward on each request. Centralized so the tests and the
+// code agree on one number.
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 
-// createSession — mint a builder_sessions row. Defaults expiry to NOW()+TTL when
-// the caller passes null/undefined (refresh-on-use keeps active sessions alive).
+// createSession — mint a builder_sessions row.
+//
+// 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
+// revoked, because an idle expiry only ever logged out the legitimate holder —
+// the remedy for a leaked bearer is the own-scoped revoke of ADR 0206, which is
+// immediate where a timer is not. Every caller that passes null is source='cli'.
+//
+// Web callers pass an explicit date (30 days) and are untouched by this default.
 async function createSession({ builderId, token, source, userAgent, expiresAt }) {
-  const effectiveExpiresAt = expiresAt === undefined || expiresAt === null
-    ? new Date(Date.now() + SESSION_TTL_MS)
-    : expiresAt;
+  const effectiveExpiresAt = expiresAt ?? null;
   const { rows } = await pool.query(
     `INSERT INTO builder_sessions (builder_id, token, source, user_agent, expires_at)
      VALUES ($1, $2, $3, $4, $5)
@@ -282,9 +291,10 @@ async function createSession({ builderId, token, source, userAgent, expiresAt })
 }
 
 // lookupSession — resolve a live (unrevoked, unexpired) session token to its
-// builder identity, and refresh-on-use (bump last_used_at + roll expiry forward,
-// fire-and-forget). Returns null for missing/revoked/expired. Read fresh per
-// request, never cached (ADR 0016).
+// builder identity, and refresh-on-use (bump last_used_at, and roll expiry
+// forward for a row that has one, fire-and-forget). Returns null for
+// missing/revoked/expired; a row with expires_at NULL never expires. Read fresh
+// per request, never cached (ADR 0016).
 //
 // The governance FOLD (task 1002556): when the governance module is enabled, the
 // same round-trip also aggregates the builder's raw permission grant keys, so
@@ -335,11 +345,19 @@ async function lookupSession(token) {
   if (!row) return null;
   if (row.revoked_at) return null;
   if (row.expires_at && row.expires_at < new Date()) return null;
+  // Refresh-on-use. last_used_at always moves — the own-sessions list (ADR 0206)
+  // is how a person spots a session they don't recognise, and that reading is the
+  // whole remedy now that CLI rows never lapse. expires_at only rolls forward for
+  // a row that HAS one: the CASE is what stops a use from minting an expiry on a
+  // never-expires row and quietly reintroducing the timeout per ADR 0294.
   pool
     .query(
       `UPDATE builder_sessions
           SET last_used_at = now(),
-              expires_at   = now() + ($2::int * INTERVAL '1 millisecond')
+              expires_at   = CASE
+                               WHEN expires_at IS NULL THEN NULL
+                               ELSE now() + ($2::int * INTERVAL '1 millisecond')
+                             END
         WHERE id = $1`,
       [row.session_id, SESSION_TTL_MS]
     )

package/src/bongos/db.js

@@ -664,32 +664,41 @@ async function reactivateBuilder({ builderId, actorBuilderId }) {
 // Sessions (auth tokens)
 // -------------------------------------------------------------------------
 //
-// V3.R38 / task #259 — short-lived sessions with refresh-on-use.
+// V3.R38 / task #259 — short-lived sessions with refresh-on-use (1h).
 // V3.R90 / task #400 (2026-05-29) — TTL widened from 1h to 24h.
+// ADR 0294 / task 1003956 (2026-09-16) — CLI sessions lose their expiry entirely.
 //
-//   * Every NEW session (CLI or web) defaults to a 24-hour TTL. The caller may
-//     still pass an explicit expiresAt to override (web flow uses 30 days for
-//     the cookie's max-age, but the SERVER-SIDE row still uses 24h + roll-on-use
-//     so a logged-out browser tab in someone's history can't be replayed weeks
-//     later).
-//   * Every successful lookupSession bumps BOTH last_used_at AND expires_at to
-//     NOW() + 24h. This is the "refresh-on-use" half: an actively-used session
-//     stays valid; an idle session expires after 24h. The bump is fire-and-
-//     forget — it's an optimization for the next request, not a precondition
-//     for THIS request, so we don't add request latency by awaiting it.
-//   * Migration 035 backfilled all pre-existing rows with a 24h grace runway
-//     so deploying the V3.R38 change didn't kick the supervisor / mid-flow
-//     builders. With the V3.R90 TTL = 24h, the refresh window matches that
-//     grace formula exactly — no further migration needed.
-//   * The 1h value originally backstopped C7 (rank-change-near-instant), but
-//     setBuilderRank already calls revokeAllSessionsForBuilder on every
-//     demotion (see below), so the TTL is no longer load-bearing for C7. Its
-//     remaining job is idle-session hygiene under C9 (security baseline).
-//     24h still kills idle sessions overnight; an active builder no longer
-//     gets kicked out over lunch.
-
-// Session TTL on refresh / creation, in milliseconds. Centralized so the
-// migration's grace formula, the test suite, and the code agree on one number.
+// The arc is one long argument the idle timer kept losing. 1h kicked builders
+// out over lunch; 24h kicked them out over a weekend. Each round shortened the
+// nuisance without touching the threat, because the timer never bounded a leaked
+// token in the first place — refresh-on-use means the thief's own traffic keeps
+// it alive, and only the legitimate holder, who steps away, is ever signed out.
+// So the expiry is gone from CLI sessions rather than widened a third time.
+//
+//   * A NEW session whose caller names no expiry gets NONE — expires_at NULL,
+//     which lookupSession treats as never-expires. Every such caller is
+//     source='cli'. The WEB flow passes an explicit 30 days and is unchanged.
+//   * Every successful lookupSession bumps last_used_at, and rolls expires_at
+//     forward to NOW()+24h ONLY for a row that already has one. A NULL stays
+//     NULL — otherwise the first request after sign-in would mint the very
+//     timeout this removed. The bump is fire-and-forget: an optimization for the
+//     next request, not a precondition for THIS one, so it isn't awaited.
+//   * Migration core_243 cleared expires_at on live source='cli' rows, so the
+//     change reached sessions that already existed instead of making every
+//     builder re-auth one last time. (Migration 035 had backfilled a 24h grace
+//     in the other direction, for the same reason: don't sign out the session
+//     deploying the migration.)
+//   * Nothing here is load-bearing for C7 (rank-change-near-instant):
+//     setBuilderRank calls revokeAllSessionsForBuilder on every demotion (see
+//     below) and requireBuilder denies a deactivated builder on the hot path, so
+//     authority drift is closed by revocation, not by waiting out a clock.
+//   * The remedy for a leaked bearer is the own-scoped revoke of ADR 0206 —
+//     GET/POST /me/sessions, and "Sign out everywhere" in the hall — which kills
+//     it now rather than within a day. That is why the timer is affordable to
+//     lose: the thing it was nominally for has a faster answer that already ships.
+
+// The roll-forward window for a session that HAS an expiry, in milliseconds.
+// Centralized so the test suite and the code agree on one number.
 
 // SESSION_TTL_MS — carved to ./db-kernel (ADR 0102); imported + re-exported above.
 

package/src/bongos/routes/auth.js

@@ -1025,7 +1025,7 @@ module.exports = function buildAuthRouter() {
   // the requesting builder, gated on a WEB COOKIE session (not a bearer). The
   // browser already proves identity via the gds_session cookie; this endpoint
   // mints a separate cli-source session row the builder can paste into
-  // ~/.config/otb/gds-session.json via scripts/gds/paste-token.js. Replaces
+  // ~/.config/otb/gds-session.json via `bongos paste-token`. Replaces
   // the ~30-60s Device Flow when the CLI bearer has expired.
   //
   // rank: any-builder (own identity only) — no rank gate.
@@ -1049,7 +1049,8 @@ module.exports = function buildAuthRouter() {
         // audit_log distinguishes portal-reissue from Device Flow tokens.
         source: 'cli',
         userAgent: req.headers['user-agent'] ?? null,
-        // expiresAt: null → createSession applies SESSION_TTL_MS (24h after V3.R90).
+        // expiresAt: null → NO expiry: a CLI bearer lasts until revoked (ADR 0294).
+        // The builder kills it from this same Settings page, under Active sessions.
         expiresAt: null,
       });
       res.json({
@@ -1057,7 +1058,15 @@ module.exports = function buildAuthRouter() {
         token,
         expires_at: row.expires_at,
         builder_login: req.builder.github_login,
-        paste_command: `node scripts/gds/paste-token.js ${token}`,
+        // A VERB, never a path (task 1003961). This string is composed HERE and run
+        // THERE — on an instance, where the core is an installed dependency and
+        // `scripts/gds/` does not exist, so the previous
+        // `node scripts/gds/paste-token.js <token>` named a file the builder did not
+        // have and the copy button handed out a command that could not run. `bongos`
+        // is on PATH in any installed instance, so the verb form is layout- and
+        // directory-independent. Same discipline as configuredOAuthOrigin() above:
+        // nothing about the RECIPIENT's filesystem may be assumed here.
+        paste_command: `bongos paste-token ${token}`,
       });
     } catch (err) {
       log.error('[gds] POST /auth/cli-token/issue', err);
@@ -1189,7 +1198,7 @@ module.exports = function buildAuthRouter() {
         token,
         source: 'cli', // 003_pms.sql CHECK; the app is a CLI-class bearer client
         userAgent: `devbox-app pair (${req.headers['user-agent'] ?? 'unknown'})`,
-        expiresAt: null, // createSession applies the 24h refresh-on-use TTL
+        expiresAt: null, // no expiry — a CLI bearer lasts until revoked (ADR 0294)
       });
       const out = pairStore.approve((req.body || {}).pair_code, {
         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.791'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.793'; // 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/auth_session_expiry_db.mjs

@@ -0,0 +1,183 @@
+// tests/auth_session_expiry_db.mjs — ADR 0294, task 1003956 (real DB).
+//
+// The DB-free sibling (auth_session_ttl.mjs) pins the CONSTANT, createSession's
+// choice of value against a stub pool, and the TEXT of the refresh statement and
+// the migration. That last part is the weak half, and the grader on this task was
+// right to say so — though not for the reason first assumed. Most edits to the
+// guard's WORDING do break its regex, so the sibling is tighter than it looks.
+// What a regex cannot see is whether Postgres ACCEPTS the statement at all.
+//
+// Measured, by deleting the CASE's `END` and running both files: the sibling
+// reported 20 passed, 0 failed on SQL that fails to parse — SQL that would throw
+// on every authenticated request in production. This file caught it.
+//
+// Worth knowing WHICH assertions caught it, because it is not the obvious one.
+// The refresh is fire-and-forget with a `.catch()`, so a broken UPDATE fails
+// SILENTLY: expires_at stays NULL and the never-expires assertion still passes.
+// What failed was `last_used_at` never moving and the web row never rolling. Those
+// two are not padding — on this statement they are the only live smoke alarm.
+//
+// So this file proves what only a real transaction engine can:
+//
+//   1. A CLI session is CREATED with no expiry, and a web session's explicit
+//      30 days survives untouched — the two halves of the default change.
+//   2. THE REGRESSION GUARD EXECUTES — after a real lookupSession, a CLI row's
+//      expires_at is still NULL. Without the CASE this is where the timeout
+//      comes back, on the first request after sign-in.
+//   3. A web row's expiry STILL rolls forward, so the guard narrowed the write
+//      to NULL rows rather than disabling refresh-on-use for everyone.
+//   4. Expiry is still HONOURED where present, and revocation still wins — the
+//      two things a "sessions never expire" change could plausibly have broken.
+//   5. THE MIGRATION, run for real: it clears a pre-existing CLI expiry, leaves
+//      web and revoked rows alone, and is idempotent.
+//   6. The point of the whole task — a session idle far past 24h authenticates.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in
+// run-unit-tests.js's INTEGRATION set so the default DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=... node tests/auth_session_expiry_db.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIGRATION = join(here, '..', 'migrations', 'core_243_cli_sessions_never_expire.sql');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`auth_session_expiry_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+// An isolated schema, so this never touches a real builders/builder_sessions.
+const SCHEMA = `ttl_probe_${process.pid}`;
+await pool.query(`CREATE SCHEMA ${SCHEMA}`);
+await pool.query(`SET search_path TO ${SCHEMA}`);
+await pool.query(`
+  CREATE TABLE builders (id bigserial PRIMARY KEY, github_id text, github_login text,
+    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(),
+    last_used_at timestamptz DEFAULT now(), expires_at timestamptz, revoked_at timestamptz);
+  INSERT INTO builders (github_login) VALUES ('probe');
+`);
+
+// Run the REAL kernel against this schema: stub ./pool in the require cache so
+// db-kernel binds our client, exactly as the production code binds the singleton.
+const client = await pool.connect();
+await client.query(`SET search_path TO ${SCHEMA}`);
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: client } };
+const kernel = require('../src/bongos/db-kernel.js');
+
+let passed = 0, failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+const row = async (sql, p) => (await client.query(sql, p)).rows[0];
+// refresh-on-use is fire-and-forget: let the UPDATE land before reading it back.
+const settle = () => new Promise((r) => setTimeout(r, 300));
+
+const thirtyDays = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+
+await t('a CLI session is created with NO expiry', async () => {
+  const s = await kernel.createSession({ builderId: '1', token: 'cli-tok', source: 'cli', userAgent: 'probe', expiresAt: null });
+  assert.equal(s.expires_at, null);
+});
+
+await t("a web session's explicit 30-day expiry is stored as given", async () => {
+  const s = await kernel.createSession({ builderId: '1', token: 'web-tok', source: 'web', userAgent: 'probe', expiresAt: thirtyDays });
+  assert.equal(s.expires_at.getTime(), thirtyDays.getTime());
+});
+
+await t('lookupSession resolves a CLI bearer to its builder', async () => {
+  const got = await kernel.lookupSession('cli-tok');
+  assert.equal(got && got.github_login, 'probe');
+});
+
+// THE GUARD. This is the assertion the source-matching sibling cannot make.
+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);
+});
+
+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'`);
+  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;
+  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;
+  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')`);
+  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())`);
+  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(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);
+});
+
+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);
+});
+
+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);
+});
+
+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);
+});
+
+// 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'`);
+  assert.notEqual(await kernel.lookupSession('cli-tok'), null);
+});
+
+await client.query(`SET search_path TO public`);
+client.release();
+await pool.query(`DROP SCHEMA ${SCHEMA} CASCADE`);
+await pool.end();
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);