@bongos/core 1.24.95 → 1.25.1

package/modules/economy/processor-stripe.js

@@ -0,0 +1,292 @@
+'use strict';
+
+// modules/economy/processor-stripe.js — THE PAYMENT-RAIL ADAPTER: Stripe Connect, TEST MODE
+// ONLY (task 1005040, goal 1000092; ADR 0397 D1-D3, D5, D7).
+//
+// This is the one file that may name Stripe (ADR 0397: "a processor adapter module is the
+// only place that may name it"). Everything else calls the `economy.processor` port; a rail
+// change (the written J.P. Morgan fallback) replaces this file, not the product.
+//
+// TEST MODE ONLY. The factory refuses any key that is not `sk_test_…`, so no live key can be
+// stored or used by this build. Opening a live account is the owner's act and counsel's
+// items 1-4 (ADR 0385/0397) still gate it; lifting this guard is a separate, deliberate task.
+//
+// THE PORT (every method the callers already name; each is optional to the callers, all are
+// provided here):
+//   balanceMicro()                          the project's connected account balance
+//   memberBalanceMicro(accountRef)          one person's connected account balance
+//   confirmMemberAccount({accountRef, builderId})  true only for an account THIS project's
+//                                           connection opened for that person (metadata we set)
+//   memberTransfer({idempotencyKey, amountCents, currency, fromAccount, toAccount, toProject})
+//   transfer({idempotencyKey, amountCents, currency, builderId, payTo, taskId|moduleShareId})
+//                                           project account → the payee (self, or the guardian)
+//   memberPayout({idempotencyKey, amountCents, currency, account, payTo})
+//                                           connected account → the person's bank
+//   readSale({ref})                         a charge's own figures, never a screen's
+//   listMovements({since, until})           the project account's movements, by object id
+// Every money-moving call carries the caller's idempotency key as Stripe's `Idempotency-Key`,
+// so a retry gets back the object already made, never a second.
+//
+// ERROR MAPPING (ADR 0397 D7). An error carries `refused: true` ONLY when Stripe answered
+// 4xx (other than 408/409/429): it understood and created nothing. A timeout, a network
+// failure, a 5xx, a 409 or a 429 may have created the object, so they are not `refused` and
+// the caller retries on the same key.
+//
+// OPEN, UNVERIFIED AGAINST A LIVE TEST ACCOUNT (no Stripe account exists yet; the owner opens
+// it): account-to-account transfers (`memberTransfer`, `transfer`) are sent as a transfer made
+// "on behalf of" the paying connected account (the Stripe-Account header). If Stripe's account
+// type does not allow that, the call is refused and recorded `failed`; it never silently
+// moves money by another route.
+
+const crypto = require('node:crypto');
+
+const API = 'https://api.stripe.com';
+const MICRO_PER_CENT = 10_000;
+const CURRENCY = 'usd';
+const ACCOUNT_RE = /^acct_[A-Za-z0-9]{6,64}$/;
+const WEBHOOK_TOLERANCE_S = 300;
+
+class StripeError extends Error {
+  constructor(message, { code = 'stripe_error', status = null, refused = false } = {}) {
+    super(message);
+    this.name = 'StripeError';
+    this.code = code;
+    this.status = status;
+    this.refused = refused;
+  }
+}
+
+// Stripe takes form-encoded bodies, nested as a[b]=c.
+function encode(params, prefix = '') {
+  const out = [];
+  for (const [k, v] of Object.entries(params || {})) {
+    if (v === undefined || v === null) continue;
+    const key = prefix ? `${prefix}[${k}]` : k;
+    if (typeof v === 'object') out.push(...encode(v, key));
+    else out.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
+  }
+  return out;
+}
+
+function createStripeProcessor({
+  secretKey, projectAccount = null, projectKey = projectAccount || 'project', webhookSecret = null,
+  allowedOrigin = null,
+  fetchImpl = globalThis.fetch, memberAccountFor = null, timeoutMs = 12_000, now = () => Date.now(),
+} = {}) {
+  if (typeof secretKey !== 'string' || !/^sk_test_[A-Za-z0-9]{8,}$/.test(secretKey)) {
+    throw new StripeError('The Stripe key must be a test-mode secret key (sk_test_…); live keys are not accepted by this build.', { code: 'test_key_only' });
+  }
+  if (projectAccount !== null && !ACCOUNT_RE.test(projectAccount)) {
+    throw new StripeError('The project connected account must look like acct_….', { code: 'bad_project_account' });
+  }
+  if (typeof fetchImpl !== 'function') throw new StripeError('No fetch available.', { code: 'no_fetch' });
+
+  async function call(method, path, { params = null, account = null, idempotencyKey = null } = {}) {
+    const query = method === 'GET' && params ? `?${encode(params).join('&')}` : '';
+    const headers = { Authorization: `Bearer ${secretKey}` };
+    if (account) headers['Stripe-Account'] = account;
+    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
+    let body;
+    if (method !== 'GET') { headers['Content-Type'] = 'application/x-www-form-urlencoded'; body = encode(params).join('&'); }
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetchImpl(`${API}${path}${query}`, { method, headers, body, signal: ctl.signal });
+    } catch (e) {
+      // may have reached Stripe: not refused
+      throw new StripeError(e && e.name === 'AbortError' ? 'Stripe did not answer in time' : `could not reach Stripe: ${e && e.message}`, { code: e && e.name === 'AbortError' ? 'timeout' : 'network' });
+    } finally { clearTimeout(timer); }
+    let json = null;
+    try { json = await res.json(); } catch { /* handled below */ }
+    if (res.ok && json) return json;
+    // a 2xx we cannot read may have created the object: not refused, retried on the same key
+    if (res.ok) throw new StripeError('Stripe answered but the reply could not be read', { code: 'bad_response', status: res.status });
+    const e = (json && json.error) || {};
+    const status = res.status;
+    const refused = status >= 400 && status < 500 && ![408, 409, 429].includes(status);
+    throw new StripeError(e.message || `Stripe answered ${status}`, { code: e.code || e.type || `http_${status}`, status, refused });
+  }
+
+  const microOf = (cents) => cents * MICRO_PER_CENT;
+  const checkMoney = ({ amountCents, currency }) => {
+    if (!Number.isSafeInteger(amountCents) || amountCents <= 0) throw new StripeError('amountCents must be a positive whole number.', { code: 'bad_amount', refused: true });
+    if (String(currency).toLowerCase() !== CURRENCY) throw new StripeError('Only US dollars are supported.', { code: 'currency_not_supported', refused: true });
+  };
+  const needProject = () => {
+    if (!projectAccount) throw new StripeError('No project connected account is configured (STRIPE_PROJECT_ACCOUNT).', { code: 'no_project_account', refused: true });
+    return projectAccount;
+  };
+
+  // Balance reads sit behind any-builder pages, so identical reads inside a few seconds share one
+  // Stripe call (and one in-flight request). A stale figure is harmless: Stripe refuses an overdraw.
+  const BALANCE_TTL_MS = 5000;
+  const balanceCache = new Map();
+  function balanceOf(account) {
+    const hit = balanceCache.get(account);
+    if (hit && now() - hit.at < BALANCE_TTL_MS) return hit.p;
+    const p = readBalance(account);
+    balanceCache.set(account, { at: now(), p });
+    p.catch(() => { if (balanceCache.get(account) && balanceCache.get(account).p === p) balanceCache.delete(account); });
+    return p;
+  }
+  // The figure counts available plus pending, so it matches what our record books on funding.
+  async function readBalance(account) {
+    const b = await call('GET', '/v1/balance', { account });
+    const avail = (b.available || []).filter((x) => x.currency === CURRENCY).reduce((s, x) => s + Number(x.amount), 0);
+    const pending = (b.pending || []).filter((x) => x.currency === CURRENCY).reduce((s, x) => s + Number(x.amount), 0);
+    return microOf(avail + pending);
+  }
+
+  // Resolve the account a payout/transfer lands in: the person's own, or the guardian's for a
+  // 16-17 recipient (payout-gates `pay_to`). Never taken from the request.
+  async function payeeAccount({ builderId, payTo }) {
+    if (payTo && typeof payTo === 'object') {
+      if (!ACCOUNT_RE.test(String(payTo.guardian_account || ''))) throw new StripeError('The guardian has no usable account.', { code: 'no_guardian_account', refused: true });
+      return payTo.guardian_account;
+    }
+    const acct = typeof memberAccountFor === 'function' ? await memberAccountFor(String(builderId)) : null;
+    if (!acct || !ACCOUNT_RE.test(acct)) throw new StripeError('The person has no connected account in this project.', { code: 'no_member_account', refused: true });
+    return acct;
+  }
+
+  const adapter = {
+    name: 'stripe-connect-test',
+    testMode: true,
+
+    balanceMicro: () => balanceOf(needProject()),
+    memberBalanceMicro: (accountRef) => {
+      if (!ACCOUNT_RE.test(String(accountRef))) throw new StripeError('bad account reference', { code: 'bad_account', refused: true });
+      return balanceOf(accountRef);
+    },
+
+    // Opened by us for that person: the metadata is written only by createMemberAccount below.
+    async confirmMemberAccount({ accountRef, builderId }) {
+      if (!ACCOUNT_RE.test(String(accountRef))) return false;
+      const a = await call('GET', `/v1/accounts/${accountRef}`);
+      const m = a.metadata || {};
+      return m.bongos_builder_id === String(builderId) && m.bongos_project === projectKey;
+    },
+
+    // The processor's hosted onboarding starts here: an Express account stamped with whose it is.
+    async createMemberAccount({ builderId, idempotencyKey }) {
+      const a = await call('POST', '/v1/accounts', {
+        idempotencyKey: idempotencyKey || `bongos-account-${projectKey}-${builderId}`,
+        params: { type: 'express', capabilities: { transfers: { requested: true } }, metadata: { bongos_builder_id: String(builderId), bongos_project: projectKey } },
+      });
+      return { ref: a.id };
+    },
+    async onboardingLink({ accountRef, returnUrl, refreshUrl }) {
+      for (const u of [returnUrl, refreshUrl]) {
+        const okUrl = allowedOrigin ? String(u).startsWith(`${allowedOrigin}/`) : /^https:\/\//.test(String(u));
+        if (!okUrl) throw new StripeError('Onboarding return addresses must be on the project own site.', { code: 'bad_return_url', refused: true });
+      }
+      const l = await call('POST', '/v1/account_links', { params: { account: accountRef, type: 'account_onboarding', return_url: returnUrl, refresh_url: refreshUrl } });
+      return { url: l.url };
+    },
+
+    async memberTransfer({ idempotencyKey, amountCents, currency, fromAccount, toAccount, toProject }) {
+      checkMoney({ amountCents, currency });
+      const dest = toProject ? needProject() : toAccount;
+      if (!ACCOUNT_RE.test(String(fromAccount)) || !ACCOUNT_RE.test(String(dest))) throw new StripeError('bad account reference', { code: 'bad_account', refused: true });
+      const t = await call('POST', '/v1/transfers', {
+        idempotencyKey, account: fromAccount,
+        params: { amount: amountCents, currency: CURRENCY, destination: dest, metadata: { bongos_key: idempotencyKey } },
+      });
+      return { ref: t.id };
+    },
+
+    async transfer({ idempotencyKey, amountCents, currency, builderId, payTo }) {
+      checkMoney({ amountCents, currency });
+      const dest = await payeeAccount({ builderId, payTo });
+      const t = await call('POST', '/v1/transfers', {
+        idempotencyKey, account: needProject(),
+        params: { amount: amountCents, currency: CURRENCY, destination: dest, metadata: { bongos_key: idempotencyKey } },
+      });
+      return { ref: t.id };
+    },
+
+    async memberPayout({ idempotencyKey, amountCents, currency, account, payTo = 'self' }) {
+      checkMoney({ amountCents, currency });
+      // A Stripe payout goes to the bank on the connected account itself. A 16-17 recipient's
+      // money must go to the guardian (payout-gates `pay_to`), which this call cannot do, so it
+      // is refused rather than paid to the wrong person. Nothing is sent.
+      if (payTo !== 'self') throw new StripeError('This payout must go to a guardian account, which a bank payout cannot do.', { code: 'guardian_payout_unsupported', refused: true });
+      if (!ACCOUNT_RE.test(String(account))) throw new StripeError('bad account reference', { code: 'bad_account', refused: true });
+      const p = await call('POST', '/v1/payouts', {
+        idempotencyKey, account,
+        params: { amount: amountCents, currency: CURRENCY, metadata: { bongos_key: idempotencyKey } },
+      });
+      return { ref: p.id, paid: p.status === 'paid' };
+    },
+
+    // ref is the PaymentIntent id of the buyer's charge. Figures come from Stripe, not the caller.
+    async readSale({ ref }) {
+      const p = await call('GET', `/v1/payment_intents/${encodeURIComponent(ref)}`);
+      if (p.status !== 'succeeded') throw new StripeError(`The sale ${ref} has not been paid.`, { code: 'sale_not_paid', refused: true });
+      return {
+        moduleKey: (p.metadata || {}).module_key,
+        priceCents: Number(p.amount),
+        platformFeeCents: p.application_fee_amount == null ? 0 : Number(p.application_fee_amount),
+        currency: String(p.currency || '').toUpperCase(),
+      };
+    },
+
+    // Compared with our record by object id (tr_, po_, py_…); the size of the movement, unsigned.
+    async listMovements({ since, until }) {
+      const account = needProject();
+      const out = [];
+      let after = null;
+      for (let page = 0; page < 50; page++) {
+        const r = await call('GET', '/v1/balance_transactions', {
+          account,
+          params: { limit: 100, 'created[gte]': Math.floor(new Date(since).getTime() / 1000), 'created[lt]': Math.ceil(new Date(until).getTime() / 1000), starting_after: after },
+        });
+        for (const t of r.data || []) {
+          if (t.currency !== CURRENCY || !t.source) continue;
+          out.push({ ref: typeof t.source === 'string' ? t.source : t.source.id, amountMicro: microOf(Math.abs(Number(t.amount))), createdAt: new Date(t.created * 1000).toISOString() });
+        }
+        if (!r.has_more || !(r.data || []).length) return out;
+        after = r.data[r.data.length - 1].id;
+      }
+      throw new StripeError('Too many movements to list in one check.', { code: 'too_many' });
+    },
+
+    // Webhook: verify Stripe's signature over the RAW body, then translate the payout news into
+    // the cash-out call. Returns { handled, outcome?, ref?, reason? }; throws on a bad signature.
+    verifyWebhook(rawBody, signatureHeader) {
+      if (!webhookSecret) throw new StripeError('No webhook secret is configured.', { code: 'no_webhook_secret' });
+      const parts = Object.fromEntries(String(signatureHeader || '').split(',').map((p) => p.split('=')).filter((p) => p.length === 2));
+      const t = Number(parts.t);
+      // a timestamp from the future is as suspect as an old one; replays inside the window are
+      // harmless only because recordProcessorOutcome repeats as a no-op (the route must keep that).
+      const age = now() / 1000 - t;
+      if (!Number.isFinite(t) || age > WEBHOOK_TOLERANCE_S || age < -60) throw new StripeError('Stale or missing webhook timestamp.', { code: 'bad_signature' });
+      const want = crypto.createHmac('sha256', webhookSecret).update(`${t}.${rawBody}`).digest('hex');
+      const ok = String(signatureHeader).split(',').some((p) => p.startsWith('v1=') && p.length === 3 + want.length
+        && crypto.timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(want)));
+      if (!ok) throw new StripeError('Webhook signature does not match.', { code: 'bad_signature' });
+      return JSON.parse(rawBody);
+    },
+    payoutNews(event) {
+      const o = event && event.data && event.data.object;
+      if (!o || !o.id) return { handled: false };
+      if (event.type === 'payout.paid') return { handled: true, outcome: 'paid', ref: o.id };
+      if (event.type === 'payout.failed') return { handled: true, outcome: 'returned', ref: o.id, reason: o.failure_message || o.failure_code || 'the bank returned this payout' };
+      return { handled: false };
+    },
+  };
+  return adapter;
+}
+
+// Built from the environment; null when no key is set (every flow then holds `no_processor`).
+function fromEnv(env = process.env, extra = {}) {
+  if (!env.STRIPE_SECRET_KEY) return null;
+  return createStripeProcessor({
+    secretKey: env.STRIPE_SECRET_KEY, projectAccount: env.STRIPE_PROJECT_ACCOUNT || null,
+    projectKey: env.STRIPE_PROJECT_KEY || env.STRIPE_PROJECT_ACCOUNT || 'project', allowedOrigin: env.STRIPE_ONBOARDING_ORIGIN || null,
+    webhookSecret: env.STRIPE_WEBHOOK_SECRET || null, ...extra,
+  });
+}
+
+module.exports = { createStripeProcessor, fromEnv, StripeError, encode };

package/modules/economy/routes/balances.js

@@ -31,6 +31,7 @@ function personalWebSession(req) {
 
 module.exports = function buildBalancesRouter({ processor = null } = {}) {
   const router = express.Router();
+  const proc = () => processor || api.resolveOptional('economy.processor');
 
   const fail = (res, err, what) => {
     if (err instanceof TransferRefusal) return res.fail(err.code, { status: err.status, message: err.message });
@@ -41,7 +42,7 @@ module.exports = function buildBalancesRouter({ processor = null } = {}) {
   // rank: any-builder — the signed-in person's own balance and their own payments.
   router.get('/balances/me', api.requireBuilder, async (req, res) => {
     try {
-      const out = await readMyBalance(api.pool, req.builder.id, { processor, limit: req.query.limit, log });
+      const out = await readMyBalance(api.pool, req.builder.id, { processor: proc(), limit: req.query.limit, log });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fail(res, err, 'GET /balances/me'); }
@@ -50,7 +51,7 @@ module.exports = function buildBalancesRouter({ processor = null } = {}) {
   // rank: any-builder — the project's balance figure, so a member can see whether it needs funding.
   router.get('/balances/project', api.requireBuilder, async (req, res) => {
     try {
-      const out = await readProjectBalance({ processor, log });
+      const out = await readProjectBalance({ processor: proc(), log });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fail(res, err, 'GET /balances/project'); }
@@ -65,7 +66,7 @@ module.exports = function buildBalancesRouter({ processor = null } = {}) {
       const out = await transfer({
         kind, fromBuilderId: String(req.builder.id), toBuilderId: b.to_builder_id,
         amountCents: b.amount_cents, instructionId: b.instruction_id, note: b.note,
-      }, { pool: api.pool, processor });
+      }, { pool: api.pool, processor: proc() });
       res.status(out.status === 'sent' ? 200 : 202).json(out);
     } catch (err) { fail(res, err, `POST /balances/${kind}`); }
   };

package/modules/economy/routes/project-account.js

@@ -18,6 +18,7 @@ const api = require('../../../src/module-api');
 const { readAccount, recordMovement, lockAccount, releaseSettledHolds, readAvailable } = require('../project-account');
 const { readOutflow } = require('../outflow');
 const { readLedgerChecks } = require('../ledger-check');
+const { fromEnv: stripeFromEnv } = require('../processor-stripe');
 const { memberAccount } = require('../user-balances');
 
 const log = api.logger('economy');
@@ -33,18 +34,28 @@ function registerSeams() {
   if (!api.hasProvider('economy.account')) {
     api.registerProvider('economy.account', { recordMovement, lockAccount, releaseSettledHolds, readAvailable, memberAccount });
   }
+  // The `economy.processor` PORT (task 1005040, ADR 0397): the Stripe Connect TEST-mode adapter,
+  // registered only when STRIPE_SECRET_KEY (an sk_test_ key) is set. With none, every flow holds
+  // `no_processor`, exactly as before. A bad key is logged and leaves the port unregistered.
+  if (!api.hasProvider('economy.processor')) {
+    try {
+      const adapter = stripeFromEnv(process.env, { memberAccountFor: (builderId) => memberAccount(api.pool, builderId) });
+      if (adapter) api.registerProvider('economy.processor', adapter);
+    } catch (e) { log.error({ err: e.message }, 'economy.processor not registered'); }
+  }
 }
 
 module.exports = function buildProjectAccountRouter({ processor = null } = {}) {
   registerSeams();
   const router = express.Router();
+  const proc = () => processor || api.resolveOptional('economy.processor');
 
   // rank: payout.approve (archon floor) — the owner. The account's balance and who was paid what
   // is the project's own money, so only the payout authority reads it (ADR 0016: enforced here, server-side).
   router.get('/project-account', api.requireBuilder, api.requirePermission('payout.approve'), async (req, res) => {
     try {
       const { limit, offset } = api.parsePagination(req, { defaultLimit: 50, maxLimit: 200 });
-      const out = await readAccount(api.pool, { limit, offset, processor, log });
+      const out = await readAccount(api.pool, { limit, offset, processor: proc(), log });
       res.set('Cache-Control', 'no-store');
       res.json({ ...out, page: api.pageMeta(limit, offset, out.movement_count) });
     } catch (err) {

package/modules/economy/tests/processor_stripe.mjs

@@ -0,0 +1,135 @@
+// modules/economy/tests/processor_stripe.mjs — task 1005040. DB-free, no network: the Stripe
+// Connect test-mode adapter against a fake fetch. Run: node modules/economy/tests/processor_stripe.mjs
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+import crypto from 'node:crypto';
+const require = createRequire(import.meta.url);
+const { createStripeProcessor, fromEnv } = require('../processor-stripe.js');
+
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+// Fake keys are assembled at run time so no key-shaped literal sits in the repo.
+const FAKE = 'placeholder12345678';
+const KEY = ['sk', 'test', FAKE].join('_');
+const LIVE = ['sk', 'live', FAKE].join('_');
+const RESTRICTED = ['rk', 'test', FAKE].join('_');
+const PROJ = 'acct_project0001';
+const ME = 'acct_member00001';
+
+const calls = [];
+const fake = (answer) => async (url, init) => {
+  calls.push({ url, ...init });
+  const r = await answer(url, init);
+  return { ok: (r.status || 200) < 400, status: r.status || 200, json: async () => r.body };
+};
+const make = (answer, extra = {}) => createStripeProcessor({ secretKey: KEY, projectAccount: PROJ, projectKey: 'p1', fetchImpl: fake(answer), memberAccountFor: async (id) => (id === '5' ? ME : null), ...extra });
+const err = async (fn) => { try { await fn(); } catch (e) { return e; } return null; };
+
+// ── test mode only ───────────────────────────────────────────────────────
+ok((await err(() => createStripeProcessor({ secretKey: LIVE }))).code === 'test_key_only', 'a live key is refused');
+ok((await err(() => createStripeProcessor({ secretKey: RESTRICTED }))).code === 'test_key_only', 'only test secret keys are accepted');
+ok(fromEnv({}) === null, 'no key in the environment: no adapter (flows hold no_processor)');
+ok(fromEnv({ STRIPE_SECRET_KEY: KEY, STRIPE_PROJECT_ACCOUNT: PROJ }).testMode === true, 'built from the environment, flagged test mode');
+
+// ── payout: key, account header, paid flag, refused mapping ──────────────
+let p = make(() => ({ body: { id: 'po_1', status: 'in_transit' } }));
+let out = await p.memberPayout({ idempotencyKey: 'bongos-cashout-7-1', amountCents: 2500, currency: 'USD', account: ME });
+ok(out.ref === 'po_1' && out.paid === false, 'payout returns the reference, not yet paid');
+const c = calls.at(-1);
+ok(c.url.endsWith('/v1/payouts') && c.headers['Idempotency-Key'] === 'bongos-cashout-7-1', 'payout sends the caller idempotency key');
+ok(c.headers['Stripe-Account'] === ME && c.body.includes('amount=2500') && c.body.includes('currency=usd'), "payout acts on the person's account for the exact amount");
+p = make(() => ({ body: { id: 'po_2', status: 'paid' } }));
+ok((await p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME })).paid === true, 'a payout Stripe reports paid is paid');
+p = make(() => ({ status: 400, body: { error: { code: 'balance_insufficient', message: 'no funds' } } }));
+let e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+ok(e.refused === true && e.code === 'balance_insufficient', 'a 4xx that created nothing is refused');
+for (const status of [500, 409, 429, 408]) {
+  p = make(() => ({ status, body: { error: { message: 'x' } } }));
+  e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+  ok(e && e.refused === false, `a ${status} may have paid, so it is not refused (retry on the same key)`);
+}
+p = make(() => { throw new Error('socket hang up'); });
+e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+ok(e.refused === false && e.code === 'network', 'a network failure is not refused');
+p = make(() => ({ body: {} }));
+ok((await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 10.5, currency: 'USD', account: ME }))).refused === true, 'a fractional amount is refused before any call');
+ok((await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'EUR', account: ME }))).code === 'currency_not_supported', 'only dollars');
+ok((await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: 'nope' }))).code === 'bad_account', 'a malformed account is refused');
+
+// guardian routing, unreadable replies, project key, cache, urls
+p = make(() => ({ body: { id: 'po_x' } }));
+const n0 = calls.length;
+e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME, payTo: { guardian_id: '2', guardian_account: 'acct_guardian001' } }));
+ok(e.code === 'guardian_payout_unsupported' && e.refused === true && calls.length === n0, 'a guardian-routed payout is refused and nothing is sent');
+p = make(() => ({ status: 200, body: null }));
+e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+ok(e.code === 'bad_response' && e.refused === false, 'a 2xx with an unreadable body is not refused and says so');
+ok(fromEnv({ STRIPE_SECRET_KEY: KEY, STRIPE_PROJECT_ACCOUNT: PROJ }).confirmMemberAccount.length >= 0, 'built without a project key falls back to the project account');
+let reads = 0;
+p = make(() => { reads++; return { body: { available: [{ amount: 100, currency: 'usd' }], pending: [] } }; });
+await Promise.all([p.balanceMicro(), p.balanceMicro(), p.memberBalanceMicro(ME), p.memberBalanceMicro(ME)]);
+ok(reads === 2, 'identical balance reads at once share one Stripe call per account');
+p = make(() => ({ body: { url: 'https://x' } }), { allowedOrigin: 'https://proj.example' });
+ok((await err(() => p.onboardingLink({ accountRef: ME, returnUrl: 'https://evil.example/x', refreshUrl: 'https://proj.example/y' }))).code === 'bad_return_url', 'onboarding addresses outside the project origin are refused');
+ok((await p.onboardingLink({ accountRef: ME, returnUrl: 'https://proj.example/a', refreshUrl: 'https://proj.example/b' })).url === 'https://x', 'addresses on the project origin pass');
+
+// ── balances ─────────────────────────────────────────────────────────────
+p = make(() => ({ body: { available: [{ amount: 1000, currency: 'usd' }, { amount: 5, currency: 'eur' }], pending: [{ amount: 250, currency: 'usd' }] } }));
+ok(await p.balanceMicro() === 1250 * 10000, 'project balance is the dollar total in micro-dollars (other currencies ignored)');
+ok(calls.at(-1).headers['Stripe-Account'] === PROJ, 'read from the project account');
+ok(await p.memberBalanceMicro(ME) === 1250 * 10000 && calls.at(-1).headers['Stripe-Account'] === ME, 'member balance reads the member account');
+
+// ── account confirmation ─────────────────────────────────────────────────
+p = make(() => ({ body: { id: ME, metadata: { bongos_builder_id: '5', bongos_project: 'p1' } } }));
+ok(await p.confirmMemberAccount({ accountRef: ME, builderId: '5' }) === true, 'an account we opened for that person is confirmed');
+ok(await p.confirmMemberAccount({ accountRef: ME, builderId: '6' }) === false, 'not for someone else');
+p = make(() => ({ body: { id: ME, metadata: { bongos_builder_id: '5', bongos_project: 'other' } } }));
+ok(await p.confirmMemberAccount({ accountRef: ME, builderId: '5' }) === false, 'not an account another project opened');
+
+// ── transfers ────────────────────────────────────────────────────────────
+p = make(() => ({ body: { id: 'tr_1' } }));
+out = await p.transfer({ idempotencyKey: 'bongos-payout-9', amountCents: 700, currency: 'USD', builderId: '5', payTo: 'self' });
+ok(out.ref === 'tr_1' && calls.at(-1).headers['Stripe-Account'] === PROJ && calls.at(-1).body.includes(`destination=${ME}`), "a payout transfer goes project → the builder's own account");
+await p.transfer({ idempotencyKey: 'k2', amountCents: 700, currency: 'USD', builderId: '5', payTo: { guardian_id: '2', guardian_account: 'acct_guardian001' } });
+ok(calls.at(-1).body.includes('destination=acct_guardian001'), 'a 16-17 recipient is paid to the guardian');
+e = await err(() => p.transfer({ idempotencyKey: 'k3', amountCents: 700, currency: 'USD', builderId: '99', payTo: 'self' }));
+ok(e.code === 'no_member_account' && e.refused, 'no connected account: refused, nothing sent');
+const before = calls.length;
+await p.memberTransfer({ idempotencyKey: 'k4', amountCents: 300, currency: 'USD', fromAccount: ME, toAccount: null, toProject: true });
+ok(calls.length === before + 1 && calls.at(-1).body.includes(`destination=${PROJ}`) && calls.at(-1).headers['Stripe-Account'] === ME, 'funding the project: member account → project account');
+const bare = createStripeProcessor({ secretKey: KEY, fetchImpl: fake(() => ({ body: { id: 'x' } })) });
+ok((await err(() => bare.balanceMicro())).code === 'no_project_account', 'no project account configured: refused');
+
+// ── sale ─────────────────────────────────────────────────────────────────
+p = make(() => ({ body: { id: 'pi_1', status: 'succeeded', amount: 1000, currency: 'usd', application_fee_amount: 100, metadata: { module_key: 'cool-mod' } } }));
+const sale = await p.readSale({ ref: 'pi_1' });
+ok(sale.moduleKey === 'cool-mod' && sale.priceCents === 1000 && sale.platformFeeCents === 100 && sale.currency === 'USD', 'a sale is read from Stripe, in the shape the module-share code checks');
+p = make(() => ({ body: { id: 'pi_2', status: 'requires_payment_method', amount: 1000, currency: 'usd' } }));
+ok((await err(() => p.readSale({ ref: 'pi_2' }))).code === 'sale_not_paid', 'an unpaid sale is refused');
+
+// ── movements, with paging ───────────────────────────────────────────────
+let page = 0;
+p = make(() => (++page === 1
+  ? { body: { has_more: true, data: [{ id: 'txn_1', source: 'tr_1', amount: -700, currency: 'usd', created: 1_700_000_000 }] } }
+  : { body: { has_more: false, data: [{ id: 'txn_2', source: 'po_1', amount: 2500, currency: 'usd', created: 1_700_000_100 }] } }));
+const mv = await p.listMovements({ since: new Date(1_699_000_000_000), until: new Date(1_701_000_000_000) });
+ok(mv.length === 2 && mv[0].ref === 'tr_1' && mv[0].amountMicro === 700 * 10000 && mv[1].ref === 'po_1', 'movements are paged and listed by object id, unsigned, in micro-dollars');
+ok(calls.at(-1).url.includes('starting_after=txn_1'), 'the second page continues after the first');
+
+// ── webhook ──────────────────────────────────────────────────────────────
+const SECRET = 'webhook-test-secret';
+const hook = createStripeProcessor({ secretKey: KEY, webhookSecret: SECRET, fetchImpl: fake(() => ({})), now: () => 1_700_000_000_000 });
+const body = JSON.stringify({ type: 'payout.failed', data: { object: { id: 'po_9', failure_message: 'account closed' } } });
+const sign = (t, b) => `t=${t},v1=${crypto.createHmac('sha256', SECRET).update(`${t}.${b}`).digest('hex')}`;
+const ev = hook.verifyWebhook(body, sign(1_700_000_000, body));
+ok(ev.type === 'payout.failed', 'a correctly signed webhook is accepted');
+const news = hook.payoutNews(ev);
+ok(news.outcome === 'returned' && news.ref === 'po_9' && news.reason === 'account closed', "payout.failed becomes a return with the bank's reason");
+ok(hook.payoutNews({ type: 'payout.paid', data: { object: { id: 'po_9' } } }).outcome === 'paid', 'payout.paid becomes paid');
+ok(hook.payoutNews({ type: 'charge.succeeded', data: { object: { id: 'ch_1' } } }).handled === false, 'other events are ignored');
+ok((await err(() => hook.verifyWebhook(`${body} `, sign(1_700_000_000, body)))).code === 'bad_signature', 'a tampered body is refused');
+ok((await err(() => hook.verifyWebhook(body, sign(1_699_990_000, body)))).code === 'bad_signature', 'a stale timestamp is refused');
+ok((await err(() => hook.verifyWebhook(body, sign(1_700_000_200, body)))).code === 'bad_signature', 'a timestamp from the future is refused');
+ok((await err(() => hook.verifyWebhook(body, 't=1700000000,v1=abcd'))).code === 'bad_signature', 'a wrong signature is refused');
+
+console.log(`\n${pass} passed`);

package/modules/government/catalog.js

@@ -128,7 +128,7 @@ const PERMISSIONS = [
   // "runner operators" should be able to compose one. It can never widen the fence
   // — the project allowlist and the kill switch stay behind autonomy.fence.manage —
   // so delegating it delegates only "whose machine may work the allowed goals".
-  { key: 'autonomy.run', system: false, floor: 'metic', guards: 'PUT /autonomy/me/goals (a builder\'s own runner scope); also decides whether GET /autonomy/fence answers enabled for the caller' },
+  { key: 'autonomy.run', system: false, floor: 'metic', guards: 'PUT /autonomy/me/goals (a builder\'s own runner scope) and GET /autonomy/me/goals/:goalId/stats (its numbers on one goal); also decides whether GET /autonomy/fence answers enabled for the caller' },
   // BV1.R21 (task 1003608, goal 1000086). ADR 0250 §6 amends ADR 0157 for exactly
   // this key: `version.create` returns to the Archon floor.
   //

package/modules/government/routes/government.js

@@ -1344,7 +1344,7 @@ module.exports = function buildGovernmentRouter() {
   // seat while it is unseated — may (403 not_the_holder). Only an open goal.
   //
   // Body: { budget_usd: number | null }  → 200 { ok, pot | removed }
-  router.put('/government/treasury/pots/:goalId', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+  router.put('/government/treasury/pots/:goalId', api.requireBuilder, api.requirePermission('board.vote.cast'), api.requireCardStepUp, async (req, res) => {
     const goalId = parseId(req, res, { param: 'goalId', code: 'bad_goal_id', positiveInt: true });
     if (goalId === null) return;
     if (validateOrRespond(req, res, { budget_usd: {} })) return; // a number of dollars, or null to take the pot away; parsed below
@@ -1375,7 +1375,7 @@ module.exports = function buildGovernmentRouter() {
   // stops nothing: with no spend limit, work runs on and the overspend is debt.
   //
   // Body: { key: 'lend' | 'half' | 'no' }  → 200 { ok, borrow }
-  router.post('/government/treasury/borrows/:borrowId/answer', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+  router.post('/government/treasury/borrows/:borrowId/answer', api.requireBuilder, api.requirePermission('board.vote.cast'), api.requireCardStepUp, async (req, res) => {
     const borrowId = parseId(req, res, { param: 'borrowId', code: 'bad_borrow_id', positiveInt: true });
     if (borrowId === null) return;
     if (validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: 16 } })) return;

package/modules/hall-ui/public/home-city-draw.js

@@ -297,6 +297,8 @@
       const a = it.a, x0 = a.x, y0 = a.y, x1 = x0 + FOOT, y1 = y0 + FOOT, base = 4;
       const d = doneAt(a, t), built = Math.max(2, (d.build + d.art) * m.px), clad = d.art * m.px;
       const site = sites[a.id], who = site ? m.people[site.builder] : null, agent = !!(site && (site.agent || (who && who.agent)));
+      // your runner sent here (task 1005243): its marker stands in for the agent's face
+      const mine = latest && o.runner && o.runner.goal === a.id ? o.runner.state : null;
       const wait = latest ? (m.waiting[a.id] || 0) : 0;
       const g = [];
       g.push(...box(x0 - 0.12, y0 - 0.12, x1 + 0.12, y1 + 0.12, 0, base, I.plinth));
@@ -330,12 +332,13 @@
         const hx = mx + 1.8;
         g.push(line(P(hx, my, ct), P(hx, my, top - 6), I.steel, 1));
         g.push(node('g', { class: 'hc-slab' }, box(hx - 0.3, my - 0.2, hx + 0.3, my + 0.2, top - 38, 3, I.slab)));
-        if (who) over.push({ k: 'face', p: P(mx + 0.9, my, ct + 30), who, agent, a });
+        if (who && !mine) over.push({ k: 'face', p: P(mx + 0.9, my, ct + 30), who, agent, a });
       }
+      if (mine) over.push({ k: 'runner', p: site ? P(x0 + 1.4, y0 + 0.5, top + 86) : P((x0 + x1) / 2, (y0 + y1) / 2, top + 40), state: mine, a });
       if (wait) over.push({ k: 'dot', p: P((x0 + x1) / 2, (y0 + y1) / 2, top + (site ? 12 : 22)), a, n: wait });
       const shipped = Math.round(d.build + d.art), byArt = Math.round(d.art);
       const tip = `${shipped} shipped${byArt ? ` · ${byArt} by artists` : ''}${who ? ` · ${agent ? `${who.name}'s agent` : who.name} on site` : ''} · click to open the goal`;
-      out.push(node('a', { href: `/goals#/goal/${encodeURIComponent(a.id)}`, class: 'hc-tower', 'aria-label': `${a.title}: ${shipped} shipped. Open the goal.`, 'data-tip': a.title, 'data-tip-body': tip }, g));
+      out.push(node('a', { href: `/goals#/goal/${encodeURIComponent(a.id)}`, class: 'hc-tower' + (o.picked === a.id ? ' hc-tower--picked' : ''), 'data-goal': a.id, 'aria-label': `${a.title}: ${shipped} shipped. Open the goal.`, 'data-tip': a.title, 'data-tip-body': tip }, g));
       // the cloud at its foot, over this tower and under the next one forward
       if (cloudy) out.push(puff(x1 - 0.5, y1 - 0.5, 62));
     });
@@ -344,6 +347,7 @@
 
     over.forEach((v, n) => {
       if (v.k === 'face') { out.push(avatarNode(v.p, v.who, v.agent, v.a, I, n, node, line, circle)); return; }
+      if (v.k === 'runner') { out.push(runnerNode(v.p, v.state, v.a, I, node, line, circle)); return; }
       const cx = v.p[0] - 30, cy = v.p[1];
       out.push(node('g', { class: 'hc-wait', 'data-tip': v.a.title, 'data-tip-body': `${v.n} waiting on you` }, [
         circle(cx, cy, 11, { fill: 'var(--accent)', stroke: 'var(--bg-card)', 'stroke-width': 2.5 }),
@@ -607,6 +611,24 @@
     return node('g', { class: 'hc-face-pin', 'data-tip': agent ? `${who.name}'s agent` : who.name, 'data-tip-body': a.title }, g);
   }
 
+  // Your Autobongos runner on the tower it was sent to (task 1005243): the agent's robot face,
+  // ringed in the state it is in. Working wears the accent ring that turns (CSS, under the
+  // Kill Switch); resting a dashed ring; starting the info ring; ready a soft ring; off no ring
+  // and a faded face. The words for each are the visor's card, never this mark alone.
+  // The same words the visor's card puts on the device's face (runner-button.js buttonState).
+  const RUNNER_WORDS = { working: 'Running', resting: 'Resting', starting: 'Starting…', ready: 'Ready', off: 'Recalled' };
+  function runnerNode(p, state, a, I, node, line, circle) {
+    const x = p[0], y = p[1];
+    const st = RUNNER_WORDS[state] ? state : 'off';
+    return node('g', { class: `hc-runner hc-runner--${st}`, 'data-goal': a.id, 'data-tip': 'Your runner', 'data-tip-body': `${RUNNER_WORDS[st]} · ${a.title}` }, [
+      line([x, y + 18], [x, y + 32], I.steel, 1),
+      circle(x, y, 21, { class: 'hc-runner__ring', fill: 'none', 'stroke-width': 2.5 }),
+      circle(x, y, 16, { class: 'hc-runner__face', fill: I.avAgent, stroke: 'var(--bg-card)', 'stroke-width': 3 }),
+      node('rect', { class: 'hc-runner__ink', x: r1(x - 7), y: r1(y - 5), width: 14, height: 11, rx: 3, fill: 'none', stroke: I.avInk, 'stroke-width': 1.5 }),
+      circle(x - 3, y + 0.5, 1.5, { class: 'hc-runner__eye', fill: I.avInk }), circle(x + 3, y + 0.5, 1.5, { class: 'hc-runner__eye', fill: I.avInk }),
+    ]);
+  }
+
   function initial(name) { const s = String(name || '').trim(); return s ? s[0].toUpperCase() : '?'; }
   // a stable spread for an idea's place in the sky (FNV-1a over its id)
   function hash(s) { let h = 2166136261; for (const c of String(s)) { h ^= c.charCodeAt(0); h = Math.imul(h, 16777619); } return Math.abs(h); }

package/modules/hall-ui/public/home-city.css

@@ -38,6 +38,20 @@ html[data-game="on"] body[data-page="home"] .page-head--hall .page-head__h { wid
 .hc-svg a:focus { outline: none; }
 .hc-svg a:focus-visible .hc-face { filter: brightness(1.35); }
 .hc-svg .hc-tower:hover .hc-face { filter: brightness(1.3); }
+/* game mode, your runner (task 1005243): the tower picked for the visor's card is lit and edged
+   in the accent; your runner's marker is the agent's face in a ring that says its state */
+.hc-svg .hc-tower--picked .hc-face { filter: brightness(1.2); stroke: var(--accent); stroke-width: 2px; }
+.hc-svg .hc-runner { cursor: pointer; }
+.hc-svg .hc-runner__ring { stroke: var(--ink-soft); stroke-opacity: .5; stroke-width: 3.5px; }
+/* yours, not anyone's agent: the accent face, the dark ink on it */
+.hc-svg .hc-runner__face { fill: var(--accent); }
+.hc-svg .hc-runner__ink { stroke: var(--accent-on); }
+.hc-svg .hc-runner__eye { fill: var(--accent-on); }
+.hc-svg .hc-runner--working .hc-runner__ring { stroke: var(--accent); stroke-opacity: 1; stroke-dasharray: 22 10; transform-box: fill-box; transform-origin: center; animation: hc-turn 6s linear infinite; }
+.hc-svg .hc-runner--starting .hc-runner__ring { stroke: var(--info); stroke-opacity: 1; stroke-dasharray: 4 6; }
+.hc-svg .hc-runner--resting .hc-runner__ring { stroke: var(--info); stroke-opacity: .9; stroke-dasharray: 2 5; }
+.hc-svg .hc-runner--off { opacity: .55; }
+.hc-svg .hc-runner--off .hc-runner__ring { stroke-opacity: 0; }
 /* the core and the museum stay quiet on the builder's Home so the new buildings lead;
    each comes back to full colour under the pointer or the keyboard */
 .hc-svg .hc-quiet { opacity: .62; filter: saturate(.3); transition: opacity .3s, filter .3s; }
@@ -110,6 +124,7 @@ html[data-theme="dark"] .home-city.hc-is-sky { background: linear-gradient(color
 
 /* live, and nothing more: a crane's slab climbs, this week's ideas glow (20s+) */
 @keyframes hc-lift { 0%, 12% { transform: translateY(0); } 55%, 70% { transform: translateY(-24px); } 100% { transform: translateY(0); } }
+@keyframes hc-turn { to { transform: rotate(360deg); } }
 @keyframes hc-glow { 0%, 100% { opacity: .55; } 50% { opacity: 1; } }
 @keyframes hc-live { 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--ok) 55%, transparent); } 100% { box-shadow: 0 0 0 8px transparent; } }
 .hc-slab { animation: hc-lift 20s ease-in-out infinite; }