@arcforgelabs/flow 2026.10.38 → 2026.10.39

package/server/core/custom-fields.js

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { and, asc, eq, inArray, isNull, sql } from 'drizzle-orm';
-import { CUSTOM_FIELD_TYPES, jobFieldEvents, jobFields, jobFieldValues, people } from '../db/schema.js';
+import {
+  CUSTOM_FIELD_TYPES, integrationSettingEvents, integrationSettings, jobFieldEvents, jobFields, jobFieldSettings, jobFieldValues, people,
+} from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 
 // Custom fields (docs/CUSTOM_FIELDS.md): fields a lab makes for its jobs in
@@ -14,6 +16,14 @@ export { CUSTOM_FIELD_TYPES };
 // person, or yes and no.
 export const GROUPABLE_TYPES = ['dropdown', 'person', 'checkbox'];
 export const OPTION_COLORS = ['gray', 'blue', 'teal', 'green', 'amber', 'red', 'purple', 'pink'];
+// Each type group's own colour, until the lab picks another.
+export const TYPE_COLORS = { dropdown: 'green', person: 'blue', checkbox: 'purple', date: 'teal', number: 'amber', text: 'gray' };
+
+function readColor(raw, what) {
+  if (raw === null) return null;
+  if (!OPTION_COLORS.includes(raw)) throw invalid(`${what} must be one of ${OPTION_COLORS.join(', ')}`);
+  return raw;
+}
 
 const MAX_FIELDS = 50;
 const MAX_OPTIONS = 50;
@@ -74,6 +84,7 @@ export function readField(raw, { partial = false, previous = null } = {}) {
   } else if (input.type !== undefined && input.type !== previous?.type) {
     throw invalid('the type of a field cannot change; make a new field instead');
   }
+  if (input.color !== undefined) out.color = readColor(input.color, 'color');
   const type = out.type ?? previous?.type;
   if (type === 'dropdown' && (!partial || input.options !== undefined)) out.options = readOptions(input.options, previous?.options ?? []);
   else if (type !== 'dropdown' && input.options !== undefined && input.options !== null && !(Array.isArray(input.options) && !input.options.length)) {
@@ -87,6 +98,7 @@ export const publicField = (row) => ({
   name: row.name,
   type: row.type,
   options: row.options ?? [],
+  color: row.color ?? null,
   position: row.position,
   groupable: GROUPABLE_TYPES.includes(row.type),
   archived: Boolean(row.archivedAt),
@@ -95,11 +107,15 @@ export const publicField = (row) => ({
   updatedAt: row.updatedAt?.toISOString?.() ?? row.updatedAt,
 });
 
+// `valueCount` is how many jobs have a value, so Delete can say what goes.
 export async function listFields(db, organisationId, { archived = false } = {}) {
   const where = [eq(jobFields.organisationId, organisationId)];
   if (!archived) where.push(isNull(jobFields.archivedAt));
-  const rows = await db.select().from(jobFields).where(and(...where)).orderBy(asc(jobFields.position), asc(jobFields.createdAt));
-  return rows.map(publicField);
+  const rows = await db.select({
+    field: jobFields,
+    valueCount: sql`(select count(*) from ${jobFieldValues} v where v.organisation_id = ${jobFields.organisationId} and v.field_id = ${jobFields.id})`.mapWith(Number),
+  }).from(jobFields).where(and(...where)).orderBy(asc(jobFields.position), asc(jobFields.createdAt));
+  return rows.map(({ field, valueCount }) => ({ ...publicField(field), valueCount }));
 }
 
 async function readRow(db, organisationId, id) {
@@ -135,11 +151,20 @@ export async function createField(db, organisationId, raw, { personId = null } =
 
 // Every lab gets an Assignee: a person field, made once, the first time
 // the lab's fields are read and it has no person field at all (live or
-// archived). The lab can then rename it or archive it like any field, and
-// Flow does not make it again. A field already named Assignee of another
-// type is left alone.
+// archived). The lab can then rename, archive or delete it like any field,
+// and Flow does not make it again: job_field_settings.assignee_made_at
+// records that it was made (or that the lab already had a person field).
+// A field already named Assignee of another type is left alone.
 export const ASSIGNEE = { name: 'Assignee', type: 'person' };
 export async function ensureAssignee(db, organisationId) {
+  const [settings] = await db.select({ at: jobFieldSettings.assigneeMadeAt }).from(jobFieldSettings)
+    .where(eq(jobFieldSettings.organisationId, organisationId));
+  if (settings?.at) return null;
+  // Only the request that marks it makes it.
+  const [marked] = await db.insert(jobFieldSettings).values({ organisationId, assigneeMadeAt: new Date() })
+    .onConflictDoUpdate({ target: jobFieldSettings.organisationId, set: { assigneeMadeAt: new Date() }, setWhere: isNull(jobFieldSettings.assigneeMadeAt) })
+    .returning({ organisationId: jobFieldSettings.organisationId });
+  if (!marked) return null;
   const [{ count }] = await db.select({ count: sql`count(*)`.mapWith(Number) }).from(jobFields)
     .where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.type, 'person')));
   if (count > 0) return null;
@@ -151,6 +176,39 @@ export async function ensureAssignee(db, organisationId) {
   }
 }
 
+// Each type group's colour: TYPE_COLORS, with the lab's own choices on top.
+export async function readGroupColors(db, organisationId) {
+  const [row] = await db.select({ colors: jobFieldSettings.groupColors }).from(jobFieldSettings)
+    .where(eq(jobFieldSettings.organisationId, organisationId));
+  const own = row?.colors ?? {};
+  return Object.fromEntries(CUSTOM_FIELD_TYPES.map((t) => [t, OPTION_COLORS.includes(own[t]) ? own[t] : TYPE_COLORS[t]]));
+}
+
+// Give one type group a colour. null puts back its own colour.
+export async function setGroupColor(db, organisationId, type, raw, { personId = null } = {}) {
+  if (!CUSTOM_FIELD_TYPES.includes(type)) throw notFound('group');
+  const color = raw === undefined ? undefined : readColor(raw, 'color');
+  if (color === undefined) throw invalid('color is required (null puts back the group\'s own colour)');
+  const own = { ...(await db.select({ colors: jobFieldSettings.groupColors }).from(jobFieldSettings)
+    .where(eq(jobFieldSettings.organisationId, organisationId)))[0]?.colors };
+  if (color === null || color === TYPE_COLORS[type]) delete own[type]; else own[type] = color;
+  await db.insert(jobFieldSettings).values({ organisationId, groupColors: own, updatedBy: personId })
+    .onConflictDoUpdate({ target: jobFieldSettings.organisationId, set: { groupColors: own, updatedBy: personId, updatedAt: new Date() } });
+  return readGroupColors(db, organisationId);
+}
+
+// When an integration was connected: the first time its settings were saved
+// or it was turned on in Flow, or, for one set up in the host's own
+// settings, the first time Flow saw one of its records (`seenSince`).
+export async function integrationConnectedAt(db, adapterId, seenSince = null) {
+  const [[saved], [event]] = await Promise.all([
+    db.select({ at: sql`min(${integrationSettings.createdAt})` }).from(integrationSettings).where(eq(integrationSettings.adapterId, adapterId)),
+    db.select({ at: sql`min(${integrationSettingEvents.createdAt})` }).from(integrationSettingEvents).where(eq(integrationSettingEvents.adapterId, adapterId)),
+  ]);
+  const times = [saved?.at, event?.at, seenSince].filter(Boolean).map((t) => new Date(t)).filter((t) => !Number.isNaN(t.getTime()));
+  return times.length ? new Date(Math.min(...times)).toISOString() : null;
+}
+
 export async function updateField(db, organisationId, id, raw, { personId = null } = {}) {
   const previous = await readRow(db, organisationId, id);
   if (previous.archivedAt) throw new FlowError('conflict', 'the field is archived; bring it back first');
@@ -171,6 +229,16 @@ export async function archiveField(db, organisationId, id, { archived = true, pe
   return publicField(row);
 }
 
+// Delete a field for good, with every job's value and its history (the
+// tables cascade). Archive is the step that keeps them.
+export async function deleteField(db, organisationId, id) {
+  const field = await readRow(db, organisationId, id);
+  const [{ count }] = await db.select({ count: sql`count(*)`.mapWith(Number) }).from(jobFieldValues)
+    .where(and(eq(jobFieldValues.organisationId, organisationId), eq(jobFieldValues.fieldId, field.id)));
+  await db.delete(jobFields).where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.id, field.id)));
+  return { id: field.id, name: field.name, valuesDeleted: count };
+}
+
 // Put the fields in this order. `ids` lists every field that is not archived.
 export async function orderFields(db, organisationId, ids, { personId = null } = {}) {
   if (!Array.isArray(ids) || ids.some((i) => typeof i !== 'string')) throw invalid('ids must be a list of field ids');

package/server/core/ledger.js

@@ -305,20 +305,21 @@ function changedReview(obligation, compare) {
 
 // "Use new lines": a person takes the work system's new lines (and its
 // customer, when that changed) into Flow's own unsent draft. Flow writes only
-// its own draft, never another system. Refused when the draft changed too,
-// or has left Flow: those stay alerts for a person.
-export async function useSourceLines(db, organisationId, obligationId, { actor }) {
+// its own draft, never another system. Refused when the invoice has left
+// Flow. When the draft changed too, `accept` (a person's "Accept change")
+// takes the work system's value over the draft's; without it, refused.
+export async function useSourceLines(db, organisationId, obligationId, { actor, accept = false }) {
   requireActor(actor);
   return db.transaction(async (tx) => {
     const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
     if (!obligation.invoiceId) throw new FlowError('invalid', 'the job has no invoice');
     const compare = await compareWithDraft(tx, organisationId, obligation, obligation);
-    if (compare.outcome === 'conflict') {
-      throw new FlowError('conflict', compare.sent ? 'the invoice has left Flow; change it where it is now' : 'the draft changed in Flow too; a person must compare them', { fields: compare.fields });
+    if (compare.outcome === 'conflict' && (compare.sent || compare.missing || !accept)) {
+      throw new FlowError('conflict', compare.missing ? 'the invoice was not found' : compare.sent ? 'the invoice has left Flow; change it where it is now' : 'the draft changed in Flow too; a person must compare them', { fields: compare.fields });
     }
     const changes = {};
     for (const { field, changedIn } of compare.fields) {
-      if (changedIn !== 'work') continue;
+      if (changedIn !== 'work' && !(accept && changedIn === 'both')) continue;
       if (field === 'lines') {
         changes.lines = obligation.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
           { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }
@@ -338,12 +339,30 @@ export async function useSourceLines(db, organisationId, obligationId, { actor }
     const fields = { draftBasis: basisOf(obligation) };
     if (obligation.holdState === 'review' && obligation.holdReason === CHANGED_REASON) Object.assign(fields, { holdState: 'none', holdReason: null });
     const row = await update(tx, obligation, fields);
-    await addEvent(tx, row, 'source_lines_used', actor, { invoiceId: invoice.id, changed: Object.keys(changes), totalCents: invoice.totalCents });
+    await addEvent(tx, row, 'source_lines_used', actor, { invoiceId: invoice.id, changed: Object.keys(changes), totalCents: invoice.totalCents, ...(accept ? { accepted: compare.outcome } : {}) });
     await resolveReviewFor(tx, organisationId, { kind: REVIEW_CHANGED, entity: 'obligation', flowId: row.id, resolution: 'used_new_lines', actor });
     return { obligation: row, invoice };
   });
 }
 
+// After a person rechecks a job (POST /jobs/:id/recheck): a "job changed"
+// hold whose job now matches the draft again (the work system was fixed, or
+// the draft was) is over. Answers the obligation.
+export async function settleJobChange(db, organisationId, obligationId, { actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (!obligation.invoiceId || obligation.holdState !== 'review' || obligation.holdReason !== CHANGED_REASON) return obligation;
+    const compare = await compareWithDraft(tx, organisationId, obligation, obligation);
+    const settled = compare.fields.every(({ changedIn }) => ['none', 'same', 'flow'].includes(changedIn)) && !compare.missing;
+    if (!settled) return obligation;
+    const row = await update(tx, obligation, { holdState: 'none', holdReason: null, draftBasis: basisOf(obligation) });
+    await addEvent(tx, row, 'review_settled', actor, { invoiceId: obligation.invoiceId });
+    await resolveReviewFor(tx, organisationId, { kind: REVIEW_CHANGED, entity: 'obligation', flowId: row.id, resolution: 'job_matches_invoice', actor });
+    return row;
+  });
+}
+
 // What changed in a job after its invoice was made, for the invoice page:
 // each line as it was (the draft basis) and as the work system has it now.
 // Lines pair by price item, else item code, account or description; an
@@ -411,6 +430,9 @@ export async function jobChangeFor(db, organisationId, invoiceId) {
     outcome: compare.outcome,
     sent: compare.sent,
     canAdopt: compare.outcome === 'offer',
+    // "Accept change": the draft takes the work system's values, even when
+    // the draft changed too. Not once the invoice has left Flow.
+    canAccept: !compare.sent && !compare.missing,
     lines: diffJobLines(was.lines ?? [], obligation.lines ?? []),
     contact: (was.contactId ?? null) === (obligation.contactId ?? null) ? null : { was: was.contactId ?? null, now: obligation.contactId ?? null },
     total: { was: was.totalCents ?? null, now: obligation.totalCents },

package/server/core/price-list.js

@@ -174,13 +174,13 @@ export async function linkByCode(db, organisationId, catalogue, { items = null,
 // A person's link: `externalId` in `system`'s list goes to this price item.
 // For an accounting system it replaces the item's earlier link; a record
 // linked elsewhere moves here.
-export async function linkPriceItem(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId = null }) {
+async function writeLink(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId }) {
   const item = await loadItem(db, organisationId, priceItemId);
   const catalogue = catalogues.get(system);
   if (!catalogue) throw new FlowError('conflict', `${system} is not connected, or its price list has not been read yet`);
   const record = catalogue.byId.get(String(externalId ?? ''));
   if (!record) throw notFound(`${catalogue.name} record`);
-  const link = await db.transaction(async (tx) => {
+  return db.transaction(async (tx) => {
     await tx.delete(priceItemLinks).where(and(
       eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.system, system), eq(priceItemLinks.externalId, String(record.id)),
     ));
@@ -194,10 +194,35 @@ export async function linkPriceItem(db, organisationId, priceItemId, { system, e
     }).returning();
     return row;
   });
+}
+
+export async function linkPriceItem(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId = null }) {
+  const link = await writeLink(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId });
   await remapJobs(db, organisationId);
   return link;
 }
 
+// Many links at once (Reconcile prices, "Link sure matches"): each one as
+// linkPriceItem makes it, then one remap. A link that fails stops the rest;
+// the ones before it stay.
+export const MAX_LINKS_AT_ONCE = 500;
+export async function linkPriceItems(db, organisationId, links, { catalogues, personId = null }) {
+  if (!Array.isArray(links) || !links.length) throw invalid('links must be a list of { priceItemId, system, externalId }');
+  if (links.length > MAX_LINKS_AT_ONCE) throw invalid(`${MAX_LINKS_AT_ONCE} links at once at most`);
+  const made = [];
+  try {
+    for (const link of links) {
+      if (!link || typeof link !== 'object' || !link.priceItemId || !link.system || !link.externalId) {
+        throw invalid('each link needs priceItemId, system and externalId');
+      }
+      made.push(await writeLink(db, organisationId, link.priceItemId, link, { catalogues, personId }));
+    }
+  } finally {
+    if (made.length) await remapJobs(db, organisationId);
+  }
+  return made;
+}
+
 export async function unlinkPriceItem(db, organisationId, linkId) {
   const rows = await db.delete(priceItemLinks)
     .where(and(eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.id, linkId))).returning();

package/server/core/read-before-act.js

@@ -30,11 +30,12 @@ const NO_LONGER_BILLABLE = 'the work system no longer reports the job as billabl
 // Answers Map(obligationId -> { outcome, obligation, reason? }), where
 // outcome is fresh (no read needed), read, review (sent to review) or
 // waiting (the read could not run).
-export async function readBeforeAct(db, organisationId, obligations, { work, now = new Date(), actor }) {
+// `force` reads even a fresh report (a person's "Recheck").
+export async function readBeforeAct(db, organisationId, obligations, { work, now = new Date(), actor, force = false }) {
   const outcomes = new Map();
   let toJob = null;
   for (const obligation of obligations) {
-    if (!needsRead(obligation, { work, now })) {
+    if (!needsRead(obligation, { work, now: force ? new Date(8.64e15) : now })) {
       outcomes.set(obligation.id, { outcome: 'fresh', obligation });
       continue;
     }

package/server/core/sending.js

@@ -3,19 +3,19 @@ import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
 import { billingObligations, invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
 import { issueInvoice } from './invoices.js';
+import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
 import { soleOrganisation } from './pipeline.js';
 import { needsRead, readAccountingFirst, readBeforeAct, READS_PER_PASS } from './read-before-act.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
-// Drafts, Problem, Ready and Send all ready (docs/INVOICE_SENDING.md).
+// Pending, Ready and Send all ready (docs/INVOICE_SENDING.md).
 //
 // Flow checks every draft. It checks its own data first: the draft has lines,
 // a total above zero, and a price item (or, for a line such as a rush
 // charge, an account) on every line. When an accounting
 // system is connected, its own checks are added (for Xero: the customer
 // matches one Xero contact, every item is in Xero). A draft with a problem is
-// in Problem. A person marks a draft without one ready. A saved change keeps
-// it ready; only Move to Drafts (markNotReady) takes it back.
+// Pending (the "problem" view). A draft without one is Ready.
 //
 // Send all ready issues every ready draft (each gets its number) and, when an
 // accounting system is connected, queues it to go there. The send worker
@@ -35,19 +35,35 @@ const LEASE_MS = 15 * 60 * 1000;
 // Outcomes that mean the accounting system holds the invoice.
 const SENT = new Set(['created', 'reconciled', 'existing', 'already_in_xero']);
 
-const problem = (code, message) => ({ code, message });
+// `short` is the few words the Invoices list shows; `message` says how to fix it.
+const problem = (code, message, short = null) => ({ code, message, ...(short ? { short } : {}) });
 
 // Flow's own checks of one draft. `lines` are its invoice lines.
 export function draftProblems(invoice, lines) {
   const problems = [];
-  if (!lines.length) problems.push(problem('no_lines', 'The invoice has no lines.'));
-  else if (invoice.totalCents <= 0) problems.push(problem('no_amount', 'The total is $0.00 or less.'));
+  if (!lines.length) problems.push(problem('no_lines', 'The invoice has no lines.', 'No lines'));
+  else if (invoice.totalCents <= 0) problems.push(problem('no_amount', 'The total is $0.00 or less.', 'Total $0'));
   for (const line of lines) {
-    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`));
+    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`, `Line ${line.position}: no item`));
   }
   return problems;
 }
 
+// The few words for a job in review: what changed, for this job.
+export function reviewShort(obligation) {
+  if (obligation.holdReason === STATUS_BACK_REASON) return 'Status moved back';
+  if (obligation.holdReason !== CHANGED_REASON) return /deleted/.test(obligation.holdReason ?? '') ? 'Job deleted' : 'Job needs a look';
+  const basis = obligation.draftBasis;
+  if (!basis) return 'Job changed';
+  const changes = diffJobLines(basis.lines ?? [], obligation.lines ?? []);
+  const words = changes.map((c) => (['added', 'removed'].includes(c.change)
+    ? `Line ${c.position} ${c.change}`
+    : `Line ${c.position} ${{ item: 'item', description: 'text', quantity: 'qty', price: 'price' }[c.fields[0]] ?? 'changed'}`));
+  if ((basis.contactId ?? null) !== (obligation.contactId ?? null)) words.unshift('Client changed');
+  if (!words.length) return 'Job changed';
+  return words.length > 1 ? `${words[0]} +${words.length - 1}` : words[0];
+}
+
 // Flow's checks, and the accounting system's, for some drafts. Answers
 // Map(id -> problems) holding only the drafts that have one.
 async function checkDrafts(db, organisationId, drafts, accounting) {
@@ -63,11 +79,11 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
   }
   // A draft whose job the ledger sent to review (the job changed after the
   // draft was made, or the work system deleted it) waits for a person.
-  const reviewed = await db.select({ invoiceId: billingObligations.invoiceId, reason: billingObligations.holdReason })
-    .from(billingObligations)
+  const reviewed = await db.select().from(billingObligations)
     .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids), eq(billingObligations.holdState, 'review')));
-  for (const { invoiceId, reason } of reviewed) {
-    const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`);
+  for (const obligation of reviewed) {
+    const { invoiceId, holdReason: reason } = obligation;
+    const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`, reviewShort(obligation));
     problems.set(invoiceId, [...(problems.get(invoiceId) ?? []), found]);
   }
   if (accounting) {
@@ -80,8 +96,8 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
 }
 
 // The views of the Invoices page. `accounting` is the accounting adapter, or
-// null. Every draft is in one view: Problem (a check failed), Ready (a person
-// marked it ready) or To check (the rest). An issued invoice is Sending while
+// null. Every draft is in one view: Problem (a check failed; the Pending tab)
+// or Ready (its checks pass). An issued invoice is Sending while
 // queued, and a Problem when the accounting system refused it. Answers
 // { toCheck: [ids], ready: [ids], problems: Map(id -> problems), sending: Set(ids) }.
 export async function invoiceViews(db, organisationId, { accounting = null } = {}) {
@@ -96,12 +112,14 @@ export async function invoiceViews(db, organisationId, { accounting = null } = {
     .orderBy(desc(invoices.sendUpdatedAt));
   for (const row of issued) {
     if (row.sendState === 'queued') sending.add(row.id);
-    else problems.set(row.id, [row.sendError ?? problem('send_failed', 'Sending failed.')]);
+    else problems.set(row.id, [row.sendError ?? problem('send_failed', 'Sending failed.', 'Send failed')]);
   }
+  // A draft whose checks pass is ready (Samuel, 2026-10-20): no person
+  // needs to mark it. toCheck stays for callers that still read it.
   const clean = drafts.filter((d) => !problems.has(d.id));
   return {
-    toCheck: clean.filter((d) => !d.readyAt).map((d) => d.id),
-    ready: clean.filter((d) => d.readyAt).map((d) => d.id),
+    toCheck: [],
+    ready: clean.map((d) => d.id),
     problems,
     sending,
   };
@@ -112,11 +130,11 @@ export async function invoiceView(db, organisationId, invoice, { accounting = nu
   if (invoice.status === 'void') return { view: null, problems: [] };
   if (invoice.status === 'issued') {
     if (invoice.sendState === 'queued') return { view: 'sending', problems: [] };
-    if (invoice.sendState === 'failed') return { view: 'problem', problems: [invoice.sendError ?? problem('send_failed', 'Sending failed.')] };
+    if (invoice.sendState === 'failed') return { view: 'problem', problems: [invoice.sendError ?? problem('send_failed', 'Sending failed.', 'Send failed')] };
     return { view: null, problems: [] };
   }
   const found = (await checkDrafts(db, organisationId, [invoice], accounting)).get(invoice.id) ?? [];
-  return { view: found.length ? 'problem' : invoice.readyAt ? 'ready' : 'to_check', problems: found };
+  return { view: found.length ? 'problem' : 'ready', problems: found };
 }
 
 // Mark ready: a person checked these drafts. A draft with a problem stays

package/server/db/doctor.js

@@ -12,12 +12,10 @@ import { migrationsTable } from '../integrations/schema.js';
 //   - the tables in public that neither declares (another app's, or an
 //     earlier Flow's).
 //
-// On Replit it runs on the workspace's database after each update
-// (scripts/replit-deploy.sh), and compares that database with the live app's
-// GET /health, which reports the same migration counts. Replit's publish step
-// offers to make production's tables match the workspace's, so the
-// comparison says what that step will show (docs/REPLIT.md, "The workspace
-// updater"). Anyone who runs Flow can run it: `flow-server doctor`.
+// On Replit, `flow-server doctor --live <address>` compares the workspace's
+// database with the live app's GET /health, which reports the same migration
+// counts, and says what Replit's publish step will show (docs/REPLIT.md, "The
+// workspace database"). Anyone who runs Flow can run it: `flow-server doctor`.
 
 const CORE_MIGRATIONS = fileURLToPath(new URL('./migrations', import.meta.url));
 const CORE_TABLE = '__drizzle_migrations';
@@ -114,26 +112,27 @@ export async function diagnoseDatabase(pool, { adapters = [] } = {}) {
   };
 }
 
-// What Replit's publish step will offer, from the workspace's report and the
+// What Replit's publish step will show, from the workspace's report and the
 // live app's migration counts (GET /health's schema.migrations, or null when
-// the live app could not say).
+// the live app could not say). Flow migrates production itself when it
+// starts, so the answer to "Development database changes detected" is always
+// Cancel (docs/REPLIT.md, "The workspace database").
 //
-//   broken  the workspace database is not at this build: do not publish
-//   behind  production has migrations the workspace lacks: the list would
-//           drop them, so Cancel and update the workspace first
-//   adds    the workspace is ahead: the list holds additions only; approve
 //   same    the two match: no list
-//   unknown the live app did not say: approve additions, Cancel a DROP
+//   behind  production has migrations the workspace lacks: follow production
+//   ahead   the workspace has migrations production does not run
+//   unknown the live app did not say
+export const CANCEL_RULE = 'If Replit shows "Development database changes detected", press Cancel.';
+
 export function publishVerdict(report, live) {
-  if (!report.ok) return { verdict: 'broken', say: 'The workspace database is not at this build. Do not publish. Update the workspace again.' };
-  if (!live) return { verdict: 'unknown', say: 'The live app did not report its migrations. Publish: approve a list of additions; Cancel any DROP.' };
+  if (!live) return { verdict: 'unknown', say: `The live app did not report its migrations. ${CANCEL_RULE}` };
   const behind = Object.entries(live).filter(([id, n]) => n > (report.migrations[id] ?? 0)).map(([id]) => id);
-  if (behind.length) {
-    return { verdict: 'behind', say: `Production has ${behind.join(', ')} migrations the workspace lacks. Do not publish: Replit would offer to DROP them. Update the workspace first.` };
-  }
   const ahead = Object.entries(report.migrations).filter(([id, n]) => n > (live[id] ?? 0)).map(([id]) => id);
   if (ahead.length) {
-    return { verdict: 'adds', say: `The workspace is ahead of production (${ahead.join(', ')}). Publish: Replit offers to add tables or columns only. Approve.` };
+    return { verdict: 'ahead', say: `The workspace has ${ahead.join(', ')} migrations production does not run. ${CANCEL_RULE} Production applies its own migrations when it starts.` };
+  }
+  if (behind.length) {
+    return { verdict: 'behind', say: `Production has ${behind.join(', ')} migrations the workspace lacks. Run npm run db:follow-production (or press Run). ${CANCEL_RULE}` };
   }
   return { verdict: 'same', say: 'The workspace and production are at the same migrations. Publish: Replit shows no database changes.' };
 }

package/server/db/index.js

@@ -6,6 +6,13 @@ import * as schema from './schema.js';
 
 const migrationsFolder = fileURLToPath(new URL('./migrations', import.meta.url));
 
+// Session advisory lock held while any migration runs (Flow's own, each
+// integration's, and the Replit workspace sync), so two processes sharing one
+// database never apply the same migration at once. Field uses the same
+// pattern with its own key.
+export const MIGRATION_LOCK_KEY = 7_139_000_101n;
+const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 300_000;
+
 // Opens Flow's PostgreSQL database. The caller owns the pool: call close().
 export function openDatabase({ url = process.env.DATABASE_URL, max = 10 } = {}) {
   if (!url) throw new Error('flow: DATABASE_URL is not set');
@@ -14,8 +21,72 @@ export function openDatabase({ url = process.env.DATABASE_URL, max = 10 } = {})
   return { db, pool, close: () => pool.end() };
 }
 
-export function migrateDatabase(db) {
-  return migrate(db, { migrationsFolder });
+// A transaction-mode pooler (PgBouncer, Neon's "-pooler" hosts) does not keep
+// a session, so it cannot hold a session lock. Neon names a pooled endpoint
+// by adding "-pooler" to the endpoint id; the same host without it is the
+// direct endpoint, which migrations use instead (as Field does).
+const POOLER_HOST = /-pooler(?=\.|$)/i;
+
+export function directUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (!POOLER_HOST.test(parsed.hostname)) return null;
+  parsed.hostname = parsed.hostname.replace(POOLER_HOST, '');
+  return parsed.toString();
+}
+
+function migrationLockTimeoutMs(env = process.env) {
+  const value = Number.parseInt(env.FLOW_DB_MIGRATION_LOCK_TIMEOUT_MS || '', 10);
+  return Number.isInteger(value) && value >= 0 ? value : DEFAULT_MIGRATION_LOCK_TIMEOUT_MS;
+}
+
+// Runs fn(lockedDb) under MIGRATION_LOCK_KEY. The lock and fn share one
+// connection taken from db's pool (or the pooler's direct endpoint), because
+// a session lock belongs to one connection. It waits up to
+// FLOW_DB_MIGRATION_LOCK_TIMEOUT_MS (300000) for another process to finish.
+export async function withMigrationLock(db, fn, { timeoutMs = migrationLockTimeoutMs() } = {}) {
+  const source = db?.$client;
+  if (!source) throw new Error('flow: a migration needs a PostgreSQL database from openDatabase');
+  const direct = source instanceof pg.Pool ? directUrl(source.options?.connectionString) : null;
+  let client;
+  if (direct) {
+    client = new pg.Client({ connectionString: direct });
+    await client.connect();
+  } else {
+    client = source instanceof pg.Pool ? await source.connect() : source;
+  }
+  let broken = false;
+  try {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const { rows } = await client.query('select pg_try_advisory_lock($1::bigint) as locked', [MIGRATION_LOCK_KEY.toString()]);
+      if (rows[0].locked) break;
+      if (Date.now() >= deadline) {
+        throw new Error(`flow: another process held the migration lock (advisory lock ${MIGRATION_LOCK_KEY}) for over ${timeoutMs} ms; is a migration hung? (FLOW_DB_MIGRATION_LOCK_TIMEOUT_MS)`);
+      }
+      await new Promise((wake) => setTimeout(wake, 250));
+    }
+    try {
+      return await fn(drizzle(client, { schema }));
+    } finally {
+      // A connection that cannot unlock is closed, which also frees the lock.
+      await client.query('select pg_advisory_unlock($1::bigint)', [MIGRATION_LOCK_KEY.toString()]).catch(() => { broken = true; });
+    }
+  } finally {
+    if (direct) await client.end().catch(() => {});
+    else if (client !== source) client.release(broken);
+  }
+}
+
+// Applies the migrations in `folder` (this build's own by default) under the
+// migration lock. `table` names the journal: drizzle.__drizzle_migrations for
+// Flow's own, one per integration (server/integrations/schema.js).
+export function migrateDatabase(db, { folder = migrationsFolder, table } = {}) {
+  return withMigrationLock(db, (locked) => migrate(locked, { migrationsFolder: folder, ...(table ? { migrationsTable: table } : {}) }));
 }
 
-export { schema };
+export { migrationsFolder, schema };

package/server/db/migrate-all.js

@@ -3,10 +3,9 @@ import { adapters as shipped } from '../integrations/adapters.js';
 import { migrateAdapterSchema } from '../integrations/schema.js';
 
 // Brings a database up to this build: the core migrations, then the tables
-// of every adapter this build ships, whether or not it is on. On Replit the
-// workspace's database runs this before a publish (scripts/replit-deploy.sh
-// update-workspace), so it holds every table production can hold and
-// publishing never offers to drop one (docs/REPLIT.md).
+// of every adapter this build ships, whether or not it is on
+// (`flow-server migrate`). Not for a Replit workspace: its database follows
+// production instead (scripts/replit-workspace-db.js, docs/REPLIT.md).
 export async function migrateEverything(db, { adapters = shipped, log = () => {} } = {}) {
   await migrateDatabase(db);
   for (const adapter of adapters) {

package/server/db/migrations/0020_custom_field_colours.sql

@@ -0,0 +1,21 @@
+CREATE TABLE IF NOT EXISTS "job_field_settings" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL,
+	"group_colors" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"assignee_made_at" timestamp with time zone,
+	"updated_by" uuid,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "job_fields" ADD COLUMN IF NOT EXISTS "color" text;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_field_settings" ADD CONSTRAINT "job_field_settings_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_field_settings" ADD CONSTRAINT "job_field_settings_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_fields" ADD CONSTRAINT "job_fields_color_valid" CHECK ("job_fields"."color" is null or "job_fields"."color" in ('gray', 'blue', 'teal', 'green', 'amber', 'red', 'purple', 'pink'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;