@arcforgelabs/flow 2026.10.32 → 2026.10.34

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

@@ -120,6 +120,20 @@
       "when": 1792456270558,
       "tag": "0016_invoice_reference",
       "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1792458167234,
+      "tag": "0017_sync_basis",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1792472460808,
+      "tag": "0018_custom_fields",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -250,6 +250,9 @@ export const billingObligations = pgTable('billing_obligations', {
   holdReason: text('hold_reason'),
   // The Flow invoice made for this job.
   invoiceId: uuid('invoice_id'),
+  // The job facts the invoice was built from: the merge base for the
+  // three-way compare when the job changes later (server/core/ledger.js).
+  draftBasis: jsonb('draft_basis'),
   // What the accounting system reported, how it matched, and when Flow checked.
   accountingState: text('accounting_state').notNull().default('unknown'),
   accountingRef: text('accounting_ref'),
@@ -763,3 +766,62 @@ export const priceItemLinks = pgTable('price_item_links', {
   check('price_item_links_matched_by_valid', sql`${t.matchedBy} in ('code', 'person')`),
   check('price_item_links_system_valid', sql`${t.system} ~ '^[a-z][a-z0-9-]{1,31}$'`),
 ]);
+
+// Custom fields (server/core/custom-fields.js, docs/CUSTOM_FIELDS.md): fields
+// a lab makes for its jobs in Flow, in Settings, Custom fields. Only an owner
+// or admin makes or changes one. A dropdown's options are
+// [{ id, name, color }] in lane order; an option a person removes stays in
+// `options` with `archived: true`, so old values and history still read.
+// The type never changes after a field is made.
+export const CUSTOM_FIELD_TYPES = ['dropdown', 'person', 'checkbox', 'date', 'number', 'text'];
+export const jobFields = pgTable('job_fields', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  name: text('name').notNull(),
+  type: text('type').notNull(),
+  options: jsonb('options').notNull().default(sql`'[]'::jsonb`),
+  position: integer('position').notNull(),
+  archivedAt: timestamp('archived_at', { withTimezone: true }),
+  createdBy: uuid('created_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('job_fields_org_id').on(t.organisationId, t.id),
+  check('job_fields_type_valid', sql`${t.type} in ('dropdown', 'person', 'checkbox', 'date', 'number', 'text')`),
+  check('job_fields_name_valid', sql`length(${t.name}) between 1 and 60`),
+]);
+
+// A job's value for one custom field. A job is the work system's job
+// (source_system, source_job_ref), the same key the Jobs board uses, so a
+// value needs no Flow copy of the job. `value` is JSON: an option id, a person
+// id, true or false, a YYYY-MM-DD date, a number or text. No row means empty.
+export const jobFieldValues = pgTable('job_field_values', {
+  organisationId: organisationId().references(() => organisations.id),
+  fieldId: uuid('field_id').notNull(),
+  sourceSystem: text('source_system').notNull(),
+  sourceJobRef: text('source_job_ref').notNull(),
+  value: jsonb('value').notNull(),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedAt: updatedAt(),
+}, (t) => [
+  primaryKey({ columns: [t.organisationId, t.fieldId, t.sourceSystem, t.sourceJobRef] }),
+  foreignKey({ name: 'job_field_values_field_same_org', columns: [t.organisationId, t.fieldId], foreignColumns: [jobFields.organisationId, jobFields.id] }).onDelete('cascade'),
+  index('job_field_values_job').on(t.organisationId, t.sourceSystem, t.sourceJobRef),
+]);
+
+// Every change of a job's custom field value: who, when, from and to.
+export const jobFieldEvents = pgTable('job_field_events', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  fieldId: uuid('field_id').notNull(),
+  sourceSystem: text('source_system').notNull(),
+  sourceJobRef: text('source_job_ref').notNull(),
+  fromValue: jsonb('from_value'),
+  toValue: jsonb('to_value'),
+  actor: uuid('actor').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+}, (t) => [
+  foreignKey({ name: 'job_field_events_field_same_org', columns: [t.organisationId, t.fieldId], foreignColumns: [jobFields.organisationId, jobFields.id] }).onDelete('cascade'),
+  index('job_field_events_job').on(t.organisationId, t.sourceSystem, t.sourceJobRef, t.createdAt),
+]);

package/server/index.js

@@ -10,7 +10,9 @@ import {
   importEarlierAtStart, importEarlierLinksAtStart, importEarlierMappingsAtStart, resolveImportAtStart,
 } from './import/at-start.js';
 import { createMonitoredLog } from './core/monitoring.js';
+import { createTracing, traceQueries } from './core/tracing.js';
 import { createPipelineWorker } from './core/pipeline.js';
+import { createReconcileWorker } from './core/reconcile.js';
 import { createSendWorker } from './core/sending.js';
 import { resolveSecretsKey } from './core/secrets.js';
 import { adapters as shippedAdapters } from './integrations/adapters.js';
@@ -77,6 +79,10 @@ await importEarlierMappingsAtStart({ db: database.db, pool: database.pool, setti
 // own error service while one is on (docs/SENTRY.md).
 let integrations;
 const log = createMonitoredLog({ log: console, reporters: () => integrations?.with('captureError') ?? [] });
+// Performance traces, while a tracing service is on (docs/SENTRY.md, "Traces"):
+// each request, and each database query inside one.
+const tracing = createTracing({ tracers: () => integrations?.with('traceRequest') ?? [] });
+traceQueries(database.pool, tracing);
 try {
   const stored = await readStoredSettings(database.db);
   const { env: settingsEnv, unreadable } = settingsEnvironment({ env: process.env, stored, adapters: shippedAdapters, secrets });
@@ -97,6 +103,10 @@ console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'}; secrets
 if (process.env.FLOW_PIPELINE !== 'off') {
   createPipelineWorker({ db: database.db, integrations, log }).start();
 }
+// The daily reconcile (server/core/reconcile.js) compares Flow's own copies
+// and opens a review item for a day that does not agree. It never calls or
+// writes to another system.
+createReconcileWorker({ db: database.db, integrations, log }).start();
 // The send worker (server/core/sending.js) sends only what a person queued
 // with Send all ready, to the accounting integration that is on.
 createSendWorker({ db: database.db, integrations, log }).start();
@@ -142,7 +152,7 @@ const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : fa
 
 const updates = createUpdateChecker();
 
-createApp({ database, schemaJournals: expectedSchema({ adapters: shippedAdapters }).journals, auth, trustProxy, updates, integrations, secrets, defaultFamily, log }).listen(port, () => {
+createApp({ database, schemaJournals: expectedSchema({ adapters: shippedAdapters }).journals, auth, trustProxy, updates, integrations, secrets, defaultFamily, log, tracing }).listen(port, () => {
   console.log(`[flow] listening on ${port}; design system ${defaultFamily} (FLOW_THEME)`);
 });
 

package/server/integrations/port.js

@@ -11,6 +11,7 @@ import { isMissingTable, migrateAdapterSchema } from './schema.js';
 
 export const CAPABILITIES = Object.freeze([
   'pullWorkItems', // billable work since a cursor (Seazona: completed cases)
+  'readWorkItem', // { state: read | withdrawn | unavailable }: one job read from the work system now, as pullWorkItems gives it (read before act, server/core/read-before-act.js)
   'pullHistoryJobs', // past work from a history import, as ledger jobs marked historical (Seazona: its API backfill)
   'pushInvoice', // send an issued invoice; the Flow record id is the idempotency key
   'pushInvoices', // send several issued invoices in one pass (Send all ready, server/core/sending.js)
@@ -20,16 +21,24 @@ 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)
+  'billableJobs', // billable jobs by day from the work system's copy in Flow, for the daily reconcile; never a live call
   'jobReferenceFields', // { patient }: the fields a job gives the invoice Reference (server/core/references.js)
-  'listWork', // the work system's jobs from its copy in Flow, open and lately finished, for the Jobs board
+  'listWork', // the work system's jobs from its copy in Flow, open and lately finished, for the Jobs board; a job may carry `pendingMove`
+  'moveWork', // { sourceJobRef, toStatus, personId }: a person moved a job to another stage on the Jobs board; answers what happens (a hand-off when the system's API cannot change it)
+  'cancelMove', // { sourceJobRef }: take back a move the work system has not made yet
+  'personSettings', // { personId }: each person's own choices in this integration, as [{ key, label, hint, kind, value }]
+  'setPersonSetting', // { personId, key, value }: change one, answers the new list
   'jobIssues', // open issues the integration holds for jobs, by job ref: a short phrase and the page where a person fixes it
   '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
+  'readChanges', // { state: fresh | read | unavailable }: the accounting system's latest changes into its copy now, just before Flow drafts or sends (read before act)
   'listPriceItems', // the system's own price list from its copy in Flow, for the price list's links and check; never a live call
   'health', // connection state for Settings
   'alerts', // what only a person can clear (a refused sign-in, stopped calls), for the Integrations page; reads Flow's data only
   'captureError', // an error Flow logged, sent to the installation's own error service (Sentry)
   'browserMonitoring', // the public settings a browser needs to report errors and problems to that service
+  'traceSpan', // runs work inside a span of the current performance trace (server/core/tracing.js)
+  'traceRequest', // names a request's performance trace by its route, once the route is known
 ]);
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;

package/server/integrations/seazona/act.js

@@ -0,0 +1,48 @@
+import { readBillableOrder } from './feed.js';
+import { readOrder } from './lanes.js';
+
+// Read before act (issue #141). Just before Flow drafts or sends from a job
+// whose report is old, it reads that one order from Seazona: one
+// GET orders/{id}, through the call guard, stored through the mirror like
+// any lane read. The answer is the order as the feed gives it:
+//
+//   { state: 'read', item }               billable; `item` is a feed item
+//   { state: 'withdrawn', ledgerWithdrawn, reason }
+//                                          deleted in Seazona, or no longer
+//                                          billable
+//   { state: 'unavailable', reason }      the read failed or calls are stopped
+//
+// The day's counts are kept in memory for /health; a restart starts them again.
+export function createActReader({ now }) {
+  let tally = null;
+  function count(key) {
+    const day = new Date(Number(now())).toISOString().slice(0, 10);
+    if (tally?.day !== day) tally = { day, reads: 0, changed: 0, withdrawn: 0, unavailable: 0 };
+    tally[key] += 1;
+  }
+  const unavailable = (reason) => {
+    count('unavailable');
+    return { state: 'unavailable', reason };
+  };
+
+  async function read({ db, client, settings }, orderId) {
+    count('reads');
+    let result;
+    try {
+      result = await readOrder({ db, client, sync: settings.sync, at: new Date(Number(now())) }, orderId, { known: true });
+    } catch (error) {
+      return unavailable(error?.message || 'the read failed');
+    }
+    if (result.outcome === 'failed') return unavailable(result.failure?.error || 'the read failed');
+    if (result.summary?.changed || result.summary?.created) count('changed');
+    const entry = await readBillableOrder(db, orderId);
+    if (!entry) return unavailable('Flow has no copy of the order');
+    if (entry.withdrawn) {
+      count('withdrawn');
+      return { state: 'withdrawn', ledgerWithdrawn: entry.withdrawn.ledgerWithdrawn, reason: entry.withdrawn.reason };
+    }
+    return { state: 'read', item: entry.item };
+  }
+
+  return { read, status: () => (tally ? { ...tally } : null) };
+}

package/server/integrations/seazona/feed.js

@@ -1,5 +1,5 @@
 import { and, desc, eq, gte, isNull, or, sql } from 'drizzle-orm';
-import { ledgerLinesFor, toLedgerHold, toLedgerJob } from './ledger.js';
+import { ledgerLinesFor, toLedgerJob, toLedgerWithdrawn } from './ledger.js';
 import { isFinalStatus, orderStatusLabel, parseSeazonaDate } from './map.js';
 import { seazonaClients, seazonaInvoices, seazonaOrders, seazonaReference } from './schema.js';
 
@@ -36,11 +36,9 @@ function encodeCursor(at, id) {
   return Buffer.from(JSON.stringify({ at, id })).toString('base64url');
 }
 
-export async function readBillableWork(db, { cursor = null, limit = 200 } = {}) {
-  const after = decodeCursor(cursor);
-  const changedAt = sql`greatest(${seazonaOrders.lastChangedAt}, coalesce(${seazonaInvoices.lastChangedAt}, ${seazonaOrders.lastChangedAt}), date_trunc(${SEEN_STEP}, ${seazonaOrders.lastSyncedAt}))`;
-  const pageSize = Math.max(1, Math.min(1000, limit));
-  const rows = await db.select({
+// One order, its invoice and its client, as the feed reads them.
+function feedQuery(db, changedAt) {
+  return db.select({
     order: seazonaOrders,
     invoice: seazonaInvoices,
     client: { accountNumber: seazonaClients.accountNumber, company: seazonaClients.company, email: seazonaClients.email },
@@ -50,56 +48,70 @@ export async function readBillableWork(db, { cursor = null, limit = 200 } = {})
   })
     .from(seazonaOrders)
     .leftJoin(seazonaInvoices, eq(seazonaInvoices.invoiceNumber, seazonaOrders.invoiceNumber))
-    .leftJoin(seazonaClients, eq(seazonaClients.id, seazonaOrders.clientId))
+    .leftJoin(seazonaClients, eq(seazonaClients.id, seazonaOrders.clientId));
+}
+
+// A feed row as an item, or as a withdrawn entry when it is not billable.
+function toFeedEntry({ order, invoice, client, invoiceOrderCount }) {
+  const billable = !order.deletedInSourceAt && BILLABLE.test(order.status ?? '');
+  if (!billable) {
+    const entry = {
+      sourceId: order.id,
+      status: orderStatusLabel(order),
+      reason: order.deletedInSourceAt ? 'deleted_in_seazona' : 'not_billable',
+    };
+    const syncedAt = order.lastSyncedAt?.toISOString() ?? null;
+    return { withdrawn: { ...entry, ledgerWithdrawn: toLedgerWithdrawn({ ...entry, syncedAt }) } };
+  }
+  const item = {
+    source: 'seazona',
+    sourceId: order.id,
+    invoiceNumber: order.invoiceNumber,
+    status: order.status,
+    shipped: SHIPPED.test(order.status ?? ''),
+    clientId: order.clientId,
+    company: order.company,
+    doctorName: order.doctorName,
+    orderedOn: parseSeazonaDate(order.orderedText),
+    dueOn: parseSeazonaDate(order.dueText),
+    lines: order.lines,
+    subtotalCents: order.subtotalCents,
+    patientReference: order.patientReference,
+    syncedAt: order.lastSyncedAt.toISOString(),
+    invoice: invoice ? {
+      invoiceNumber: invoice.invoiceNumber,
+      status: invoice.status,
+      accountNumber: invoice.accountNumber,
+      invoiceDate: parseSeazonaDate(invoice.invoiceDateText),
+      dueDate: parseSeazonaDate(invoice.dueText),
+      lines: invoice.lines,
+      subtotalCents: invoice.subtotalCents,
+      taxCents: invoice.taxCents,
+      totalCents: invoice.totalCents,
+      discountCents: invoice.discountCents,
+      patientReference: invoice.patientReference,
+    } : null,
+    client: client?.accountNumber || client?.company || client?.email ? client : null,
+    invoiceOrderCount: order.invoiceNumber ? Number(invoiceOrderCount) : 0,
+  };
+  return { item: { ...item, linesFrom: ledgerLinesFor(item).linesFrom, ledgerJob: toLedgerJob(item) } };
+}
+
+export async function readBillableWork(db, { cursor = null, limit = 200 } = {}) {
+  const after = decodeCursor(cursor);
+  const changedAt = sql`greatest(${seazonaOrders.lastChangedAt}, coalesce(${seazonaInvoices.lastChangedAt}, ${seazonaOrders.lastChangedAt}), date_trunc(${SEEN_STEP}, ${seazonaOrders.lastSyncedAt}))`;
+  const pageSize = Math.max(1, Math.min(1000, limit));
+  const rows = await feedQuery(db, changedAt)
     .where(after ? sql`(${changedAt}, ${seazonaOrders.id}) > (${after.at}::timestamptz, ${after.id})` : undefined)
     .orderBy(changedAt, seazonaOrders.id)
     .limit(pageSize);
 
   const items = [];
   const withdrawn = [];
-  for (const { order, invoice, client, invoiceOrderCount } of rows) {
-    const billable = !order.deletedInSourceAt && BILLABLE.test(order.status ?? '');
-    if (!billable) {
-      const entry = {
-        sourceId: order.id,
-        status: orderStatusLabel(order),
-        reason: order.deletedInSourceAt ? 'deleted_in_seazona' : 'not_billable',
-      };
-      withdrawn.push({ ...entry, ledgerHold: toLedgerHold(entry) });
-      continue;
-    }
-    const item = {
-      source: 'seazona',
-      sourceId: order.id,
-      invoiceNumber: order.invoiceNumber,
-      status: order.status,
-      shipped: SHIPPED.test(order.status ?? ''),
-      clientId: order.clientId,
-      company: order.company,
-      doctorName: order.doctorName,
-      orderedOn: parseSeazonaDate(order.orderedText),
-      dueOn: parseSeazonaDate(order.dueText),
-      lines: order.lines,
-      subtotalCents: order.subtotalCents,
-      patientReference: order.patientReference,
-      syncedAt: order.lastSyncedAt.toISOString(),
-      invoice: invoice ? {
-        invoiceNumber: invoice.invoiceNumber,
-        status: invoice.status,
-        accountNumber: invoice.accountNumber,
-        invoiceDate: parseSeazonaDate(invoice.invoiceDateText),
-        dueDate: parseSeazonaDate(invoice.dueText),
-        lines: invoice.lines,
-        subtotalCents: invoice.subtotalCents,
-        taxCents: invoice.taxCents,
-        totalCents: invoice.totalCents,
-        discountCents: invoice.discountCents,
-        patientReference: invoice.patientReference,
-      } : null,
-      client: client?.accountNumber || client?.company || client?.email ? client : null,
-      invoiceOrderCount: order.invoiceNumber ? Number(invoiceOrderCount) : 0,
-    };
-    items.push({ ...item, linesFrom: ledgerLinesFor(item).linesFrom, ledgerJob: toLedgerJob(item) });
+  for (const row of rows) {
+    const entry = toFeedEntry(row);
+    if (entry.item) items.push(entry.item);
+    else withdrawn.push(entry.withdrawn);
   }
   const lastRow = rows.at(-1);
   return {
@@ -110,6 +122,14 @@ export async function readBillableWork(db, { cursor = null, limit = 200 } = {})
   };
 }
 
+// One order as the feed gives it (issue #141, read before act): `{ item }`
+// when it is billable, `{ withdrawn }` when it is not, or null when Flow's
+// copy does not have it.
+export async function readBillableOrder(db, orderId) {
+  const [row] = await feedQuery(db, seazonaOrders.lastChangedAt).where(eq(seazonaOrders.id, orderId));
+  return row ? toFeedEntry(row) : null;
+}
+
 // Seazona clients, by id and the company name an invoice bills. A client
 // 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

package/server/integrations/seazona/governor.js

@@ -68,6 +68,30 @@ export class SeazonaCallsStopped extends CallsStopped {
   }
 }
 
+// A request path with its record ids taken out, so /health can say which
+// calls failed and never names a record: /v1/orders/5591234 is
+// /v1/orders/:id. A name is lowercase words joined by hyphens, or a version.
+export function pathShape(path) {
+  const name = /^(v\d+|[a-z]+(-[a-z]+)*)$/;
+  return `/${String(path || '').split('/').filter(Boolean).map((part) => (name.test(part) ? part : ':id')).join('/')}`;
+}
+
+// Issue #144: the last day's failed calls split into faults (what the call
+// guard counts, and a vendor may count against the API client) and 404s
+// (a record that is gone), and the top groups by path shape, status and
+// kind.
+function failureKinds(day, top = 10) {
+  const groups = new Map();
+  for (const row of day.failures) {
+    const group = { path: pathShape(row.path), statusCode: row.statusCode ?? null, failureKind: row.failureKind ?? null };
+    const key = JSON.stringify(group);
+    groups.set(key, { ...group, requests: (groups.get(key)?.requests ?? 0) + row.requests });
+  }
+  const sorted = [...groups.values()].sort((a, b) => b.requests - a.requests).slice(0, top);
+  // Every failed call is a fault but a 404 (countsAsFailure, call-guard.js).
+  return { faults: day.failed - day.notFound, notFound: day.notFound, failures: sorted };
+}
+
 export function createSeazonaGovernor({
   db,
   clientKey,
@@ -171,7 +195,7 @@ export function createSeazonaGovernor({
     const calls = await guard.status(key);
     const [{ lastMinute }] = await db.select({ lastMinute: count() }).from(seazonaApiRequests)
       .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 day = await summarise({ from: new Date(nowMs - 24 * 60 * 60_000), to: new Date(nowMs), topFailures: 500 });
     const cooldownUntil = state && state.cooldownUntil.getTime() > nowMs ? state.cooldownUntil.toISOString() : null;
     return {
       limitPerMinute: limit,
@@ -184,7 +208,7 @@ export function createSeazonaGovernor({
       haltedAt: calls.haltedAt,
       failedToday: calls.failedToday,
       dailyFailureBudget: calls.dailyFailureBudget,
-      lastDay: { requests: day.requests, failed: day.failed, rateLimited: day.rateLimited, retries: day.retries },
+      lastDay: { requests: day.requests, failed: day.failed, rateLimited: day.rateLimited, retries: day.retries, ...failureKinds(day) },
     };
   }
 
@@ -201,6 +225,7 @@ export function createSeazonaGovernor({
       failed: sql`count(*) filter (where ${seazonaApiRequests.statusCode} is null or ${seazonaApiRequests.statusCode} >= 400)`,
       rateLimited: sql`count(*) filter (where ${seazonaApiRequests.statusCode} = 429)`,
       retries: sql`count(*) filter (where ${seazonaApiRequests.isRetry})`,
+      notFound: sql`count(*) filter (where ${seazonaApiRequests.statusCode} = 404)`,
     }).from(seazonaApiRequests).where(range);
     const failures = await db.select({
       path: seazonaApiRequests.requestPath,
@@ -219,6 +244,7 @@ export function createSeazonaGovernor({
       failed: Number(totals.failed),
       rateLimited: Number(totals.rateLimited),
       retries: Number(totals.retries),
+      notFound: Number(totals.notFound),
       failures: failures.map((row) => ({ ...row, requests: Number(row.requests) })),
     };
   }

package/server/integrations/seazona/index.js

@@ -1,12 +1,18 @@
 import { guardAlerts } from '../call-guard.js';
+import { createActReader } from './act.js';
 import { createSeazonaClient } from './client.js';
 import { listClients, listProducts, listWork, readBillableWork } from './feed.js';
 import { historyJobIssues, historySummary, readHistoryWork } from './history/index.js';
 import { readSeazonaSyncHealth, runSeazonaSync } from './lanes.js';
+import { readBillableJobs } from './reconcile.js';
 import { SEAZONA_CALL_GUARD } from './governor.js';
 import { createSeazonaRouter } from './routes.js';
+import {
+  cancelStageMove, expiredStageMoves, readPersonSettings, requestStageMove, settleStageMoves, waitingStageMoves, writePersonSetting,
+} from './stage-moves.js';
 import { orderPatient } from './patients.js';
 import { createSeazonaScheduler } from './scheduler.js';
+import { readSweepHealth } from './sweep.js';
 import { resetFailedLanes, resetStoppedLanes } from './store.js';
 import { describeSeazonaSettings, resolveSeazonaSettings } from './settings.js';
 import { seazonaSchema } from './tables.js';
@@ -45,12 +51,26 @@ export const SEAZONA_SETUP = {
     { name: 'SEAZONA_API_BASE_URL', label: 'API address', kind: 'url', help: 'The API root of your account, https://…' },
     { name: 'SEAZONA_API_CLIENT_ID', label: 'Client id' },
     { name: 'SEAZONA_API_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
+    { name: 'SEAZONA_ORDER_URL', label: 'Order address', kind: 'url', help: 'Optional. The address of one order in Seazona, with {ref} for the order number. Stage moves on the Jobs board open it.' },
     { name: 'SEAZONA_KEEP_PATIENT_REFERENCE', label: 'Keep patient names', kind: 'onoff', help: 'On: Flow keeps the patient name of each job for the invoice Reference.' },
   ],
 };
 
+// What a person reads for each lane: the Seazona records it copies.
+const READ_NAMES = {
+  invoices: 'invoices',
+  orders_recent: 'new orders',
+  orders_active: 'open orders',
+  clients: 'practices',
+  products: 'products',
+  users: 'lab users',
+  history: 'past orders',
+};
+const readNames = (lanes) => lanes.map((lane) => READ_NAMES[lane.lane] ?? lane.lane).join(', ');
+
 export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.now, timers } = {}) {
   let runtime = null; // { settings, db, client, scheduler }
+  const actReader = createActReader({ now });
 
   function current() {
     if (!runtime) throw new Error('The Seazona adapter has not started');
@@ -107,13 +127,17 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
         if (!runtime) return { ok: false, reason: 'not_started', ...describeSeazonaSettings(null) };
         const { settings, db, client, scheduler } = runtime;
         const sync = await readSeazonaSyncHealth(db, settings, { now });
+        const schedulerStatus = scheduler ? scheduler.status() : null;
         return {
-          ok: sync.ok,
+          ok: sync.ok && !schedulerStatus?.stuckSince,
           ...describeSeazonaSettings(settings),
-          scheduler: scheduler ? scheduler.status() : null,
+          scheduler: schedulerStatus,
           governor: await client.governor.status(),
           ...sync,
+          // Issue #141: today's reads before a draft or a send.
+          readsBeforeAct: actReader.status(),
           history: await historySummary(db),
+          sweep: await readSweepHealth(db, settings, { now }),
         };
       },
 
@@ -122,7 +146,42 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       // a person saves the settings. Reads Flow's database only.
       async alerts() {
         if (!runtime?.client.governor) return [];
-        return guardAlerts('Seazona', await runtime.client.governor.status(), { fix: 'Check the API client in the Seazona settings, then save them.' });
+        const status = await runtime.client.governor.status();
+        const alerts = guardAlerts('Seazona', status, { fix: 'Check the API client in the Seazona settings, then save them.' });
+        // Stage moves nobody made in Seazona within a day (stage-moves.js).
+        await settleStageMoves(runtime.db, { now: now() });
+        const expired = await expiredStageMoves(runtime.db, { now: now() });
+        if (expired.length) {
+          alerts.push({
+            id: 'stage-moves-expired',
+            tone: 'warn',
+            title: `${expired.length === 1 ? 'One stage move was' : `${expired.length} stage moves were`} not made in Seazona within a day: ${expired.slice(0, 5).map((m) => `${m.orderId} to ${m.toStatus}`).join(', ')}${expired.length > 5 ? ', …' : ''}. The cards went back to their Seazona stage.`,
+            members: expired.map((m) => `${m.orderId}:${m.settledAt?.toISOString() ?? ''}`),
+          });
+        }
+        // Issue #143: what the lanes cannot fix by themselves. A refused API
+        // client already has its own alert above, so it stops no lane here.
+        if (!runtime.settings.scheduled) return alerts;
+        const { lanes } = await readSeazonaSyncHealth(runtime.db, runtime.settings, { now });
+        const stopped = status.haltedReason ? [] : lanes.filter((lane) => lane.status === 'stopped');
+        if (stopped.length) {
+          alerts.push({
+            id: 'reads-stopped',
+            tone: 'danger',
+            title: `Seazona refused Flow's request for ${readNames(stopped)}. Flow stopped reading them. Check the Seazona settings, then save them.`,
+            members: stopped.map((lane) => `${lane.lane}:${lane.lastAttemptAt ?? ''}`),
+          });
+        }
+        const stale = lanes.filter((lane) => lane.stale && lane.status !== 'stopped');
+        if (stale.length) {
+          alerts.push({
+            id: 'reads-late',
+            tone: 'warn',
+            title: `Flow has not read ${readNames(stale)} from Seazona on time. Jobs and invoices may show old Seazona data.`,
+            members: stale.map((lane) => `${lane.lane}:${lane.lastSuccessAt ?? ''}`),
+          });
+        }
+        return alerts;
       },
 
       // Billable work since a cursor: complete and shipped orders that
@@ -133,12 +192,25 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
         return readBillableWork(current().db, { cursor, ...options });
       },
 
+      // Read before act (issue #141): reads one order from Seazona now, and
+      // answers it as the feed would (act.js). The only capability here that
+      // calls Seazona on a person's or an automation's behalf.
+      async readWorkItem({ sourceJobRef }) {
+        return actReader.read(current(), sourceJobRef);
+      },
+
       // Past work from the history import (docs/SEAZONA.md, "History
       // import"), as ledger jobs marked `historical`. Reads Flow's copy only.
       async pullHistoryJobs(cursor = null, options = {}) {
         return readHistoryWork(current().db, { cursor, ...options });
       },
 
+      // Billable jobs by day, for the daily reconcile
+      // (server/core/reconcile.js). Reads Flow's copy only.
+      async billableJobs({ from = null, to = null } = {}) {
+        return readBillableJobs(current().db, { from, to });
+      },
+
       // Seazona clients by id and company name, for the identity map. Reads
       // Flow's copy only.
       async listCustomers() {
@@ -148,7 +220,38 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       // 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() });
+        const { db } = current();
+        await settleStageMoves(db, { now: now() });
+        const [work, waiting] = await Promise.all([listWork(db, { now: now() }), waitingStageMoves(db)]);
+        // A stage move Seazona has not made yet (stage-moves.js): the card
+        // shows in its new lane, waiting for Seazona.
+        for (const item of work.items) {
+          const move = waiting.get(item.sourceJobRef);
+          if (move) item.pendingMove = { to: move.toStatus, from: move.fromStatus, requestedAt: move.requestedAt.toISOString(), expiresAt: move.expiresAt.toISOString() };
+        }
+        return work;
+      },
+
+      // A person's move of a job to another Seazona stage. Seazona's API
+      // cannot change an order's status, so this never calls Seazona: it
+      // records a hand-off and answers what the person does in Seazona.
+      async moveWork({ sourceJobRef, toStatus, personId = null }) {
+        const { db, settings } = current();
+        return requestStageMove(db, { orderId: sourceJobRef, toStatus, personId, orderUrlTemplate: settings.orderUrlTemplate, now: now() });
+      },
+
+      async cancelMove({ sourceJobRef }) {
+        return cancelStageMove(current().db, { orderId: sourceJobRef, now: now() });
+      },
+
+      // Each person's own Seazona choices: today, whether the board asks
+      // before a stage move.
+      async personSettings({ personId }) {
+        return readPersonSettings(current().db, personId);
+      },
+
+      async setPersonSetting({ personId, key, value }) {
+        return writePersonSetting(current().db, personId, { key, value }, { now: now() });
       },
 
       // The fields a job gives the invoice Reference: the patient name, when