@bongos/core 1.24.95 → 1.25.1

package/src/bongos/passkeys.js

@@ -15,6 +15,8 @@ const crypto = require('node:crypto');
 const CHALLENGE_TTL_SECONDS = 300;
 const MAX_CHALLENGE_TTL_SECONDS = 600;
 const PURPOSES = Object.freeze(['register', 'authenticate']);
+// How long one card tap keeps a session cleared for the protected actions (ADR 0382 D2).
+const STEP_UP_WINDOW_SECONDS = 600;
 
 function defaultPool() { return require('./pool').pool; }
 
@@ -146,7 +148,35 @@ async function renameCredential(builderId, credentialId, nickname, { pool = defa
   return r.rowCount > 0;
 }
 
+// Stamp the session that just passed a card check. Keyed on the builder as well, so a
+// session id that is not the caller's matches no row. Returns true when stamped.
+async function markSessionCardVerified(sessionId, builderId, { pool = defaultPool() } = {}) {
+  const r = await pool.query(
+    `UPDATE builder_sessions SET card_verified_at = now()
+      WHERE id = $1 AND builder_id = $2 AND revoked_at IS NULL`,
+    [sessionId, builderId],
+  );
+  return r.rowCount > 0;
+}
+
+// Where this session stands: is a card required of the builder, and is the session's
+// last tap inside the window? Read fresh from the DB on every call, never cached.
+async function stepUpStatus(sessionId, builderId, { pool = defaultPool(), windowSeconds = STEP_UP_WINDOW_SECONDS } = {}) {
+  const { rows } = await pool.query(
+    `SELECT b.require_card,
+            (s.card_verified_at IS NOT NULL
+               AND s.card_verified_at > now() - make_interval(secs => $3::int)) AS fresh
+       FROM builders b JOIN builder_sessions s ON s.builder_id = b.id
+      WHERE b.id = $1 AND s.id = $2`,
+    [builderId, sessionId, String(windowSeconds)],
+  );
+  const r = rows[0];
+  if (!r) return null;
+  return { required: r.require_card === true, fresh: r.fresh === true };
+}
+
 module.exports = {
+  STEP_UP_WINDOW_SECONDS, markSessionCardVerified, stepUpStatus,
   CHALLENGE_TTL_SECONDS, MAX_CHALLENGE_TTL_SECONDS, PURPOSES, clampTtlSeconds, counterAdvances,
   createChallenge, consumeChallenge, sweepExpiredChallenges,
   getOrCreateUserHandle, addCredential, getCredentialById, listCredentials, recordUse, removeCredential, renameCredential,

package/src/bongos/routes/auth.js

@@ -1418,7 +1418,7 @@ module.exports = function buildAuthRouter() {
   // rank: archon — kills an arbitrary session; can lock other builders out. Gate:
   // requirePermission('auth.session.revoke') — BV1.R104; the seeded rank-role makes
   // the permission and the old rank floor identical (ADR 0151).
-  router.post('/auth/revoke', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), async (req, res) => {
+  router.post('/auth/revoke', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), require('../step-up').requireCardStepUp, async (req, res) => {
     if (validateOrRespond(req, res, { session_id: {} })) return;  // bigint as number or string; validated below
     const sessionId = req.body && req.body.session_id;
     if (sessionId === undefined || sessionId === null) {
@@ -1446,7 +1446,7 @@ module.exports = function buildAuthRouter() {
   // rank: archon — same authority as PATCH /builders/:id/rank. Gate:
   // requirePermission('auth.session.revoke') — BV1.R104; the same atom /auth/revoke
   // gates on (ADR 0151).
-  router.post('/auth/revoke-all', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), async (req, res) => {
+  router.post('/auth/revoke-all', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), require('../step-up').requireCardStepUp, async (req, res) => {
     if (validateOrRespond(req, res, { builder_id: {} })) return;  // bigint as number or string; validated below
     const builderId = req.body && req.body.builder_id;
     if (builderId === undefined || builderId === null) {

package/src/bongos/routes/builders.js

@@ -24,6 +24,7 @@
 
 const express = require('express');
 const auth = require('../auth');
+const { requireCardStepUp } = require('../step-up');
 // WHO DECIDES AT TREASURY (task 1004657; ADR 0363 D5): the budget write refuses a
 // lone act while Treasury's decision-rules row names a sitting. A passed Treasury
 // matter sets the limit through setMonthlyBudget directly (the governor.matterAct
@@ -271,7 +272,7 @@ module.exports = function buildBuildersRouter() {
   // the permission and the old rank floor identical (ADR 0151). The atom is
   // `system: true`, so no CUSTOM role may ever be granted it — only the seeded archon
   // role holds it, which is exactly the meta-escalation wall ADR 0016 wants.
-  router.patch('/builders/:id/rank', auth.requireBuilder, auth.requirePermission('builder.rank.set'), async (req, res) => {
+  router.patch('/builders/:id/rank', auth.requireBuilder, auth.requirePermission('builder.rank.set'), requireCardStepUp, async (req, res) => {
     if (validateOrRespond(req, res, {
       rank: { required: true, type: 'string', maxLength: 32 },
     })) return;

package/src/bongos/routes/module-payouts.js

@@ -28,6 +28,8 @@ module.exports = function buildModulePayoutsRouter({
   requirePermission = auth.requirePermission,
 } = {}) {
   const router = express.Router();
+  // the processor adapter (modules/economy/processor-stripe.js, task 1005040) is a port, resolved per call
+  const proc = () => processor || require('../../module-seams').resolveOptional('economy.processor');
 
   function personal(req, res) {
     const p = store.personalSession(req);
@@ -74,7 +76,7 @@ module.exports = function buildModulePayoutsRouter({
     if (!actor) return;
     if (validateOrRespond(req, res, { processor_sale_ref: { required: true } })) return;
     try {
-      const out = await payouts.recordSale({ processorSaleRef: req.body.processor_sale_ref, actorId: actor.id }, { processor });
+      const out = await payouts.recordSale({ processorSaleRef: req.body.processor_sale_ref, actorId: actor.id }, { processor: proc() });
       res.status(out.already ? 200 : 201).json(out);
     } catch (err) { fail(res, err, 'POST /payouts/module-sales'); }
   });
@@ -104,7 +106,7 @@ module.exports = function buildModulePayoutsRouter({
     if (!actor) return;
     if (validateOrRespond(req, res, { approval_id: { required: true } })) return;
     try {
-      const out = await payouts.payShare({ shareId: req.params.id, approvalId: req.body.approval_id, actorId: actor.id }, { processor });
+      const out = await payouts.payShare({ shareId: req.params.id, approvalId: req.body.approval_id, actorId: actor.id }, { processor: proc() });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fail(res, err, 'POST /payouts/module-shares/:id/pay'); }

package/src/bongos/routes/my-cash-outs.js

@@ -30,6 +30,8 @@ function buildMyCashOutsRouter({
   requireBuilder = auth.requireBuilder,
 } = {}) {
   const router = express.Router();
+  // the processor adapter (modules/economy/processor-stripe.js, task 1005040) is a port, resolved per call
+  const proc = () => processor || require('../../module-seams').resolveOptional('economy.processor');
 
   function personal(req, res) {
     const p = approvals.personalSession(req);
@@ -62,7 +64,7 @@ function buildMyCashOutsRouter({
   // GET /api/bongos/me/cash-outs — my withdrawals and where each stands.
   router.get('/me/cash-outs', requireBuilder, async (req, res) => {
     try {
-      const out = await cashOuts.listMyCashOuts(req.builder.id, { processor, limit: req.query.limit, log });
+      const out = await cashOuts.listMyCashOuts(req.builder.id, { processor: proc(), limit: req.query.limit, log });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fault(res, err, 'GET /me/cash-outs'); }
@@ -76,7 +78,7 @@ function buildMyCashOutsRouter({
     try {
       const out = await cashOuts.requestCashOut({
         builderId: String(req.builder.id), actor, amountCents: req.body.amount_cents, instructionId: req.body.instruction_id,
-      }, { processor, log });
+      }, { processor: proc(), log });
       answer(res, out);
     } catch (err) { fault(res, err, 'POST /me/cash-outs'); }
   });
@@ -85,7 +87,7 @@ function buildMyCashOutsRouter({
   router.post('/me/cash-outs/:id/retry', requireBuilder, async (req, res) => {
     if (!personal(req, res)) return;
     try {
-      answer(res, await cashOuts.retryCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }, { processor }));
+      answer(res, await cashOuts.retryCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }, { processor: proc() }));
     } catch (err) { fault(res, err, 'POST /me/cash-outs/:id/retry'); }
   });
 

package/src/bongos/routes/my-passkeys.js

@@ -206,6 +206,76 @@ module.exports = function buildMyPasskeysRouter({
     }
   });
 
+  // POST /api/bongos/me/passkeys/authenticate/options — start a card check.
+  // rank: any-builder (own identity only). The challenge is bound to the caller.
+  router.post('/me/passkeys/authenticate/options', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {})) return;
+    try {
+      const rp = relyingParty(req);
+      if (!rp) return res.fail('passkeys_not_configured', { status: 503, message: 'security cards are not configured on this site yet' });
+      const cards = await store.listCredentials(req.builder.id);
+      if (!cards.length) return res.fail('no_cards', { status: 409, message: 'register a security card first' });
+      const { challenge } = await store.createChallenge({ purpose: 'authenticate', builderId: req.builder.id });
+      const options = await lib().generateAuthenticationOptions({
+        rpID: rp.rpID,
+        challenge: Buffer.from(challenge, 'base64url'),
+        allowCredentials: cards.map((c) => ({ id: c.credential_id, transports: c.transports })),
+        userVerification: 'required',
+      });
+      res.json({ options });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'authenticate/options failed');
+      res.fail('options_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/me/passkeys/authenticate/verify — finish a card check.
+  // Body: { response } the browser's assertion. On success the CALLER'S session row
+  // is stamped; that stamp (never anything the client sends) is the step-up proof.
+  // rank: any-builder (own identity only).
+  router.post('/me/passkeys/authenticate/verify', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, { response: {} })) return;
+    const response = req.body && req.body.response;
+    if (!response || typeof response !== 'object' || typeof response.id !== 'string') {
+      return res.fail('bad_response', { status: 400, message: 'response is required' });
+    }
+    const refuse = () => res.fail('verification_failed', { status: 400, message: 'the card could not be verified' });
+    try {
+      const rp = relyingParty(req);
+      if (!rp) return res.fail('passkeys_not_configured', { status: 503, message: 'security cards are not configured on this site yet' });
+      const sessionId = req.gdsSession && req.gdsSession.session_id;
+      if (sessionId === undefined || sessionId === null) return res.fail('unauthenticated', 401);
+      const cred = await store.getCredentialById(response.id);
+      // One answer whether the card is unknown or somebody else's.
+      if (!cred || String(cred.builder_id) !== String(req.builder.id)) return refuse();
+      let verification;
+      try {
+        verification = await lib().verifyAuthenticationResponse({
+          response,
+          expectedChallenge: async (c) => !!(await store.consumeChallenge(c, { expectPurpose: 'authenticate', expectBuilderId: req.builder.id })),
+          expectedOrigin: rp.origin,
+          expectedRPID: rp.rpID,
+          credential: { id: cred.credential_id, publicKey: new Uint8Array(cred.public_key), counter: Number(cred.sign_count), transports: cred.transports || [] },
+          requireUserVerification: true,
+        });
+      } catch (err) {
+        log.info({ err: err && err.message }, 'authenticate/verify refused');
+        return refuse();
+      }
+      if (!verification.verified || !verification.authenticationInfo) return refuse();
+      const use = await store.recordUse(cred.credential_id, verification.authenticationInfo.newCounter);
+      if (!use.ok) {
+        log.warn({ reason: use.reason, builder_id: String(req.builder.id) }, 'card counter did not advance: possible clone');
+        return refuse();
+      }
+      if (!(await store.markSessionCardVerified(sessionId, req.builder.id))) return refuse();
+      res.json({ ok: true, valid_for_seconds: store.STEP_UP_WINDOW_SECONDS });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'authenticate/verify failed');
+      res.fail('authenticate_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // POST /api/bongos/me/passkeys/rename — Body: { credential_id, nickname }.
   // rank: any-builder (own identity only) — the WHERE clause is the boundary.
   router.post('/me/passkeys/rename', requireBuilder, async (req, res) => {

package/src/bongos/routes/payout-approvals.js

@@ -59,13 +59,15 @@ module.exports = function buildPayoutApprovalsRouter({
   store = require('../payout-approvals'),
   gates = require('../payout-gates'),
   payouts = builderPayouts,
-  // The processor adapter (ADR 0397: the only code that may name the rail) does not exist
-  // yet, so nothing is sent: every builder payout is recorded as owed and held.
+  // The processor adapter (ADR 0397: the only code that may name the rail) is the optional
+  // `economy.processor` port; with none registered nothing is sent and every payout is held.
   processor = null,
   requireBuilder = auth.requireBuilder,
   requirePermission = auth.requirePermission,
 } = {}) {
   const router = express.Router();
+  // the processor adapter (modules/economy/processor-stripe.js, task 1005040) is a port, resolved per call
+  const proc = () => processor || require('../../module-seams').resolveOptional('economy.processor');
 
   function personal(req, res) {
     const p = store.personalSession(req);
@@ -338,7 +340,7 @@ module.exports = function buildPayoutApprovalsRouter({
     if (validateOrRespond(req, res, { approval_id: { required: true }, task_id: { required: true } })) return;
     const body = req.body || {};
     try {
-      const out = await payouts.payForTask({ approvalId: body.approval_id, taskId: body.task_id, actorId: actor.id }, { processor });
+      const out = await payouts.payForTask({ approvalId: body.approval_id, taskId: body.task_id, actorId: actor.id }, { processor: proc() });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) {

package/src/bongos/step-up.js

@@ -0,0 +1,42 @@
+// src/bongos/step-up.js — the card step-up gate (task 1004747, ADR 0382 D2/D5).
+//
+// requireCardStepUp is mounted AFTER requireBuilder (and after any rank/permission
+// gate) on the routes where a stolen session does the most damage. A builder an
+// Archon has NOT switched the requirement on for passes straight through, so landing
+// this changes nothing for anybody. For a builder with the requirement on, the
+// request is refused 403 `card_required` unless THIS session passed a card check in
+// the last 10 minutes — a timestamp on the server-side session row, set only by
+// POST /me/passkeys/authenticate/verify.
+//
+// It fails CLOSED: if the state cannot be read, the request is refused. The flag and
+// the timestamp are read from the DB per request, never from the token or the client.
+'use strict';
+
+const passkeys = require('./passkeys');
+const log = require('./logger').logger.child({ src: 'step-up' });
+
+const CARD_REQUIRED = Object.freeze({
+  status: 403,
+  message: 'This action needs your hardware card. Tap it on the card page, then try again.',
+});
+
+function buildRequireCardStepUp({ store = passkeys } = {}) {
+  return async function requireCardStepUp(req, res, next) {
+    try {
+      const sessionId = req.gdsSession && req.gdsSession.session_id;
+      const builderId = req.builder && req.builder.id;
+      if (sessionId === undefined || sessionId === null || builderId === undefined || builderId === null) {
+        return res.fail('unauthenticated', 401);
+      }
+      const st = await store.stepUpStatus(sessionId, builderId);
+      if (!st) return res.fail('card_required', CARD_REQUIRED);
+      if (!st.required || st.fresh) return next();
+      return res.fail('card_required', CARD_REQUIRED);
+    } catch (err) {
+      log.error({ err: err && err.message }, 'step-up check failed; refusing');
+      return res.fail('card_check_failed', { status: 503, message: 'could not check your hardware card; try again' });
+    }
+  };
+}
+
+module.exports = { requireCardStepUp: buildRequireCardStepUp(), buildRequireCardStepUp };

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.95'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.1'; // 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('discord'); log.info('mounted');
@@ -157,6 +157,10 @@ module.exports = {
   //     sitting, one builder acting alone is refused (409 decided_by_sitting,
   //     pointing at the matter route). No government module → as today.
   get requireActAlone() { return require('./bongos/act-alone').requireActAlone; },
+  // requireCardStepUp — the hardware-card step-up gate (task 1004747; ADR 0382 D2/D5),
+  //     mounted AFTER the route's permission gate. A builder with no card requirement
+  //     passes untouched; one with it on needs a card tap in the last 10 minutes.
+  get requireCardStepUp() { return require('./bongos/step-up').requireCardStepUp; },
   get rankMeetsThreshold() { return require('./bongos/auth').rankMeetsThreshold; },
   get requireBfgPrincipal() { return require('./bongos/auth').requireBfgPrincipal; },
   // allowBoxScope — DEPRECATED no-op, kept so the doorway loses no export inside

package/tests/autonomy_runner_goal_stats.mjs

@@ -0,0 +1,92 @@
+// tests/autonomy_runner_goal_stats.mjs — one goal, seen from the caller's runner
+// (task 1005243): the numbers the game's runner card on Home shows.
+//
+// The route is driven as a REAL request through the assembled router with only the
+// auth gates stubbed, and the SQL against a stubbed pool (the
+// autonomy_builder_scope precedent). DB-free, no network.
+// Run:  node --test tests/autonomy_runner_goal_stats.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const req = createRequire(import.meta.url);
+const express = req('express');
+const { attachFail } = req(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+const api = req(path.join(ROOT, 'src/module-api.js'));
+const db = req(path.join(ROOT, 'modules/autonomy/db.js'));
+
+const permStub = (key) => { const mw = (_q, _s, next) => next(); mw.permKey = key; return mw; };
+const passBuilder = (q, _s, next) => { q.builder = { id: 7, rank: 'metic' }; next(); };
+
+function router() {
+  const saved = { b: api.requireBuilder, p: api.requirePermission };
+  api.requireBuilder = passBuilder;
+  api.requirePermission = permStub;
+  const p = req.resolve(path.join(ROOT, 'modules/autonomy/routes/autonomy.js'));
+  delete req.cache[p];
+  try { return req(p)(); } finally { api.requireBuilder = saved.b; api.requirePermission = saved.p; }
+}
+async function serve(r) {
+  const app = express();
+  app.use(express.json()); app.use(attachFail); app.use(r);
+  const server = app.listen(0);
+  await new Promise((ok) => server.once('listening', ok));
+  return { base: `http://127.0.0.1:${server.address().port}`, close: () => server.close() };
+}
+async function withPool(answer, fn) {
+  const saved = api.pool.query;
+  const calls = [];
+  api.pool.query = async (sql, params) => { calls.push({ sql, params }); return answer(sql, params); };
+  try { return await fn(calls); } finally { api.pool.query = saved; }
+}
+
+test('the read counts only the caller\'s RUNNER claims that shipped in that goal, and their sessions\' tokens', async () => {
+  await withPool(() => ({ rows: [{ tasks_done: 7, tokens: '4820000', avg_s: '2280.4', tasks_left: 5 }] }), async (calls) => {
+    const out = await db.readRunnerGoalStats(7, 1000090);
+    assert.deepEqual(out, { tasks_done: 7, tokens: 4820000, avg_task_seconds: 2280, tasks_left: 5 });
+    const { sql, params } = calls[0];
+    assert.deepEqual(params, [7, 1000090], 'scoped to the caller and the goal');
+    assert.match(sql, /c\.autonomous/, 'a runner\'s claim, not a person\'s');
+    assert.match(sql, /c\.outcome = 'shipped'/, 'shipped, by the ledger');
+    assert.match(sql, /sr\.builder_id = \$1/, 'only the caller\'s sessions');
+    assert.match(sql, /status IN \('ready', 'active'\)/, 'what is left is what a runner could still take');
+  });
+});
+
+test('a goal not opened to runners tells no count of what is left', async () => {
+  await withPool(() => ({ rows: [{ tasks_done: 0, tokens: '0', avg_s: null, tasks_left: null }] }), async () => {
+    assert.equal((await db.readRunnerGoalStats(7, 9)).tasks_left, null);
+  });
+});
+
+test('nothing done yet reads as zeros and no average, never a made-up pace', async () => {
+  await withPool(() => ({ rows: [{ tasks_done: 0, tokens: '0', avg_s: null, tasks_left: 3 }] }), async () => {
+    assert.deepEqual(await db.readRunnerGoalStats(7, 1), { tasks_done: 0, tokens: 0, avg_task_seconds: null, tasks_left: 3 });
+  });
+});
+
+test('GET /autonomy/me/goals/:id/stats: behind autonomy.run, the caller\'s own, a bad id refused', async () => {
+  const r = router();
+  const layer = r.stack.find((l) => l.route && l.route.path === '/autonomy/me/goals/:goalId/stats' && l.route.methods.get);
+  assert.ok(layer, 'the route is registered');
+  assert.deepEqual(layer.route.stack.map((s) => s.handle.permKey).filter(Boolean), ['autonomy.run']);
+  const s = await serve(r);
+  try {
+    await withPool(() => ({ rows: [{ tasks_done: 2, tokens: 1000, avg_s: 600, tasks_left: 1 }] }), async (calls) => {
+      const ok = await fetch(`${s.base}/autonomy/me/goals/1000090/stats`);
+      assert.equal(ok.status, 200);
+      assert.deepEqual(await ok.json(), { goal_id: 1000090, tasks_done: 2, tokens: 1000, avg_task_seconds: 600, tasks_left: 1 });
+      assert.deepEqual(calls[0].params, [7, 1000090], 'keyed by the session\'s builder, never the request');
+      const bad = await fetch(`${s.base}/autonomy/me/goals/abc/stats`);
+      assert.equal(bad.status, 400);
+    });
+    await withPool(() => { throw new Error('db down'); }, async () => {
+      const down = await fetch(`${s.base}/autonomy/me/goals/5/stats`);
+      assert.equal(down.status, 503);
+    });
+  } finally { s.close(); }
+});

package/tests/government_act_alone_buildings.mjs

@@ -197,7 +197,8 @@ test('the source → the record: every mounted gate is listed under the building
 
 // ── 3. every building, through its real router ──────────────────────────────
 
-const fakeBuilder = (req, res, next) => { req.builder = { id: 42, rank: 'archon', github_login: 'someone' }; next(); };
+const fakeBuilder = (req, res, next) => { req.builder = { id: 42, rank: 'archon', github_login: 'someone' }; req.gdsSession = { session_id: '1' }; next(); };
+require('../src/bongos/passkeys').stepUpStatus = async () => ({ required: false, fresh: false }); // task 1004747: no DB in this test
 const realApiRequireBuilder = api.requireBuilder;
 const realAuthRequireBuilder = authMod.requireBuilder;
 api.requireBuilder = fakeBuilder;

package/tests/government_treasury.mjs

@@ -288,7 +288,8 @@ const realArchons = db.listActiveArchons;
 let caller = 3;
 let held = ['board.vote.cast'];
 let leads = [];
-api.requireBuilder = (req, res, next) => { req.builder = { id: caller, rank: caller === 3 ? 'archon' : 'metic' }; next(); };
+api.requireBuilder = (req, res, next) => { req.builder = { id: caller, rank: caller === 3 ? 'archon' : 'metic' }; req.gdsSession = { session_id: '1' }; next(); };
+require('../src/bongos/passkeys').stepUpStatus = async () => ({ required: false, fresh: false }); // task 1004747: no DB in this test
 resolver.resolveBuilderPermissions = async () => held;
 db.listLeads = async () => leads;
 db.listActiveArchons = async () => [{ id: '3', github_login: 'ada', display_name: 'Ada' }];

package/tests/hall_visor.mjs

@@ -271,6 +271,26 @@ test('Escape closes one layer, top first: the sheet, then the scene\'s pick, the
   await ctx.close();
 });
 
+test('a scene\'s pick: the card is on the glass, its action takes the accent button, Escape closes it first (task 1005243)', { skip }, async () => {
+  const { ctx, page, errors } = await open();
+  await page.evaluate(() => OTBVisor.focus({ key: 'runner:2', title: 'Area 2', status: { text: 'Running', tone: 'ok' }, lines: ['7 tasks done here'],
+    lead: { label: 'Recall runner', run() { window.led = (window.led || 0) + 1; } }, onClose() { window.unpicked = true; } }));
+  const g = await page.evaluate(() => ({
+    title: document.querySelector('.visor__focus-title').textContent,
+    status: document.querySelector('.visor__focus-status').textContent,
+    main: document.querySelector('.visor__main').textContent,
+    takes: getComputedStyle(document.querySelector('.visor__focus')).pointerEvents,
+  }));
+  assert.deepEqual(g, { title: 'Area 2', status: 'Running', main: 'Recall runner', takes: 'auto' });
+  await page.click('[data-visor-lead]');
+  assert.equal(await page.evaluate(() => window.led), 1, 'the accent button runs the scene\'s action');
+  await page.keyboard.press('Escape');
+  const s = await page.evaluate(() => ({ focus: OTBVisor.focused(), unpicked: window.unpicked, picked: window.picked, menu: window.optionsOpened, main: document.querySelector('.visor__main').textContent }));
+  assert.deepEqual(s, { focus: null, unpicked: true, picked: true, menu: 0, main: 'Goal skyG' }, 'the card took the press; the character\'s own button is back');
+  assert.deepEqual(errors, []);
+  await ctx.close();
+});
+
 test('a lead scene action is the first key hint, and its click and its key run it (task 1005209)', { skip }, async () => {
   const { ctx, page, errors } = await open();
   await page.evaluate(() => OTBVisor.scene({ name: 'test', place: 'Test city', actions: [{ label: 'Decide 2 in a row', key: 'd', bind: true, lead: true, run() { window.decided = (window.decided || 0) + 1; } }] }));

package/tests/home_runner.mjs

@@ -0,0 +1,115 @@
+// tests/home_runner.mjs — your Autobongos runner on Home's city (task 1005243).
+//
+// The decision is pure (home-runner.js cardFor / stateOf), so it runs here for
+// real against the same runner-button.js the Settings card draws from. The page
+// wiring is pinned by its source: the scene paints the pick, every button is the
+// visor's (ADR 0403), and only a viewer the server says may run gets any of it.
+// Run:  node --test tests/home_runner.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const require = createRequire(import.meta.url);
+const R = require(path.join(HALL, 'home-runner.js'));
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+
+const NOW = Date.parse('2026-11-12T10:00:00Z');
+const seen = new Date(NOW - 20000).toISOString();
+const fenceOf = (picks, allowed = [1, 2, 3], extra = {}) => ({ enabled: true, goals: picks, scope: { may_run: true, goals: picks }, project: { enabled: true, goals: allowed }, ...extra });
+const dev = (o = {}) => ({ host: 'pc', run_requested: true, run_changed_at: new Date(NOW - 3600e3).toISOString(), last_seen_at: seen, health: { state: 'alive', workingTaskId: null }, ...o });
+const STATS = { tasks_done: 7, tokens: 4820000, avg_task_seconds: 2280, tasks_left: 5 };
+const card = (o) => R.cardFor({ goal: { id: 2, title: 'Area 2' }, nowMs: NOW, titleOf: (g) => `Area ${g}`, stats: STATS, ...o });
+
+test('no permission to run, or no fence read: no card, the tower stays a link', () => {
+  assert.equal(card({ runners: [dev()], fence: null }), null);
+  assert.equal(card({ runners: [dev()], fence: { ...fenceOf([]), scope: { may_run: false, goals: [] } } }), null);
+});
+
+test('no runner set up yet: the card offers setting one up', () => {
+  const c = card({ runners: [], fence: fenceOf([]) });
+  assert.equal(c.lead.act, 'setup');
+  assert.equal(c.status.text, 'No runner yet');
+});
+
+test('a goal the project has not opened to runners: no send, only the goal', () => {
+  const c = card({ runners: [dev()], fence: fenceOf([], [1, 3]) });
+  assert.equal(c.lead.act, 'open');
+  assert.match(c.lines[0], /not opened this goal to runners/);
+});
+
+test('your runner is elsewhere or resting: Send runner here, with what it did here and what is left', () => {
+  const away = card({ runners: [dev()], fence: fenceOf([1]) });
+  assert.deepEqual(away.lead, { label: 'Send runner here', act: 'send' });
+  assert.equal(away.status.text, 'Your runner is at Area 1');
+  assert.deepEqual(away.lines, ['7 tasks done here · 4.8M tokens', '5 tasks ready · about 3 h for your runner']);
+  const off = card({ runners: [dev({ run_requested: false })], fence: fenceOf([]) });
+  assert.equal(off.status.text, 'Your runner is resting');
+  assert.equal(off.lead.act, 'send');
+});
+
+test('your runner is here and on: its device face, the numbers, and Recall runner', () => {
+  const work = card({ runners: [dev({ health: { state: 'alive', workingTaskId: '9' } })], fence: fenceOf([2]) });
+  assert.deepEqual(work.lead, { label: 'Recall runner', act: 'recall' });
+  assert.deepEqual([work.status.text, work.status.tone], ['Running', 'ok']);
+  assert.equal(work.lines[0], 'Working on task 9.');
+  const rest = card({ runners: [dev({ health: { state: 'alive', workingTaskId: null, holdUntil: new Date(NOW + 42 * 60e3).toISOString() } })], fence: fenceOf([2]) });
+  assert.match(rest.status.text, /^Resting until .+ · 42 min$/);
+  assert.equal(rest.lead.act, 'recall');
+});
+
+test('recalled here: it says so and offers to send it back', () => {
+  const c = card({ runners: [dev({ run_requested: false })], fence: fenceOf([2]) });
+  assert.equal(c.status.text, 'Recalled');
+  assert.equal(c.lead.act, 'send');
+});
+
+test('nothing done yet: no invented numbers; nothing ready: says so', () => {
+  const c = card({ runners: [dev()], fence: fenceOf([1]), stats: { tasks_done: 0, tokens: 0, avg_task_seconds: null, tasks_left: 0 } });
+  assert.deepEqual(c.lines, ['Nothing ready to build here right now.']);
+  const noPace = card({ runners: [dev()], fence: fenceOf([1]), stats: { tasks_done: 0, tokens: 0, avg_task_seconds: null, tasks_left: 4 } });
+  assert.deepEqual(noPace.lines, ['4 tasks ready'], 'no time is promised without a pace to measure it by');
+});
+
+test('the marker\'s state follows the device; several picks are not one tower', () => {
+  assert.equal(R.stateOf({ runners: [dev({ health: { state: 'alive', workingTaskId: '9' } })], fence: fenceOf([2]), nowMs: NOW }), 'working');
+  assert.equal(R.stateOf({ runners: [dev({ run_requested: false })], fence: fenceOf([2]), nowMs: NOW }), 'off');
+  assert.equal(R.stateOf({ runners: [dev({ health: { state: 'alive', holdUntil: new Date(NOW + 60e3).toISOString() } })], fence: fenceOf([2]), nowMs: NOW }), 'resting');
+  assert.equal(R.assignedGoal(fenceOf([2])), '2');
+  assert.equal(R.assignedGoal(fenceOf([1, 2])), null);
+});
+
+test('numbers read like a person would say them', () => {
+  assert.equal(R.tokensText(4820000), '4.8M tokens');
+  assert.equal(R.tokensText(340400), '340k tokens');
+  assert.equal(R.aboutText(5 * 2280), 'about 3 h');
+  assert.equal(R.aboutText(1200), 'about 20 min');
+  assert.equal(R.aboutText(3 * 86400), 'about 3 days');
+  assert.equal(R.aboutText(0), '');
+});
+
+test('source: the scene paints the pick, the visor holds every button (ADR 0403), the writes are Settings\' routes', () => {
+  const src = read('home-runner.js');
+  assert.match(src, /OTBVisor\.focus/, 'the card and its button are the visor\'s');
+  assert.doesNotMatch(src, /createElement\(['"]button/, 'no button is drawn in the scene');
+  assert.match(src, /scope\.may_run === true/, 'only a viewer the server says may run');
+  assert.match(src, /dataset\.game === 'on'/, 'game mode only: in classic a tower stays a link');
+  for (const route of ["'PUT', '/autonomy/me/goals'", '/autonomy/runners/${encodeURIComponent(r.host)}/run', '/autonomy/me/goals/${encodeURIComponent(picked)}/stats']) assert.ok(src.includes(route), route);
+  const draw = read('home-city-draw.js');
+  assert.match(draw, /'data-goal': a\.id/, 'every tower names its goal');
+  assert.match(draw, /hc-tower--picked/);
+  const html = read('index.html');
+  const at = (f) => html.indexOf(`/builders/${f}`);
+  assert.ok(at('runner-button.js') > 0 && at('runner-button.js') < at('home-runner.js') && at('home-runner.js') < at('home-city.js'), 'runner-button.js, then home-runner.js, before home-city.js');
+});
+
+test('source: the marker moves only in CSS, and the hall\'s reduced-motion rule stills it', () => {
+  const css = read('home-city.css');
+  assert.match(css, /\.hc-runner--working \.hc-runner__ring \{[^}]*animation: hc-turn/);
+  assert.doesNotMatch(read('home-runner.js'), /requestAnimationFrame|setInterval/, 'no motion in script');
+});

package/tests/module_api.mjs

@@ -23,6 +23,7 @@ const PUBLISHED_SURFACE = [
   'escapeHtml', // task 1004876: THE server-side HTML escaper (1.22.0) — modules render user text through it, never a private copy
   'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope', 'resolveSession',
   'requirePermission', // BV1.R105: the authority-atom gate module routes migrate onto (1.19.0; ADR 0151)
+  'requireCardStepUp', // added by task 1004747 (ADR 0382): the hardware-card step-up gate a module mounts after its permission gate
   'requireActAlone', // added by task 1004657 (ADR 0363 D5): a building's own page asks its decision-rules row before one builder acts alone. On the doorway because eight buildings' pages live in six modules and core, and each must refuse the same way People does
   'pool', 'getPool', 'instanceDbName', 'withTx', 'getBuilderById',
   // added by task 1003575 (ADR 0241 §3): the instance's PROJECT OWNER — its first