@arcforgelabs/flow 2026.11.3 → 2026.11.4

package/SECURITY.md

@@ -32,7 +32,8 @@ paste a credential, in full or in part.
   (`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_AGENT_KEY_SHA256` and `FLOW_AGENT_EMAIL` (and at most one more pair,
+  `FLOW_AGENT_KEY_SHA256_2` and `FLOW_AGENT_EMAIL_2`), each bearer key acts as its own
   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

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.11.3",
+  "version": "2026.11.4",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/agents/gate.js

@@ -6,7 +6,21 @@ import { agentLimits } from './settings.js';
 export function createAgentGate({ pool, verify, resource, limits: input, log = console }) {
   const limits = agentLimits(input);
   let active = 0, pruneAfter = 0;
-  const running = new Map();
+  const running = new Map(), waiting = new Set();
+  const capacity = () => Math.min(limits.fleet, Math.max(0,(pool.options?.max ?? 10)-1));
+  // A lease stays held through the audit after a response. A call that comes
+  // while a lease is only auditing waits up to a second for it, then is refused.
+  const lease = async () => {
+    const until = Date.now() + 1000;
+    while (active >= capacity()) {
+      const left = until - Date.now();
+      if (left <= 0) return false;
+      await new Promise(resolve => { const timer = setTimeout(done, left); function done() { clearTimeout(timer); waiting.delete(done); resolve(); } waiting.add(done); });
+    }
+    active++;
+    return true;
+  };
+  const unlease = () => { active--; for (const wake of [...waiting]) wake(); };
   const fail = (res, status, code) => {
     if (res.writableEnded || res.destroyed) return;
     if ([429,503].includes(status) && !res.hasHeader('Retry-After')) res.set('Retry-After', '60');
@@ -35,8 +49,7 @@ export function createAgentGate({ pool, verify, resource, limits: input, log = c
     }
   }
   const handle = handler => async (req,res) => {
-    if (active >= Math.min(limits.fleet, Math.max(0,(pool.options?.max ?? 10)-1))) return fail(res,429,'agent_capacity');
-    active++;
+    if (!await lease()) return fail(res,429,'agent_capacity');
     const started = Date.now(), controller = new AbortController();
     let client, acquiring, grant, ownConcurrency = false, status = 200, count = 0, tool = 'protocol', expired = false;
     // pg.Pool has no per-acquisition cancellation. Bound only the MCP wait,
@@ -104,6 +117,14 @@ export function createAgentGate({ pool, verify, resource, limits: input, log = c
       check();
       await handler(req,res);
     })();
+    // The grant's slot covers its work, not the audit after the response: a
+    // client that sends its next call at once must not meet its own last call.
+    const freed = () => {
+      if (!ownConcurrency) return;
+      ownConcurrency = false;
+      const n = running.get(grant.id) - 1; n ? running.set(grant.id,n) : running.delete(grant.id);
+    };
+    work.then(freed, freed);
     try { await Promise.race([work,deadline]); }
     catch { if (!expired) { status=503; fail(res,503,'agent_unavailable'); } }
     finally {
@@ -122,8 +143,7 @@ export function createAgentGate({ pool, verify, resource, limits: input, log = c
         }
       } catch { if (client) { client.release(true); client=undefined; } log.warn?.('[mcp] audit unavailable'); }
       await Promise.allSettled([acquiring]);
-      if (ownConcurrency) { const n=running.get(grant.id)-1; n ? running.set(grant.id,n) : running.delete(grant.id); }
-      active--;
+      unlease();
     }
   };
   return { handle, fail, limits };

package/server/api/invoicing.js

@@ -11,7 +11,7 @@ import {
 } from '../core/invoices.js';
 import { listAutomations, saveAutomation, workStatuses } from '../core/automations.js';
 import {
-  ACTIONS, createRule, deleteRule, FIELDS, listRules, TESTS, updateRule,
+  ACTIONS, addRuleItem, createRule, deleteRule, exceptDraft, exceptJob, FIELDS, jobRuleExceptions, listRuleExceptions, listRules, removeRuleException, TESTS, updateRule,
 } from '../core/invoice-rules.js';
 import {
   createMapping, deleteMapping, listMappings, STEP_LABELS, STEPS, updateMapping,
@@ -383,12 +383,34 @@ async function invoiceDetail(db, organisationId, invoiceId, accounting = null, w
       : null,
     contact: contact ?? null,
     job: withLink(jobs.get(invoiceId) ?? null, work),
+    // Lines this invoice has and its job in the work system does not (a
+    // rule's added shipping, for example). Flow cannot write lines to the
+    // work system, so the page shows the gap until the work system has them.
+    sourceGap: await sourceGap(db, organisationId, invoice),
+    // The exceptions people gave this invoice's job, current or ended.
+    ruleExceptions: await exceptionsOfInvoice(db, organisationId, invoice),
     // The Linked card: each connected system, and this invoice's link there.
     linksTo: linkedSystems(work, accounting),
     versions: versions.map(({ version, issuedAt, issuedBy }) => ({ version, issuedAt, issuedBy })),
   };
 }
 
+async function exceptionsOfInvoice(db, organisationId, invoice) {
+  const [job] = await db.select({ id: billingObligations.id }).from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoice.id)));
+  return job ? jobRuleExceptions(db, organisationId, job.id) : [];
+}
+
+async function sourceGap(db, organisationId, invoice) {
+  if (invoice.status === 'void') return [];
+  const [job] = await db.select({ lines: billingObligations.lines }).from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoice.id)));
+  if (!job) return [];
+  const inSource = new Set((job.lines ?? []).map((l) => l.priceItemId).filter(Boolean));
+  return invoice.lines.filter((l) => l.priceItemId && !inSource.has(l.priceItemId))
+    .map((l) => ({ description: l.description, quantity: l.quantity, unitAmountCents: l.unitAmountCents }));
+}
+
 // A person's Recheck reads a job from its work system at most once in this
 // time; a second click inside it answers from Flow's copy.
 const RECHECK_GAP_MS = 10 * 1000;
@@ -1020,6 +1042,51 @@ export function createInvoicingRouter({
     res.json({ ok: true });
   }));
 
+  // Exceptions (docs/INVOICE_RULES.md): each job a person let through although
+  // the rule matched, with who, when and why.
+  router.get('/rules/:id/exceptions', ...signedIn, handle(log, async (req, res) => {
+    const ruleId = pathId(req.params.id, 'rule');
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, exceptions: await listRuleExceptions(db, organisationId, ruleId) });
+  }));
+
+  router.delete('/rules/:id/exceptions/:exceptionId', ...manager, handle(log, async (req, res) => {
+    const ruleId = pathId(req.params.id, 'rule');
+    const exceptionId = pathId(req.params.exceptionId, 'exception');
+    const organisationId = await organisationOf(req);
+    await removeRuleException(db, organisationId, ruleId, exceptionId, { actor: `person:${req.person.id}` });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} removed exception ${exceptionId} from rule ${ruleId}`);
+    res.json({ ok: true });
+  }));
+
+  // A Pending draft's rule fix: add the rule's item, or skip with a reason.
+  router.post('/invoices/:id/rules/:ruleId/add-item', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const ruleId = pathId(req.params.ruleId, 'rule');
+    const organisationId = await organisationOf(req);
+    await addRuleItem(db, organisationId, invoiceId, ruleId);
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} added rule ${ruleId}'s item to invoice ${invoiceId}`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting(), work()) });
+  }));
+
+  router.post('/invoices/:id/rules/:ruleId/exception', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const ruleId = pathId(req.params.ruleId, 'rule');
+    const organisationId = await organisationOf(req);
+    await exceptDraft(db, organisationId, invoiceId, ruleId, { reason: req.body?.reason, actor: `person:${req.person.id}` });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} made an exception to rule ${ruleId} for invoice ${invoiceId}`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting(), work()) });
+  }));
+
+  router.post('/jobs/:id/rules/:ruleId/exception', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const ruleId = pathId(req.params.ruleId, 'rule');
+    const organisationId = await organisationOf(req);
+    const exception = await exceptJob(db, organisationId, obligationId, ruleId, { reason: req.body?.reason, actor: `person:${req.person.id}` });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} made an exception to rule ${ruleId} for job ${obligationId}`);
+    res.json({ ok: true, exception });
+  }));
+
   router.get('/line-mappings', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
     res.json({ ok: true, mappings: await listMappings(db, organisationId), steps: STEPS.map((key) => ({ key, label: STEP_LABELS[key] })) });

package/server/app.js

@@ -8,7 +8,7 @@ import { createWorkMovesRouter } from './api/work-moves.js';
 import { createConnectorApi } from './api/connector.js';
 import { createInvoicingRouter } from './api/invoicing.js';
 import { createSignInRouter } from './auth/routes.js';
-import { integrationAlertsSource, invoiceProblemsSource, priceDifferencesSource } from './core/alerts.js';
+import { integrationAlertsSource, invoiceProblemsSource, jobGapsSource, priceDifferencesSource } from './core/alerts.js';
 import { boardJobs } from './core/job-board.js';
 import { reconcileHealth } from './core/reconcile.js';
 import { appliedMigrationCounts } from './db/doctor.js';
@@ -154,7 +154,7 @@ export function createApp({
   if (database && auth?.personAuth) {
     const liveCheckFor = (organisationId) => {
       const [adapter] = integrations?.with('checkInvoice') ?? [];
-      return adapter ? (obligation) => adapter.capabilities.checkInvoice({ organisationId, obligation }) : null;
+      return adapter ? (obligation, { reference = null } = {}) => adapter.capabilities.checkInvoice({ organisationId, obligation, reference }) : null;
     };
     // Send all ready (server/core/sending.js): the first enabled integration
     // that sends invoices (Xero).
@@ -184,6 +184,7 @@ export function createApp({
       personAuth: auth.personAuth,
       log,
       sources: {
+        jobs: [jobGapsSource(database.db)],
         invoices: [invoiceProblemsSource(database.db, { accounting })],
         'price-list': [priceDifferencesSource(database.db)],
         integrations: [integrationAlertsSource(() => integrations?.with('alerts') ?? [])],

package/server/auth/session.js

@@ -54,6 +54,7 @@ export function createPersonAuth({
   now = Date.now,
   clerkUserCacheMs = 60 * 1000,
   agentKey = null,
+  agentKeys = agentKey ? [agentKey] : [],
 }) {
   if (!db) throw new Error('createPersonAuth: db is required');
   if (!clerk?.authenticate || !clerk?.getUser) throw new Error('createPersonAuth: a Clerk adapter is required');
@@ -122,7 +123,8 @@ export function createPersonAuth({
   async function requireSession(req, res, next) {
     const token = bearerToken(req);
     if (!token) return deny(res, 'signed_out');
-    if (agentKey && isAgentKey(token)) return agentSession(req, res, next);
+    const agent = agentKeys.length ? agentKeyFor(token) : null;
+    if (agent) return agentSession(req, res, next, agent);
     let auth;
     try {
       auth = await clerk.authenticate(req);
@@ -149,24 +151,28 @@ export function createPersonAuth({
     return next();
   }
 
-  // The AI assistant key (FLOW_AGENT_KEY). It acts as one Flow person, and
+  // The AI assistant keys (FLOW_AGENT_KEY_SHA256, and _2). Each acts as its own 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);
+  const agentDigests = agentKeys.map((key) => ({ email: key.email, digest: Buffer.from(key.digest, 'hex') }));
+  function agentKeyFor(token) {
+    if (token.length < 32) return null;
+    const hash = createHash('sha256').update(token).digest();
+    let found = null;
+    for (const key of agentDigests) if (timingSafeEqual(hash, key.digest)) found = key;
+    return found;
   }
   // 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) {
+  async function agentSession(req, res, next, agent) {
     if (!AGENT_PATHS.test(`${req.baseUrl}${req.path}`)) return deny(res, 'role_required');
     let person;
     try {
-      person = await findPersonByEmail(db, agentKey.email);
+      person = await findPersonByEmail(db, agent.email);
     } catch (error) {
       log.error?.(`[auth] Flow agent person lookup failed: ${error.message}`);
       return deny(res, 'sign_in_unavailable');

package/server/auth/settings.js

@@ -132,16 +132,27 @@ export function isPlainEmail(email) {
 // 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();
+export function resolveAgentKey(env = process.env, suffix = '') {
+  const digestName = `FLOW_AGENT_KEY_SHA256${suffix}`;
+  const emailName = `FLOW_AGENT_EMAIL${suffix}`;
+  const digest = readEnv(env, digestName).toLowerCase();
+  const email = readEnv(env, emailName).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');
+  if (!digest || !email) throw new Error(`${digestName} and ${emailName} must be set together`);
+  if (!/^[0-9a-f]{64}$/.test(digest)) throw new Error(`${digestName} must be 64 hex characters (the SHA-256 of the key)`);
+  if (!isPlainEmail(email)) throw new Error(`${emailName} must be a plain (ASCII) email address`);
   return { digest, email };
 }
 
+// Up to two assistant keys: the first pair, and a second pair with the
+// suffix _2. Each key acts as its own Flow person.
+export function resolveAgentKeys(env = process.env) {
+  const keys = [resolveAgentKey(env), resolveAgentKey(env, '_2')].filter(Boolean);
+  if (keys.length === 2 && keys[0].digest === keys[1].digest) throw new Error('FLOW_AGENT_KEY_SHA256_2 must differ from FLOW_AGENT_KEY_SHA256');
+  if (keys.length === 2 && keys[0].email === keys[1].email) throw new Error('FLOW_AGENT_EMAIL_2 must differ from FLOW_AGENT_EMAIL');
+  return keys;
+}
+
 export function resolveSignInSettings(env = process.env) {
   const mode = resolveAuthMode(env);
   if (mode === 'off') return { mode };
@@ -154,6 +165,6 @@ export function resolveSignInSettings(env = process.env) {
     ownerGoogleDomains: parseOwnerGoogleDomains(readEnv(env, 'FLOW_OWNER_GOOGLE_DOMAINS')),
     authorizedParties: resolveAuthorizedParties(env),
     firstOwnerEmail: resolveFirstOwnerEmail(env),
-    agentKey: resolveAgentKey(env),
+    agentKeys: resolveAgentKeys(env),
   };
 }

package/server/core/alerts.js

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
-import { and, eq, inArray, sql } from 'drizzle-orm';
-import { alertDismissals, invoices } from '../db/schema.js';
+import { and, asc, eq, inArray, isNull, lt, sql } from 'drizzle-orm';
+import { alertDismissals, billingObligations, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
+import { READY_GRACE_DAYS } from './reconcile.js';
 import { listReview } from './review.js';
 import { invoiceViews } from './sending.js';
 
@@ -19,7 +20,7 @@ import { invoiceViews } from './sending.js';
 // they never leave the server. `roles` are who may see it. `action`, when
 // there is one, is { label, href } or { label, tab } for a tab on the page.
 
-export const ALERT_PAGES = Object.freeze(['invoices', 'price-list', 'integrations']);
+export const ALERT_PAGES = Object.freeze(['jobs', 'invoices', 'price-list', 'integrations']);
 const ALL_ROLES = Object.freeze(['owner', 'admin', 'staff']);
 const MANAGERS = Object.freeze(['owner', 'admin']);
 const TONES = new Set(['warn', 'danger']);
@@ -41,6 +42,40 @@ function checkAlert(alert) {
 
 // ── Sources ────────────────────────────────────────────────────────────────
 
+// Jobs: finished jobs that nothing is billing. A job ready longer than the
+// daily reconcile's grace, with no Flow invoice, no accounting invoice and
+// no hold, opens Reconcile, where a person links its invoice or makes one.
+// A hold is how a person says "do not bill".
+export function jobGapsSource(db, { now = () => Date.now() } = {}) {
+  return async (organisationId) => {
+    const before = new Date(now() - READY_GRACE_DAYS * 86_400_000);
+    const unbilled = await db.select({ id: billingObligations.id, totalCents: billingObligations.totalCents })
+      .from(billingObligations)
+      .where(and(
+        eq(billingObligations.organisationId, organisationId),
+        isNull(billingObligations.invoiceId),
+        isNull(billingObligations.accountingRef),
+        eq(billingObligations.holdState, 'none'),
+        lt(billingObligations.readyAt, before),
+      ))
+      .orderBy(asc(billingObligations.readyAt))
+      .limit(MAX_MEMBERS);
+    const alerts = [];
+    if (unbilled.length) {
+      alerts.push({
+        key: 'jobs:not-invoiced',
+        page: 'jobs',
+        tone: 'warn',
+        title: `${plural(unbilled.length, 'finished job has', 'finished jobs have')} no invoice after ${READY_GRACE_DAYS} days.`,
+        action: { label: 'Open Reconcile', href: '/reconcile' },
+        moneyAtRiskCents: unbilled.reduce((sum, o) => sum + Number(o.totalCents ?? 0), 0),
+        members: unbilled.map((o) => o.id),
+      });
+    }
+    return alerts;
+  };
+}
+
 // Invoices: drafts a check stopped and issued invoices the accounting system
 // refused (server/core/sending.js). One alert for all of them.
 export function invoiceProblemsSource(db, { accounting = () => null } = {}) {

package/server/core/automations.js

@@ -1,4 +1,4 @@
-import { and, eq, sql } from 'drizzle-orm';
+import { and, asc, eq, sql } from 'drizzle-orm';
 import { automations, billingObligations, invoices } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { autoDraftJobs, readInvoicingSettings } from './invoicing-rules.js';
@@ -176,14 +176,19 @@ const actorOf = (key) => `automation:${key}`;
 // that job to people from then on.
 async function markReadyFromWorkStatus(db, organisationId, { statuses }) {
   const actor = actorOf('mark_ready_from_work_status');
+  const wanted = [...new Set(statuses.map(norm).filter(Boolean))];
+  if (!wanted.length) return { marked: 0 };
+  // The status test runs in the query, with the same normalising as
+  // statusMatches, so the batch holds only jobs to mark, oldest first: jobs
+  // still in work never fill it and push a shipped job out.
   const jobs = await db.select().from(billingObligations).where(and(
     eq(billingObligations.organisationId, organisationId),
     sql`${billingObligations.readyAt} is null`,
     sql`${billingObligations.invoiceId} is null`,
-    sql`${billingObligations.sourceStatus} is not null`,
+    sql`lower(regexp_replace(btrim(${billingObligations.sourceStatus}), '\\s+', ' ', 'g')) in (${sql.join(wanted.map((w) => sql`${w}`), sql`, `)})`,
     sql`not exists (select 1 from obligation_events e where e.obligation_id = ${billingObligations.id}
       and e.kind = 'in_work' and e.actor not like 'automation:%')`,
-  )).limit(BATCH);
+  )).orderBy(asc(billingObligations.createdAt)).limit(BATCH);
   let marked = 0;
   for (const job of jobs) {
     if (!statusMatches(job.sourceStatus, statuses)) continue;

package/server/core/invoice-rules.js

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import { and, asc, eq, sql } from 'drizzle-orm';
-import { invoiceRules, invoicingSettings } from '../db/schema.js';
+import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
+import { billingObligations, invoiceRuleExceptions, invoiceRules, invoicingSettings, obligationEvents, priceItems } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
+import { getInvoice, updateDraftInvoice } from './invoices.js';
 
 // Invoice rules (docs/INVOICE_RULES.md): a lab's own checks on a job before
 // Flow drafts its invoice. Each rule is When, If and Then, and a lab owner
@@ -62,7 +63,7 @@ export const FIELDS = Object.freeze({
   // one marker, so a new branch needs no new rule.
   customer: {
     label: 'Customer', kind: 'choice', options: 'customers',
-    tests: ['is', 'is_not', 'is_one_of', 'contains', 'does_not_contain', 'is_empty'],
+    tests: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'contains', 'does_not_contain', 'is_empty'],
     read: (j) => j.contactId,
   },
   customer_billable: { label: 'Customer is billable', kind: 'boolean', read: (j, { customer }) => customer.billable !== false },
@@ -73,7 +74,7 @@ export const FIELDS = Object.freeze({
 export const TESTS = Object.freeze({
   number: ['more_than', 'at_most', 'is', 'is_not', 'is_empty'],
   money: ['more_than', 'at_most', 'is', 'is_not'],
-  choice: ['is', 'is_not', 'is_one_of', 'is_empty'],
+  choice: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'is_empty'],
   text: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'contains', 'does_not_contain', 'starts_with', 'does_not_start_with', 'has_number', 'number_in_words', 'one_word', 'is_empty', 'is_not_empty'],
   boolean: ['is'],
   items: ['has', 'has_not'],
@@ -134,6 +135,13 @@ export function readRule(raw) {
     const note = typeof raw.action.note === 'string' ? raw.action.note.trim() : '';
     if (!note || note.length > MAX_NOTE) throw invalid(`a pending rule needs a note of ${MAX_NOTE} characters at most: what a person must fix`);
     action.note = note;
+    // The fix a person can take with one press: add this price list item to
+    // the draft (for example a shipping line the work system left off).
+    if (raw.action.addItem !== undefined && raw.action.addItem !== null) {
+      const item = typeof raw.action.addItem === 'string' ? raw.action.addItem.trim() : '';
+      if (!item || item.length > 40) throw invalid('addItem must be a price list code of 40 characters at most');
+      action.addItem = item;
+    }
   } else {
     const early = conditions.find((c) => FIELDS[c.field].draftOnly);
     if (early) throw invalid(`${FIELDS[early.field].label} is on the draft only: use Then "Pending, with a note"`);
@@ -189,6 +197,7 @@ function matches(condition, job, context) {
     default: {
       const left = norm(have);
       if (test === 'is_one_of') return value.some((v) => norm(v) === left);
+      if (test === 'is_not_one_of') return !value.some((v) => norm(v) === left);
       return test === 'is' ? left === norm(value) : left !== norm(value);
     }
   }
@@ -227,12 +236,21 @@ const ruleResolution = (rule) => {
   return { kind: 'rule_review' };
 };
 
+// A rule leaves a job alone when a person made an exception for it
+// (`job.ruleExceptions`, rule ids), or, for a rule with `addItem`, when the
+// draft already has that item (`job.draftItems`, codes): the fix was taken.
 export function rulePending(rules, job, { customer = {}, now = new Date() } = {}) {
   const context = { customer, now };
+  const excepted = new Set(job.ruleExceptions ?? []);
+  const onDraft = new Set((job.draftItems ?? []).map(norm));
   return rules
     .filter((r) => r.enabled && r.trigger === 'job_ready' && r.action.kind === 'pending')
+    .filter((r) => !excepted.has(r.id) && !(r.action.addItem && onDraft.has(norm(r.action.addItem))))
     .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))], resolution: ruleResolution(r) }));
+    .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), ...(r.action.addItem ? { addItem: r.action.addItem } : {}),
+    }));
 }
 
 // Drafts an enabled skip rule matches stay on Pending at Send (sending.js).
@@ -295,9 +313,9 @@ async function seed(db, organisationId) {
   });
 }
 
-const shape = (r) => ({
+const shape = (r, exceptions = 0) => ({
   id: r.id, name: r.name, icon: r.icon, position: r.position, enabled: r.enabled, trigger: r.trigger,
-  conditions: r.conditions, action: r.action, starter: Boolean(r.starterKey), updatedAt: r.updatedAt,
+  conditions: r.conditions, action: r.action, starter: Boolean(r.starterKey), updatedAt: r.updatedAt, exceptions,
 });
 
 // The organisation's rules, in order. The first read makes the starter rules.
@@ -307,11 +325,101 @@ export async function listRules(db, organisationId) {
   if (!settings?.seeded) await seed(db, organisationId);
   const rows = await db.select().from(invoiceRules).where(eq(invoiceRules.organisationId, organisationId))
     .orderBy(asc(invoiceRules.position), asc(invoiceRules.createdAt));
-  return rows.map(shape);
+  const counts = await db.select({ ruleId: invoiceRuleExceptions.ruleId, count: sql`count(*)::int` }).from(invoiceRuleExceptions)
+    .where(eq(invoiceRuleExceptions.organisationId, organisationId)).groupBy(invoiceRuleExceptions.ruleId);
+  const byRule = new Map(counts.map((c) => [c.ruleId, Number(c.count)]));
+  return rows.map((r) => shape(r, byRule.get(r.id) ?? 0));
+}
+
+// ── Exceptions ─────────────────────────────────────────────────────────────
+
+// A person says one job is fine although a rule matches it. The rule then
+// leaves the job alone. Only a rule with an item to add takes one: its Skip.
+// Each exception keeps who, when and why, stays listed on the rule, and is
+// in the job's history. It holds while the rule's item and the job's lines
+// stay as they were; a change to either ends it, so a person looks again.
+export async function addRuleException(db, organisationId, ruleId, obligationId, { reason, actor }) {
+  const why = typeof reason === 'string' ? reason.trim() : '';
+  if (!why || why.length > 200) throw invalid('an exception needs a reason of 1 to 200 characters');
+  if (!actor) throw invalid('actor is required');
+  const rule = await loadRule(db, organisationId, ruleId);
+  if (rule.action?.kind !== 'pending' || !rule.action.addItem) throw invalid('only a pending rule with an item to add takes an exception; change or turn off the rule');
+  return db.transaction(async (tx) => {
+    const [job] = await tx.select({ id: billingObligations.id, lineFingerprint: billingObligations.lineFingerprint }).from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId))).for('update');
+    if (!job) throw notFound('job');
+    const values = { reason: why, actor, itemCode: rule.action.addItem, lineFingerprint: job.lineFingerprint, createdAt: sql`now()` };
+    const [row] = await tx.insert(invoiceRuleExceptions).values({ organisationId, ruleId, obligationId, ...values })
+      .onConflictDoUpdate({ target: [invoiceRuleExceptions.ruleId, invoiceRuleExceptions.obligationId], set: values })
+      .returning();
+    await tx.insert(obligationEvents).values({ organisationId, obligationId, kind: 'rule_exception_added', actor,
+      evidence: { ruleId, rule: rule.name, item: rule.action.addItem, reason: why } });
+    return row;
+  });
+}
+
+// The rule ids each job has a current exception for, by job.
+export async function ruleExceptionsFor(db, organisationId, obligationIds) {
+  if (!obligationIds.length) return new Map();
+  const rows = await db.select({ ruleId: invoiceRuleExceptions.ruleId, obligationId: invoiceRuleExceptions.obligationId }).from(invoiceRuleExceptions)
+    .innerJoin(invoiceRules, eq(invoiceRules.id, invoiceRuleExceptions.ruleId))
+    .innerJoin(billingObligations, eq(billingObligations.id, invoiceRuleExceptions.obligationId))
+    .where(and(eq(invoiceRuleExceptions.organisationId, organisationId), inArray(invoiceRuleExceptions.obligationId, obligationIds), CURRENT));
+  const out = new Map();
+  for (const r of rows) out.set(r.obligationId, [...(out.get(r.obligationId) ?? []), r.ruleId]);
+  return out;
+}
+const CURRENT = sql`(${invoiceRuleExceptions.itemCode} is not distinct from (${invoiceRules.action} ->> 'addItem')
+  and ${invoiceRuleExceptions.lineFingerprint} is not distinct from ${billingObligations.lineFingerprint})`;
+
+// One rule's exceptions, newest first. `current` is false when the rule's
+// item or the job's lines changed since: the rule applies to that job again.
+export async function listRuleExceptions(db, organisationId, ruleId) {
+  await loadRule(db, organisationId, ruleId);
+  return db.select({ id: invoiceRuleExceptions.id, obligationId: invoiceRuleExceptions.obligationId, reason: invoiceRuleExceptions.reason,
+    actor: invoiceRuleExceptions.actor, itemCode: invoiceRuleExceptions.itemCode, createdAt: invoiceRuleExceptions.createdAt, current: sql`${CURRENT}`.mapWith(Boolean) })
+    .from(invoiceRuleExceptions)
+    .innerJoin(invoiceRules, eq(invoiceRules.id, invoiceRuleExceptions.ruleId))
+    .innerJoin(billingObligations, eq(billingObligations.id, invoiceRuleExceptions.obligationId))
+    .where(and(eq(invoiceRuleExceptions.organisationId, organisationId), eq(invoiceRuleExceptions.ruleId, ruleId)))
+    .orderBy(desc(invoiceRuleExceptions.createdAt));
+}
+
+// One job's exceptions, for its invoice page.
+export async function jobRuleExceptions(db, organisationId, obligationId) {
+  return db.select({ id: invoiceRuleExceptions.id, ruleId: invoiceRuleExceptions.ruleId, rule: invoiceRules.name, reason: invoiceRuleExceptions.reason,
+    actor: invoiceRuleExceptions.actor, itemCode: invoiceRuleExceptions.itemCode, createdAt: invoiceRuleExceptions.createdAt, current: sql`${CURRENT}`.mapWith(Boolean) })
+    .from(invoiceRuleExceptions)
+    .innerJoin(invoiceRules, eq(invoiceRules.id, invoiceRuleExceptions.ruleId))
+    .innerJoin(billingObligations, eq(billingObligations.id, invoiceRuleExceptions.obligationId))
+    .where(and(eq(invoiceRuleExceptions.organisationId, organisationId), eq(invoiceRuleExceptions.obligationId, obligationId)))
+    .orderBy(desc(invoiceRuleExceptions.createdAt));
+}
+
+// Takes an exception back: the rule applies to the job again.
+export async function removeRuleException(db, organisationId, ruleId, exceptionId, { actor = 'system' } = {}) {
+  return db.transaction(async (tx) => {
+    const [row] = await tx.delete(invoiceRuleExceptions).where(and(eq(invoiceRuleExceptions.organisationId, organisationId),
+      eq(invoiceRuleExceptions.ruleId, ruleId), eq(invoiceRuleExceptions.id, exceptionId))).returning();
+    if (!row) throw notFound('exception');
+    await tx.insert(obligationEvents).values({ organisationId, obligationId: row.obligationId, kind: 'rule_exception_removed', actor,
+      evidence: { ruleId, item: row.itemCode, reason: row.reason } });
+  });
+}
+
+// A rule's item must be on the price list, and not archived.
+async function checkRuleItem(db, organisationId, rule) {
+  const code = rule.action.addItem;
+  if (!code) return;
+  const [item] = await db.select({ archivedAt: priceItems.archivedAt }).from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), sql`upper(${priceItems.code}) = upper(${code})`));
+  if (!item) throw invalid(`the price list has no item ${code}`);
+  if (item.archivedAt) throw invalid(`price item ${code} is archived`);
 }
 
 export async function createRule(db, organisationId, raw, { personId = null } = {}) {
   const rule = readRule(raw);
+  await checkRuleItem(db, organisationId, rule);
   const existing = await listRules(db, organisationId);
   if (existing.length >= MAX_RULES) throw invalid(`an organisation can have ${MAX_RULES} rules at most`);
   const position = existing.length ? Math.max(...existing.map((r) => r.position)) + 1 : 0;
@@ -331,6 +439,7 @@ export async function updateRule(db, organisationId, ruleId, changes, { personId
   const row = await loadRule(db, organisationId, ruleId);
   if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the change must be an object');
   const rule = readRule({ name: row.name, icon: row.icon, enabled: row.enabled, conditions: row.conditions, action: row.action, ...changes });
+  if (rule.action.addItem && rule.action.addItem !== row.action?.addItem) await checkRuleItem(db, organisationId, rule);
   const [saved] = await db.update(invoiceRules).set({ ...rule, updatedBy: personId, updatedAt: sql`now()` })
     .where(eq(invoiceRules.id, row.id)).returning();
   return shape(saved);
@@ -340,3 +449,44 @@ export async function deleteRule(db, organisationId, ruleId) {
   const row = await loadRule(db, organisationId, ruleId);
   await db.delete(invoiceRules).where(eq(invoiceRules.id, row.id));
 }
+
+// ── A rule's one-press fix ─────────────────────────────────────────────────
+
+// "Add <item>" on a Pending draft: adds one of the rule's price list item to
+// the draft, at the price list's price. The rule then leaves the draft alone.
+// Flow never writes the line to the work system: the invoice page says the
+// job and the work system differ until the work system has it too.
+export async function addRuleItem(db, organisationId, invoiceId, ruleId) {
+  const rule = await loadRule(db, organisationId, ruleId);
+  const code = rule.action?.addItem;
+  if (!code || rule.action.kind !== 'pending') throw invalid('this rule has no item to add');
+  if (!rule.enabled) throw invalid('this rule is off');
+  const [item] = await db.select().from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), sql`upper(${priceItems.code}) = upper(${code})`));
+  if (!item) throw invalid(`the price list has no item ${code}`);
+  if (item.archivedAt) throw invalid(`price item ${code} is archived`);
+  // The lines are read under the draft's lock: a second press, or an edit at
+  // the same time, adds nothing twice and loses nothing.
+  await updateDraftInvoice(db, organisationId, invoiceId, {
+    lines: (current) => (current.some((l) => l.priceItemId === item.id) ? null : [
+      ...current.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
+        { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode })),
+      { priceItemId: item.id, quantity: 1 },
+    ]),
+  });
+  return getInvoice(db, organisationId, invoiceId);
+}
+
+// "Skip" on a Pending draft: an exception for the draft's job, with a reason.
+// The same, before the job has a draft: the job board shows the job needs an
+// item, and the person knows it does not (picked up, for example).
+export async function exceptJob(db, organisationId, obligationId, ruleId, { reason, actor }) {
+  return addRuleException(db, organisationId, ruleId, obligationId, { reason, actor });
+}
+
+export async function exceptDraft(db, organisationId, invoiceId, ruleId, { reason, actor }) {
+  const [job] = await db.select({ id: billingObligations.id }).from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId)));
+  if (!job) throw invalid('this invoice has no job; edit the invoice instead');
+  return addRuleException(db, organisationId, ruleId, job.id, { reason, actor });
+}