@arcforgelabs/flow 2026.10.45 → 2026.10.47

package/server/core/sending.js

@@ -1,8 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
-import { billingObligations, invoiceLines, invoices } from '../db/schema.js';
+import { billingObligations, contacts, invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
-import { listRules, rulePending } from './invoice-rules.js';
+import { listRules, rulePending, ruleSkip } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings } from './invoicing-rules.js';
 import { issueInvoice } from './invoices.js';
 import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
@@ -17,7 +17,9 @@ import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 // charge, an account) on every line. When an accounting
 // system is connected, its own checks are added (for Xero: the customer
 // matches one Xero contact, every item is in Xero), and the lab's pending
-// rules (invoice-rules.js) add their notes. A draft with a problem is
+// rules (invoice-rules.js) add their notes. An enabled skip rule does too:
+// a draft whose job it matches stays Pending, even when the draft was made
+// by hand or before the rule existed. A draft with a problem is
 // Pending (the "problem" view). A draft without one is Ready.
 //
 // Send all ready issues every ready draft (each gets its number) and, when an
@@ -81,19 +83,21 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
     const found = draftProblems(draft, linesOf.get(draft.id) ?? []);
     if (found.length) problems.set(draft.id, found);
   }
-  const jobs = await db.select({ obligation: billingObligations, reference: invoices.reference }).from(billingObligations)
+  const jobs = await db.select({ obligation: billingObligations, reference: invoices.reference, customerName: contacts.name }).from(billingObligations)
     .innerJoin(invoices, eq(invoices.id, billingObligations.invoiceId))
+    .leftJoin(contacts, and(eq(contacts.id, billingObligations.contactId), eq(contacts.organisationId, billingObligations.organisationId)))
     .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids)));
-  // The lab's pending rules (invoice-rules.js): a draft from a job that
-  // matches one waits on Pending with the rule's note, such as a Reference
-  // with no real practitioner.
-  const rules = (await listRules(db, organisationId)).filter((r) => r.enabled && r.action.kind === 'pending');
+  // The lab's rules (invoice-rules.js). A pending rule puts its note on the
+  // draft. A skip rule holds a draft that already exists: void it, or change
+  // the rule. Matching stays in invoice-rules.js.
+  const rules = (await listRules(db, organisationId)).filter((r) => r.enabled && (r.action.kind === 'pending' || r.action.kind === 'skip'));
   if (rules.length && jobs.length) {
     const settings = await readInvoicingSettings(db, organisationId);
     const customers = await customerBillingByContact(db, organisationId, jobs.map((j) => j.obligation.contactId));
-    for (const { obligation, reference } of jobs) {
-      const customer = effectiveSettings(settings, customers.get(obligation.contactId));
-      const found = rulePending(rules, { ...obligation, reference }, { customer });
+    for (const { obligation, reference, customerName } of jobs) {
+      const customer = { ...effectiveSettings(settings, customers.get(obligation.contactId)), name: customerName ?? null };
+      const job = { ...obligation, reference };
+      const found = [...rulePending(rules, job, { customer }), ...ruleSkip(rules, job, { customer })];
       if (found.length) problems.set(obligation.invoiceId, [...(problems.get(obligation.invoiceId) ?? []), ...found]);
     }
   }
@@ -196,23 +200,61 @@ async function assertCanSend(accounting, organisationId) {
 // Read before act (issue #141): the jobs behind these drafts whose work
 // system report is old are read again first. Answers the drafts that may go
 // now; a draft whose job went to review, or could not be read, waits.
+// `stops` names each held draft: `unread` (read failed or past the cap) or
+// `review` (the job changed).
 async function readJobsFirst(db, organisationId, invoiceIds, { work, now, personId }) {
-  if (!invoiceIds.length || typeof work?.capabilities?.readWorkItem !== 'function') return { go: invoiceIds, waiting: [] };
+  if (!invoiceIds.length || typeof work?.capabilities?.readWorkItem !== 'function') {
+    return { go: invoiceIds, waiting: [], stops: [] };
+  }
   const jobs = await db.select().from(billingObligations)
     .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, invoiceIds)));
   const old = jobs.filter((job) => needsRead(job, { work, now }));
   const outcomes = await readBeforeAct(db, organisationId, old.slice(0, READS_PER_PASS), { work, now, actor: `person:${personId}` });
-  const held = new Set(old.slice(READS_PER_PASS).map((job) => job.invoiceId));
+  const held = new Set();
+  const stops = [];
+  for (const job of old.slice(READS_PER_PASS)) {
+    held.add(job.invoiceId);
+    stops.push({ invoiceId: job.invoiceId, kind: 'deferred' });
+  }
   for (const { outcome, obligation } of outcomes.values()) {
-    if (outcome === 'waiting' || outcome === 'review') held.add(obligation.invoiceId);
+    if (outcome === 'waiting') {
+      held.add(obligation.invoiceId);
+      stops.push({ invoiceId: obligation.invoiceId, kind: 'unread' });
+    } else if (outcome === 'review') {
+      held.add(obligation.invoiceId);
+      stops.push({ invoiceId: obligation.invoiceId, kind: 'review' });
+    }
+  }
+  return { go: invoiceIds.filter((id) => !held.has(id)), waiting: invoiceIds.filter((id) => held.has(id)), stops };
+}
+
+// The error when a ticked press sends nothing: name the cause (and the count
+// for jobs), never one shared sentence.
+function stoppedSendMessage({ accountingWaiting, accountingReason, stops, waiting }) {
+  if (accountingWaiting) {
+    if (accountingReason && /more changes than one read takes/i.test(accountingReason)) {
+      return 'The accounting copy has more changes than one read takes. Nothing was sent.';
+    }
+    if (accountingReason) return `${accountingReason.replace(/\.?$/, '')}. Nothing was sent.`;
+    return 'The accounting copy could not be read. Nothing was sent.';
+  }
+  const unread = stops.filter((stop) => stop.kind === 'unread').length;
+  const reviews = stops.filter((stop) => stop.kind === 'review').length;
+  if (unread) {
+    return `${unread} ${unread === 1 ? 'job' : 'jobs'} could not be read from the work system. Nothing was sent.`;
+  }
+  if (reviews) {
+    return `${reviews} ${reviews === 1 ? 'job' : 'jobs'} changed and ${reviews === 1 ? 'needs' : 'need'} a look. Nothing was sent.`;
   }
-  return { go: invoiceIds.filter((id) => !held.has(id)), waiting: invoiceIds.filter((id) => held.has(id)) };
+  const n = waiting.length || 1;
+  return `${n} ${n === 1 ? 'job' : 'jobs'} could not be confirmed with the work system. Nothing was sent.`;
 }
 
 // Send all ready: issues each ready draft, then queues it for the accounting
-// system. With `invoiceIds`, only those drafts, and each must be ready (the
-// Send button on one invoice). `work` is the work integration, for the read
-// before act. Answers { issued, queued, remaining, waiting }.
+// system. With `invoiceIds`, only those drafts. One id (the invoice page) is
+// all or nothing. More than one id (the bulk bar) sends the ones Flow could
+// confirm and leaves the rest. `work` is the work integration, for the read
+// before act. Answers { issued, queued, remaining, waiting, held }.
 export async function sendAllReady(db, organisationId, { accounting = null, work = null, personId, issueDate, invoiceIds = null, now = new Date() }) {
   await assertCanSend(accounting, organisationId);
   // Issue #45: the accounting copy reads its latest changes first, so the
@@ -236,11 +278,23 @@ export async function sendAllReady(db, organisationId, { accounting = null, work
         : 'Only a ready invoice can be sent. Mark it ready first.');
     }
   }
-  const { go, waiting } = accountingRead.outcome === 'waiting'
-    ? { go: [], waiting: ready.slice(0, SEND_BATCH) }
+  const accountingWaiting = accountingRead.outcome === 'waiting';
+  const { go, waiting, stops } = accountingWaiting
+    ? { go: [], waiting: ready.slice(0, SEND_BATCH), stops: [] }
     : await readJobsFirst(db, organisationId, ready.slice(0, SEND_BATCH), { work, now, personId });
-  if (invoiceIds && waiting.length) {
-    throw new FlowError('not_ready', 'Flow could not confirm the job with the work system or the accounting system just now, or the job changed. Nothing was sent. Look at the invoice, then try again.');
+  // One invoice (the invoice page) is all or nothing: a job Flow could not
+  // confirm stops the send. A bulk press sends the ones it confirmed. The
+  // rest stay for the next press (`waiting`), or on Pending when the read
+  // sent the job to review. An accounting read that cannot run still stops
+  // every ticked invoice: that one read covers the whole press. When nothing
+  // can go, the error names the cause and the count.
+  if (invoiceIds && waiting.length && go.length === 0) {
+    throw new FlowError('not_ready', stoppedSendMessage({
+      accountingWaiting,
+      accountingReason: accountingRead.reason,
+      stops,
+      waiting,
+    }));
   }
   const batch = go;
   let issued = 0;

package/server/integrations/call-guard.js

@@ -203,6 +203,10 @@ export function createCallGuard({
   lockName = `${integration}-call-guard`,
   report: reports = true,
   policy: overrides = {},
+  // Optional columns on this adapter's call table, filled from record().
+  // `lane` is the allow-list (anything else is stored null). `rateLimitProblem`
+  // keeps a short token such as Xero's X-Rate-Limit-Problem.
+  telemetry = {},
   now = Date.now,
   log = console,
 } = {}) {
@@ -215,6 +219,14 @@ export function createCallGuard({
   const C = { key: sql.identifier(columns.key ?? 'key'), at: sql.identifier(columns.at ?? 'at') };
   const tag = `[${integration}]`;
   const failed = sql`(failure_kind is not null or status_code >= 500 or (status_code >= 400 and status_code <> 404))`;
+  const laneAllowed = Array.isArray(telemetry.lane) ? telemetry.lane : null;
+  const keepProblem = telemetry.rateLimitProblem === true;
+  const cleanLane = (value) => (laneAllowed?.includes(value) ? value : null);
+  const cleanProblem = (value) => {
+    if (!keepProblem || typeof value !== 'string') return null;
+    const text = value.trim();
+    return /^[A-Za-z][A-Za-z0-9_-]{0,39}$/.test(text) ? text : null;
+  };
 
   const lock = (tx, key) => tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`${lockName}:${key}`}))`);
   const extraColumns = Object.keys(callDefaults).map((column) => sql`, ${sql.identifier(column)}`);
@@ -263,12 +275,17 @@ export function createCallGuard({
   // resourceResumed, opened, closed, budgetSpent }),
   // each of which was just reported once. `callId` names a call row the
   // adapter wrote when it admitted the call: that row is updated, not added.
-  async function record(rawKey, { callId = null, resource = null, path = null, statusCode = null, failureKind = null, durationMs = null } = {}) {
+  async function record(rawKey, { callId = null, resource = null, path = null, statusCode = null, failureKind = null, durationMs = null, lane: laneRaw = null, rateLimitProblem = null } = {}) {
     const key = cleanKey(rawKey);
     const where = cleanResource(resource);
     const nowMs = Number(now());
     const nowAt = new Date(nowMs);
     const status = Number.isInteger(statusCode) ? statusCode : null;
+    const lane = cleanLane(laneRaw);
+    const problem = cleanProblem(rateLimitProblem);
+    const extraCols = sql`${laneAllowed ? sql`, lane` : sql``}${keepProblem ? sql`, rate_limit_problem` : sql``}`;
+    const extraVals = sql`${laneAllowed ? sql`, ${lane}` : sql``}${keepProblem ? sql`, ${problem}` : sql``}`;
+    const extraSet = sql`${laneAllowed ? sql`, lane = ${lane}` : sql``}${keepProblem ? sql`, rate_limit_problem = ${problem}` : sql``}`;
     const outcome = await db.transaction(async (tx) => {
       await lock(tx, key);
       await ensureRow(tx, key);
@@ -276,10 +293,10 @@ export function createCallGuard({
       const took = Number.isFinite(durationMs) ? Math.max(0, Math.round(durationMs)) : null;
       if (callId !== null) {
         await tx.execute(sql`update ${T.calls} set resource = ${where}, request_path = ${normaliseRequestPath(path)}, status_code = ${status},
-          failure_kind = ${kind}, duration_ms = ${took} where id = ${callId} and ${C.key} = ${key}`);
+          failure_kind = ${kind}, duration_ms = ${took}${extraSet} where id = ${callId} and ${C.key} = ${key}`);
       } else {
-        await tx.execute(sql`insert into ${T.calls} (${C.key}, ${C.at}, resource, request_path, status_code, failure_kind, duration_ms${sql.join(extraColumns, sql``)})
-          values (${key}, ${nowAt}, ${where}, ${normaliseRequestPath(path)}, ${status}, ${kind}, ${took}${sql.join(extraValues, sql``)})`);
+        await tx.execute(sql`insert into ${T.calls} (${C.key}, ${C.at}, resource, request_path, status_code, failure_kind, duration_ms${extraCols}${sql.join(extraColumns, sql``)})
+          values (${key}, ${nowAt}, ${where}, ${normaliseRequestPath(path)}, ${status}, ${kind}, ${took}${extraVals}${sql.join(extraValues, sql``)})`);
       }
       const state = await readState(tx, key);
       if (!countsAsFailure({ statusCode: status, failureKind })) {

package/server/integrations/sentry/index.js

@@ -9,13 +9,17 @@ import { scrubSpan } from '../../ui/monitoring.js';
 // the host setting SENTRY_DSN. It has no tables.
 
 // The browser SDK, loaded from Sentry's CDN only while this adapter is on
-// (server/ui/monitoring.js). Pinned, with its integrity hash. With traces on,
-// the bundle that also traces; Sentry ships it only with session replay in
-// it too, which Flow never turns on.
+// (server/ui/monitoring.js). Pinned, with its integrity hash. With replay on,
+// the bundle with session replay; with traces on, the bundle that also traces
+// (Sentry ships it only with replay in it).
 export const SENTRY_BROWSER = Object.freeze({
   src: 'https://browser.sentry-cdn.com/11.4.0/bundle.feedback.min.js',
   integrity: 'sha384-H9RmZ/VaqOPZrUezgCSqHp4t3LoQMd/5+0Y4oEGUB2bddZzSnwZiOYoWneK4diWt',
 });
+export const SENTRY_BROWSER_REPLAY = Object.freeze({
+  src: 'https://browser.sentry-cdn.com/11.4.0/bundle.replay.feedback.min.js',
+  integrity: 'sha384-9Iyc17wHvpK0bqZe+cuAedQDHoWwenMrxXR+HgLLkQ3rHM4zQD+amLzBnmrQgowj',
+});
 export const SENTRY_BROWSER_TRACING = Object.freeze({
   src: 'https://browser.sentry-cdn.com/11.4.0/bundle.tracing.replay.feedback.min.js',
   integrity: 'sha384-LjwHQKAojcITl6Q7innDSAFjziFnqV9ovZBNXnXnQwub1VXIdBMJnYrQNihtxSa6',
@@ -44,6 +48,7 @@ export const SENTRY_SETUP = {
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
     { name: 'SENTRY_CLIENT', label: 'Client', help: 'The name your support desk files this installation\'s reports under. Sent as the client tag. Empty: no client tag.' },
     { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
+    { name: 'SENTRY_REPLAY', label: 'Replay with reports', kind: 'onoff', help: 'On: each report and each browser error keeps up to the last minute of the page, as a replay with every word hidden.' },
     { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
 };
@@ -56,6 +61,7 @@ export function readSentrySettings(env) {
   // labelled apart so they never read as the live app's.
   const environment = String(env.SENTRY_ENVIRONMENT ?? '').trim() || (isReplitWorkspace(env) ? 'workspace' : 'production');
   const feedback = String(env.SENTRY_FEEDBACK ?? 'on').trim() !== 'off';
+  const replay = String(env.SENTRY_REPLAY ?? 'on').trim() !== 'off';
   const rate = String(env.SENTRY_TRACES_SAMPLE_RATE ?? '').trim();
   const tracesSampleRate = rate === '' ? DEFAULT_TRACES_SAMPLE_RATE : Number(rate);
   if (!/^\d*\.?\d+$/.test(rate || '0') || !(tracesSampleRate >= 0 && tracesSampleRate <= 1)) {
@@ -66,7 +72,7 @@ export function readSentrySettings(env) {
   // Every event says which product and, when set, which client it is from,
   // so one support desk can serve many installations.
   const tags = client ? { product: 'flow', client } : { product: 'flow' };
-  return { dsn, environment, feedback, tracesSampleRate, tags };
+  return { dsn, environment, feedback, replay, tracesSampleRate, tags };
 }
 
 // No trace for the host's health check: it is not a person waiting.
@@ -108,7 +114,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
         ),
         beforeSendSpan: scrubSpan,
       });
-      log.info?.(`[sentry] on: environment ${settings.environment}; report button ${settings.feedback ? 'on' : 'off'}; traces ${settings.tracesSampleRate > 0 ? settings.tracesSampleRate : 'off'}`);
+      log.info?.(`[sentry] on: environment ${settings.environment}; report button ${settings.feedback ? 'on' : 'off'}; replay ${settings.replay ? 'on' : 'off'}; traces ${settings.tracesSampleRate > 0 ? settings.tracesSampleRate : 'off'}`);
     },
     async stop() {
       if (settings) await sdk.close(2000);
@@ -133,15 +139,16 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
       // meant for browsers.
       browserMonitoring() {
         if (!settings) return null;
-        const { tracesSampleRate } = settings;
+        const { tracesSampleRate, replay } = settings;
         return {
           dsn: settings.dsn,
           environment: settings.environment,
           release,
           feedback: settings.feedback,
+          replay,
           tags: settings.tags,
           tracesSampleRate,
-          script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : SENTRY_BROWSER,
+          script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : replay ? SENTRY_BROWSER_REPLAY : SENTRY_BROWSER,
         };
       },
       // Runs `work` in a span of the current trace (server/core/tracing.js).

package/server/integrations/xero/client.js

@@ -1,4 +1,5 @@
 import { FlowError } from '../../core/errors.js';
+import { currentXeroLane } from './governor.js';
 import { XERO_ENDPOINTS } from './settings.js';
 
 // The Xero Accounting API client. Every call goes through the rate-limit
@@ -130,7 +131,7 @@ export function createXeroClient({
       } catch (error) {
         if (error?.code === 'xero_replay_no_match') throw error;
         const timedOut = error?.name === 'AbortError';
-        await guard?.record(tenantId, { ...call, failureKind: timedOut ? 'timeout' : 'network', durationMs: Date.now() - startedAt });
+        await guard?.record(tenantId, { ...call, failureKind: timedOut ? 'timeout' : 'network', durationMs: Date.now() - startedAt, lane: currentXeroLane() });
         throw xeroError(timedOut ? 'xero_timeout' : 'xero_unreachable',
           timedOut ? `Xero did not answer within ${timeoutMs} ms.` : 'Flow could not reach Xero.',
           { status: timedOut ? 504 : 503 });
@@ -169,7 +170,16 @@ export function createXeroClient({
       // A first 401 usually means the access token expired: it is not counted,
       // and the call is tried once more with a fresh token.
       const expiredToken = response.status === 401 && !refreshed;
-      if (!expiredToken) await guard?.record(tenantId, { ...call, statusCode: response.status, durationMs });
+      const problem = response.status === 429 ? response.headers?.get?.('x-rate-limit-problem')?.trim() || null : null;
+      if (!expiredToken) {
+        await guard?.record(tenantId, {
+          ...call,
+          statusCode: response.status,
+          durationMs,
+          lane: currentXeroLane(),
+          rateLimitProblem: problem,
+        });
+      }
       if (response.ok) return payload ?? {};
 
       const error = apiError(response, payload);

package/server/integrations/xero/migrations/0010_xero_call_usage.sql

@@ -0,0 +1,11 @@
+-- The lane a call counted against, and a 429's X-Rate-Limit-Problem, so the
+-- Xero card can show the day's calls without asking Xero. A row from before
+-- this column has no lane: the card does not guess one.
+ALTER TABLE "xero_calls" ADD COLUMN IF NOT EXISTS "lane" text;
+--> statement-breakpoint
+ALTER TABLE "xero_calls" ADD COLUMN IF NOT EXISTS "rate_limit_problem" text;
+--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "xero_calls" ADD CONSTRAINT "xero_calls_lane_valid" CHECK ("lane" is null or "lane" in ('writes', 'sync', 'reads', 'other'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;

package/server/integrations/xero/migrations/meta/_journal.json

@@ -71,6 +71,13 @@
       "when": 1792520000000,
       "tag": "0009_xero_sent_to_contact",
       "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1792530000000,
+      "tag": "0010_xero_call_usage",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/routes.js

@@ -14,6 +14,7 @@ import { accountingStatus, checkSentInvoices } from './reconcile.js';
 import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
 import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
 import { writesAllowed } from './settings.js';
+import { readXeroUsage } from './usage.js';
 import { saveEvents, signatureValid } from './webhooks.js';
 import { DEFAULT_FAMILY } from '../../theme/themes.js';
 import { messagePage as themedMessagePage } from '../../ui/page.js';
@@ -109,8 +110,12 @@ export function callsState(status) {
   return { stopped: Boolean(status.haltedReason) || resources.length > 0, all: Boolean(status.haltedReason), resources, since };
 }
 
+const XERO_INTEGRATION = Object.freeze({ name: 'Xero', logo: 'xero.svg' });
+
 export function createXeroRouter({ db, personAuth, runtime, log = console, buttonCooldowns = true, actions = createActionGuard({ integration: 'xero', actions: XERO_ACTIONS, off: !buttonCooldowns }), messagePage = (options) => themedMessagePage({ ...options, defaultFamily: DEFAULT_FAMILY }) }) {
-  const page = (title, text, tone) => messagePage({ title, text, tone });
+  // Shared callback card (server/ui/page.js): integration marks, status line,
+  // and a short auto-return on success only (issue #211).
+  const page = (title, text, tone, extra = {}) => messagePage({ title, text, tone, integration: XERO_INTEGRATION, ...extra });
   const { settings } = runtime;
   const router = express.Router();
   const act = (name, key) => actions.route(name, { key });
@@ -144,16 +149,29 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
   router.get('/status', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.query.organisationId);
     const connection = await readConnection(db, organisationId);
+    const connected = Boolean(connection && connection.mode === settings.mode);
+    const picture = connected
+      ? await readXeroUsage(db, {
+        organisationId,
+        tenantId: connection.tenantId,
+        governor: runtime.governor.status(connection.tenantId),
+        warningFraction: settings.usageWarningFraction,
+        refreshedAt: connection.refreshedAt,
+        now: runtime.now(),
+      })
+      : { usage: null, freshness: null };
     res.json({
       ok: true,
       mode: settings.mode,
       writesAllowed: writesAllowed(settings),
       redirectUri: settings.redirectUri,
-      connected: Boolean(connection && connection.mode === settings.mode),
+      connected,
       connection: describeConnection(connection),
-      rateLimit: connection ? runtime.governor.status(connection.tenantId) : null,
-      calls: connection ? callsState(await runtime.guardFor(db).status(connection.tenantId)) : null,
+      rateLimit: connected ? runtime.governor.status(connection.tenantId) : null,
+      calls: connected ? callsState(await runtime.guardFor(db).status(connection.tenantId)) : null,
       lastSync: await lastSync(db, organisationId),
+      usage: picture.usage,
+      freshness: picture.freshness,
     });
   }));
 
@@ -213,7 +231,13 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
       if (previous && previous.tenantId !== connection.tenantId) await resetImport(db, entry.organisationId);
       await queueHistoryImport(db, entry.organisationId, { reason: 'connected' });
       log.info?.(`[xero] organisation ${entry.organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}) by person ${entry.personId}`);
-      return res.type('html').send(page('Xero is connected', `Flow is connected to ${connection.tenantName || 'your Xero organisation'} (${settings.mode}). Flow is now copying its invoice and payment history in the background. You can close this tab.`, 'success'));
+      const organisation = connection.tenantName || 'your Xero organisation';
+      return res.type('html').send(page(
+        'Xero is connected',
+        'Flow is now copying its invoice and payment history in the background.',
+        'success',
+        { organisation, mode: settings.mode, autoReturnSeconds: 5 },
+      ));
     } catch (error) {
       log.error?.(`[xero] connect failed: ${error.code ?? 'error'}: ${error.message}`);
       const message = error instanceof FlowError ? error.message : 'Something went wrong talking to Xero. Try again.';

package/server/integrations/xero/runtime.js

@@ -21,6 +21,11 @@ export const XERO_CALL_GUARD = Object.freeze({
   name: 'Xero',
   tables: Object.freeze({ state: 'xero_call_guard', calls: 'xero_calls' }),
   policy: Object.freeze({ authStops: 'resource' }),
+  // Kept on the call row so the Xero card can show lanes and 429s after a restart.
+  telemetry: Object.freeze({
+    lane: Object.freeze(['writes', 'sync', 'reads', 'other']),
+    rateLimitProblem: true,
+  }),
 });
 
 export function requireXeroSettings(env = process.env) {

package/server/integrations/xero/usage.js

@@ -0,0 +1,74 @@
+import { sql } from 'drizzle-orm';
+import { assembleUsage, startOfUtcDay } from '../../ui/xero-usage-model.js';
+
+// What the Xero card draws. Read from counters Flow already keeps: the
+// governor's budget, the call log, and the copy's own timestamps. No Xero call.
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const iso = (value) => (value ? new Date(value).toISOString() : null);
+
+// Calls that count toward the day's budget. A token refresh is recorded, and
+// it is not an Accounting API call, so it stays out of the lanes.
+const BUDGET_CALL = sql`lane is not null and coalesce(resource, '') <> 'token'`;
+
+export async function readXeroUsage(db, { organisationId, tenantId, governor, warningFraction, refreshedAt, now = Date.now() }) {
+  const at = Number(now);
+  const dayStart = startOfUtcDay(at);
+  const weekStart = new Date(dayStart - 6 * DAY_MS);
+  const dayEnd = new Date(dayStart + DAY_MS);
+  const today = new Date(dayStart);
+
+  const [hours, days, tasks, limited, freshness] = await Promise.all([
+    db.execute(sql`
+      select to_char(date_trunc('hour', "at" at time zone 'UTC'), 'YYYY-MM-DD"T"HH24:00:00"Z"') as hour,
+             lane, count(*)::int as n
+      from xero_calls
+      where key = ${tenantId} and "at" >= ${today} and "at" < ${dayEnd} and ${BUDGET_CALL}
+      group by 1, 2`),
+    db.execute(sql`
+      select to_char("at" at time zone 'UTC', 'YYYY-MM-DD') as day, count(*)::int as n
+      from xero_calls
+      where key = ${tenantId} and "at" >= ${weekStart} and "at" < ${dayEnd} and ${BUDGET_CALL}
+      group by 1`),
+    db.execute(sql`
+      select coalesce(nullif(resource, ''), 'call') as task, count(*)::int as n
+      from xero_calls
+      where key = ${tenantId} and "at" >= ${today} and "at" < ${dayEnd} and coalesce(resource, '') <> 'token'
+      group by 1
+      order by n desc, task
+      limit 8`),
+    db.execute(sql`
+      select "at", rate_limit_problem as problem, lane, resource as task
+      from xero_calls
+      where key = ${tenantId} and status_code = 429 and "at" >= ${weekStart}
+      order by "at" desc
+      limit 12`),
+    db.execute(sql`
+      select
+        (select max(received_at) from xero_webhook_events where organisation_id = ${organisationId} and source = 'webhook') as webhook_at,
+        (select max(last_read_at) from xero_mirror_cursors where organisation_id = ${organisationId}) as poll_at,
+        (select last_finished_at from xero_daily_checks where organisation_id = ${organisationId}) as nightly_at,
+        (select max(read_at) from xero_webhook_events where organisation_id = ${organisationId}) as read_at`),
+  ]);
+
+  const fresh = freshness.rows[0] ?? {};
+  const copyCandidates = [fresh.poll_at, fresh.nightly_at, fresh.read_at].filter(Boolean).map((value) => new Date(value).getTime());
+  return {
+    usage: assembleUsage({
+      hourRows: hours.rows,
+      dayRows: days.rows,
+      taskRows: tasks.rows,
+      limitRows: limited.rows,
+      governor,
+      warningFraction,
+      now: at,
+    }),
+    freshness: {
+      webhookAt: iso(fresh.webhook_at),
+      pollAt: iso(fresh.poll_at),
+      nightlyAt: iso(fresh.nightly_at),
+      copyAt: copyCandidates.length ? new Date(Math.max(...copyCandidates)).toISOString() : null,
+      tokenRefreshedAt: iso(refreshedAt),
+    },
+  };
+}

package/server/ui/alerts.js

@@ -33,8 +33,9 @@ export function alertStrip(ui, page, { onTab = () => {}, scope = null, onLoad =
     let action = null;
     if (first.action?.href && first.action.href !== location.pathname) action = h('a', { class: 'fx-alerts__action', href: first.action.href, onclick: go }, first.action.label);
     else if (first.action?.tab) action = h('button', { class: 'fx-alerts__action', type: 'button', onclick: () => onTab(first.action.tab) }, first.action.label);
+    const line = first.moneyAtRiskCents > 0 ? `${first.title} ${money.format(first.moneyAtRiskCents / 100)} at risk.` : first.title;
     element.replaceChildren(...[
-      h('p', { class: 'fx-alerts__text' },
+      h('p', { class: 'fx-alerts__text', title: line },
         first.title,
         first.moneyAtRiskCents > 0 ? h('span', { class: 'fx-alerts__money' }, ` ${money.format(first.moneyAtRiskCents / 100)} at risk.`) : null),
       action,