@burdenoff/microfe-movethewheels 2026.1101.4 → 2026.1102.2

package/src/movethewheels/components/freight-invoice/InvoiceReviewPanel.tsx

@@ -0,0 +1,319 @@
+import { useState } from 'react';
+import { Button } from '../ui';
+import { FreightSelect } from '../freight-cost/FreightFields';
+import { ReuseState, reuseCard } from '../ReuseControls';
+import { useConditionApi, useConditionQuery } from '../../hooks/useContainerCondition';
+import {
+  DecideInvoiceReviewDocument,
+  HandOffInvoiceSettlementDocument,
+  InvoiceReviewExactDocument,
+  RecordInvoiceSupplierResponseDocument,
+  ResolveInvoiceDisputeDocument,
+  type InvoiceReceiptFragment,
+  type InvoiceReviewExactQuery,
+  type InvoiceReviewFragment,
+  type MtwFreightInvoiceDecision,
+  type MtwFreightInvoiceResolution,
+  type MtwFreightInvoiceReviewAction,
+} from '../../../generated/freight-invoice-operations';
+import { invoiceMoney } from '../../utils/invoiceComparison';
+import {
+  DRAFT_PROBLEM_LABELS,
+  REVIEW_EVENT_LABELS,
+  REVIEW_STATUS_LABELS,
+  authorNotice,
+  availableReviewActions,
+  decisionInput,
+  handOffInput,
+  isDraftProblem,
+  resolutionInput,
+  supplierResponseInput,
+  type ReviewPermissions,
+} from '../../utils/invoiceReview';
+
+const textArea = 'mt-1 min-h-24 w-full rounded border p-2';
+
+/**
+ * Review, dispute and Billing hand-off for one exact comparison revision
+ * (BOFF-10588). Every step appends to the revision's history; nothing is edited.
+ */
+export function InvoiceReviewPanel({
+  record,
+  permissions,
+  onChanged,
+}: {
+  record: Pick<InvoiceReceiptFragment, 'id' | 'shipmentId' | 'facts'>;
+  permissions: ReviewPermissions;
+  onChanged?: () => void;
+}) {
+  const [revision, setRevision] = useState(0);
+  const review = useConditionQuery<InvoiceReviewExactQuery>(
+    InvoiceReviewExactDocument,
+    permissions.canRead ? { shipmentId: record.shipmentId, comparisonId: record.id } : null,
+    revision
+  );
+  if (!permissions.canRead)
+    return (
+      <section className={reuseCard} aria-label="Invoice review">
+        <h2 className="text-lg font-semibold">Invoice review</h2>
+        <p>Freight invoice read permission is required to see the review status of this invoice.</p>
+      </section>
+    );
+  const value = review.data?.mtwFreightInvoiceReview;
+  return (
+    <section className={reuseCard} aria-label="Invoice review">
+      <h2 className="text-lg font-semibold">Invoice review</h2>
+      <ReuseState loading={review.loading} error={review.error} />
+      {value && (
+        <ReviewBody
+          key={`${value.comparisonId}:${value.sequence}`}
+          review={value}
+          lines={record.facts.rows}
+          permissions={permissions}
+          onRecorded={() => {
+            setRevision((n) => n + 1);
+            onChanged?.();
+          }}
+        />
+      )}
+    </section>
+  );
+}
+
+function ReviewBody({
+  review,
+  lines,
+  permissions,
+  onRecorded,
+}: {
+  review: InvoiceReviewFragment;
+  lines: InvoiceReceiptFragment['facts']['rows'];
+  permissions: ReviewPermissions;
+  onRecorded: () => void;
+}) {
+  const actions = availableReviewActions(review, permissions);
+  const notice = authorNotice(review);
+  const lineLabel = (id: string) => lines.find((line) => line.id === id)?.description ?? id;
+  return (
+    <div className="space-y-4">
+      <p className="font-medium" role="status">
+        Status: {REVIEW_STATUS_LABELS[review.status]}
+      </p>
+      <p>
+        Revision {review.revision} of {review.latestRevision}. Known invoice amount{' '}
+        {invoiceMoney(review.knownInvoiceAmountMinor, review.currency)}
+        {review.invoiceAmountComplete
+          ? ''
+          : ' (some reported amounts are unknown and are not counted as zero)'}
+        .
+      </p>
+      {review.status === 'SUPERSEDED' && (
+        <p>
+          A newer correction replaces this revision; review continues on the latest revision.
+          {review.resolvedByCorrection && ' Its open dispute was resolved by that correction.'}
+        </p>
+      )}
+      {review.settlementReference && (
+        <p>
+          Handed to platform Billing for settlement under reference{' '}
+          <span className="break-all font-mono">{review.settlementReference}</span>. This revision
+          can no longer be corrected.
+        </p>
+      )}
+      {notice && <p>{notice}</p>}
+      {review.events.length > 0 && (
+        <ol className="space-y-2" aria-label="Review history">
+          {review.events.map((event) => (
+            <li key={event.id} className="rounded border p-3 text-sm">
+              <p className="font-medium">
+                {event.sequence}. {REVIEW_EVENT_LABELS[event.kind]} —{' '}
+                {REVIEW_STATUS_LABELS[event.statusAfter]}
+              </p>
+              <p>
+                {event.recordedAt} by {event.createdBy}
+              </p>
+              {event.reason && <p className="whitespace-pre-wrap break-words">{event.reason}</p>}
+              {event.disputedLineIds.length > 0 && (
+                <p>Disputed lines: {event.disputedLineIds.map(lineLabel).join(', ')}</p>
+              )}
+            </li>
+          ))}
+        </ol>
+      )}
+      {actions.length > 0 ? (
+        <ReviewStep review={review} actions={actions} lines={lines} onRecorded={onRecorded} />
+      ) : (
+        review.status !== 'SUPERSEDED' &&
+        review.status !== 'SETTLEMENT_HANDED_OFF' &&
+        !notice && <p>Your role cannot take the next review step on this invoice.</p>
+      )}
+    </div>
+  );
+}
+
+const ACTION_LABELS: Record<MtwFreightInvoiceReviewAction, string> = {
+  DECIDE: 'Accept or dispute',
+  RECORD_SUPPLIER_RESPONSE: 'Record supplier response',
+  RESOLVE_DISPUTE: 'Resolve dispute',
+  HAND_OFF_SETTLEMENT: 'Hand off to Billing',
+};
+
+function ReviewStep({
+  review,
+  actions,
+  lines,
+  onRecorded,
+}: {
+  review: InvoiceReviewFragment;
+  actions: MtwFreightInvoiceReviewAction[];
+  lines: InvoiceReceiptFragment['facts']['rows'];
+  onRecorded: () => void;
+}) {
+  const request = useConditionApi();
+  const [action, setAction] = useState<MtwFreightInvoiceReviewAction>(actions[0]);
+  const [decision, setDecision] = useState<MtwFreightInvoiceDecision>('ACCEPTED');
+  const [resolution, setResolution] = useState<MtwFreightInvoiceResolution>('ACCEPTED');
+  const [reason, setReason] = useState('');
+  const [disputed, setDisputed] = useState<string[]>([]);
+  // One key per draft: a resend after a lost response replays instead of recording twice.
+  const [idempotencyKey, setKey] = useState(() => crypto.randomUUID());
+  const [busy, setBusy] = useState(false);
+  const [problem, setProblem] = useState<string | null>(null);
+  const edit =
+    <T,>(set: (value: T) => void) =>
+    (value: T) => {
+      set(value);
+      setKey(crypto.randomUUID());
+      setProblem(null);
+    };
+  const base = { review, idempotencyKey };
+  const submit = async () => {
+    const plan =
+      action === 'DECIDE'
+        ? {
+            document: DecideInvoiceReviewDocument,
+            input: decisionInput(base, decision, reason, disputed),
+          }
+        : action === 'RECORD_SUPPLIER_RESPONSE'
+          ? {
+              document: RecordInvoiceSupplierResponseDocument,
+              input: supplierResponseInput(base, reason),
+            }
+          : action === 'RESOLVE_DISPUTE'
+            ? {
+                document: ResolveInvoiceDisputeDocument,
+                input: resolutionInput(base, resolution, reason),
+              }
+            : { document: HandOffInvoiceSettlementDocument, input: handOffInput(base, reason) };
+    if (isDraftProblem(plan.input)) {
+      setProblem(DRAFT_PROBLEM_LABELS[plan.input]);
+      return;
+    }
+    setBusy(true);
+    setProblem(null);
+    try {
+      await request(plan.document, { input: plan.input });
+      onRecorded();
+    } catch (failure) {
+      setProblem(failure instanceof Error ? failure.message : 'The review step was not recorded.');
+    } finally {
+      setBusy(false);
+    }
+  };
+  return (
+    <form
+      className="space-y-3 border-t pt-4"
+      aria-label="Next review step"
+      onSubmit={(event) => {
+        event.preventDefault();
+        void submit();
+      }}
+    >
+      {actions.length > 1 && (
+        <FreightSelect
+          label="Review step"
+          value={action}
+          onChange={(value) => edit(setAction)(value as MtwFreightInvoiceReviewAction)}
+        >
+          {actions.map((item) => (
+            <option key={item} value={item}>
+              {ACTION_LABELS[item]}
+            </option>
+          ))}
+        </FreightSelect>
+      )}
+      {action === 'DECIDE' && (
+        <>
+          <FreightSelect
+            label="Decision"
+            value={decision}
+            onChange={(value) => edit(setDecision)(value as MtwFreightInvoiceDecision)}
+          >
+            <option value="ACCEPTED">Accept</option>
+            <option value="ACCEPTED_WITH_VARIANCE">Accept with variance</option>
+            <option value="DISPUTED">Dispute</option>
+          </FreightSelect>
+          {decision === 'DISPUTED' && (
+            <fieldset className="space-y-2">
+              <legend className="text-sm font-medium">Disputed invoice lines</legend>
+              {lines.map((line) => (
+                <label key={line.id} className="flex min-h-11 items-center gap-2 text-sm">
+                  <input
+                    type="checkbox"
+                    checked={disputed.includes(line.id)}
+                    onChange={(event) =>
+                      edit(setDisputed)(
+                        event.target.checked
+                          ? [...disputed, line.id]
+                          : disputed.filter((id) => id !== line.id)
+                      )
+                    }
+                  />
+                  {line.description} ({invoiceMoney(line.amountMinor, line.currency)})
+                </label>
+              ))}
+            </fieldset>
+          )}
+        </>
+      )}
+      {action === 'RESOLVE_DISPUTE' && (
+        <FreightSelect
+          label="Resolution"
+          value={resolution}
+          onChange={(value) => edit(setResolution)(value as MtwFreightInvoiceResolution)}
+        >
+          <option value="ACCEPTED">Accept as invoiced</option>
+          <option value="ACCEPTED_WITH_VARIANCE">Accept with variance</option>
+        </FreightSelect>
+      )}
+      <label className="block text-sm">
+        {action === 'RECORD_SUPPLIER_RESPONSE'
+          ? "Supplier's response"
+          : action === 'HAND_OFF_SETTLEMENT'
+            ? 'Note for Billing (optional)'
+            : 'Reason'}
+        <textarea
+          className={textArea}
+          value={reason}
+          maxLength={1000}
+          onChange={(event) => edit(setReason)(event.target.value)}
+        />
+      </label>
+      {action === 'RESOLVE_DISPUTE' && (
+        <p className="text-sm">
+          A dispute can also close by recording a corrected invoice revision.
+        </p>
+      )}
+      {action === 'HAND_OFF_SETTLEMENT' && (
+        <p className="text-sm">
+          Billing settles the invoice; MoveTheWheels keeps no payment ledger. After hand-off this
+          revision can no longer be corrected.
+        </p>
+      )}
+      {problem && <p role="alert">{problem}</p>}
+      <Button type="submit" disabled={busy}>
+        {busy ? 'Recording…' : ACTION_LABELS[action]}
+      </Button>
+    </form>
+  );
+}

package/src/movethewheels/components/freight-invoice/InvoiceReviewQueue.tsx

@@ -0,0 +1,96 @@
+import { useState } from 'react';
+import { Button } from '../ui';
+import { FreightSelect } from '../freight-cost/FreightFields';
+import { ReusePager, ReuseState, reuseCard } from '../ReuseControls';
+import { useConditionQuery } from '../../hooks/useContainerCondition';
+import {
+  InvoiceReviewQueueDocument,
+  InvoiceReviewSummaryDocument,
+  type InvoiceReviewFragment,
+  type InvoiceReviewQueueQuery,
+  type InvoiceReviewSummaryQuery,
+  type MtwFreightInvoiceReviewStatus,
+} from '../../../generated/freight-invoice-operations';
+import { invoiceMoney } from '../../utils/invoiceComparison';
+import { REVIEW_QUEUE_STATUSES, REVIEW_STATUS_LABELS } from '../../utils/invoiceReview';
+
+const PAGE = 10;
+
+/** The latest revision of every recorded carrier invoice, filtered by review status (BOFF-10588). */
+export function InvoiceReviewQueue({
+  revision,
+  onOpen,
+  locked = false,
+}: {
+  revision: number;
+  onOpen: (review: InvoiceReviewFragment) => void;
+  /** True while an invoice or correction draft is open: opening a review would discard it. */
+  locked?: boolean;
+}) {
+  const [status, setStatus] = useState<MtwFreightInvoiceReviewStatus | ''>('AWAITING_REVIEW');
+  const [offset, setOffset] = useState(0);
+  const queue = useConditionQuery<InvoiceReviewQueueQuery>(
+    InvoiceReviewQueueDocument,
+    { status: status || null, pagination: { limit: PAGE, offset } },
+    revision
+  );
+  const page = queue.data?.mtwFreightInvoiceReviewPage;
+  return (
+    <section className={reuseCard} aria-label="Invoice review queue">
+      <h2 className="text-lg font-semibold">Invoice review queue</h2>
+      <p>The latest revision of each recorded carrier invoice. Open one to review it.</p>
+      {locked && (
+        <p role="status">Finish or cancel the invoice draft below before opening a review.</p>
+      )}
+      <FreightSelect
+        label="Review status"
+        value={status}
+        onChange={(value) => {
+          setStatus(value as MtwFreightInvoiceReviewStatus | '');
+          setOffset(0);
+        }}
+      >
+        <option value="">All statuses</option>
+        {REVIEW_QUEUE_STATUSES.map((item) => (
+          <option key={item} value={item}>
+            {REVIEW_STATUS_LABELS[item]}
+          </option>
+        ))}
+      </FreightSelect>
+      <ReuseState loading={queue.loading} error={queue.error} />
+      {page && page.items.length === 0 && <p>No invoices with this review status.</p>}
+      <ul className="space-y-2">
+        {page?.items.map((item) => (
+          <li key={item.comparisonId}>
+            <Button
+              type="button"
+              variant="outline"
+              className="h-auto w-full max-w-full justify-start whitespace-normal break-words text-left"
+              disabled={locked}
+              onClick={() => onOpen(item)}
+            >
+              {item.supplierLabel ?? item.supplierReference} / invoice {item.invoiceReference},
+              revision {item.revision} — {REVIEW_STATUS_LABELS[item.status]} —{' '}
+              {invoiceMoney(item.knownInvoiceAmountMinor, item.currency)}
+              {item.invoiceAmountComplete ? '' : ' known'}
+            </Button>
+          </li>
+        ))}
+      </ul>
+      <ReusePager page={page} busy={queue.loading} offset={offset} onChange={setOffset} />
+    </section>
+  );
+}
+
+/** Review counts over the latest revision of every recorded carrier invoice. */
+export function useInvoiceReviewSummary(enabled: boolean) {
+  const summary = useConditionQuery<InvoiceReviewSummaryQuery>(
+    InvoiceReviewSummaryDocument,
+    enabled ? {} : null
+  );
+  return {
+    summary: summary.data?.mtwFreightInvoiceReviewSummary ?? null,
+    loading: summary.loading,
+    error: summary.error,
+  };
+}

package/src/movethewheels/hooks/useCustomers.ts

@@ -35,6 +35,8 @@ interface ApiCustomer {
   businessLicense?: string | null;
   taxId?: string | null;
   rating?: number | null;
+  notifyByEmail?: boolean | null;
+  notifyBySms?: boolean | null;
   createdAt: string;
   updatedAt: string;
   deletedAt?: string | null;
@@ -53,6 +55,8 @@ const LIST_CUSTOMERS_QUERY = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -74,6 +78,8 @@ const GET_CUSTOMER_QUERY = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -94,6 +100,8 @@ const CREATE_CUSTOMER_MUTATION = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -114,6 +122,8 @@ const UPDATE_CUSTOMER_MUTATION = `
       businessLicense
       taxId
       rating
+      notifyByEmail
+      notifyBySms
       createdAt
       updatedAt
       deletedAt
@@ -144,6 +154,9 @@ function mapCustomer(customer: ApiCustomer): Customer {
     businessLicense: customer.businessLicense ?? undefined,
     taxId: customer.taxId ?? undefined,
     rating: customer.rating ?? undefined,
+    // Absent only from an older service; match its defaults (email on, SMS off).
+    notifyByEmail: customer.notifyByEmail ?? true,
+    notifyBySms: customer.notifyBySms ?? false,
     createdAt: new Date(customer.createdAt),
     updatedAt: new Date(customer.updatedAt),
   };
@@ -263,6 +276,8 @@ export function useCustomers(options: UseCustomersOptions = {}): UseCustomersRes
           businessLicense: customerData.businessLicense,
           taxId: customerData.taxId,
           rating: customerData.rating,
+          notifyByEmail: customerData.notifyByEmail,
+          notifyBySms: customerData.notifyBySms,
         },
       });
 
@@ -289,6 +304,8 @@ export function useCustomers(options: UseCustomersOptions = {}): UseCustomersRes
           businessLicense: updates.businessLicense,
           taxId: updates.taxId,
           rating: updates.rating,
+          notifyByEmail: updates.notifyByEmail,
+          notifyBySms: updates.notifyBySms,
         },
       });
 

package/src/movethewheels/hooks/useInvoiceReviewPermissions.ts

@@ -0,0 +1,25 @@
+import { usePermissions } from '@burdenoff/fe-libs/shared/providers/shell';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import type { ReviewPermissions } from '../utils/invoiceReview';
+
+/** Freight invoice review grants for this page's current actor and workspace (BOFF-10588). */
+export function useInvoiceReviewPermissions(): ReviewPermissions & { loading: boolean } {
+  const permissions = usePermissions();
+  const { workspaceId, currentUser } = useMoveTheWheels();
+  const currentScope = Boolean(
+    workspaceId &&
+    currentUser?.id &&
+    permissions.scopeId === workspaceId &&
+    (permissions.isSuperAdmin ||
+      (permissions.permissions?.scopeId === workspaceId &&
+        permissions.permissions.actorId === currentUser.id))
+  );
+  const ready = currentScope && !permissions.isLoading && !permissions.error;
+  const canRead = ready && permissions.hasPermission('mtw-freight-invoice:read');
+  return {
+    canRead,
+    canUpdate: canRead && permissions.hasPermission('mtw-freight-invoice:update'),
+    canApprove: canRead && permissions.hasPermission('mtw-freight-invoice:approve'),
+    loading: permissions.isLoading,
+  };
+}

package/src/movethewheels/pages/CustomerDetailsPage.tsx

@@ -18,6 +18,7 @@ import {
   Package,
   X,
   Trash2,
+  BellRing,
 } from 'lucide-react';
 import { PageLayout, LoadingState, ErrorState } from '../components/PageLayout';
 import { TypeBadge, StatusBadge } from '../components/StatusBadge';
@@ -51,6 +52,10 @@ import { useOrders } from '../hooks/useOrders';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatAddress, formatCurrency, formatDate } from '../utils/formatters';
 import { joinPath, buildOrderCustomerPath, getSafeCustomerReturnPath } from '../utils/navigation';
+import {
+  CustomerDeliveryUpdatesFields,
+  deliveryUpdatesSummary,
+} from '../components/CustomerDeliveryUpdatesFields';
 import { FormError } from '../components/FormError';
 import { Notice, useNotice } from '../components/Notice';
 
@@ -68,6 +73,8 @@ interface CustomerFormState {
   businessLicense: string;
   taxId: string;
   rating: string;
+  notifyByEmail: boolean;
+  notifyBySms: boolean;
 }
 
 const emptyCustomerForm: CustomerFormState = {
@@ -84,6 +91,8 @@ const emptyCustomerForm: CustomerFormState = {
   businessLicense: '',
   taxId: '',
   rating: '',
+  notifyByEmail: true,
+  notifyBySms: false,
 };
 
 function NewCustomerForm() {
@@ -125,6 +134,8 @@ function NewCustomerForm() {
         businessLicense: form.businessLicense.trim() || undefined,
         taxId: form.taxId.trim() || undefined,
         rating: form.rating ? Number(form.rating) : undefined,
+        notifyByEmail: form.notifyByEmail,
+        notifyBySms: form.notifyBySms,
       });
       const destination = returnTo
         ? buildOrderCustomerPath(returnTo, created.id)
@@ -320,6 +331,13 @@ function NewCustomerForm() {
                 />
               </div>
             </div>
+            <div className="mt-6">
+              <CustomerDeliveryUpdatesFields
+                idPrefix="new-customer"
+                value={{ notifyByEmail: form.notifyByEmail, notifyBySms: form.notifyBySms }}
+                onChange={(next) => setForm((prev) => ({ ...prev, ...next }))}
+              />
+            </div>
           </CardContent>
         </Card>
       </form>
@@ -343,6 +361,8 @@ function customerToForm(customer: {
   businessLicense?: string;
   taxId?: string;
   rating?: number;
+  notifyByEmail: boolean;
+  notifyBySms: boolean;
 }): CustomerFormState {
   return {
     name: customer.name,
@@ -358,6 +378,8 @@ function customerToForm(customer: {
     businessLicense: customer.businessLicense ?? '',
     taxId: customer.taxId ?? '',
     rating: customer.rating ? String(customer.rating) : '',
+    notifyByEmail: customer.notifyByEmail,
+    notifyBySms: customer.notifyBySms,
   };
 }
 
@@ -424,6 +446,8 @@ export default function CustomerDetailsPage() {
         businessLicense: form.businessLicense.trim() || undefined,
         taxId: form.taxId.trim() || undefined,
         rating: form.rating ? Number(form.rating) : undefined,
+        notifyByEmail: form.notifyByEmail,
+        notifyBySms: form.notifyBySms,
       });
       notify('Customer updated.');
       setEditing(false);
@@ -662,6 +686,12 @@ export default function CustomerDetailsPage() {
                     />
                   </div>
                 </div>
+                <CustomerDeliveryUpdatesFields
+                  idPrefix="edit-customer"
+                  value={{ notifyByEmail: form.notifyByEmail, notifyBySms: form.notifyBySms }}
+                  onChange={(next) => setForm((prev) => ({ ...prev, ...next }))}
+                  disabled={saving}
+                />
               </div>
             ) : (
               <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
@@ -691,6 +721,15 @@ export default function CustomerDetailsPage() {
                       </div>
                     </div>
                   )}
+                  <div className="flex items-center gap-3">
+                    <BellRing size={18} className="text-text-secondary" />
+                    <div>
+                      <p className="text-sm text-text-secondary">Delivery updates</p>
+                      <p className="font-medium" data-testid="customer-delivery-updates">
+                        {deliveryUpdatesSummary(customer)}
+                      </p>
+                    </div>
+                  </div>
                 </div>
               </div>
             )}

package/src/movethewheels/pages/FinancePage.tsx

@@ -7,7 +7,9 @@
  * settlement are handled by the platform Billing module, which this page
  * deep-links to rather than re-implementing an Invoice ledger here. Carrier
  * invoices are checked against the agreed freight estimate on the freight
- * invoice comparison page, which this page links to (BOFF-4395).
+ * invoice comparison page, which this page links to (BOFF-4395). The review
+ * counts (awaiting review, disputed, accepted, handed to Billing) come from
+ * Query.mtwFreightInvoiceReviewSummary over real recorded invoices (BOFF-10588).
  */
 
 import { useMemo } from 'react';
@@ -30,6 +32,34 @@ import { useAnalytics, useFinanceMetrics } from '../hooks/useAnalytics';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatCurrency } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
+import { useInvoiceReviewSummary } from '../components/freight-invoice/InvoiceReviewQueue';
+
+function InvoiceReviewCounts() {
+  const { summary, loading, error } = useInvoiceReviewSummary(true);
+  if (loading) return <p className="text-sm text-text-secondary">Loading invoice review counts…</p>;
+  if (error || !summary)
+    return (
+      <p className="text-sm text-text-secondary">
+        Invoice review counts need freight invoice read permission.
+      </p>
+    );
+  const counts = [
+    { label: 'Awaiting review', value: summary.awaitingReview },
+    { label: 'Disputed', value: summary.disputed + summary.supplierResponded },
+    { label: 'Accepted', value: summary.accepted + summary.acceptedWithVariance },
+    { label: 'Handed to Billing', value: summary.settlementHandedOff },
+  ];
+  return (
+    <dl className="grid grid-cols-2 gap-2" aria-label="Carrier invoice review">
+      {counts.map((count) => (
+        <div key={count.label} className="rounded-lg border border-border-default p-3">
+          <dt className="text-xs text-text-secondary">{count.label}</dt>
+          <dd className="text-lg font-semibold text-text-primary">{count.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
 
 export default function FinancePage() {
   const { analytics } = useAnalytics();
@@ -156,8 +186,10 @@ export default function FinancePage() {
             <h3 className="text-sm font-semibold text-text-primary">Freight cost control</h3>
             <p className="text-sm text-text-secondary">
               Record the agreed freight estimate for a shipment, then check the carrier&apos;s
-              invoice against it line by line before it is settled in Billing.
+              invoice against it line by line. Someone other than its author accepts or disputes it,
+              and accepted invoices are handed to Billing for settlement.
             </p>
+            <InvoiceReviewCounts />
             <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
               <Button variant="outline" onClick={openFreightEstimates}>
                 <Receipt size={16} /> Freight estimates