@arcforgelabs/flow 2026.11.2 → 2026.11.4

package/SECURITY.md

@@ -31,6 +31,18 @@ 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` (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
+  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.2",
+  "version": "2026.11.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.11.2",
+      "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.2",
+  "version": "2026.11.4",
   "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/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

@@ -4,13 +4,14 @@ 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,
 } 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,
@@ -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
 //
@@ -380,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;
@@ -825,6 +850,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);
@@ -848,10 +890,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');
@@ -971,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/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,8 @@ export function createPersonAuth({
   log = console,
   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');
@@ -118,7 +121,10 @@ 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');
+    const agent = agentKeys.length ? agentKeyFor(token) : null;
+    if (agent) return agentSession(req, res, next, agent);
     let auth;
     try {
       auth = await clerk.authenticate(req);
@@ -145,6 +151,41 @@ export function createPersonAuth({
     return next();
   }
 
+  // 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 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, agent) {
+    if (!AGENT_PATHS.test(`${req.baseUrl}${req.path}`)) return deny(res, 'role_required');
+    let person;
+    try {
+      person = await findPersonByEmail(db, agent.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 +206,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 +224,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,32 @@ 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, 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(`${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 };
@@ -139,5 +165,6 @@ export function resolveSignInSettings(env = process.env) {
     ownerGoogleDomains: parseOwnerGoogleDomains(readEnv(env, 'FLOW_OWNER_GOOGLE_DOMAINS')),
     authorizedParties: resolveAuthorizedParties(env),
     firstOwnerEmail: resolveFirstOwnerEmail(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;