@arcforgelabs/flow 2026.10.27 → 2026.10.30

package/server/db/migrations/meta/_journal.json

@@ -92,6 +92,13 @@
       "when": 1792414436676,
       "tag": "0012_invoice_sending",
       "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1792414148360,
+      "tag": "0013_line_mappings",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -59,6 +59,9 @@ export const priceItems = pgTable('price_items', {
   organisationId: organisationId().references(() => organisations.id),
   code: text('code').notNull(),
   name: text('name').notNull(),
+  // The accounting system's longer text for the item, when it has one. Line
+  // mapping (server/core/line-mapping.js) compares a work line with it too.
+  description: text('description'),
   unitAmountCents: integer('unit_amount_cents').notNull(),
   taxCode: text('tax_code').notNull().default('GST'),
   archivedAt: timestamp('archived_at', { withTimezone: true }),
@@ -120,6 +123,9 @@ export const invoiceLines = pgTable('invoice_lines', {
   quantity: integer('quantity').notNull(),
   unitAmountCents: integer('unit_amount_cents').notNull(),
   taxCode: text('tax_code').notNull(),
+  // A line with no price item may name the accounting account it books to,
+  // for example a surcharge (server/core/line-mapping.js).
+  accountCode: text('account_code'),
   lineAmountCents: integer('line_amount_cents').notNull(),
   taxCents: integer('tax_cents').notNull(),
 }, (t) => [
@@ -674,3 +680,40 @@ export const automations = pgTable('automations', {
 }, (t) => [
   primaryKey({ name: 'automations_pk', columns: [t.organisationId, t.key] }),
 ]);
+
+// Line mappings (docs/LINE_MAPPING.md): how a work system's line label finds
+// the lab's price item, as rows the lab edits. `kind` says which step of the
+// line mapping routine uses the row:
+//   alias        label (exact, or the start of it) -> price item code
+//   price_alias  label and unit price -> price item code
+//   saved        label and unit price -> price item code, chosen by a person
+//   account      label -> a line with no price item, booked to an account
+// `label` is stored in the lookup form (lineLookupText), so it matches in any
+// case, spacing or punctuation.
+export const LINE_MAPPING_KINDS = ['alias', 'price_alias', 'saved', 'account'];
+export const lineMappings = pgTable('line_mappings', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  kind: text('kind').notNull(),
+  match: text('match').notNull().default('exact'),
+  label: text('label').notNull(),
+  unitAmountCents: integer('unit_amount_cents'),
+  itemCode: text('item_code'),
+  accountCode: text('account_code'),
+  taxCode: text('tax_code'),
+  description: text('description'),
+  enabled: boolean('enabled').notNull().default(true),
+  // Who made it: a person, a setup profile, or the earlier codebase's rules.
+  origin: text('origin').notNull().default('person'),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  uniqueIndex('line_mappings_unique').on(t.organisationId, t.kind, t.match, t.label, sql`coalesce(${t.unitAmountCents}, -1)`),
+  check('line_mappings_kind_valid', sql`${t.kind} in ('alias', 'price_alias', 'saved', 'account')`),
+  check('line_mappings_match_valid', sql`${t.match} in ('exact', 'starts_with')`),
+  check('line_mappings_tax_code_valid', sql`${t.taxCode} is null or ${t.taxCode} in ('GST', 'GST_FREE')`),
+  check('line_mappings_target', sql`(${t.kind} = 'account' and ${t.accountCode} is not null) or (${t.kind} <> 'account' and ${t.itemCode} is not null)`),
+  check('line_mappings_price', sql`${t.kind} not in ('price_alias', 'saved') or ${t.unitAmountCents} is not null`),
+  check('line_mappings_label_valid', sql`length(${t.label}) between 1 and 200`),
+]);

package/server/import/at-start.js

@@ -1,5 +1,6 @@
-import { sql } from 'drizzle-orm';
-import { organisations, priorLinks } from '../db/schema.js';
+import { and, eq, isNull, sql } from 'drizzle-orm';
+import { lineMappings, organisations, priceItems, priorLinks } from '../db/schema.js';
+import { lineLookupText, remapJobs } from '../core/line-mapping.js';
 import { applyImport, planImport, readEarlierFlow, summarisePlan } from './earlier-flow.js';
 
 // The import from the earlier codebase, run once by the server itself. On a
@@ -118,3 +119,64 @@ export async function importEarlierLinksAtStart({ db, pool, settings, log = cons
   log.info?.(`[import] links from schema "${settings.schema}": ${JSON.stringify(counts)}`);
   return counts;
 }
+
+// Carries the earlier app's line mapping knowledge into Flow, at every start
+// while the import settings are set, in the same read-only way:
+// - each label and price a person matched to an item becomes a "saved" line
+//   mapping (server/core/line-mapping.js), unless the lab already has one;
+// - each price item with no description takes the accounting item's own.
+// Answers counts, or null when there is nothing to read.
+const EARLIER_RULES = 'xero_item_match_rules';
+const EARLIER_ITEMS = 'xero_catalog_items';
+
+export async function importEarlierMappingsAtStart({ db, pool, settings, log = console }) {
+  if (!settings) return null;
+  const { rows: labs } = await db.execute(sql`select id, name from ${organisations}`);
+  const organisation = labs.find((lab) => lab.name === settings.organisationName) ?? (labs.length === 1 ? labs[0] : null);
+  if (!organisation) return null;
+
+  let rules = [];
+  let items = [];
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN TRANSACTION READ ONLY');
+    await client.query(`SET LOCAL search_path TO "${settings.schema}"`);
+    const present = async (table) => (await client.query('select to_regclass($1) is not null as present', [table])).rows[0].present;
+    if (await present(EARLIER_RULES)) {
+      ({ rows: rules } = await client.query(`select source_lookup_text, unit_amount_cents, xero_item_code from ${EARLIER_RULES}`));
+    }
+    if (await present(EARLIER_ITEMS)) {
+      ({ rows: items } = await client.query(`select item_code, description from ${EARLIER_ITEMS} where coalesce(description, '') <> ''`));
+    }
+    await client.query('COMMIT');
+  } catch (error) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw new Error(`could not read mappings from schema "${settings.schema}": ${error.message}`);
+  } finally {
+    client.release();
+  }
+
+  const values = rules
+    .map((row) => ({
+      organisationId: organisation.id,
+      kind: 'saved',
+      match: 'exact',
+      label: lineLookupText(row.source_lookup_text),
+      unitAmountCents: Number(row.unit_amount_cents),
+      itemCode: String(row.xero_item_code ?? '').trim(),
+      origin: `earlier:${EARLIER_RULES}`,
+    }))
+    .filter((v) => v.label && v.label.length <= 200 && v.itemCode && Number.isInteger(v.unitAmountCents) && v.unitAmountCents >= 0);
+  const added = values.length ? (await db.insert(lineMappings).values(values).onConflictDoNothing().returning({ id: lineMappings.id })).length : 0;
+  let described = 0;
+  for (const item of items) {
+    const updated = await db.update(priceItems).set({ description: String(item.description).trim().slice(0, 1000) })
+      .where(and(eq(priceItems.organisationId, organisation.id), eq(priceItems.code, String(item.item_code).trim()), isNull(priceItems.description)))
+      .returning({ id: priceItems.id });
+    described += updated.length;
+  }
+  if (added) await remapJobs(db, organisation.id);
+  const counts = { rules: values.length, added, described };
+  log.info?.(`[import] mappings from schema "${settings.schema}": ${JSON.stringify(counts)}`);
+  return counts;
+}

package/server/index.js

@@ -5,7 +5,9 @@ import { seedFirstOwner } from './auth/people.js';
 import { createPersonAuth } from './auth/session.js';
 import { resolveSignInSettings } from './auth/settings.js';
 import { migrateDatabase, openDatabase } from './db/index.js';
-import { importEarlierAtStart, importEarlierLinksAtStart, resolveImportAtStart } from './import/at-start.js';
+import {
+  importEarlierAtStart, importEarlierLinksAtStart, importEarlierMappingsAtStart, resolveImportAtStart,
+} from './import/at-start.js';
 import { createMonitoredLog } from './core/monitoring.js';
 import { createPipelineWorker } from './core/pipeline.js';
 import { createSendWorker } from './core/sending.js';
@@ -66,6 +68,8 @@ try {
 // failure is logged and the start goes on.
 await importEarlierLinksAtStart({ db: database.db, pool: database.pool, settings: importAtStart })
   .catch((error) => console.error(`[import] ${error.message}`));
+await importEarlierMappingsAtStart({ db: database.db, pool: database.pool, settings: importAtStart })
+  .catch((error) => console.error(`[import] ${error.message}`));
 // What an owner set in Settings, Integrations, with the host's own
 // environment over it (server/integrations/setup.js).
 // Every part of Flow logs here: each error also goes to the installation's

package/server/integrations/port.js

@@ -18,6 +18,7 @@ export const CAPABILITIES = Object.freeze([
   'pushBill', // send an approved bill; the Flow record id is the idempotency key
   'pullPayments', // payments since a cursor, matched to invoices and bills
   'checkInvoice', // does the accounting system hold an invoice for a billable job? (the ledger's liveCheck)
+  'listWork', // the work system's jobs from its copy in Flow, open and lately finished, for the Jobs board
   'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
   'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
   'health', // connection state for Settings
@@ -233,7 +234,9 @@ export function createRegistry({ log = console, env = process.env } = {}) {
           tablesReady.add(id);
         }
         if (adapter.start) {
-          await adapter.start({ db: database, log, env: settingsEnv });
+          // A person changed the settings: an adapter may clear a stop that
+          // waits for a person (issue #101).
+          await adapter.start({ db: database, log, env: settingsEnv, reconfigured: true });
           running.push(adapter);
         }
       } catch (error) {

package/server/integrations/seazona/client.js

@@ -17,6 +17,8 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, m
 // A failed Seazona request. The message names the method, the path and the
 // status or failure kind; never the host, the query or a credential.
 // kind: http, timeout, network, invalid_json, replay_miss, governor_timeout.
+// The governor's own SeazonaCallsStopped (kind calls_stopped) passes through
+// unchanged: no call was made.
 export class SeazonaApiError extends Error {
   constructor(message, { statusCode = null, kind = 'http', path = null, retryAfterMs = null } = {}) {
     super(message);
@@ -93,6 +95,10 @@ export function createSeazonaClient({
       requestsPerMinute: rate.requestsPerMinute,
       maxWaitMs: rate.maxWaitMs,
       telemetryRetentionMs: rate.telemetryRetentionMs,
+      circuitFailures: rate.circuitFailures,
+      circuitWindowMs: rate.circuitWindowMs,
+      circuitPauseMs: rate.circuitPauseMs,
+      dailyFailureBudget: rate.dailyFailureBudget,
       now,
       sleepFn,
     });

package/server/integrations/seazona/feed.js

@@ -1,6 +1,6 @@
-import { eq, sql } from 'drizzle-orm';
+import { and, desc, eq, gte, isNull, or, sql } from 'drizzle-orm';
 import { ledgerLinesFor, toLedgerHold, toLedgerJob } from './ledger.js';
-import { orderStatusLabel, parseSeazonaDate } from './map.js';
+import { isFinalStatus, orderStatusLabel, parseSeazonaDate } from './map.js';
 import { seazonaClients, seazonaInvoices, seazonaOrders } from './schema.js';
 
 // The billing feed behind the port's pullWorkItems: every order that changed
@@ -104,12 +104,70 @@ export async function readBillableWork(db, { cursor = null, limit = 200 } = {})
 }
 
 // Seazona clients, by id and the company name an invoice bills. A client
-// with no company name is listed by its full name.
+// with no company name is listed by its full name. A client the client list
+// never gave (the list can be closed to an API client) is listed by the
+// company name its orders carry, so its jobs still find their customer.
 export async function listClients(db) {
   const rows = await db.select({ id: seazonaClients.id, company: seazonaClients.company, fullName: seazonaClients.fullName, active: seazonaClients.active })
     .from(seazonaClients);
-  return rows
+  const listed = rows
     .filter((r) => r.active !== false)
     .map((r) => ({ id: r.id, name: (r.company || r.fullName || '').trim() }))
     .filter((r) => r.name);
+  const known = new Set(rows.map((r) => r.id));
+  const fromOrders = await db.selectDistinctOn([seazonaOrders.clientId], { id: seazonaOrders.clientId, company: seazonaOrders.company })
+    .from(seazonaOrders)
+    .where(sql`${seazonaOrders.clientId} is not null and coalesce(${seazonaOrders.company}, '') <> '' and ${seazonaOrders.deletedInSourceAt} is null`)
+    .orderBy(seazonaOrders.clientId, sql`${seazonaOrders.lastChangedAt} desc`);
+  return [
+    ...listed,
+    ...fromOrders.filter((r) => !known.has(r.id)).map((r) => ({ id: r.id, name: r.company.trim() })),
+  ];
+}
+
+// A final order (shipped, delivered, cancelled; map.js isFinalStatus) stays on
+// the Jobs board this long after it last changed.
+export const WORK_FINISHED_DAYS = 30;
+const WORK_LIMIT = 2000;
+const FINAL_SQL = sql`coalesce(${seazonaOrders.status}, '') ~* '(shipped|delivered|cancelled|canceled|void|closed|archived|deleted)'`;
+
+// The orders behind the port's listWork, for the Jobs board: every open
+// order, and each final order that changed in the last WORK_FINISHED_DAYS
+// days, newest change first. An order deleted in Seazona is never listed.
+// The client name is the Seazona client's company (or full name), else the
+// order's own company. `statuses` lists each status once, with the first time
+// Flow saw an order in it, so the board can order its columns.
+export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINISHED_DAYS, limit = WORK_LIMIT } = {}) {
+  const since = new Date(now - finishedDays * 86_400_000);
+  const rows = await db.select({ order: seazonaOrders, company: seazonaClients.company, fullName: seazonaClients.fullName })
+    .from(seazonaOrders)
+    .leftJoin(seazonaClients, eq(seazonaClients.id, seazonaOrders.clientId))
+    .where(and(isNull(seazonaOrders.deletedInSourceAt), or(sql`not (${FINAL_SQL})`, gte(seazonaOrders.lastChangedAt, since))))
+    .orderBy(desc(seazonaOrders.lastChangedAt), seazonaOrders.id)
+    .limit(limit);
+  const firstSeen = new Map();
+  const items = rows.map(({ order, company, fullName }) => {
+    const status = orderStatusLabel(order) || null;
+    const seen = firstSeen.get(status);
+    if (status && (!seen || order.firstSeenAt < seen)) firstSeen.set(status, order.firstSeenAt);
+    return {
+      sourceSystem: 'seazona',
+      sourceJobRef: order.id,
+      // The Seazona order id is the case number. Never patient data.
+      caseRef: order.id,
+      status,
+      clientId: order.clientId,
+      clientName: (company || order.company || fullName || '').trim() || null,
+      practitioner: order.doctorName,
+      department: order.department,
+      orderedOn: parseSeazonaDate(order.orderedText),
+      dueOn: parseSeazonaDate(order.dueText),
+      lines: (order.lines ?? []).map((l) => ({ code: l.code ?? null, description: l.description, amountCents: l.amountCents ?? null })),
+      totalCents: order.subtotalCents,
+    };
+  });
+  return {
+    items,
+    statuses: [...firstSeen].map(([label, at]) => ({ label, final: isFinalStatus(label), firstSeenAt: at.toISOString() })),
+  };
 }

package/server/integrations/seazona/governor.js

@@ -10,9 +10,39 @@ import { MAX_REQUESTS_PER_MINUTE } from './settings.js';
 // admitted in the last minute, the minimum gap since the last admission has
 // passed, and no 429 cooldown is running. Admission takes a transaction-level
 // advisory lock per client, so two processes never admit the same slot.
+//
+// Issue #101: a vendor can cut off API access after many failed calls, even
+// inside the rate limit. So the governor also stops calls outright:
+//   - a 401 or 403 halts every call until a person acts (the adapter restarts
+//     with new or saved settings, which calls resume());
+//   - `circuitFailures` failed calls inside `circuitWindowMs` open the circuit:
+//     no call for `circuitPauseMs`, then one probe call; a failed probe opens
+//     it again for twice as long, to at most 6 hours, and a success closes it;
+//   - `dailyFailureBudget` failed calls in one UTC day stop calls until the
+//     next day.
+// A stopped call fails at once with SeazonaCallsStopped; it never waits.
 
 const WINDOW_MS = 60_000;
 const MAX_COOLDOWN_MS = 60_000;
+const MAX_CIRCUIT_PAUSE_MS = 6 * 60 * 60_000;
+const DAY_MS = 24 * 60 * 60_000;
+const EPOCH = new Date(0);
+
+// A call that failed in a way the vendor sees as a fault: no answer, a 5xx, a
+// 429, or a 4xx other than 404 (a 404 on one record means it was deleted).
+export function countsAsFailure({ statusCode = null, failureKind = null } = {}) {
+  if (failureKind) return true;
+  if (!Number.isInteger(statusCode)) return false;
+  return statusCode >= 500 || (statusCode >= 400 && statusCode !== 404);
+}
+
+const failedCall = sql`(${seazonaApiRequests.failureKind} is not null or ${seazonaApiRequests.statusCode} >= 500
+  or (${seazonaApiRequests.statusCode} >= 400 and ${seazonaApiRequests.statusCode} <> 404))`;
+
+const startOfUtcDay = (ms) => {
+  const date = new Date(ms);
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+};
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 
@@ -36,12 +66,34 @@ export class SeazonaGovernorTimeout extends Error {
   }
 }
 
+// Calls are stopped: halted for a person, circuit open, or the day's failed
+// calls are spent. `retryAfterMs` is null for a halt, which no wait clears.
+export class SeazonaCallsStopped extends Error {
+  constructor(reason, retryAfterMs = null) {
+    const what = {
+      halted: 'Seazona calls are stopped until a person checks the API client (it was refused)',
+      circuit_open: 'Seazona calls are paused after repeated failures',
+      budget_spent: "Seazona calls are stopped for today: the day's failed calls are spent",
+    }[reason];
+    super(what);
+    this.name = 'SeazonaCallsStopped';
+    this.code = { halted: 'seazona_api_halted', circuit_open: 'seazona_api_circuit_open', budget_spent: 'seazona_api_failure_budget_spent' }[reason];
+    this.kind = 'calls_stopped';
+    this.reason = reason;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
 export function createSeazonaGovernor({
   db,
   clientKey,
   requestsPerMinute = MAX_REQUESTS_PER_MINUTE,
   maxWaitMs = 120_000,
   telemetryRetentionMs = 35 * 24 * 60 * 60_000,
+  circuitFailures = 5,
+  circuitWindowMs = 10 * 60_000,
+  circuitPauseMs = 5 * 60_000,
+  dailyFailureBudget = 50,
   now = Date.now,
   sleepFn = sleep,
 } = {}) {
@@ -59,6 +111,8 @@ export function createSeazonaGovernor({
       const nowAt = new Date(nowMs);
       await tx.insert(seazonaApiGovernor).values({ clientKey: key }).onConflictDoNothing();
       const [state] = await tx.select().from(seazonaApiGovernor).where(eq(seazonaApiGovernor.clientKey, key));
+      const stopped = await stoppedReason(tx, state, nowMs);
+      if (stopped) return { admitted: false, stopped };
       const windowStart = new Date(nowMs - WINDOW_MS);
       const [{ admitted, oldestMs }] = await tx
         .select({ admitted: count(), oldestMs: sql`(extract(epoch from min(${seazonaApiRequests.admittedAt})) * 1000)::float8` })
@@ -84,12 +138,31 @@ export function createSeazonaGovernor({
     });
   }
 
+  async function failuresSince(tx, fromMs) {
+    const [{ failed }] = await tx.select({ failed: count() }).from(seazonaApiRequests)
+      .where(and(eq(seazonaApiRequests.clientKey, key), gte(seazonaApiRequests.admittedAt, new Date(fromMs)), failedCall));
+    return Number(failed);
+  }
+
+  // Why no call may go now, or null.
+  async function stoppedReason(tx, state, nowMs) {
+    if (state.haltedReason) return { reason: 'halted', retryAfterMs: null };
+    const openUntil = state.circuitOpenUntil.getTime();
+    if (openUntil > nowMs) return { reason: 'circuit_open', retryAfterMs: openUntil - nowMs };
+    const dayStart = startOfUtcDay(nowMs);
+    if (await failuresSince(tx, dayStart) >= dailyFailureBudget) {
+      return { reason: 'budget_spent', retryAfterMs: dayStart + DAY_MS - nowMs };
+    }
+    return null;
+  }
+
   // Waits for a slot and records the admission. Returns { requestId }.
   async function reserve({ workflow = 'seazona', isRetry = false } = {}) {
     let waitedMs = 0;
     for (;;) {
       const decision = await tryAdmit(workflow, isRetry);
       if (decision.admitted) return { requestId: decision.requestId, waitedMs };
+      if (decision.stopped) throw new SeazonaCallsStopped(decision.stopped.reason, decision.stopped.retryAfterMs);
       const delay = Math.max(1, Math.min(decision.waitMs, maxWaitMs));
       if (waitedMs + delay > maxWaitMs) throw new SeazonaGovernorTimeout(waitedMs, delay);
       waitedMs += delay;
@@ -97,25 +170,67 @@ export function createSeazonaGovernor({
     }
   }
 
-  // Records how a request ended, and any cooldown a 429 asked for.
+  // Records how a request ended, any cooldown a 429 asked for, and what the
+  // ending does to the circuit. Answers { halted, opened } when this response
+  // stopped calls, so the caller can report it once.
   async function recordResponse({ requestId, path = null, statusCode = null, failureKind = null, durationMs = null, retryAfterMs = null } = {}) {
     const nowMs = Number(now());
-    await db.update(seazonaApiRequests).set({
-      requestPath: normaliseRequestPath(path),
-      statusCode: Number.isInteger(statusCode) ? statusCode : null,
-      failureKind: failureKind ? String(failureKind).slice(0, 40) : null,
-      durationMs: Number.isFinite(durationMs) ? Math.max(0, Math.round(durationMs)) : null,
-    }).where(and(eq(seazonaApiRequests.id, requestId), eq(seazonaApiRequests.clientKey, key)));
-    if (Number.isFinite(retryAfterMs) && retryAfterMs > 0) {
-      const until = new Date(nowMs + Math.min(retryAfterMs, MAX_COOLDOWN_MS));
-      await db.update(seazonaApiGovernor)
-        .set({ cooldownUntil: sql`greatest(${seazonaApiGovernor.cooldownUntil}, ${until})`, updatedAt: new Date(nowMs) })
+    const nowAt = new Date(nowMs);
+    const outcome = await db.transaction(async (tx) => {
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${lockKey}))`);
+      await tx.update(seazonaApiRequests).set({
+        requestPath: normaliseRequestPath(path),
+        statusCode: Number.isInteger(statusCode) ? statusCode : null,
+        failureKind: failureKind ? String(failureKind).slice(0, 40) : null,
+        durationMs: Number.isFinite(durationMs) ? Math.max(0, Math.round(durationMs)) : null,
+      }).where(and(eq(seazonaApiRequests.id, requestId), eq(seazonaApiRequests.clientKey, key)));
+      if (Number.isFinite(retryAfterMs) && retryAfterMs > 0) {
+        const until = new Date(nowMs + Math.min(retryAfterMs, MAX_COOLDOWN_MS));
+        await tx.update(seazonaApiGovernor)
+          .set({ cooldownUntil: sql`greatest(${seazonaApiGovernor.cooldownUntil}, ${until})`, updatedAt: nowAt })
+          .where(eq(seazonaApiGovernor.clientKey, key));
+      }
+      const [state] = await tx.select().from(seazonaApiGovernor).where(eq(seazonaApiGovernor.clientKey, key));
+      if (!state) return {};
+      if (!countsAsFailure({ statusCode, failureKind })) {
+        if (state.circuitOpens > 0) {
+          await tx.update(seazonaApiGovernor).set({ circuitOpens: 0, updatedAt: nowAt }).where(eq(seazonaApiGovernor.clientKey, key));
+        }
+        return {};
+      }
+      if (statusCode === 401 || statusCode === 403) {
+        if (state.haltedReason) return {};
+        await tx.update(seazonaApiGovernor).set({ haltedReason: 'auth', haltedAt: nowAt, updatedAt: nowAt })
+          .where(eq(seazonaApiGovernor.clientKey, key));
+        return { halted: 'auth' };
+      }
+      const openUntil = state.circuitOpenUntil.getTime();
+      // After a pause the next call is a probe: if it fails, open again at once.
+      const probeFailed = state.circuitOpens > 0 && openUntil <= nowMs;
+      const counted = probeFailed ? 0 : await failuresSince(tx, Math.max(nowMs - circuitWindowMs, openUntil));
+      if (!probeFailed && counted < circuitFailures) return {};
+      if (!probeFailed && openUntil > nowMs) return {};
+      const pauseMs = Math.min(MAX_CIRCUIT_PAUSE_MS, circuitPauseMs * 2 ** Math.min(state.circuitOpens, 10));
+      const until = new Date(nowMs + pauseMs);
+      await tx.update(seazonaApiGovernor)
+        .set({ circuitOpenUntil: until, circuitOpens: state.circuitOpens + 1, updatedAt: nowAt })
         .where(eq(seazonaApiGovernor.clientKey, key));
-    }
+      return { opened: { until: until.toISOString(), pauseMs, opens: state.circuitOpens + 1 } };
+    });
     await db.delete(seazonaApiRequests).where(and(
       eq(seazonaApiRequests.clientKey, key),
       lt(seazonaApiRequests.admittedAt, new Date(nowMs - telemetryRetentionMs)),
     ));
+    return outcome;
+  }
+
+  // A person acted (new or saved settings, or the adapter turned on again):
+  // clear a halt and close the circuit. The day's failure budget stays.
+  async function resume() {
+    await db.insert(seazonaApiGovernor).values({ clientKey: key }).onConflictDoNothing();
+    await db.update(seazonaApiGovernor)
+      .set({ haltedReason: null, haltedAt: null, circuitOpenUntil: EPOCH, circuitOpens: 0, updatedAt: new Date(Number(now())) })
+      .where(eq(seazonaApiGovernor.clientKey, key));
   }
 
   // Counts for /health: the last minute, and the last day by status.
@@ -126,11 +241,21 @@ export function createSeazonaGovernor({
       .where(and(eq(seazonaApiRequests.clientKey, key), gte(seazonaApiRequests.admittedAt, new Date(nowMs - WINDOW_MS))));
     const day = await summarise({ from: new Date(nowMs - 24 * 60 * 60_000), to: new Date(nowMs) });
     const cooldownUntil = state && state.cooldownUntil.getTime() > nowMs ? state.cooldownUntil.toISOString() : null;
+    const openUntil = state?.circuitOpenUntil?.getTime() ?? 0;
+    const circuit = state?.haltedReason ? 'halted'
+      : openUntil > nowMs ? 'open'
+        : state?.circuitOpens > 0 ? 'half_open' : 'closed';
     return {
       limitPerMinute: limit,
       minIntervalMs,
       lastMinute: Number(lastMinute),
       cooldownUntil,
+      circuit,
+      circuitOpenUntil: openUntil > nowMs ? state.circuitOpenUntil.toISOString() : null,
+      haltedReason: state?.haltedReason ?? null,
+      haltedAt: state?.haltedAt?.toISOString() ?? null,
+      failedToday: await failuresSince(db, startOfUtcDay(nowMs)),
+      dailyFailureBudget,
       lastDay: { requests: day.requests, failed: day.failed, rateLimited: day.rateLimited, retries: day.retries },
     };
   }
@@ -170,5 +295,5 @@ export function createSeazonaGovernor({
     };
   }
 
-  return { clientKey: key, limitPerMinute: limit, minIntervalMs, reserve, recordResponse, status, summarise };
+  return { clientKey: key, limitPerMinute: limit, minIntervalMs, reserve, recordResponse, resume, status, summarise };
 }

package/server/integrations/seazona/index.js

@@ -1,7 +1,8 @@
 import { createSeazonaClient } from './client.js';
-import { listClients, readBillableWork } from './feed.js';
+import { listClients, listWork, readBillableWork } from './feed.js';
 import { readSeazonaSyncHealth, runSeazonaSync } from './lanes.js';
 import { createSeazonaScheduler } from './scheduler.js';
+import { resetFailedLanes, resetStoppedLanes } from './store.js';
 import { describeSeazonaSettings, resolveSeazonaSettings } from './settings.js';
 import { seazonaSchema } from './tables.js';
 
@@ -58,9 +59,21 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
     schema: seazonaSchema,
     setup: SEAZONA_SETUP,
 
-    async start({ db, log = console, env: settingsEnv }) {
+    // `reconfigured` is true when a person saved the settings or turned
+    // Seazona on (issue #101): that clears a halt after a refused API client,
+    // closes the circuit, and runs every failed lane again. A plain start (a
+    // restart or a new release) runs again only the lanes stopped by a
+    // refused path; a halt still waits for a person.
+    async start({ db, log = console, env: settingsEnv, reconfigured = false }) {
       const settings = requireSeazonaSettings(env ?? settingsEnv ?? process.env);
       const client = createSeazonaClient({ settings, db, fetchImpl: fetchImpl ?? undefined, workflow: 'seazona-sync', now });
+      const at = new Date(Number(now()));
+      if (reconfigured) {
+        await client.governor?.resume();
+        await resetFailedLanes(db, { at });
+      } else {
+        await resetStoppedLanes(db, { at });
+      }
       const run = (options = {}) => runSeazonaSync(db, client, { settings, now, ...options });
       // The background sync starts in live mode only. A sandbox or replay
       // installation syncs only when someone asks (sync-once.js).
@@ -105,6 +118,12 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       async listCustomers() {
         return listClients(current().db);
       },
+
+      // Open orders and orders finished lately, with their statuses, for the
+      // Jobs board. Reads Flow's copy only.
+      async listWork() {
+        return listWork(current().db, { now: now() });
+      },
     },
   };
 }