@arcforgelabs/flow 2026.10.30 → 2026.10.32

package/server/integrations/xero/webhooks.js

@@ -0,0 +1,311 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { isCallsStopped } from '../call-guard.js';
+import { lastSync, parseXeroDate, syncCatalogue } from './catalogue.js';
+import { withXeroLane } from './governor.js';
+import { mirrorState } from './lookup.js';
+import { mapRecords, mirrorXero, storeRows, toCents } from './mirror.js';
+import { checkSentInvoices } from './reconcile.js';
+
+// Xero's webhooks, and the daily check (issue #45). The poll (import.js) reads
+// Xero's changes every 15 minutes. Webhooks make a change reach Flow in
+// seconds, and the daily check finds what both of them missed.
+//
+//   1. Xero posts an event to /api/xero/webhooks: a record id and what
+//      happened, never the record. Flow checks the signature, saves the id in
+//      the inbox (xero_webhook_events) and answers 200 at once.
+//   2. The worker reads the waiting invoices by id, up to 50 a call, into the
+//      copy (mirror.js), then compares the sent invoices again (reconcile.js).
+//      Credit notes are read as changes since the cursor; contacts refresh the
+//      contacts and items copy.
+//   3. While webhooks arrive, the poll waits an hour instead of 15 minutes. If
+//      they stop, it goes back to 15 minutes by itself.
+//   4. Once a day, one summary read of every invoice (about 1,000 a call)
+//      finds each copy row whose status, amounts or change time differ from
+//      Xero, and each row Xero no longer lists. Those go into the inbox and are
+//      read by id like an event. This catches part payments that do not move
+//      Xero's change time, and a webhook that never came.
+//
+// Every read goes through the call guard and the governor's sync lane, and
+// leaves the mirror's reserve of the day's calls for drafts and people. Flow
+// never writes to Xero here.
+
+export const BY_ID_BATCH = 50;
+// The poll's wait while webhooks arrive, and how recent the last one must be.
+export const WEBHOOK_REFRESH_MS = 60 * 60 * 1000;
+export const WEBHOOK_ACTIVE_MS = 24 * 60 * 60 * 1000;
+export const DAILY_CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+// A daily check that failed is tried again after this wait.
+const DAILY_CHECK_RETRY_MS = 60 * 60 * 1000;
+const SUMMARY_PAGE = 1000;
+// At most this many records a day go back for a read by id (5 calls), so a
+// check that finds the whole copy different cannot spend the day. The rest
+// wait for the next day's check.
+export const DAILY_FLAG_MAX = 250;
+const MAX_SUMMARY_PAGES = 50;
+// Contacts and items are read again at most this often for contact events.
+const CONTACTS_EVERY_MS = 60 * 60 * 1000;
+
+const CATEGORIES = { INVOICE: 'invoices', CREDITNOTE: 'credit_notes', CREDIT_NOTE: 'credit_notes', CONTACT: 'contacts' };
+
+// Xero signs the raw body with HMAC-SHA256 and the webhook key, in base64
+// (x-xero-signature). Compared in constant time.
+export function signatureValid(key, rawBody, signature) {
+  if (!key || typeof signature !== 'string' || !signature) return false;
+  const expected = createHmac('sha256', key).update(rawBody).digest();
+  let given;
+  try {
+    given = Buffer.from(signature, 'base64');
+  } catch {
+    return false;
+  }
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+// Saves the events of one verified delivery. An event for an organisation not
+// connected in this mode is dropped. Answers how many were saved.
+export async function saveEvents(db, runtime, payload, { now = new Date() } = {}) {
+  const events = Array.isArray(payload?.events) ? payload.events : [];
+  if (!events.length) return 0;
+  const { rows } = await db.execute(sql`select organisation_id, tenant_id from xero_connections where mode = ${runtime.settings.mode}`);
+  const byTenant = new Map(rows.map((r) => [r.tenant_id, r.organisation_id]));
+  let saved = 0;
+  for (const event of events) {
+    const organisationId = byTenant.get(event?.tenantId);
+    if (!organisationId || typeof event.resourceId !== 'string' || !event.resourceId) continue;
+    const resource = CATEGORIES[String(event.eventCategory ?? '').toUpperCase()] ?? 'other';
+    const at = Date.parse(`${String(event.eventDateUtc ?? '').replace(/Z?$/, 'Z')}`);
+    await flag(db, organisationId, resource, event.resourceId, {
+      source: 'webhook', eventType: event.eventType ?? null, eventAt: Number.isNaN(at) ? null : new Date(at), now,
+    });
+    saved += 1;
+  }
+  return saved;
+}
+
+// Marks one record as waiting to be read by id.
+async function flag(db, organisationId, resource, resourceId, { source, eventType = null, eventAt = null, now = new Date() }) {
+  await db.execute(sql`
+    insert into xero_webhook_events (organisation_id, resource, resource_id, event_type, source, event_at, received_at)
+    values (${organisationId}, ${resource}, ${resourceId}, ${eventType}, ${source}, ${eventAt}, ${now})
+    on conflict (organisation_id, resource, resource_id) do update set
+      event_type = excluded.event_type, source = excluded.source, event_at = excluded.event_at,
+      received_at = excluded.received_at, pending = true`);
+}
+
+async function markRead(db, organisationId, resource, ids = null) {
+  const only = ids ? sql`and resource_id = any(${sql.param(ids)}::text[])` : sql``;
+  await db.execute(sql`update xero_webhook_events set pending = false, read_at = now()
+    where organisation_id = ${organisationId} and resource = ${resource} and pending ${only}`);
+}
+
+// Whether a webhook for this organisation arrived recently: the poll can wait.
+export async function webhooksActive(db, runtime, organisationId, { now = Date.now() } = {}) {
+  if (!runtime.settings.webhookKey) return false;
+  const { rows: [row] } = await db.execute(sql`select max(received_at) as at from xero_webhook_events
+    where organisation_id = ${organisationId} and source = 'webhook'`);
+  return Boolean(row?.at && Number(now) - new Date(row.at).getTime() <= WEBHOOK_ACTIVE_MS);
+}
+
+// Calls left above the reserve the mirror keeps for drafts and people.
+function overReserve(runtime, tenantId) {
+  const budget = runtime.governor.status(tenantId);
+  return budget.dayRemaining > Math.ceil(budget.dayLimit * runtime.settings.mirrorReserveFraction);
+}
+
+async function pendingIds(db, organisationId) {
+  const { rows } = await db.execute(sql`select resource, resource_id from xero_webhook_events
+    where organisation_id = ${organisationId} and pending order by received_at`);
+  const out = new Map();
+  for (const r of rows) out.set(r.resource, [...(out.get(r.resource) ?? []), r.resource_id]);
+  return out;
+}
+
+// Reads every waiting record of one organisation. Answers counts, or a
+// `stopped` reason: 'calls_stopped' (the call guard) or 'budget'.
+export async function readInbox(db, runtime, organisationId, { now = Date.now } = {}) {
+  const waiting = await pendingIds(db, organisationId);
+  const result = { invoices: { read: 0, inserted: 0, changed: 0, unchanged: 0 }, creditNotes: 0, contacts: false, sent: null };
+  if (!waiting.size) return result;
+  const { rows: [connection] } = await db.execute(sql`select tenant_id from xero_connections
+    where organisation_id = ${organisationId} and mode = ${runtime.settings.mode}`);
+  if (!connection) return result;
+  try {
+    await runtime.guardFor(db).check(connection.tenant_id);
+  } catch (error) {
+    if (isCallsStopped(error)) return { ...result, stopped: 'calls_stopped' };
+    throw error;
+  }
+
+  const invoiceIds = waiting.get('invoices') ?? [];
+  if (invoiceIds.length) {
+    const counts = result.invoices;
+    const stopped = await runtime.serial(organisationId, () => withXeroLane('sync', async () => {
+      const { client } = await runtime.clientFor(db, organisationId);
+      for (let i = 0; i < invoiceIds.length; i += BY_ID_BATCH) {
+        if (!overReserve(runtime, client.tenantId)) return 'budget';
+        const batch = invoiceIds.slice(i, i + BY_ID_BATCH);
+        const rows = mapRecords('invoices', await client.listInvoicesByIds(batch), runtime.settings);
+        await db.transaction(async (tx) => {
+          await storeRows(tx, organisationId, 'invoices', rows, counts);
+          // An id Xero did not return is read too: there is nothing more to get.
+          await markRead(tx, organisationId, 'invoices', batch);
+        });
+        counts.read += rows.length;
+      }
+      return null;
+    }));
+    if (stopped) return { ...result, stopped };
+    if (counts.inserted || counts.changed) result.sent = await checkSentInvoices(db, runtime, organisationId);
+  }
+
+  if (waiting.get('credit_notes')?.length) {
+    // Credit notes are few: one read of the changes since the cursor gets them.
+    const [read] = await mirrorXero(db, runtime, organisationId, { resources: ['credit_notes'] });
+    if (read?.stopped === 'budget') return { ...result, stopped: 'budget' };
+    result.creditNotes = read?.read ?? 0;
+    await markRead(db, organisationId, 'credit_notes');
+  }
+
+  if (waiting.get('contacts')?.length) {
+    const last = await lastSync(db, organisationId);
+    const at = last?.finishedAt ?? last?.startedAt;
+    if (!at || Number(now()) - new Date(at).getTime() >= CONTACTS_EVERY_MS) {
+      await syncCatalogue(db, runtime, organisationId);
+      await markRead(db, organisationId, 'contacts');
+      result.contacts = true;
+    }
+  }
+
+  // Events Flow does not copy (other categories) need no read.
+  if (waiting.get('other')?.length) await markRead(db, organisationId, 'other');
+  return result;
+}
+
+// The daily check for one organisation: one summary read of every invoice,
+// compared with the copy. Each row that differs, and each live copy row Xero
+// no longer lists, waits in the inbox to be read by id. Answers counts, or
+// `stopped`.
+export async function dailyCheck(db, runtime, organisationId, { now = () => new Date() } = {}) {
+  await db.execute(sql`insert into xero_daily_checks (organisation_id, last_started_at) values (${organisationId}, ${now()})
+    on conflict (organisation_id) do update set last_started_at = excluded.last_started_at`);
+  try {
+    const seen = [];
+    const stopped = await runtime.serial(organisationId, () => withXeroLane('sync', async () => {
+      const { client } = await runtime.clientFor(db, organisationId);
+      for (let page = 1; page <= MAX_SUMMARY_PAGES; page += 1) {
+        if (!overReserve(runtime, client.tenantId)) return 'budget';
+        const list = await client.listInvoiceSummaries({ page, pageSize: SUMMARY_PAGE });
+        seen.push(...list.filter((i) => i.InvoiceID));
+        if (list.length < SUMMARY_PAGE) return null;
+      }
+      return 'max_pages';
+    }));
+    if (stopped) {
+      await db.execute(sql`update xero_daily_checks set last_error = ${stopped} where organisation_id = ${organisationId}`);
+      return { read: seen.length, flagged: 0, stopped };
+    }
+    const { rows: copy } = await db.execute(sql`select xero_invoice_id, status, total_cents, amount_due_cents,
+      amount_paid_cents, amount_credited_cents, xero_updated_at from xero_invoices where organisation_id = ${organisationId}`);
+    const byId = new Map(copy.map((r) => [r.xero_invoice_id, r]));
+    const flagged = new Set();
+    for (const x of seen) {
+      const row = byId.get(x.InvoiceID);
+      byId.delete(x.InvoiceID);
+      if (!row || summaryDiffers(row, x)) flagged.add(x.InvoiceID);
+    }
+    // A live copy row Xero no longer lists: read it by id to learn its state.
+    for (const row of byId.values()) if (!['DELETED', 'VOIDED'].includes(row.status)) flagged.add(row.xero_invoice_id);
+    const at = now();
+    const list = [...flagged].slice(0, DAILY_FLAG_MAX);
+    for (const id of list) await flag(db, organisationId, 'invoices', id, { source: 'daily_check', now: at });
+    await db.execute(sql`update xero_daily_checks set last_finished_at = ${at}, last_read = ${seen.length},
+      last_flagged = ${flagged.size}, last_error = null where organisation_id = ${organisationId}`);
+    return { read: seen.length, flagged: flagged.size, queued: list.length, stopped: null };
+  } catch (error) {
+    await db.execute(sql`update xero_daily_checks set last_error = ${`${error.code ?? 'error'}: ${String(error.message).slice(0, 300)}`}
+      where organisation_id = ${organisationId}`);
+    throw error;
+  }
+}
+
+const cents = (value) => (value === null || value === undefined ? null : Number(value));
+
+// Whether a summary from Xero differs from the copy row in what the summary
+// carries: status, money, and the change time.
+export function summaryDiffers(row, summary) {
+  if (row.status !== summary.Status) return true;
+  for (const [column, field] of [['total_cents', 'Total'], ['amount_due_cents', 'AmountDue'], ['amount_paid_cents', 'AmountPaid'], ['amount_credited_cents', 'AmountCredited']]) {
+    if (summary[field] !== undefined && cents(row[column]) !== toCents(summary[field])) return true;
+  }
+  // Xero changed it after the copy's version (whole seconds, as Xero compares).
+  const changed = parseXeroDate(summary.UpdatedDateUTC);
+  const copied = row.xero_updated_at ? new Date(row.xero_updated_at) : null;
+  return Boolean(changed && (!copied || Math.floor(changed / 1000) > Math.floor(copied / 1000)));
+}
+
+// The organisations whose daily check is due: a complete copy, and no check
+// finished in the last day (or none tried in the last hour after a failure).
+export async function dueDailyChecks(db, runtime, { now = Date.now() } = {}) {
+  const { rows } = await db.execute(sql`select c.organisation_id, c.tenant_id, d.last_started_at, d.last_finished_at
+    from xero_connections c left join xero_daily_checks d on d.organisation_id = c.organisation_id
+    where c.mode = ${runtime.settings.mode}`);
+  const due = [];
+  for (const r of rows) {
+    const finished = r.last_finished_at ? new Date(r.last_finished_at).getTime() : null;
+    const started = r.last_started_at ? new Date(r.last_started_at).getTime() : null;
+    if (finished && Number(now) - finished < DAILY_CHECK_EVERY_MS) continue;
+    if (started && (!finished || started > finished) && Number(now) - started < DAILY_CHECK_RETRY_MS) continue;
+    if (!(await mirrorState(db, r.organisation_id, { now: new Date(Number(now)) })).complete) continue;
+    due.push({ organisationId: r.organisation_id, tenantId: r.tenant_id });
+  }
+  return due;
+}
+
+// After a failed read, an organisation waits 1 minute, then 2, 4 and up to an
+// hour, so a failing read is never tried every tick.
+export const RETRY_FIRST_MS = 60 * 1000;
+export const RETRY_MAX_MS = 60 * 60 * 1000;
+
+// One worker step: reads each organisation's inbox, then runs any daily check
+// that is due. A stop by the call guard skips that organisation quietly; the
+// guard has reported it. A failure is logged once as an error; the same
+// failure again is a warning. `holds` keeps each organisation's wait between
+// steps.
+export async function runWebhookWork(db, runtime, { log = console, now = Date.now, holds = new Map() } = {}) {
+  const failed = (organisationId, what, error) => {
+    const held = holds.get(organisationId);
+    const failures = (held?.failures ?? 0) + 1;
+    holds.set(organisationId, { failures, until: Number(now()) + Math.min(RETRY_MAX_MS, RETRY_FIRST_MS * 2 ** (failures - 1)), code: error?.code ?? 'error' });
+    const line = `[xero] ${what} for organisation ${organisationId} failed: ${error?.code ?? 'error'}`;
+    if (held?.code === (error?.code ?? 'error')) log.warn?.(line);
+    else log.error?.(line);
+  };
+  const waiting = (organisationId) => (holds.get(organisationId)?.until ?? 0) > Number(now());
+
+  const { rows } = await db.execute(sql`select distinct e.organisation_id from xero_webhook_events e
+    join xero_connections c on c.organisation_id = e.organisation_id and c.mode = ${runtime.settings.mode}
+    where e.pending`);
+  for (const { organisation_id: organisationId } of rows) {
+    if (waiting(organisationId)) continue;
+    try {
+      const read = await readInbox(db, runtime, organisationId, { now });
+      holds.delete(organisationId);
+      if (read.invoices.read || read.creditNotes || read.contacts) {
+        log.info?.(`[xero] read waiting changes for organisation ${organisationId}: ${read.invoices.read} invoices, ${read.creditNotes} credit notes${read.contacts ? ', contacts' : ''}`);
+      }
+    } catch (error) {
+      if (!isCallsStopped(error)) failed(organisationId, 'reading waiting changes', error);
+    }
+  }
+  for (const { organisationId, tenantId } of await dueDailyChecks(db, runtime, { now: now() })) {
+    try {
+      await runtime.guardFor(db).check(tenantId);
+      const check = await dailyCheck(db, runtime, organisationId, { now: () => new Date(Number(now())) });
+      log.info?.(`[xero] daily check for organisation ${organisationId}: ${check.read} invoices, ${check.flagged} to read again${check.stopped ? `; stopped (${check.stopped})` : ''}`);
+    } catch (error) {
+      // dueDailyChecks waits an hour after a failed check.
+      if (!isCallsStopped(error)) log.error?.(`[xero] daily check for organisation ${organisationId} failed: ${error?.code ?? 'error'}`);
+    }
+  }
+}

package/server/release-channel.js

@@ -2,8 +2,8 @@
 // GitHub Releases (with npm's dist-tags as the fallback). Used by the Replit
 // deploy (scripts/deploy-release.js, FLOW_DEPLOY_REF=stable|beta).
 //
-// Release names follow docs/RELEASING.md: vYYYY.M.D is stable, and
-// vYYYY.M.D-beta.N is a beta of the upcoming YYYY.M.D.
+// Release names follow docs/RELEASING.md: vYYYY.M.N is stable, and
+// vYYYY.M.N-beta.B is a beta of the upcoming YYYY.M.N.
 //
 //   stable  GitHub's latest release (what Flow Release Promote points at, so
 //           a rollback is followed), else npm `latest`
@@ -13,7 +13,7 @@
 // Nothing here sends anything about the installation: each request is an
 // anonymous GET of public data.
 
-const TAG = /^v(20\d{2})\.([1-9]|1[0-2])\.([1-9]|[12]\d|3[01])(?:-beta\.([1-9]\d*))?$/;
+const TAG = /^v(20\d{2})\.([1-9]|1[0-2])\.([1-9]\d*)(?:-beta\.([1-9]\d*))?$/;
 export const CHANNELS = ["stable", "beta"];
 export const DEFAULT_GITHUB_API = "https://api.github.com";
 export const DEFAULT_GITHUB_DOWNLOADS = "https://github.com";

package/server/ui/alerts.js

@@ -0,0 +1,77 @@
+// The quiet alert strip (issue 117, docs/ALERTS.md): one slim line under a
+// page's header when something on that page needs this person. It is hidden
+// when nothing does. It shows the worst alert first, with "+N more" when there
+// are others; × hides that alert for this person until something new joins
+// it, and the next one shows. Data comes from /api/alerts
+// (server/api/alerts.js). The caller passes in app.js's shared pieces as `ui`.
+
+const money = new Intl.NumberFormat('en-AU', { style: 'currency', currency: 'AUD' });
+const CLOSE = '<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>';
+
+// `onTab(tab)` opens a tab on the page, for an alert whose action names one.
+// `scope` narrows the page to one part (an integration's own page), and
+// `onLoad({ alerts, danger })` hears each answer (`danger`: a danger alert is
+// open, even one this person hid), so the page can show the same state
+// elsewhere. An action that links to the page already open is left out.
+// Answers { element, refresh }: put `element` on the page, and call
+// `refresh()` after a change that can fix or make an alert.
+export function alertStrip(ui, page, { onTab = () => {}, scope = null, onLoad = () => {} } = {}) {
+  const { h, flow, go, toast } = ui;
+  const element = h('div', { class: 'fx-alerts', hidden: true, role: 'status', 'aria-live': 'polite' });
+  let alerts = [];
+
+  function draw() {
+    const [first] = alerts;
+    element.hidden = !first;
+    if (!first) {
+      element.replaceChildren();
+      return;
+    }
+    element.dataset.tone = first.tone;
+    const close = h('button', { class: 'fx-alerts__close', type: 'button', 'aria-label': 'Dismiss', title: 'Dismiss', onclick: () => dismiss(first.key) });
+    close.innerHTML = CLOSE;
+    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);
+    element.replaceChildren(...[
+      h('p', { class: 'fx-alerts__text' },
+        first.title,
+        first.moneyAtRiskCents > 0 ? h('span', { class: 'fx-alerts__money' }, ` ${money.format(first.moneyAtRiskCents / 100)} at risk.`) : null),
+      action,
+      alerts.length > 1 ? h('span', { class: 'fx-alerts__more' }, `+${alerts.length - 1} more`) : null,
+      close,
+    ].filter(Boolean));
+  }
+
+  async function dismiss(key) {
+    alerts = alerts.filter((a) => a.key !== key);
+    draw();
+    try {
+      await flow('/api/alerts/dismiss', { method: 'POST', body: JSON.stringify({ key }) });
+    } catch (error) {
+      toast(error.message, 'danger');
+    }
+  }
+
+  // An alert that cannot load shows nothing: the page works without it.
+  async function refresh() {
+    let danger = false;
+    try {
+      const query = new URLSearchParams({ page, ...(scope ? { scope } : {}) });
+      ({ alerts, danger = false } = await flow(`/api/alerts?${query}`));
+    } catch {
+      alerts = [];
+    }
+    onLoad({ alerts, danger });
+    draw();
+  }
+
+  // Coming back to the tab checks again, while this page is open.
+  const onVisible = () => {
+    if (!element.isConnected) document.removeEventListener('visibilitychange', onVisible);
+    else if (document.visibilityState === 'visible') refresh();
+  };
+  document.addEventListener('visibilitychange', onVisible);
+  refresh();
+  return { element, refresh };
+}

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -12,9 +12,11 @@ import { ACCENT_PRESETS, normalizeAccent, THEME_FAMILIES, tokensFor } from '/ass
 import { renderInvoice, renderInvoiceList } from '/assets/ui/invoicing.js';
 import { automationSection } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
+import { renderPriceList } from '/assets/ui/price-list.js';
 import { renderJobs } from '/assets/ui/jobs.js';
 import { startMonitoring } from '/assets/ui/monitoring.js';
 import { openSearch } from '/assets/ui/search.js';
+import { alertStrip } from '/assets/ui/alerts.js';
 
 const $ = (id) => document.getElementById(id);
 
@@ -194,10 +196,13 @@ let me = null;
 const VIEWS = {
   jobs: { label: 'Jobs', icon: 'jobs', group: 'Work', render: (main) => renderJobs(main, ui()) },
   invoices: { label: 'Invoices', icon: 'invoices', group: 'Work', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
-  'invoicing-settings': { label: 'Invoicing', icon: 'invoices', group: 'Settings', render: (main) => renderInvoicingSettings(main, ui()) },
+  'invoicing-settings': { label: 'Invoice rules', icon: 'invoices', group: 'Settings', render: (main) => renderInvoicingSettings(main, ui()) },
+  'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main) => renderPriceList(main, ui()) },
   people: { label: 'People', icon: 'people', group: 'Settings', ownerOnly: true, render: renderPeople },
   integrations: { label: 'Integrations', icon: 'plug', group: 'Settings', ownerOnly: true, render: (main, id) => (id ? renderIntegration(main, id) : renderIntegrations(main)) },
-  account: { label: 'Account', icon: 'person', group: 'Settings', render: renderAccount },
+  // Not in the sidebar: "Manage account" in the account menu opens the same
+  // Clerk profile. The page stays for links and Search.
+  account: { label: 'Account', icon: 'person', group: 'Settings', sidebar: false, render: renderAccount },
   appearance: { label: 'Appearance', icon: 'palette', group: 'Settings', render: renderAppearance },
 };
 
@@ -206,11 +211,12 @@ const ICON_PATHS = {
   jobs: '<rect x="3" y="4" width="5" height="16" rx="1"/><rect x="10" y="4" width="5" height="11" rx="1"/><rect x="17" y="4" width="4" height="14" rx="1"/>',
   invoices: '<path d="M6 3h9l4 4v14H6z"/><path d="M14 3v5h5M9 13h7M9 17h5"/>',
   people: '<circle cx="9" cy="8" r="3"/><path d="M3 20c0-3.5 2.7-6 6-6s6 2.5 6 6"/><path d="M16 5a3 3 0 010 6M21 20c0-3-1.6-5-4-5.7"/>',
+  tag: '<path d="M3 12V4h8l10 10-8 8z"/><circle cx="7.5" cy="8.5" r="1.5"/>',
   plug: '<path d="M9 3v5M15 3v5M6 8h12v3a6 6 0 01-12 0zM12 17v4"/>',
   person: '<circle cx="12" cy="8" r="4"/><path d="M4 21c0-4 3.6-7 8-7s8 3 8 7"/>',
   flag: '<path d="M5 21V4M5 4h11l-2 4 2 4H5"/>',
   search: '<circle cx="11" cy="11" r="6.5"/><path d="M16 16l4.5 4.5"/>',
-  menu: '<path d="M4 6h16M4 12h16M4 18h16"/>',
+  sidebar: '<rect x="3" y="4" width="18" height="16" rx="2.5"/><path d="M9.5 4v16"/>',
   palette: '<path d="M12 3a9 9 0 100 18c1.1 0 1.5-.8 1.5-1.6 0-1-.8-1.4-.8-2.4 0-.9.7-1.5 1.6-1.5H17a4 4 0 004-4c0-4.7-4-8.5-9-8.5z"/><circle cx="7.5" cy="11" r="1"/><circle cx="10" cy="7" r="1"/><circle cx="15" cy="7" r="1"/>',
 };
 
@@ -220,10 +226,12 @@ function icon(name) {
   return node;
 }
 
-// The menu button at the top of the sidebar. On a wide screen it folds the
-// sidebar to its icons and back, and the choice stays in this browser. On a
-// narrow screen the sidebar is a bar across the top, and the button opens
-// the menu below it; choosing a page, Escape or a click outside closes it.
+// The sidebar button at the top of the sidebar (a panel icon, not a
+// hamburger; folded or narrow, the logo stands in for it). On a wide screen it folds the sidebar to its icons and back,
+// and the choice stays in this browser. On a narrow screen the sidebar is a
+// bar across the top, and the button slides the menu in from the left as a
+// drawer over a dimmed page; choosing a page, Escape or a click on the page
+// closes it.
 const NARROW = window.matchMedia('(max-width: 820px)');
 const FOLDED_KEY = 'flow_sidebar_folded';
 
@@ -237,7 +245,7 @@ function drawMenu() {
   shell.toggleAttribute('data-folded', folded);
   const open = NARROW.matches ? shell.hasAttribute('data-menu-open') : !folded;
   const toggle = $('menu-toggle');
-  const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the menu' : 'Fold the menu');
+  const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the sidebar' : 'Hide the sidebar');
   toggle.setAttribute('aria-expanded', String(open));
   toggle.setAttribute('aria-label', label);
   toggle.title = label;
@@ -368,6 +376,7 @@ function renderShell() {
   let group = null;
   for (const [name, view] of Object.entries(VIEWS)) {
     if (view.ownerOnly && me?.person.role !== 'owner') continue;
+    if (view.sidebar === false) continue;
     if (view.group && view.group !== group) items.push(h('span', { class: 'fx-nav__group' }, view.group));
     group = view.group;
     items.push(h('a', { href: `/${name}`, 'data-nav': name, 'data-label': view.label, onclick: navigate }, icon(view.icon), h('span', { class: 'fx-nav__label' }, view.label)));
@@ -377,7 +386,13 @@ function renderShell() {
   const report = h('button', { type: 'button', class: 'fx-nav__report', 'data-nav': 'report', 'data-label': 'Report a problem', hidden: true },
     icon('flag'), h('span', { class: 'fx-nav__label' }, 'Report a problem'));
   nav.replaceChildren(...items, report);
-  $('menu-toggle').replaceChildren(icon('menu'));
+  // Folded or narrow, the logo is the sidebar button: it shows the mark and
+  // turns into the sidebar icon under the pointer or keyboard focus.
+  const mark = h('span', { class: 'fx-toggle__mark', 'aria-hidden': 'true' });
+  mark.innerHTML = document.querySelector('.fx-side__head .fx-brand svg')?.outerHTML ?? '';
+  const sidebar = icon('sidebar');
+  sidebar.classList.add('fx-toggle__icon');
+  $('menu-toggle').replaceChildren(mark, sidebar);
   $('menu-toggle').onclick = toggleMenu;
   drawMenu();
   // The sidebar foot shows who is signed in: photo or initial, then the name
@@ -539,6 +554,7 @@ async function renderIntegrations(main) {
   const content = h('div', { class: 'fx-int-sections' }, h('div', { class: 'fx-skeleton' }));
   main.append(
     h('header', { class: 'fx-ph' }, h('div', { class: 'fx-ph__text' }, h('h1', { class: 'fx-title' }, 'Integrations'))),
+    alertStrip(ui(), 'integrations').element,
     h('div', { class: 'fx-int-bar' }, tabs, search),
     notices, content);
   let body;
@@ -623,8 +639,24 @@ async function renderIntegration(main, id) {
     return;
   }
   const canChange = Boolean(me.ownerActions?.allowed);
+  // The quiet alert line for this integration only (server/ui/alerts.js).
+  // While a danger alert is open, even one this person hid, the status says
+  // calls are stopped instead of the integration's state.
+  let stopped = false;
+  const statusPill = (current) => (stopped && current.state === 'ready'
+    ? h('span', { class: 'fx-status', 'data-tone': 'danger', 'data-int-status': '' }, 'Calls stopped')
+    : h('span', { class: 'fx-status', 'data-tone': STATE_TONE[current.state] ?? 'mute', 'data-int-status': '' }, STATE_LABEL[current.state] ?? current.state));
+  let shown = found;
+  const alerts = alertStrip(ui(), 'integrations', {
+    scope: id,
+    onLoad: ({ danger }) => {
+      stopped = danger;
+      for (const pill of host.querySelectorAll('[data-int-status]')) pill.replaceWith(statusPill(shown));
+    },
+  });
 
   const draw = (current, progress = null) => {
+    shown = current;
     const inputs = new Map();
     const rows = [];
     for (const field of current.fields) {
@@ -732,10 +764,11 @@ async function renderIntegration(main, id) {
           h('p', { class: 'fx-int-hero__blurb' }, entry?.blurb ?? ''),
           h('div', { class: 'fx-int-hero__actions' },
             primary,
-            on ? h('span', { class: 'fx-status', 'data-tone': STATE_TONE[current.state] ?? 'mute' }, STATE_LABEL[current.state] ?? current.state) : null,
+            on ? statusPill(current) : null,
             progress ? connectProgress(progress) : null))),
       h('div', { class: 'fx-int-page__grid' },
         h('div', { class: 'fx-int-page__main' }, ...[
+          alerts.element,
           !canChange ? notice('Changing integrations needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.', 'warn', 'Read only.') : null,
           !body.secretsKey ? notice('Flow has no secrets key, so it cannot store a client secret. Ask whoever hosts Flow to set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.') : null,
           current.state === 'failed' && current.error ? notice(current.error, 'danger', 'It could not start.') : null,
@@ -753,7 +786,7 @@ async function renderIntegration(main, id) {
         ].filter(Boolean)),
         h('aside', { class: 'fx-int-page__meta' },
           h('dl', { class: 'fx-meta' }, ...[
-            ['Status', h('span', { class: 'fx-status', 'data-tone': STATE_TONE[current.state] ?? 'mute' }, STATE_LABEL[current.state] ?? current.state)],
+            ['Status', statusPill(current)],
             ['Category', h('span', { class: 'fx-chip fx-chip--static' }, CATEGORY_LABEL[entry?.category] ?? 'Integration')],
             modeLabel ? ['Mode', modeLabel] : null,
             ['Turned on by', current.enabledBy === 'host' ? 'The host' : current.enabledBy === 'flow' ? 'An owner, here' : '—'],
@@ -768,11 +801,11 @@ async function renderIntegration(main, id) {
 // One setting, laid out the same on every settings screen: a short name, one
 // line of smaller text under it, and the control on the right. Longer help
 // lives behind a link, not here. A wide control (a grid of choices) sits on
-// its own line under the name.
-function settingRow({ label, hint, control, wide = false }) {
+// its own line under the name. `tone: 'danger'` marks a row that needs a person.
+function settingRow({ label, hint, control, wide = false, tone = null }) {
   const target = control?.matches?.('input, select, textarea') ? control : control?.querySelector?.('input:not([type=color]), select, textarea');
   const id = target ? (target.id ||= `fx-set-${++settingRow.next}`) : null;
-  return h('div', { class: `fx-setting${wide ? ' fx-setting--wide' : ''}` },
+  return h('div', { class: `fx-setting${wide ? ' fx-setting--wide' : ''}`, 'data-tone': tone },
     h('div', { class: 'fx-setting__text' },
       id ? h('label', { class: 'fx-setting__name', for: id }, label) : h('span', { class: 'fx-setting__name' }, label),
       hint ? h('p', { class: 'fx-setting__hint' }, hint) : null),
@@ -800,16 +833,25 @@ function xeroConnection(organisations, canChange) {
     (async () => {
       let hint;
       let control = null;
+      let stopped = false;
       try {
         const status = await flow(`/api/xero/status?organisationId=${organisation.id}`);
-        if (status.connected) {
+        if (status.connected && status.calls?.stopped) {
+          // A refused connection stopped calls (the call guard): say so, and
+          // make Connect again the main button, which starts them again.
+          const at = status.calls.since ? ` at ${new Date(status.calls.since).toLocaleString('en-AU', { dateStyle: 'medium', timeStyle: 'short' })}` : '';
+          hint = status.calls.all
+            ? `Xero refused Flow${at}. Flow stopped all calls.`
+            : `Xero refused Flow for ${status.calls.resources.join(', ')}${at}. Flow stopped those calls.`;
+          stopped = true;
+        } else if (status.connected) {
           const mirror = await flow(`/api/xero/mirror?organisationId=${organisation.id}`).catch(() => null);
           hint = `Connected to ${status.connection?.tenantName ?? 'Xero'}.${mirror ? ` ${mirror.counts.invoices} invoices copied.` : ''}`;
         } else {
           hint = 'Not connected.';
         }
         if (canChange) {
-          control = h('button', { class: `fx-btn fx-btn--sm${status.connected ? '' : ' fx-btn--primary'}`, type: 'button', onclick: async () => {
+          control = h('button', { class: `fx-btn fx-btn--sm${status.connected && !stopped ? '' : ' fx-btn--primary'}`, type: 'button', onclick: async () => {
             try {
               const { authorizeUrl } = await flow('/api/xero/connect', { method: 'POST', body: JSON.stringify({ organisationId: organisation.id }) });
               location.assign(authorizeUrl);
@@ -821,7 +863,7 @@ function xeroConnection(organisations, canChange) {
       } catch (error) {
         hint = error.message;
       }
-      row.replaceWith(settingRow({ label: organisation.name, hint, control }));
+      row.replaceWith(settingRow({ label: organisation.name, hint, control, tone: stopped ? 'danger' : null }));
     })();
   }
   return h('div', {}, h('h2', { class: 'fx-int-section__title' }, 'Xero organisation'), host);
@@ -854,9 +896,9 @@ async function invitePerson() {
 // security), with the person's Flow role above it.
 function renderAccount(main) {
   const host = h('div', { class: 'fx-clerk-profile' });
-  main.append(
-    pageHeader('Account', { subtitle: `${me.person.email} · ${ROLE_LABEL[me.person.role]}. ${ROLE_HINT[me.person.role]}` }),
-    host);
+  // Clerk's card has its own "Account" heading; Flow's page heading is for
+  // screen readers only, so the title shows once.
+  main.append(h('h1', { class: 'fx-sr' }, 'Account'), host);
   // Clerk keeps its own pages (profile, security) in memory, so the URL
   // stays Flow's.
   mountClerk('profile', host, { routing: 'virtual' });
@@ -1011,7 +1053,7 @@ drawModeToggles();
 // the Clerk instance is called.
 const LOCALIZATION = {
   signIn: {
-    start: { title: 'Sign in to Flow', subtitle: 'Welcome back. Choose how to sign in.' },
+    start: { title: 'Sign in to Flow', subtitle: 'Choose how to sign in.' },
     password: { subtitle: 'Enter the password for your account.' },
   },
   signUp: { start: { title: 'Ask for access to Flow', subtitle: 'Use your work email. An owner approves new people.' } },