@arcforgelabs/flow 2026.11.1 → 2026.11.3

package/SECURITY.md

@@ -31,6 +31,17 @@ paste a credential, in full or in part.
   person/client/organisation read grant. The first slice exposes four bounded read tools
   (`docs/AGENT_ACCESS.md`). The reserved `/api/flow/v1` stub still refuses all
   requests. It does not implement connector keys.
+- **AI assistant key.** Also off by default. When the host sets
+  `FLOW_AGENT_KEY_SHA256` and `FLOW_AGENT_EMAIL`, one bearer key acts as one
+  Flow person, inside that person's role, on `/api/me`, `/api/invoicing/…`,
+  `/api/xero/…` (never connect or disconnect), `GET /api/seazona/api/…` and the Seazona history import `/api/seazona/history…` only (`docs/AGENT_ACCESS.md`, "AI assistant key").
+  With the admin role that includes invoice writes: rules, void, delete draft
+  and send to the accounting system. Flow stores only the key's SHA-256; the key
+  stays with the assistant. Owner actions always refuse the key. Turning the
+  person off stops the key on the next request and stops sends it queued. The
+  Seazona read answers what Seazona gives, patient fields included; the owner
+  can turn on "Hide patient details" to drop them. Use an assistant whose model
+  runs locally or with zero data retention.
 - **Integrations.** Seazona, Xero and every later adapter reach the core only
   through the integration port. Their credentials are stored per
   organisation, encrypted, and are write-only in Settings.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.11.1",
+  "version": "2026.11.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.11.1",
+      "version": "2026.11.3",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.11.1",
+  "version": "2026.11.3",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,7 @@
   },
   "files": [
     "server/",
+    "skills/",
     "SECURITY.md",
     "VISION.md",
     "npm-shrinkwrap.json"

package/server/api/invoicing.js

@@ -4,6 +4,7 @@ import { invoiceKindOf, invoicePage, INVOICE_SORTS, normaliseInvoicesView } from
 import { fieldIdOf, filterRows } from '../ui/job-view.js';
 import { listFields, listJobFieldValues } from '../core/custom-fields.js';
 import { FlowError } from '../core/errors.js';
+import { listReview } from '../core/review.js';
 import { createActionGuard } from '../integrations/call-guard.js';
 import {
   createDraftInvoice, deleteDraft, getInvoice, issueInvoice, listInvoiceVersions, reviseInvoice, updateDraftInvoice, voidInvoice,
@@ -27,7 +28,7 @@ import {
   acceptFindings, archivePriceItem, checkPrices, createPriceItem, linkPriceItem, linkPriceItems, MAX_LINKS_AT_ONCE, readCatalogues, readPriceList, unlinkPriceItem, updatePriceItem,
 } from '../core/price-list.js';
 import {
-  confirmNoInvoice, draftInvoiceForObligation, explainObligation, jobChangeFor, linkJobToInvoice, listObligations,
+  confirmNoInvoice, draftInvoiceForObligation, freeVoidedJob, setHold, explainObligation, jobChangeFor, linkJobToInvoice, listObligations,
   setReady, settleJobChange, useSourceLines,
 } from '../core/ledger.js';
 import { isHistoryHeld } from '../core/history.js';
@@ -99,6 +100,8 @@ import {
 //   PUT   /contacts/:id/billing       owner or admin: change them (null takes the organisation's)
 //   POST  /jobs/:id/ready             { ready }: mark a job ready to invoice, or back in work
 //   GET   /jobs/:id/activity          what happened to a job, newest first
+//   POST  /jobs/:id/hold              owner or admin: { state: none|held|review, reason }
+//   POST  /jobs/:id/free              owner or admin: { reason }: let go of a void invoice, then hold
 //   POST  /jobs/:id/draft             owner or admin: a job's draft invoice, after a live
 //                                     check that the accounting system holds none
 //
@@ -313,7 +316,7 @@ async function jobChangeDetail(db, organisationId, invoiceId, work) {
   const link = typeof source?.capabilities.jobLink === 'function'
     ? source.capabilities.jobLink({ sourceJobRef: change.sourceJobRef, sourceInvoiceRef: change.sourceInvoiceRef })
     : null;
-  return { ...change, contact, systemName: source?.name ?? change.sourceSystem, link: link ?? null };
+  return { ...change, contact, systemName: source?.name ?? change.sourceSystem, link: link ?? null, canRecheck: typeof source?.capabilities?.readWorkItem === 'function' };
 }
 
 // Each invoice's tab (TABS): Map(id -> tab), the ids on each tab, the
@@ -783,18 +786,35 @@ export function createInvoicingRouter({
     const source = work().find((a) => a.id === obligation.sourceSystem) ?? null;
     if (typeof source?.capabilities?.readWorkItem !== 'function') throw new FlowError('not_ready', 'the work system cannot read one job');
     // One read for each job in RECHECK_GAP_MS, whatever the clicks.
-    const last = rechecked.get(obligationId) ?? 0;
+    const last = rechecked.get(obligationId);
+    const retryAfter = (entry) => Math.max(1, Math.ceil((RECHECK_GAP_MS - (Date.now() - entry.at)) / 1000));
     let outcome = 'fresh';
-    if (Date.now() - last >= RECHECK_GAP_MS) {
-      rechecked.set(obligationId, Date.now());
-      const actor = `person:${req.person.id}`;
-      const read = (await readBeforeAct(db, organisationId, [obligation], { work: source, actor, force: true })).get(obligationId);
-      outcome = 'read';
-      if (read.outcome === 'waiting') throw new FlowError('not_ready', `${source.name} could not be read: ${read.reason ?? 'try again soon'}`);
-      await settleJobChange(db, organisationId, obligationId, { actor });
+    if (last && (last.state === 'reading' || Date.now() - last.at < RECHECK_GAP_MS)) {
+      if (last.state !== 'read') {
+        const retryAfterSeconds = retryAfter(last);
+        throw new FlowError('not_ready', last.state === 'reading'
+          ? 'No new source read. The previous recheck is still running. Wait, then recheck again.'
+          : 'No new source read. Wait ' + retryAfterSeconds + ' seconds, then recheck again. Previous error: ' + last.error,
+        { outcome: last.state === 'reading' ? 'read_in_progress' : 'cached_failed', retryAfterSeconds });
+      }
+    } else {
+      const entry = { at: Date.now(), state: 'reading', error: null };
+      rechecked.set(obligationId, entry);
+      const actor = 'person:' + req.person.id;
+      try {
+        const read = (await readBeforeAct(db, organisationId, [obligation], { work: source, actor, force: true })).get(obligationId);
+        if (read.outcome === 'waiting') throw new FlowError('not_ready', source.name + ' could not be read: ' + (read.reason ?? 'the source is unavailable') + '. Wait, then recheck again.');
+        await settleJobChange(db, organisationId, obligationId, { actor });
+        entry.state = 'read';
+        outcome = 'read';
+      } catch (error) {
+        entry.state = 'failed';
+        entry.error = error instanceof FlowError ? error.message : 'The source recheck failed. Wait, then recheck again.';
+        throw new FlowError('not_ready', entry.error, { retryAfterSeconds: retryAfter(entry) });
+      }
     }
     const invoice = obligation.invoiceId ? await invoiceDetail(db, organisationId, obligation.invoiceId, accounting(), work()) : null;
-    res.json({ ok: true, outcome, invoice });
+    res.json({ ok: true, outcome, retryAfterSeconds: retryAfter(rechecked.get(obligationId)), invoice });
   }));
 
   // A job with no invoice whose match is unclear (ledger.js). The linking
@@ -808,6 +828,23 @@ export function createInvoicingRouter({
     res.json({ ok: true, ...await listReconcile(db, organisationId) });
   }));
 
+  // The open review queue (core/review.js): daily reconcile days, job
+  // changes, links Flow could not prove, failed writes. Read only: each item
+  // closes when its cause is fixed (or by the screen that owns it).
+  router.get('/review', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const state = text(req.query.state) || 'open';
+    if (!['open', 'resolved', 'dismissed'].includes(state)) throw new FlowError('invalid', 'state must be open, resolved or dismissed');
+    const kind = text(req.query.kind) || undefined;
+    const limit = Math.min(Math.max(Number.parseInt(text(req.query.limit) || '100', 10) || 100, 1), 500);
+    const items = await listReview(db, organisationId, { state, kind, limit });
+    res.json({ ok: true, items: items.map((r) => ({
+      id: r.id, kind: r.kind, entity: r.entity, flowId: r.flowId, systems: r.systems, evidence: r.evidence,
+      moneyAtRiskCents: r.moneyAtRiskCents, seenCount: r.seenCount, state: r.state, resolution: r.resolution,
+      createdAt: r.createdAt, updatedAt: r.updatedAt,
+    })) });
+  }));
+
   router.get('/jobs/:id/reconcile', ...signedIn, handle(log, async (req, res) => {
     const obligationId = pathId(req.params.id, 'job');
     const organisationId = await organisationOf(req);
@@ -831,10 +868,39 @@ export function createInvoicingRouter({
   router.post('/jobs/:id/no-invoice', ...manager, handle(log, async (req, res) => {
     const obligationId = pathId(req.params.id, 'job');
     const organisationId = await organisationOf(req);
-    const job = await confirmNoInvoice(db, organisationId, obligationId, { actor: `person:${req.person.id}` });
+    const job = await confirmNoInvoice(db, organisationId, obligationId, { actor: `person:${req.person.id}`, system: accounting()?.id ?? null });
     res.json({ ok: true, job: { id: job.id, accountingState: job.accountingState } });
   }));
 
+  // Holds a job, sends it to review, or releases it (state "none"). Every
+  // change needs a reason, kept in the job's activity.
+  router.post('/jobs/:id/hold', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const state = text(req.body?.state);
+    const reason = text(req.body?.reason);
+    if (!['none', 'held', 'review'].includes(state)) throw invalid('state must be none, held or review');
+    if (!reason) throw invalid('a reason is required');
+    const [current] = await db.select({ holdState: billingObligations.holdState, holdReason: billingObligations.holdReason }).from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+    if (state === 'none' && isHistoryHeld(current)) {
+      throw invalid('this is a history-import hold: settle it with the history import decisions');
+    }
+    const job = await setHold(db, organisationId, obligationId, { holdState: state, reason, actor: `person:${req.person.id}` });
+    res.json({ ok: true, job: { id: job.id, holdState: job.holdState, holdReason: job.holdReason } });
+  }));
+
+  // Frees a job stuck on a void Flow invoice, or on an accounting invoice that
+  // was voided or deleted there. The job goes on hold until a person releases it.
+  router.post('/jobs/:id/free', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const reason = text(req.body?.reason);
+    if (!reason) throw invalid('a reason is required');
+    const job = await freeVoidedJob(db, organisationId, obligationId, { actor: `person:${req.person.id}`, reason, system: accounting()?.id ?? null });
+    res.json({ ok: true, job: { id: job.id, invoiceId: job.invoiceId, accountingState: job.accountingState, holdState: job.holdState, holdReason: job.holdReason } });
+  }));
+
   // Links a job to a Flow invoice that already exists.
   router.post('/jobs/:id/link', ...manager, handle(log, async (req, res) => {
     const obligationId = pathId(req.params.id, 'job');

package/server/auth/routes.js

@@ -1,3 +1,4 @@
+import { readFile } from 'node:fs/promises';
 import express from 'express';
 import { FlowError } from '../core/errors.js';
 import { rateLimit } from '../rate-limit.js';
@@ -18,6 +19,9 @@ import {
   updatePerson,
 } from './people.js';
 import { isPlainEmail } from './settings.js';
+
+// The files of skills/flow that GET /api/agent-skill/flow/<file> serves.
+const SKILL_FILES = { 'SKILL.md': 'text/markdown', 'flow.sh': 'text/x-shellscript' };
 import { APP_PATHS, appPage } from '../ui/app-page.js';
 import { navPinsFromViews } from '../ui/nav-pins.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -110,6 +114,22 @@ export function createSignInRouter({ settings, db, clerk, personAuth, defaultFam
     res.json(body);
   });
 
+  // The AI assistant's own skill, from the Flow it talks to, so the skill
+  // always matches this Flow's routes (`flow.sh update`). Only the two skill
+  // files; the release that runs here is the one they come from.
+  router.get('/api/agent-skill/flow/:file', requireSession, async (req, res) => {
+    const file = SKILL_FILES[req.params.file];
+    if (!file) return res.status(404).json({ ok: false, code: 'not_found', error: 'No such skill file.' });
+    try {
+      const text = await readFile(new URL(`../../skills/flow/${req.params.file}`, import.meta.url), 'utf8');
+      res.set('Cache-Control', 'no-store');
+      res.type(file).send(text);
+    } catch (error) {
+      log.error?.(`[auth] skill file ${req.params.file} unreadable: ${error.message}`);
+      res.status(503).json({ ok: false, code: 'skill_unavailable', error: 'This Flow has no skill files.' });
+    }
+  });
+
   // Each person sets their own appearance; it follows their account.
   router.put('/api/me/appearance', requireSession, express.json({ limit: '4kb' }), async (req, res) => {
     try {

package/server/auth/session.js

@@ -1,3 +1,4 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
 import { displayNameOf, googleWorkspaceOwner, primaryEmailOf, secondFactorVerified } from './clerk.js';
 import { fillPersonName, findPersonByClerkId, findPersonByEmail, linkPerson, recordPendingPerson } from './people.js';
 import { DEFAULT_OWNER_MFA_MAX_AGE_MINUTES, isPlainEmail } from './settings.js';
@@ -52,6 +53,7 @@ export function createPersonAuth({
   log = console,
   now = Date.now,
   clerkUserCacheMs = 60 * 1000,
+  agentKey = null,
 }) {
   if (!db) throw new Error('createPersonAuth: db is required');
   if (!clerk?.authenticate || !clerk?.getUser) throw new Error('createPersonAuth: a Clerk adapter is required');
@@ -118,7 +120,9 @@ export function createPersonAuth({
   // Every person route starts here. The session token must be in the
   // Authorization header; Clerk verifies it, and Flow checks its expiry too.
   async function requireSession(req, res, next) {
-    if (!bearerToken(req)) return deny(res, 'signed_out');
+    const token = bearerToken(req);
+    if (!token) return deny(res, 'signed_out');
+    if (agentKey && isAgentKey(token)) return agentSession(req, res, next);
     let auth;
     try {
       auth = await clerk.authenticate(req);
@@ -145,6 +149,37 @@ export function createPersonAuth({
     return next();
   }
 
+  // The AI assistant key (FLOW_AGENT_KEY). It acts as one Flow person, and
+  // only inside that person's role. Owner actions stay with people: an agent
+  // request is never a verified owner sign-in.
+  // Keys shorter than 32 characters are refused, so a digest of a short
+  // guess never matches.
+  const agentDigest = agentKey ? Buffer.from(agentKey.digest, 'hex') : null;
+  function isAgentKey(token) {
+    return token.length >= 32 && timingSafeEqual(createHash('sha256').update(token).digest(), agentDigest);
+  }
+  // The key opens only these routes: invoicing, Xero (owner routes refuse it
+  // below), the Seazona read, the Seazona history import, /api/me and its own
+  // skill files.
+  const AGENT_PATHS = /^\/api\/(?:me$|invoicing\/|xero\/|seazona\/(?:api|history)(?:\/|$)|agent-skill\/flow\/)/;
+  async function agentSession(req, res, next) {
+    if (!AGENT_PATHS.test(`${req.baseUrl}${req.path}`)) return deny(res, 'role_required');
+    let person;
+    try {
+      person = await findPersonByEmail(db, agentKey.email);
+    } catch (error) {
+      log.error?.(`[auth] Flow agent person lookup failed: ${error.message}`);
+      return deny(res, 'sign_in_unavailable');
+    }
+    if (!person) return deny(res, 'not_invited');
+    if (person.status !== 'active') return deny(res, 'access_disabled');
+    req.person = person;
+    req.clerkAuth = null;
+    req.agent = true;
+    log.info?.(`[auth] agent key: ${req.method} ${req.baseUrl}${req.path} as Flow person ${person.id} (${person.role})`);
+    return next();
+  }
+
   function requireRole(...roles) {
     return (req, res, next) => (roles.includes(req.person?.role) ? next() : deny(res, 'role_required'));
   }
@@ -165,6 +200,7 @@ export function createPersonAuth({
   //       (Replit's managed Clerk, which has no MFA).
   // A Clerk error fails closed. Returns { verified, by } or { unavailable }.
   async function ownerVerification(person, auth) {
+    if (!auth) return { verified: false, by: null };
     if (secondFactorVerified(auth, ownerMfaMaxAgeMinutes)) return { verified: true, by: 'second_factor' };
     if (!ownerGoogleDomains.length) return { verified: false, by: null };
     try {
@@ -182,6 +218,7 @@ export function createPersonAuth({
   // requireSession.
   async function requireOwner(req, res, next) {
     if (req.person?.role !== 'owner') return deny(res, 'owner_required');
+    if (req.agent) return deny(res, 'owner_verification_required', ownerMessage);
     const check = await ownerVerification(req.person, req.clerkAuth);
     if (check.unavailable) return deny(res, 'sign_in_unavailable');
     if (!check.verified) return deny(res, 'owner_verification_required', ownerMessage);

package/server/auth/settings.js

@@ -127,6 +127,21 @@ export function isPlainEmail(email) {
   return typeof email === 'string' && /^[\x21-\x3f\x41-\x7e]+@[a-z0-9.-]+\.[a-z0-9-]+$/i.test(email);
 }
 
+// FLOW_AGENT_KEY_SHA256 and FLOW_AGENT_EMAIL: one key for one AI assistant
+// (an OpenClaw Gateway). A request with `Authorization: Bearer <key>`, where
+// the key's SHA-256 is FLOW_AGENT_KEY_SHA256, acts as the Flow person with
+// FLOW_AGENT_EMAIL, inside that person's role. Flow holds only the digest, so
+// the key itself never leaves the assistant's machine. Both or neither.
+export function resolveAgentKey(env = process.env) {
+  const digest = readEnv(env, 'FLOW_AGENT_KEY_SHA256').toLowerCase();
+  const email = readEnv(env, 'FLOW_AGENT_EMAIL').toLowerCase();
+  if (!digest && !email) return null;
+  if (!digest || !email) throw new Error('FLOW_AGENT_KEY_SHA256 and FLOW_AGENT_EMAIL must be set together');
+  if (!/^[0-9a-f]{64}$/.test(digest)) throw new Error('FLOW_AGENT_KEY_SHA256 must be 64 hex characters (the SHA-256 of the key)');
+  if (!isPlainEmail(email)) throw new Error('FLOW_AGENT_EMAIL must be a plain (ASCII) email address');
+  return { digest, email };
+}
+
 export function resolveSignInSettings(env = process.env) {
   const mode = resolveAuthMode(env);
   if (mode === 'off') return { mode };
@@ -139,5 +154,6 @@ export function resolveSignInSettings(env = process.env) {
     ownerGoogleDomains: parseOwnerGoogleDomains(readEnv(env, 'FLOW_OWNER_GOOGLE_DOMAINS')),
     authorizedParties: resolveAuthorizedParties(env),
     firstOwnerEmail: resolveFirstOwnerEmail(env),
+    agentKey: resolveAgentKey(env),
   };
 }

package/server/core/invoice-rules.js

@@ -197,15 +197,24 @@ function matches(condition, job, context) {
 // The reasons the enabled rules give for one job, in rule order. An empty list
 // means no rule stops its draft. `customer` is the customer's own billing
 // settings (invoicing-rules.js).
-export function ruleReasons(rules, job, { customer = {}, now = new Date() } = {}) {
-  const context = { customer, now };
-  const reasons = [];
-  for (const rule of rules) {
-    if (!rule.enabled || rule.trigger !== 'job_ready' || ['pending', 'non_chargeable'].includes(rule.action.kind)) continue;
-    if (!rule.conditions.every((c) => matches(c, job, context))) continue;
-    reasons.push(rule.action.kind === 'skip' ? `rule "${rule.name}": not drafted by rule` : `rule "${rule.name}": waits for a person`);
-  }
-  return reasons;
+const waitingRules = (rules, job, { customer = {}, now = new Date() } = {}) => rules
+  .filter((rule) => rule.enabled && rule.trigger === 'job_ready' && !['pending', 'non_chargeable'].includes(rule.action.kind))
+  .filter((rule) => rule.conditions.every((c) => matches(c, job, { customer, now })));
+const waitMessage = (rule) => rule.action.kind === 'skip'
+  ? `rule "${rule.name}": not drafted by rule` : `rule "${rule.name}": waits for a person`;
+
+// Keep the text-only reason API for draft checks, including evaluation of
+// starter rules before they are saved. Selection/text have one owner here.
+export function ruleReasons(rules, job, options) {
+  return waitingRules(rules, job, options).map(waitMessage);
+}
+
+// Pending work needs the saved rule identity, just as a Pending invoice does.
+export function ruleWait(rules, job, options) {
+  return waitingRules(rules, job, options).map((rule) => ({ code: 'rule',
+    message: waitMessage(rule), short: rule.name.slice(0, 40), rule: rule.id,
+    resolution: ruleResolution(rule),
+  }));
 }
 
 // The notes of the enabled pending rules that match one draft, as problems:
@@ -213,12 +222,17 @@ export function ruleReasons(rules, job, { customer = {}, now = new Date() } = {}
 // `reference`, the draft's Reference. A pending rule never stops a draft.
 // `fields` names the fields the rule reads, so the invoice page marks the
 // one to fix (the Reference box goes red).
+const ruleResolution = (rule) => {
+  if (!rule.id) throw new FlowError('warning_resolution_required', 'A Pending rule needs its saved rule to resolve it.');
+  return { kind: 'rule_review' };
+};
+
 export function rulePending(rules, job, { customer = {}, now = new Date() } = {}) {
   const context = { customer, now };
   return rules
     .filter((r) => r.enabled && r.trigger === 'job_ready' && r.action.kind === 'pending')
     .filter((r) => r.conditions.every((c) => matches(c, job, context)))
-    .map((r) => ({ code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null, fields: [...new Set(r.conditions.map((c) => c.field))] }));
+    .map((r) => ({ code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null, fields: [...new Set(r.conditions.map((c) => c.field))], resolution: ruleResolution(r) }));
 }
 
 // Drafts an enabled skip rule matches stay on Pending at Send (sending.js).
@@ -236,6 +250,7 @@ export function ruleSkip(rules, job, { customer = {}, now = new Date() } = {}) {
       short: r.name.slice(0, 40),
       rule: r.id ?? null,
       fields: [...new Set(r.conditions.map((c) => c.field))],
+      resolution: ruleResolution(r),
     }));
 }
 

package/server/core/job-board.js

@@ -1,6 +1,6 @@
 import { and, eq, inArray, isNull } from 'drizzle-orm';
 import { contacts, invoices, priceItems, reviewItems } from '../db/schema.js';
-import { listRules } from './invoice-rules.js';
+import { listRules, ruleWait } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings, ruleBlockers } from './invoicing-rules.js';
 import { REVIEW_CHANGED, listObligations } from './ledger.js';
 import { isHistoryHeld } from './history.js';
@@ -54,8 +54,16 @@ export async function describeObligations(db, organisationId, listed, { accounti
       : views.sending.has(id) ? 'sending' : null);
   // The invoicing rules a job with no invoice waits on, for every view a
   // draft can still come from.
-  const waitingFor = (o, v) => (o.invoiceId || !['in_work', 'ready', 'pending', 'held'].includes(v)
-    ? [] : ruleBlockers(o, { ...effectiveSettings(settings, customers.get(o.contactId)), name: nameOf.get(o.contactId) ?? null }, { rules }));
+  const waiting = (o, v) => {
+    if (o.invoiceId || !['in_work', 'ready', 'pending', 'held'].includes(v)) return { waitingFor: [], waitingRules: [] };
+    const customer = { ...effectiveSettings(settings, customers.get(o.contactId)), name: nameOf.get(o.contactId) ?? null };
+    const waitingRules = ruleWait(rules, o, { customer });
+    // Keep the existing text projection for API consumers; links use identity.
+    return { waitingRules, waitingFor: [
+      ...ruleBlockers(o, customer),
+      ...waitingRules.map((problem) => problem.message),
+    ] };
+  };
   return listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, draftBasis: _basis, ...o }, view, reasons }) => ({
     ...o,
     canUseNewLines: offers.has(o.id),
@@ -66,7 +74,7 @@ export async function describeObligations(db, organisationId, listed, { accounti
     invoiceProblems: (o.invoiceId && views?.problems.get(o.invoiceId)) || [],
     view,
     reasons,
-    waitingFor: waitingFor(o, view),
+    ...waiting(o, view),
   }));
 }
 

package/server/core/job-match.js

@@ -101,8 +101,9 @@ export async function listReconcile(db, organisationId) {
     status: billingObligations.sourceStatus,
     sourceSystem: billingObligations.sourceSystem,
     sourceJobRef: billingObligations.sourceJobRef,
-    // An unclear accounting match: "Make invoice" settles it first.
-    unclear: sql`${billingObligations.accountingState} = 'ambiguous'`.mapWith(Boolean),
+    // An unclear accounting match, or a matched accounting invoice that was
+    // voided or deleted there: "Make invoice" settles it first.
+    unclear: sql`${billingObligations.accountingState} in ('ambiguous', 'voided', 'deleted') and ${billingObligations.invoiceId} is null`.mapWith(Boolean),
     possible: sql`(select count(*) from invoices i
       where i.organisation_id = ${billingObligations.organisationId} and i.contact_id = ${billingObligations.contactId}
         and i.status <> 'void' and i.total_cents = ${billingObligations.totalCents}
@@ -152,8 +153,9 @@ export async function jobMatchDetail(db, organisationId, obligationId, { referen
     lines: jobLines(o, codes),
     totalCents: o.totalCents,
     open: !o.invoiceId && !o.accountingRef,
-    // An unclear accounting match: "Make invoice" settles it first.
-    unclear: o.accountingState === 'ambiguous',
+    // An unclear accounting match, or a matched accounting invoice that was
+    // voided or deleted there: "Make invoice" settles it first.
+    unclear: !o.invoiceId && ['ambiguous', 'voided', 'deleted'].includes(o.accountingState),
   };
 
   const search = String(q ?? '').trim();

package/server/core/ledger.js

@@ -349,7 +349,7 @@ async function compareWithDraft(tx, organisationId, obligation, facts) {
   }
   const flow = { lines: invoice.lines, contactId: invoice.contactId };
   const compare = compareThreeWays(base, facts, flow, { sent: invoiceSent(invoice, obligation) });
-  return { ...compare, base, flow, invoiceStatus: invoice.status };
+  return { ...compare, base, flow, invoiceStatus: invoice.status, invoiceTotals: { subtotalCents: invoice.subtotalCents, taxCents: invoice.taxCents, totalCents: invoice.totalCents } };
 }
 
 function changedReview(obligation, compare) {
@@ -479,17 +479,29 @@ export function diffJobLines(wasLines = [], nowLines = []) {
   return changes.sort((a, b) => a.position - b.position || (a.change === 'removed' ? -1 : 1));
 }
 
-// The open "job changed" problem of an invoice, for the invoice page, or
+// The open job-change or source-billing problem, for the invoice page, or
 // null: the job as it was when the invoice was made, as the work system has
 // it now, and whether a person can adopt the change into Flow's own draft
 // ("Adopt changes", useSourceLines). An invoice drafted before the basis was
 // kept compares with the invoice's own lines.
 export async function jobChangeFor(db, organisationId, invoiceId) {
   const [obligation] = await db.select().from(billingObligations)
-    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId),
-      eq(billingObligations.holdState, 'review'), eq(billingObligations.holdReason, CHANGED_REASON)));
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId)));
   if (!obligation) return null;
+  const changed = obligation.holdState === 'review' && obligation.holdReason === CHANGED_REASON;
+  const sourceProblems = sourceBillingProblems(obligation);
+  if (!changed && !sourceProblems.length) return null;
   const compare = await compareWithDraft(db, organisationId, obligation, obligation);
+  // Source review is only for Flow's draft. Issued documents keep the existing
+  // job-change/accounting comparison, never a new source-resolution action.
+  const sourceReview = sourceProblems.length && compare.invoiceStatus === 'draft' ? {
+    sourceTotals: obligation.sourceTotals ?? null,
+    reconstructed: { ...invoiceTotals(obligation.lines), ...(obligation.lines.some((line) => line.taxCode === null) ? { taxCents: null, totalCents: null } : {}) },
+    unknownTaxLines: obligation.lines.flatMap((line, index) => line.taxCode === null
+      ? [{ position: index + 1, description: line.description, itemCode: line.itemCode ?? null }] : []),
+    savedInvoice: compare.invoiceTotals,
+  } : null;
+  if (!changed && !sourceReview) return null;
   const was = obligation.draftBasis
     ?? (compare.flow ? { lines: compare.flow.lines, contactId: compare.flow.contactId, totalCents: null } : basisOf(obligation));
   return {
@@ -497,13 +509,15 @@ export async function jobChangeFor(db, organisationId, invoiceId) {
     sourceSystem: obligation.sourceSystem,
     sourceJobRef: obligation.sourceJobRef,
     sourceInvoiceRef: obligation.sourceInvoiceRef,
+    caseRef: obligation.caseRef,
+    sourceReview,
     seenAt: obligation.sourceSeenAt,
     outcome: compare.outcome,
     sent: compare.sent,
-    canAdopt: compare.outcome === 'offer',
+    canAdopt: !sourceReview && 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,
+    canAccept: !sourceReview && !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 },
@@ -755,7 +769,51 @@ export async function setHold(db, organisationId, obligationId, { holdState, rea
     const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
     const row = await update(tx, obligation, { holdState, holdReason: holdState === 'none' ? null : reason.trim() });
     await addEvent(tx, row, holdState === 'none' ? 'released' : holdState, actor, {
-      from: obligation.holdState, reason: row.holdReason,
+      from: obligation.holdState, reason: holdState === 'none' ? (reason?.trim() || null) : row.holdReason,
+    });
+    return row;
+  });
+}
+
+const GONE_STATES = ['voided', 'deleted'];
+
+// A person (or the assistant, after the lab says yes) frees a job that is
+// stuck on an invoice that bills nothing now: a Flow invoice that was voided,
+// or an accounting invoice that was voided or deleted there. The job lets go
+// of that invoice and goes on hold, so nothing drafts until a person releases
+// it (setHold to 'none'). A Flow invoice that is still live must be voided
+// first: this never voids or changes an invoice.
+export async function freeVoidedJob(db, organisationId, obligationId, { actor, reason, system = null }) {
+  requireActor(actor);
+  if (!reason?.trim()) throw new FlowError('invalid', 'say why the job is freed');
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    let flowInvoice = null;
+    if (obligation.invoiceId) {
+      [flowInvoice] = await tx.select({ id: invoices.id, number: invoices.number, status: invoices.status }).from(invoices)
+        .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, obligation.invoiceId)));
+      if (flowInvoice && flowInvoice.status !== 'void') {
+        throw new FlowError('invalid', `Flow invoice ${flowInvoice.number ?? flowInvoice.id} is ${flowInvoice.status}: void it first, then free the job`);
+      }
+    }
+    const gone = GONE_STATES.includes(obligation.accountingState) ? obligation.accountingRef : null;
+    if (!flowInvoice && !gone) throw new FlowError('invalid', 'the job is not linked to a void or deleted invoice');
+    const row = await update(tx, obligation, {
+      ...(flowInvoice ? { invoiceId: null, draftBasis: null } : {}),
+      ...(gone || GONE_STATES.includes(obligation.accountingState)
+        ? { accountingState: 'not_found', accountingRef: null, accountingUrl: null, accountingMatchedBy: null, accountingCheckedAt: sql`now()` }
+        : {}),
+      holdState: 'held',
+      holdReason: reason.trim(),
+    });
+    if (gone && system) {
+      await tx.insert(linkRejections).values({ organisationId, obligationId: obligation.id, system, externalId: gone, actor }).onConflictDoNothing();
+    }
+    await addEvent(tx, row, 'freed', actor, {
+      reason: reason.trim(),
+      ...(flowInvoice ? { invoiceId: flowInvoice.id } : {}),
+      ...(gone ? { released: gone } : {}),
+      from: obligation.holdState,
     });
     return row;
   });
@@ -763,9 +821,10 @@ export async function setHold(db, organisationId, obligationId, { holdState, rea
 
 // A job with no invoice of its own whose accounting evidence is ambiguous:
 // the matcher found accounting invoices that may be this job's, but none
-// exactly. A person settles it on the Reconcile page: "Make invoice", or a
-// link to a Flow invoice (linkJobToInvoice).
-const unlinked = (o) => o.accountingState === 'ambiguous' && !o.invoiceId && !o.accountingRef;
+// exactly. Or the accounting invoice the matcher linked was voided or deleted
+// there: it bills nothing now. A person settles it on the Reconcile page or
+// the job: "Make invoice", or a link to a Flow invoice (linkJobToInvoice).
+const unlinked = (o) => !o.invoiceId && (GONE_STATES.includes(o.accountingState) || (o.accountingState === 'ambiguous' && !o.accountingRef));
 
 // The matcher's open suggestions for one job, best first.
 export async function linkSuggestionsFor(db, organisationId, obligationId) {
@@ -800,14 +859,26 @@ async function rejectSuggestions(tx, obligation, { actor }) {
 // "Make invoice": a person says the job has no invoice yet. Every suggestion
 // is rejected and the job is recorded as not found, so it can draft. The
 // live check before the draft still runs (draftInvoiceForObligation).
-export async function confirmNoInvoice(db, organisationId, obligationId, { actor }) {
+// `system` is the accounting system's id: a released voided or deleted link
+// becomes that person's "not this one" too, so the matcher never offers it.
+export async function confirmNoInvoice(db, organisationId, obligationId, { actor, system = null }) {
   requireActor(actor);
   return db.transaction(async (tx) => {
     const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
     if (!unlinked(obligation)) throw new FlowError('invalid', 'the job is not waiting for a person to settle its invoice');
     const rejected = await rejectSuggestions(tx, obligation, { actor });
-    const row = await update(tx, obligation, { accountingState: 'not_found', accountingCheckedAt: sql`now()` });
-    await addEvent(tx, row, 'accounting_checked', actor, { reported: 'not_found', state: 'not_found', matchedBy: 'person', rejected });
+    // A voided or deleted link is let go, so the matcher stops following it.
+    const gone = GONE_STATES.includes(obligation.accountingState) ? obligation.accountingRef : null;
+    const row = await update(tx, obligation, {
+      accountingState: 'not_found', accountingCheckedAt: sql`now()`,
+      ...(gone ? { accountingRef: null, accountingUrl: null, accountingMatchedBy: null } : {}),
+    });
+    if (gone && system) {
+      await tx.insert(linkRejections).values({ organisationId, obligationId: obligation.id, system, externalId: gone, actor }).onConflictDoNothing();
+    }
+    await addEvent(tx, row, 'accounting_checked', actor, {
+      reported: 'not_found', state: 'not_found', matchedBy: 'person', rejected, ...(gone ? { released: gone } : {}),
+    });
     return row;
   });
 }