@arcforgelabs/flow 2026.10.27 → 2026.10.30

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

@@ -15,6 +15,13 @@
       "when": 1792330268730,
       "tag": "0001_mirror",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1792448378477,
+      "tag": "0002_call_safety",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/seazona/scheduler.js

@@ -4,12 +4,20 @@ import { readLaneStates } from './store.js';
 // The background sync, for live mode only (issue #10: index.js never creates
 // it in sandbox or replay). It runs the lanes that are due, then sleeps until
 // the next lane is due, between 15 seconds and 30 minutes. One run at a time.
+// A stopped lane (issue #101) is not due until a person or a release resets it.
+//
+// Issue #101: each held failure is reported once to the error services
+// (log.error, server/core/monitoring.js): when a lane starts failing or its
+// failure code changes, and when records are quarantined. A repeat of the
+// same failure is a warning in the host log only. The report text is stable,
+// so the error service groups repeats.
 
 const MIN_DELAY_MS = 15_000;
 const MAX_DELAY_MS = 30 * 60_000;
 
 export function createSeazonaScheduler({
   db,
+  settings = null,
   run,
   now = Date.now,
   log = console,
@@ -21,11 +29,39 @@ export function createSeazonaScheduler({
   let stopped = false;
   let nextRunAt = null;
   let last = null;
+  // lane -> the failure code last reported, while that lane keeps failing.
+  const reported = new Map();
+  const quarantineAt = settings?.sync?.orderQuarantineFailures ?? null;
+
+  function newlyQuarantined(outcome) {
+    if (Number.isInteger(outcome.newlyQuarantined)) return outcome.newlyQuarantined;
+    const failures = outcome.failureDetails?.failures ?? [];
+    return failures.filter((f) => f.quarantinedUntil && f.failureCount === quarantineAt).length;
+  }
+
+  function report(results) {
+    for (const [lane, outcome] of Object.entries(results)) {
+      if (outcome.ok) {
+        reported.delete(lane);
+        const count = newlyQuarantined(outcome);
+        if (count) log.error?.(`[seazona] ${lane}: records quarantined after repeated failed reads`);
+        continue;
+      }
+      if (reported.get(lane) === outcome.code) {
+        log.warn?.(`[seazona] ${lane}: ${outcome.error}`);
+        continue;
+      }
+      reported.set(lane, outcome.code);
+      log.error?.(`[seazona] ${lane} lane ${outcome.status === 'stopped' ? 'stopped' : 'failed'}: ${outcome.code}`);
+      log.warn?.(`[seazona] ${lane}: ${outcome.error}`);
+    }
+  }
 
   async function nextDelayMs() {
     const states = await readLaneStates(db);
     let soonest = Infinity;
     for (const lane of LANES) {
+      if (states.get(lane)?.status === 'stopped') continue;
       const at = states.get(lane)?.nextRunAt?.getTime();
       soonest = Math.min(soonest, Number.isFinite(at) ? at - Number(now()) : 0);
     }
@@ -48,7 +84,7 @@ export function createSeazonaScheduler({
         const result = await run();
         const failed = Object.entries(result.results).filter(([, lane]) => !lane.ok);
         last = { at: startedAt, ok: result.ok, lanes: Object.keys(result.results), failed: failed.map(([lane]) => lane) };
-        for (const [lane, outcome] of failed) log.warn?.(`[seazona] ${lane}: ${outcome.error}`);
+        report(result.results);
       } catch (error) {
         last = { at: startedAt, ok: false, error: error?.message || String(error) };
         log.error?.(`[seazona] sync run failed: ${last.error}`);

package/server/integrations/seazona/schema.js

@@ -10,10 +10,17 @@ const at = (name) => timestamp(name, { withTimezone: true });
 
 // One row per API client: when the next request may go, and any cooldown a
 // 429 asked for. Every process that shares the database shares this row.
+// Issue #101: the circuit breaker (open until, and how many times in a row it
+// opened) and a stop that waits for a person (`halted_reason`, for example
+// `auth` after a 401).
 export const seazonaApiGovernor = pgTable('seazona_api_governor', {
   clientKey: text('client_key').primaryKey(),
   nextEligibleAt: at('next_eligible_at').notNull().default(sql`'epoch'`),
   cooldownUntil: at('cooldown_until').notNull().default(sql`'epoch'`),
+  circuitOpenUntil: at('circuit_open_until').notNull().default(sql`'epoch'`),
+  circuitOpens: integer('circuit_opens').notNull().default(0),
+  haltedReason: text('halted_reason'),
+  haltedAt: at('halted_at'),
   updatedAt: at('updated_at').notNull().defaultNow(),
 });
 
@@ -155,3 +162,18 @@ export const seazonaOrderReadFailures = pgTable('seazona_order_read_failures', {
   lastError: text('last_error'),
   quarantinedUntil: at('quarantined_until'),
 });
+
+// Issue #101: each failed detail read of an invoice or a client, per record.
+// Orders keep their own table (issue #12). After a few failures in a row the
+// record is quarantined: the lane skips it and its cursor moves on.
+export const seazonaRecordReadFailures = pgTable('seazona_record_read_failures', {
+  resource: text('resource').notNull(),
+  recordKey: text('record_key').notNull(),
+  failureCount: integer('failure_count').notNull(),
+  lastAttemptAt: at('last_attempt_at').notNull(),
+  lastHttpStatus: integer('last_http_status'),
+  lastFailureKind: text('last_failure_kind'),
+  quarantinedUntil: at('quarantined_until'),
+}, (t) => [
+  primaryKey({ columns: [t.resource, t.recordKey] }),
+]);

package/server/integrations/seazona/settings.js

@@ -75,6 +75,16 @@ export function resolveSeazonaSettings(env = process.env) {
     maxWaitMs: clampInt(env.SEAZONA_API_MAX_WAIT_MS, 120_000, 1_000, 15 * 60_000),
     // Long enough to answer a vendor's question about last month.
     telemetryRetentionMs: clampInt(env.SEAZONA_API_TELEMETRY_RETENTION_DAYS, 35, 1, 90) * DAY_MS,
+    // Issue #101: a vendor can cut off API access after many failed calls,
+    // even inside the rate limit. This many failed calls inside the window
+    // open the circuit: no call goes out for the pause, which doubles each
+    // time the probe after it fails, to at most 6 hours.
+    circuitFailures: clampInt(env.SEAZONA_CIRCUIT_FAILURES, 5, 1, 100),
+    circuitWindowMs: clampInt(env.SEAZONA_CIRCUIT_WINDOW_MS, 10 * 60_000, 60_000, DAY_MS),
+    circuitPauseMs: clampInt(env.SEAZONA_CIRCUIT_PAUSE_MS, 5 * 60_000, 60_000, 6 * 60 * 60_000),
+    // Failed calls allowed in one UTC day. When they are spent, calls stop
+    // until the next day.
+    dailyFailureBudget: clampInt(env.SEAZONA_DAILY_FAILURE_BUDGET, 50, 1, 10_000),
   };
 
   const MINUTE = 60_000;

package/server/integrations/seazona/store.js

@@ -6,6 +6,7 @@ import {
   seazonaLaneState,
   seazonaOrderReadFailures,
   seazonaOrders,
+  seazonaRecordReadFailures,
   seazonaReference,
 } from './schema.js';
 
@@ -192,6 +193,60 @@ export async function readQuarantinedOrders(db, { at, limit = 25 }) {
   }));
 }
 
+// Issue #101: failed detail reads of invoices and clients, per record.
+// Answers Map(key -> row) for the keys that are quarantined at `at`.
+export async function readQuarantinedRecords(db, resource, keys, { at }) {
+  if (!keys.length) return new Map();
+  const rows = await db.select().from(seazonaRecordReadFailures).where(and(
+    eq(seazonaRecordReadFailures.resource, resource),
+    inArray(seazonaRecordReadFailures.recordKey, keys),
+    gt(seazonaRecordReadFailures.quarantinedUntil, at),
+  ));
+  return new Map(rows.map((row) => [row.recordKey, row]));
+}
+
+export async function clearRecordFailures(db, resource, keys) {
+  if (!keys.length) return;
+  await db.delete(seazonaRecordReadFailures).where(and(
+    eq(seazonaRecordReadFailures.resource, resource),
+    inArray(seazonaRecordReadFailures.recordKey, keys),
+  ));
+}
+
+// Records one failed read, as recordOrderFailure does for orders. Answers
+// { failureCount, quarantinedUntil }.
+export async function recordRecordFailure(db, resource, key, failure, { at, quarantineFailures, quarantineMs }) {
+  const until = new Date(at.getTime() + quarantineMs);
+  const [row] = await db.insert(seazonaRecordReadFailures).values({
+    resource,
+    recordKey: key,
+    failureCount: 1,
+    lastAttemptAt: at,
+    lastHttpStatus: failure.httpStatus,
+    lastFailureKind: failure.kind,
+    quarantinedUntil: quarantineFailures <= 1 ? until : null,
+  }).onConflictDoUpdate({
+    target: [seazonaRecordReadFailures.resource, seazonaRecordReadFailures.recordKey],
+    set: {
+      failureCount: sql`${seazonaRecordReadFailures.failureCount} + 1`,
+      lastAttemptAt: at,
+      lastHttpStatus: failure.httpStatus,
+      lastFailureKind: failure.kind,
+      quarantinedUntil: sql`case when ${seazonaRecordReadFailures.failureCount} + 1 >= ${quarantineFailures}
+        then ${until}::timestamptz else null end`,
+    },
+  }).returning();
+  return { failureCount: row.failureCount, quarantinedUntil: row.quarantinedUntil?.toISOString() ?? null };
+}
+
+export async function readQuarantinedRecordCounts(db, { at }) {
+  const rows = await db.select({ resource: seazonaRecordReadFailures.resource, records: sql`count(*)::int` })
+    .from(seazonaRecordReadFailures)
+    .where(gt(seazonaRecordReadFailures.quarantinedUntil, at))
+    .groupBy(seazonaRecordReadFailures.resource);
+  return Object.fromEntries(rows.map((row) => [row.resource, row.records]));
+}
+
 // Lane state.
 
 export async function readLaneStates(db) {
@@ -214,6 +269,25 @@ export async function claimLane(db, lane, { at, stuckMs }) {
   return claimed.length > 0;
 }
 
+// Issue #101: a lane stopped for a person or a release runs again. Answers
+// the lanes it reset.
+export async function resetStoppedLanes(db, { at }) {
+  const rows = await db.update(seazonaLaneState)
+    .set({ status: 'idle', nextRunAt: at, failureCount: 0, heldReason: null, updatedAt: at })
+    .where(eq(seazonaLaneState.status, 'stopped'))
+    .returning({ lane: seazonaLaneState.lane });
+  return rows.map((row) => row.lane);
+}
+
+// A person acted: every lane that failed or stopped runs at the next tick.
+export async function resetFailedLanes(db, { at }) {
+  const rows = await db.update(seazonaLaneState)
+    .set({ status: 'idle', nextRunAt: at, failureCount: 0, heldReason: null, updatedAt: at })
+    .where(inArray(seazonaLaneState.status, ['stopped', 'failed', 'held']))
+    .returning({ lane: seazonaLaneState.lane });
+  return rows.map((row) => row.lane);
+}
+
 export async function finishLane(db, lane, patch) {
   await db.update(seazonaLaneState).set({ ...patch, updatedAt: patch.lastAttemptAt ?? new Date() }).where(eq(seazonaLaneState.lane, lane));
 }

package/server/integrations/seazona/tables.js

@@ -13,5 +13,6 @@ export const seazonaSchema = Object.freeze({
     'seazona_reference',
     'seazona_lane_state',
     'seazona_order_read_failures',
+    'seazona_record_read_failures',
   ]),
 });

package/server/integrations/xero/drafts.js

@@ -94,7 +94,7 @@ async function documentFor(db, organisationId, invoiceId) {
       currency: invoice.currency,
       contact: { id: contact.id, name: contact.name, email: contact.email },
       lines: invoice.lines.map((l) => ({
-        position: l.position, itemCode: codes.get(l.priceItemId) ?? null, description: l.description, quantity: l.quantity,
+        position: l.position, itemCode: codes.get(l.priceItemId) ?? null, ...(l.accountCode ? { accountCode: l.accountCode } : {}), description: l.description, quantity: l.quantity,
         unitAmountCents: l.unitAmountCents, taxCode: l.taxCode, lineAmountCents: l.lineAmountCents, taxCents: l.taxCents,
       })),
       subtotalCents: invoice.subtotalCents,
@@ -131,6 +131,9 @@ export function buildDraft(document, { settings, contact, items, sendMode = 'acc
     if (line.itemCode) {
       if (items.has(line.itemCode)) out.ItemCode = line.itemCode;
       else problems.push(problem('xero_item_missing', `Line ${line.position}: item ${line.itemCode} is not in Xero. Add it in Xero, then sync.`, { itemCode: line.itemCode }));
+    } else if (line.accountCode) {
+      // A line with no item books to its own account, such as a surcharge.
+      out.AccountCode = line.accountCode;
     }
     if (tracking) out.Tracking = [tracking];
     return out;

package/server/integrations/xero/import.js

@@ -109,6 +109,7 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
         if (ran) {
           busy = true;
           const read = (ran.job.result?.results ?? []).map((r) => `${r.resource} ${r.read}`).join(', ');
+          if (ran.outcome === 'dead') log.error?.('[xero] the history import gave up after its last attempt');
           log.info?.(`[xero] import ${ran.outcome} for organisation ${ran.job.organisationId}${read ? `: ${read}` : ''}${ran.job.result?.more ? `; more (${ran.job.result.more})` : ''}`);
         }
       } catch (error) {

package/server/integrations/xero/lookup.js

@@ -1,6 +1,5 @@
 import { sql } from 'drizzle-orm';
 import { ledgerState } from './ledger.js';
-import { MIRROR_RESOURCES } from './mirror.js';
 
 // What the core's matcher (server/core/pipeline.js) reads from Xero: the
 // customers and the sales invoices in Flow's own copy. It never calls Xero, so
@@ -10,6 +9,11 @@ import { MIRROR_RESOURCES } from './mirror.js';
 // stops counting as proof.
 export const MIRROR_FRESH_MS = 24 * 60 * 60 * 1000;
 
+// The copies that prove whether Xero holds an invoice for a job. Payments do
+// not: a connection without a payments scope (the default) never copies them,
+// and must still match jobs.
+export const PROOF_RESOURCES = Object.freeze(['invoices', 'credit_notes']);
+
 export async function listCustomers(db, organisationId) {
   const { rows } = await db.execute(sql`
     select xero_contact_id, name, status from xero_contacts
@@ -26,7 +30,7 @@ export async function mirrorState(db, organisationId, { now = new Date() } = {})
     where organisation_id = ${organisationId}`);
   const byResource = new Map(rows.map((r) => [r.resource, r]));
   const invoices = byResource.get('invoices');
-  const finished = MIRROR_RESOURCES.every((r) => (byResource.get(r)?.passes ?? 0) > 0);
+  const finished = PROOF_RESOURCES.every((r) => (byResource.get(r)?.passes ?? 0) > 0);
   const lastPass = invoices?.last_pass_finished_at ? new Date(invoices.last_pass_finished_at) : null;
   const { rows: [changed] } = await db.execute(sql`
     select max(last_changed_at) as at from xero_invoices where organisation_id = ${organisationId}`);

package/server/integrations/xero/migrations/0000_xero_connections.sql

@@ -1,6 +1,6 @@
 -- The Xero connection of each Flow organisation. The refresh token is
 -- AES-256-GCM ciphertext (XERO_TOKEN_KEY); the plain token is never stored.
-CREATE TABLE "xero_connections" (
+CREATE TABLE IF NOT EXISTS "xero_connections" (
 	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
 	"mode" text NOT NULL,
 	"tenant_id" text NOT NULL,

package/server/integrations/xero/migrations/0001_xero_catalogue.sql

@@ -1,6 +1,6 @@
 -- Flow's copy of the Xero contacts and items of each connected organisation,
 -- and a record of each sync. Xero owns these records; a sync replaces the copy.
-CREATE TABLE "xero_contacts" (
+CREATE TABLE IF NOT EXISTS "xero_contacts" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_contact_id" text NOT NULL,
 	"name" text NOT NULL,
@@ -14,9 +14,9 @@ CREATE TABLE "xero_contacts" (
 	CONSTRAINT "xero_contacts_pk" PRIMARY KEY("organisation_id", "xero_contact_id")
 );
 --> statement-breakpoint
-CREATE INDEX "xero_contacts_org_name" ON "xero_contacts" ("organisation_id", lower("name"));
+CREATE INDEX IF NOT EXISTS "xero_contacts_org_name" ON "xero_contacts" ("organisation_id", lower("name"));
 --> statement-breakpoint
-CREATE TABLE "xero_items" (
+CREATE TABLE IF NOT EXISTS "xero_items" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_item_id" text NOT NULL,
 	"code" text NOT NULL,
@@ -32,7 +32,7 @@ CREATE TABLE "xero_items" (
 	CONSTRAINT "xero_items_org_code" UNIQUE("organisation_id", "code")
 );
 --> statement-breakpoint
-CREATE TABLE "xero_sync_runs" (
+CREATE TABLE IF NOT EXISTS "xero_sync_runs" (
 	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"status" text DEFAULT 'running' NOT NULL,
@@ -46,4 +46,4 @@ CREATE TABLE "xero_sync_runs" (
 	CONSTRAINT "xero_sync_runs_status_valid" CHECK ("status" in ('running', 'succeeded', 'failed'))
 );
 --> statement-breakpoint
-CREATE INDEX "xero_sync_runs_org_started" ON "xero_sync_runs" ("organisation_id", "started_at");
+CREATE INDEX IF NOT EXISTS "xero_sync_runs_org_started" ON "xero_sync_runs" ("organisation_id", "started_at");

package/server/integrations/xero/migrations/0002_xero_invoice_pushes.sql

@@ -1,7 +1,7 @@
 -- One row for each issued Flow invoice version sent to Xero as a draft. It
 -- holds the exact request and its Idempotency-Key from before the request
 -- leaves, so an uncertain outcome is resolved without a second invoice.
-CREATE TABLE "xero_invoice_pushes" (
+CREATE TABLE IF NOT EXISTS "xero_invoice_pushes" (
 	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
 	"organisation_id" uuid NOT NULL,
 	"invoice_id" uuid NOT NULL,
@@ -29,4 +29,4 @@ CREATE TABLE "xero_invoice_pushes" (
 	CONSTRAINT "xero_invoice_pushes_settled_has_id" CHECK ("state" in ('dispatching', 'ambiguous') or "xero_invoice_id" is not null)
 );
 --> statement-breakpoint
-CREATE INDEX "xero_invoice_pushes_org_invoice" ON "xero_invoice_pushes" ("organisation_id", "invoice_id");
+CREATE INDEX IF NOT EXISTS "xero_invoice_pushes_org_invoice" ON "xero_invoice_pushes" ("organisation_id", "invoice_id");

package/server/integrations/xero/migrations/0003_xero_payment_cursors.sql

@@ -1,6 +1,6 @@
 -- Where the next read of Xero payments starts, for each Flow organisation.
 -- (This is the Xero adapter's own migration journal, not the core's.)
-CREATE TABLE "xero_payment_cursors" (
+CREATE TABLE IF NOT EXISTS "xero_payment_cursors" (
 	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
 	"payments_since" timestamp with time zone NOT NULL,
 	"updated_at" timestamp with time zone DEFAULT now() NOT NULL

package/server/integrations/xero/migrations/0004_xero_mirror.sql

@@ -4,7 +4,7 @@
 -- without spending Xero calls. A row is upserted by its Xero id, and changes
 -- only when its content hash changes. Free text (references, line
 -- descriptions) is kept only with XERO_KEEP_REFERENCE=on.
-CREATE TABLE "xero_invoices" (
+CREATE TABLE IF NOT EXISTS "xero_invoices" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_invoice_id" text NOT NULL,
 	"type" text NOT NULL,
@@ -30,11 +30,11 @@ CREATE TABLE "xero_invoices" (
 	CONSTRAINT "xero_invoices_pk" PRIMARY KEY("organisation_id", "xero_invoice_id")
 );
 --> statement-breakpoint
-CREATE INDEX "xero_invoices_number" ON "xero_invoices" ("organisation_id", "invoice_number");
+CREATE INDEX IF NOT EXISTS "xero_invoices_number" ON "xero_invoices" ("organisation_id", "invoice_number");
 --> statement-breakpoint
-CREATE INDEX "xero_invoices_contact" ON "xero_invoices" ("organisation_id", "xero_contact_id", "issued_on");
+CREATE INDEX IF NOT EXISTS "xero_invoices_contact" ON "xero_invoices" ("organisation_id", "xero_contact_id", "issued_on");
 --> statement-breakpoint
-CREATE TABLE "xero_credit_notes" (
+CREATE TABLE IF NOT EXISTS "xero_credit_notes" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_credit_note_id" text NOT NULL,
 	"type" text NOT NULL,
@@ -57,7 +57,7 @@ CREATE TABLE "xero_credit_notes" (
 	CONSTRAINT "xero_credit_notes_pk" PRIMARY KEY("organisation_id", "xero_credit_note_id")
 );
 --> statement-breakpoint
-CREATE TABLE "xero_payments" (
+CREATE TABLE IF NOT EXISTS "xero_payments" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_payment_id" text NOT NULL,
 	"payment_type" text,
@@ -75,12 +75,12 @@ CREATE TABLE "xero_payments" (
 	CONSTRAINT "xero_payments_pk" PRIMARY KEY("organisation_id", "xero_payment_id")
 );
 --> statement-breakpoint
-CREATE INDEX "xero_payments_invoice" ON "xero_payments" ("organisation_id", "xero_invoice_id");
+CREATE INDEX IF NOT EXISTS "xero_payments_invoice" ON "xero_payments" ("organisation_id", "xero_invoice_id");
 --> statement-breakpoint
 -- Where the next read of each resource starts. `modified_since` is the
 -- keyset: the next read asks Xero for records changed since then, oldest
 -- change first. `page` moves on only when one second holds a full page.
-CREATE TABLE "xero_mirror_cursors" (
+CREATE TABLE IF NOT EXISTS "xero_mirror_cursors" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"resource" text NOT NULL,
 	"modified_since" timestamp with time zone,

package/server/integrations/xero/migrations/0005_xero_send_modes.sql

@@ -2,9 +2,15 @@
 -- sent approved, whether Xero emailed it to the customer. Xero's email action
 -- is not idempotent, so Flow records `sending` before the call and retries
 -- only a refusal (`failed`), never an unknown outcome.
-ALTER TABLE "xero_invoice_pushes" ADD COLUMN "send_mode" text DEFAULT 'accounting_draft' NOT NULL;--> statement-breakpoint
-ALTER TABLE "xero_invoice_pushes" ADD COLUMN "email_state" text;--> statement-breakpoint
-ALTER TABLE "xero_invoice_pushes" ADD COLUMN "email_error" text;--> statement-breakpoint
-ALTER TABLE "xero_invoice_pushes" ADD COLUMN "emailed_at" timestamp with time zone;--> statement-breakpoint
-ALTER TABLE "xero_invoice_pushes" ADD CONSTRAINT "xero_invoice_pushes_send_mode_valid" CHECK ("send_mode" in ('accounting_draft', 'approve_and_email'));--> statement-breakpoint
-ALTER TABLE "xero_invoice_pushes" ADD CONSTRAINT "xero_invoice_pushes_email_state_valid" CHECK ("email_state" is null or "email_state" in ('pending', 'sending', 'sent', 'failed', 'unknown'));
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "send_mode" text DEFAULT 'accounting_draft' NOT NULL;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "email_state" text;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "email_error" text;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "emailed_at" timestamp with time zone;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "xero_invoice_pushes" ADD CONSTRAINT "xero_invoice_pushes_send_mode_valid" CHECK ("send_mode" in ('accounting_draft', 'approve_and_email'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "xero_invoice_pushes" ADD CONSTRAINT "xero_invoice_pushes_email_state_valid" CHECK ("email_state" is null or "email_state" in ('pending', 'sending', 'sent', 'failed', 'unknown'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;

package/server/ui/app-page.js

@@ -34,14 +34,16 @@ const BODY = `<div class="fx-app">
     <div class="fx-card fx-message__card fx-state-no-access" id="no-access"></div>
   </section>
 
-  <div class="fx-state-signed-in fx-shell">
+  <div class="fx-state-signed-in fx-shell" id="shell">
     <aside class="fx-side">
-      <a class="fx-brand" href="/">${FLOW_MARK}<span>Flow</span></a>
+      <div class="fx-side__head">
+        <a class="fx-brand" href="/">${FLOW_MARK}<span>Flow</span></a>
+        <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon" id="menu-toggle" aria-controls="nav" aria-label="Menu"></button>
+      </div>
       <nav class="fx-nav" id="nav" aria-label="Flow"></nav>
       <div class="fx-side__end">
         <div id="user-button" class="fx-side__user"></div>
-        <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon" id="report-problem" title="Report a problem" aria-label="Report a problem" hidden></button>
-        <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon fx-mode-toggle" data-mode-toggle>Light or dark</button>
+        <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon" id="search" title="Search (Ctrl+K)" aria-label="Search" aria-keyshortcuts="Control+K Meta+K"></button>
       </div>
     </aside>
     <main id="main" class="fx-main" tabindex="-1"></main>

package/server/ui/app.js

@@ -14,6 +14,7 @@ import { automationSection } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
 import { renderJobs } from '/assets/ui/jobs.js';
 import { startMonitoring } from '/assets/ui/monitoring.js';
+import { openSearch } from '/assets/ui/search.js';
 
 const $ = (id) => document.getElementById(id);
 
@@ -208,6 +209,8 @@ const ICON_PATHS = {
   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"/>',
   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"/>',
 };
 
@@ -217,6 +220,87 @@ 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.
+const NARROW = window.matchMedia('(max-width: 820px)');
+const FOLDED_KEY = 'flow_sidebar_folded';
+
+function readFolded() {
+  try { return localStorage.getItem(FOLDED_KEY) === '1'; } catch { return false; }
+}
+
+function drawMenu() {
+  const shell = $('shell');
+  const folded = readFolded();
+  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');
+  toggle.setAttribute('aria-expanded', String(open));
+  toggle.setAttribute('aria-label', label);
+  toggle.title = label;
+  // Folded, a page's name shows when the pointer rests on its icon.
+  for (const link of document.querySelectorAll('[data-nav]')) {
+    if (folded && !NARROW.matches) link.title = link.dataset.label;
+    else link.removeAttribute('title');
+  }
+}
+
+function closeMenu() {
+  if (!$('shell').hasAttribute('data-menu-open')) return;
+  $('shell').removeAttribute('data-menu-open');
+  drawMenu();
+}
+
+function toggleMenu() {
+  if (NARROW.matches) {
+    $('shell').toggleAttribute('data-menu-open');
+  } else {
+    try { localStorage.setItem(FOLDED_KEY, readFolded() ? '0' : '1'); } catch { /* the choice is only a convenience */ }
+  }
+  drawMenu();
+}
+
+NARROW.addEventListener('change', () => { $('shell').removeAttribute('data-menu-open'); drawMenu(); });
+document.addEventListener('keydown', (event) => {
+  if (event.key === 'Escape' && $('shell')?.hasAttribute('data-menu-open')) {
+    closeMenu();
+    $('menu-toggle').focus();
+  }
+});
+document.addEventListener('click', (event) => {
+  if (!event.target.closest?.('.fx-side') || event.target.closest?.('[data-nav]')) closeMenu();
+});
+
+// Search, from the sidebar foot or Ctrl+K (⌘K): the pages this person may
+// open, invoices and jobs (search.js).
+function search() {
+  const views = Object.entries(VIEWS)
+    .filter(([, view]) => !view.ownerOnly || me?.person.role === 'owner')
+    .map(([name, view]) => ({ name, label: view.label, icon: view.icon }));
+  openSearch({ h, flow, go, icon, views });
+}
+
+document.addEventListener('keydown', (event) => {
+  if (event.key.toLowerCase() !== 'k' || !(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey) return;
+  if (document.body.dataset.state !== 'signed-in') return;
+  event.preventDefault();
+  search();
+});
+
+// "Report a problem" in Clerk's account menu, between "Manage account" and
+// "Sign out". Clerk mounts and unmounts the icon itself.
+function reportMenuItem(openReport) {
+  return {
+    label: 'Report a problem',
+    onClick: () => { openReport().catch((error) => toast(error.message, 'danger')); },
+    mountIcon: (element) => element.replaceChildren(icon('flag')),
+    unmountIcon: (element) => element.replaceChildren(),
+  };
+}
+
 // The view and, for one record, its id: /invoices/<id> is ['invoices', '<id>'].
 function currentView() {
   const [name, id = null] = location.pathname.replace(/^\/+|\/+$/g, '').split('/');
@@ -230,7 +314,7 @@ async function route() {
   const [view, id] = currentView();
   const path = id ? `/${view}/${id}` : `/${view}`;
   if (location.pathname !== path) history.replaceState(null, '', path);
-  for (const link of document.querySelectorAll('[data-nav]')) {
+  for (const link of document.querySelectorAll('a[data-nav]')) {
     link.setAttribute('aria-current', link.dataset.nav === view ? 'page' : 'false');
   }
   main.replaceChildren();
@@ -242,7 +326,7 @@ async function route() {
 
 // Opens a path in place; the address changes, the page stays.
 function go(path, { replace = false } = {}) {
-  if (path !== location.pathname) history[replace ? 'replaceState' : 'pushState'](null, '', path);
+  if (path !== location.pathname + location.search) history[replace ? 'replaceState' : 'pushState'](null, '', path);
   route();
 }
 
@@ -286,14 +370,33 @@ function renderShell() {
     if (view.ownerOnly && me?.person.role !== 'owner') 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, onclick: navigate }, icon(view.icon), h('span', {}, view.label)));
+    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)));
   }
-  nav.replaceChildren(...items);
-  mountClerk('userButton', $('user-button'), { afterSignOutUrl: '/sign-in', showName: false });
+  // "Report a problem" sits at the foot of the menu, above the account chip,
+  // while Sentry and its report form are on (monitoring.js).
+  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'));
+  $('menu-toggle').onclick = toggleMenu;
+  drawMenu();
+  // The sidebar foot shows who is signed in: photo or initial, then the name
+  // (the email when the account has no name). It opens the account menu.
+  const userButton = { afterSignOutUrl: '/sign-in', showName: true };
+  $('search').replaceChildren(icon('search'));
+  $('search').onclick = search;
+  mountClerk('userButton', $('user-button'), userButton);
   // Errors and problem reports go to the installation's own Sentry, when the
-  // Sentry integration is on (monitoring.js). Flow works the same without it.
-  $('report-problem').replaceChildren(icon('flag'));
-  startMonitoring({ flow, person: me.person, button: $('report-problem') })
+  // Sentry integration is on (monitoring.js). Then "Report a problem" shows
+  // in the menu and in the account menu. Flow works the same without it.
+  startMonitoring({ flow, person: me.person })
+    .then((openReport) => {
+      if (!openReport) return;
+      report.hidden = false;
+      report.onclick = () => { openReport().catch((error) => toast(error.message, 'danger')); };
+      unmountClerk($('user-button'));
+      mountClerk('userButton', $('user-button'), { ...userButton, customMenuItems: [reportMenuItem(openReport)] });
+    })
     .catch((error) => console.warn(`[monitoring] ${error.message}`));
   window.addEventListener('popstate', route);
   return route();