@burdenoff/microfe-movethewheels 2026.1011.1 → 2026.1011.2

package/src/movethewheels/MoveTheWheelsRoot.tsx

@@ -99,6 +99,12 @@ const NavRegistrar: FC<Pick<MoveTheWheelsRootProps, 'registerNavItems' | 'basePa
               path: joinPath(basePath, 'tracking/event-quality'),
               icon: <Map size={16} />,
             },
+            {
+              id: 'mtw-status-authority',
+              label: tr('movethewheels.root.nav.statusAuthority', 'Shipment status authority'),
+              path: joinPath(basePath, 'shipments/status-authority'),
+              icon: <ClipboardList size={16} />,
+            },
           ],
         },
         {

package/src/movethewheels/MoveTheWheelsRoutes.tsx

@@ -56,6 +56,7 @@ const OrderDetailsPage = lazy(() => import('./pages/OrderDetailsPage'));
 const CreateOrderPage = lazy(() => import('./pages/CreateOrderPage'));
 const TrackingPage = lazy(() => import('./pages/TrackingPage'));
 const TrackingEventQualityPage = lazy(() => import('./pages/TrackingEventQualityPage'));
+const ShipmentStatusAuthorityPage = lazy(() => import('./pages/ShipmentStatusAuthorityPage'));
 const LiveTrackingPage = lazy(() => import('./pages/LiveTrackingPage'));
 const FleetPage = lazy(() => import('./pages/FleetPage'));
 const VehiclesPage = lazy(() => import('./pages/VehiclesPage'));
@@ -110,6 +111,7 @@ export function MoveTheWheelsRoutes() {
         <Route path="tracking" element={<TrackingPage />} />
         <Route path="tracking/live" element={<LiveTrackingPage />} />
         <Route path="tracking/event-quality" element={<TrackingEventQualityPage />} />
+        <Route path="shipments/status-authority" element={<ShipmentStatusAuthorityPage />} />
 
         {/* Driver ePOD capture (BOFF-4399) */}
         <Route path="deliveries/mine" element={<DeliveryCapturePage />} />

package/src/movethewheels/hooks/useEpod.ts

@@ -12,11 +12,13 @@
  * multi-language delivery instructions.
  */
 import { useCallback, useEffect, useMemo, useState } from 'react';
+import { parse } from 'graphql';
+import { useShipmentStatusCommand } from './useShipmentStatusAuthority';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import type { Order, ProofOfDelivery, SignatureType } from '../types';
 import { executeGraphQL } from '../utils/graphqlClient';
 
-interface ApiProofOfDelivery {
+export interface ApiProofOfDelivery {
   id: string;
   deliveryJobId: string;
   shipmentId?: string | null;
@@ -81,6 +83,7 @@ const CAPTURE_EPOD_MUTATION = `
     }
   }
 `;
+const CAPTURE_EPOD_DOCUMENT = parse(CAPTURE_EPOD_MUTATION);
 
 const INITIATE_UPLOAD_MUTATION = `
   mutation EpodInitiateUpload($input: InitiateUploadInput!) {
@@ -257,6 +260,9 @@ export function useMyPendingEpodDeliveryJobs(options: { limit?: number; offset?:
 }
 
 export interface CaptureEpodArgs {
+  expectedShipmentId: string | null;
+  expectedShipmentStatusRevision?: number;
+  completionAttestation: boolean;
   deliveryJobId: string;
   recipientName: string;
   signatureType: SignatureType;
@@ -268,22 +274,48 @@ export interface CaptureEpodArgs {
   notes?: string;
 }
 
+export function epodAcknowledged(
+  actual: ApiProofOfDelivery | null | undefined,
+  expected: CaptureEpodArgs
+): boolean {
+  return (
+    !!actual &&
+    typeof actual.id === 'string' &&
+    actual.id.trim().length > 0 &&
+    actual.deliveryJobId === expected.deliveryJobId &&
+    actual.shipmentId === expected.expectedShipmentId &&
+    actual.recipientName === expected.recipientName &&
+    actual.signatureType === toApiSignatureType(expected.signatureType) &&
+    actual.signatureData === expected.signatureData &&
+    typeof actual.capturedByDriverId === 'string' &&
+    actual.capturedByDriverId.trim().length > 0 &&
+    typeof actual.deliveredAt === 'string' &&
+    Number.isFinite(Date.parse(actual.deliveredAt)) &&
+    Array.isArray(actual.photoFileIds) &&
+    actual.photoFileIds.length === (expected.photoFileIds ?? []).length &&
+    actual.photoFileIds.every((id, index) => id === (expected.photoFileIds ?? [])[index]) &&
+    actual.latitude === (expected.latitude ?? null) &&
+    actual.longitude === (expected.longitude ?? null) &&
+    actual.locationAccuracy === (expected.locationAccuracy ?? null) &&
+    actual.notes === (expected.notes ?? null)
+  );
+}
+
 /** Driver-facing capture mutation. Identity/ownership is enforced server-side — this never sends a driver id. */
 export function useCaptureEpod() {
-  const graphQLOptions = useGraphQLOptions();
-  const [isSubmitting, setIsSubmitting] = useState(false);
+  const command = useShipmentStatusCommand();
   const [error, setError] = useState<Error | null>(null);
 
   const captureEpod = useCallback(
     async (args: CaptureEpodArgs): Promise<ProofOfDelivery> => {
-      setIsSubmitting(true);
       setError(null);
       try {
-        const data = await executeGraphQL<{ captureEpod: ApiProofOfDelivery }>(
-          graphQLOptions,
-          CAPTURE_EPOD_MUTATION,
+        const data = await command.run<{ captureEpod: ApiProofOfDelivery }>(
+          CAPTURE_EPOD_DOCUMENT,
           {
             input: {
+              expectedShipmentStatusRevision: args.expectedShipmentStatusRevision,
+              completionAttestation: args.completionAttestation,
               deliveryJobId: args.deliveryJobId,
               recipientName: args.recipientName,
               signatureType: toApiSignatureType(args.signatureType),
@@ -294,8 +326,13 @@ export function useCaptureEpod() {
               locationAccuracy: args.locationAccuracy,
               notes: args.notes,
             },
-          }
+          },
+          (data) => epodAcknowledged(data.captureEpod, args)
         );
+        if (!data)
+          throw new Error(
+            'Capture was not acknowledged. Review the recorded status and the capture message before taking further action.'
+          );
         return mapEpod(data.captureEpod);
       } catch (captureError) {
         const err =
@@ -304,14 +341,12 @@ export function useCaptureEpod() {
             : new Error('Failed to capture proof of delivery');
         setError(err);
         throw err;
-      } finally {
-        setIsSubmitting(false);
       }
     },
-    [graphQLOptions]
+    [command]
   );
 
-  return { captureEpod, isSubmitting, error };
+  return { captureEpod, isSubmitting: command.busy, error, captureFeedback: command.feedback };
 }
 
 export interface UploadedEpodPhoto {

package/src/movethewheels/hooks/useShipmentStatusAuthority.ts

@@ -0,0 +1,179 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { print, type DocumentNode } from 'graphql';
+import { graphqlFetch, clearGraphqlFetchResponseCache } from '@burdenoff/fe-libs/shared/graphql';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+
+const KNOWN_REJECTIONS = new Set([
+  'STATUS_REVISION_CONFLICT',
+  'BAD_USER_INPUT',
+  'FORBIDDEN',
+  'UNAUTHENTICATED',
+  'NOT_FOUND',
+]);
+
+export class ShipmentStatusRequestError extends Error {
+  constructor(
+    message: string,
+    readonly code: string | null
+  ) {
+    super(message);
+    this.name = 'ShipmentStatusRequestError';
+  }
+}
+
+/** Normal shared gateway transport; mutation acknowledgements are never automatically retried. */
+export function useShipmentStatusApi() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId } = useMoveTheWheels();
+  const context = useMemo(
+    () => ({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId]
+  );
+  return useCallback(
+    async <T>(
+      document: DocumentNode,
+      variables: Record<string, unknown>,
+      mutation = false,
+      signal?: AbortSignal
+    ): Promise<T> => {
+      const response = await graphqlFetch<T>({
+        gateway: 'workspace',
+        query: print(document),
+        variables,
+        baseUrl: context.apiGatewayUrl,
+        authToken: context.authToken,
+        workspaceToken: context.workspaceToken || true,
+        workspaceId: context.workspaceId || true,
+        tenantId: context.tenantId || true,
+        organizationId: true,
+        signal,
+        skipAuthRetry: mutation,
+      });
+      if (response.errors?.length) {
+        // A single verified rejection is distinct from a transport failure or partial response.
+        const first = response.errors[0];
+        const code =
+          response.data === null &&
+          response.errors.length === 1 &&
+          typeof first?.extensions?.code === 'string'
+            ? first.extensions.code
+            : null;
+        throw new ShipmentStatusRequestError(
+          first?.message ?? 'Unable to load the recorded status.',
+          code
+        );
+      }
+      if (response.data == null)
+        throw new ShipmentStatusRequestError('No acknowledgement was received.', null);
+      return response.data;
+    },
+    [context]
+  );
+}
+
+export function useShipmentStatusQuery<T>(
+  document: DocumentNode,
+  variables: Record<string, unknown> | null,
+  revision = 0
+) {
+  const request = useShipmentStatusApi();
+  const key = JSON.stringify(variables);
+  const [state, setState] = useState<{
+    request: typeof request;
+    key: string;
+    revision: number;
+    data: T | null;
+    error: string | null;
+    loading: boolean;
+  } | null>(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    const scope = { request, key, revision };
+    setState({ ...scope, data: null, error: null, loading: key !== 'null' });
+    if (key === 'null') return;
+    // An explicit review refresh must read the gateway rather than its short-lived response cache.
+    if (revision > 0) clearGraphqlFetchResponseCache();
+    const input: Record<string, unknown> = JSON.parse(key);
+    void request<T>(document, input, false, controller.signal)
+      .then((data) => {
+        if (!controller.signal.aborted) setState({ ...scope, data, error: null, loading: false });
+      })
+      .catch((failure: unknown) => {
+        if (!controller.signal.aborted)
+          setState({
+            ...scope,
+            data: null,
+            error: failure instanceof Error ? failure.message : 'Unable to load recorded status.',
+            loading: false,
+          });
+      });
+    return () => controller.abort();
+  }, [document, request, key, revision]);
+  const current = state?.request === request && state.key === key && state.revision === revision;
+  return {
+    data: current ? state.data : null,
+    error: current ? state.error : null,
+    loading: current ? state.loading : key !== 'null',
+  };
+}
+
+export function useShipmentStatusCommand() {
+  const request = useShipmentStatusApi();
+  const lock = useRef(false);
+  const uncertain = useRef(false);
+  const [busy, setBusy] = useState(false);
+  const [feedback, setFeedback] = useState<{
+    kind: 'APPLIED' | 'REJECTED' | 'UNKNOWN';
+    message: string;
+  } | null>(null);
+  const [revision, setRevision] = useState(0);
+  const run = async <T>(
+    document: DocumentNode,
+    variables: Record<string, unknown>,
+    acknowledged: (result: T) => boolean
+  ): Promise<T | null> => {
+    if (lock.current || uncertain.current) return null;
+    lock.current = true;
+    setBusy(true);
+    setFeedback(null);
+    try {
+      const result = await request<T>(document, variables, true);
+      if (!acknowledged(result))
+        throw new ShipmentStatusRequestError(
+          'The returned acknowledgement does not identify this decision.',
+          null
+        );
+      setFeedback({
+        kind: 'APPLIED',
+        message: 'Decision recorded. Review the refreshed status and history.',
+      });
+      setRevision((value) => value + 1);
+      return result;
+    } catch (failure) {
+      const known =
+        failure instanceof ShipmentStatusRequestError &&
+        failure.code !== null &&
+        KNOWN_REJECTIONS.has(failure.code);
+      uncertain.current = !known;
+      setFeedback({
+        kind: known ? 'REJECTED' : 'UNKNOWN',
+        message: known
+          ? `${failure.message} Your input is preserved; refresh and review the recorded status before another action.`
+          : 'Acknowledgement is uncertain. Do not resend this action. Refresh the recorded status and review its decisions before beginning a separate new action.',
+      });
+      return null;
+    } finally {
+      lock.current = false;
+      setBusy(false);
+    }
+  };
+  return {
+    run,
+    busy,
+    feedback,
+    revision,
+    beginSeparateAction: () => {
+      uncertain.current = false;
+      setFeedback(null);
+    },
+  };
+}

package/src/movethewheels/hooks/useTracking.ts

@@ -108,6 +108,10 @@ const LOOKUP_DELIVERY_JOBS_QUERY = `
 
 const DELIVERY_JOB_TRACKING_QUERY = `
   query GetDeliveryJobTracking($deliveryJobId: ID!, $pagination: PaginationInput) {
+    shipments(filter: { deliveryJobId: $deliveryJobId }, pagination: { limit: 2, offset: 0 }) {
+      id
+      status
+    }
     deliveryJobTracking(deliveryJobId: $deliveryJobId, pagination: $pagination) {
       id
       shipmentId
@@ -232,7 +236,8 @@ function mapTrackingEventToLocation(event: ApiTrackingEvent): Location | null {
 
 function mapTrackingEventsToTracking(
   events: ApiTrackingEvent[],
-  entityId: string
+  entityId: string,
+  recordedShipmentStatus?: string
 ): Tracking | null {
   const latest = events[0];
   if (!latest) return null;
@@ -248,7 +253,8 @@ function mapTrackingEventsToTracking(
     entityType: 'order',
     currentLocation,
     locationHistory,
-    status: latest.eventType.toLowerCase(),
+    // Observation history is not shipment-status authority. Ambiguous/unlinked shipments stay unknown.
+    status: recordedShipmentStatus?.toLowerCase() ?? 'unknown',
     estimatedArrival: undefined,
     nextCheckpoint: latest.details ?? undefined,
     alerts: [],
@@ -472,18 +478,23 @@ export function useOrderTracking(orderLookup: string | undefined) {
     setTrackingLoading(true);
     setTrackingError(null);
     try {
-      const data = await executeGraphQL<{ deliveryJobTracking: ApiTrackingEvent[] }>(
-        graphQLOptions,
-        DELIVERY_JOB_TRACKING_QUERY,
-        {
-          deliveryJobId: resolvedOrderId,
-          pagination: { limit: 50, offset: 0 },
-        }
-      );
+      const data = await executeGraphQL<{
+        deliveryJobTracking: ApiTrackingEvent[];
+        shipments: Array<{ id: string; status: string }>;
+      }>(graphQLOptions, DELIVERY_JOB_TRACKING_QUERY, {
+        deliveryJobId: resolvedOrderId,
+        pagination: { limit: 50, offset: 0 },
+      });
       const events = [...data.deliveryJobTracking].sort(
         (first, second) => Date.parse(second.timestamp) - Date.parse(first.timestamp)
       );
-      setTracking(mapTrackingEventsToTracking(events, resolvedOrderId));
+      setTracking(
+        mapTrackingEventsToTracking(
+          events,
+          resolvedOrderId,
+          data.shipments.length === 1 ? data.shipments[0]?.status : undefined
+        )
+      );
     } catch (fetchError) {
       setTrackingError(
         fetchError instanceof Error ? fetchError : new Error('Failed to load order tracking')
@@ -580,7 +591,11 @@ export function useLiveTracking() {
             order: mapOrder(deliveryJob),
             driver: deliveryJob.driver ? mapDriver(deliveryJob.driver) : null,
             vehicle: deliveryJob.vehicle ? mapVehicle(deliveryJob.vehicle) : null,
-            tracking: mapTrackingEventsToTracking(shipment.trackingEvents ?? [], deliveryJob.id),
+            tracking: mapTrackingEventsToTracking(
+              shipment.trackingEvents ?? [],
+              deliveryJob.id,
+              shipment.status
+            ),
             estimatedArrival: shipment.estimatedDelivery
               ? new Date(shipment.estimatedDelivery)
               : undefined,

package/src/movethewheels/hooks/useTrackingEventQuality.ts

@@ -16,9 +16,26 @@ export interface TrackingUpdateOutcome {
   shipmentId: string | null;
   status: 'ACCEPTED' | 'DUPLICATE' | 'CONFLICT' | 'REJECTED';
   errorCode: string | null;
+  projection: {
+    status: 'APPLIED' | 'HELD' | 'LEGACY_NO_DECISION';
+    decisionId: string | null;
+    heldReason: string | null;
+  } | null;
 }
 
 const statuses = new Set(['ACCEPTED', 'DUPLICATE', 'CONFLICT', 'REJECTED']);
+const heldReasons = new Set([
+  'LEGACY_AUTHORITY',
+  'MANUAL_AUTHORITY',
+  'NON_DESIGNATED_SOURCE',
+  'UNKNOWN_SOURCE_TIME',
+  'OLDER_SOURCE_TIME',
+  'EQUAL_SOURCE_TIME',
+  'SOURCE_TIME_TOO_OLD',
+  'SOURCE_TIME_IN_FUTURE',
+  'UNMAPPED_EVENT_TYPE',
+  'UNRECEIPTED_EVIDENCE',
+]);
 const codes = new Set([
   'KEY_CONFLICT',
   'BUDGET_EXHAUSTED',
@@ -54,6 +71,30 @@ export function trackingOutcomes(value: unknown): TrackingUpdateOutcome[] | null
     ) {
       return null;
     }
+    let projection: TrackingUpdateOutcome['projection'] = null;
+    const projectionStatus = row.projectionStatus;
+    const decisionId = row.projectionDecisionId ?? null;
+    const heldReason = row.projectionHeldReason ?? null;
+    if (projectionStatus !== undefined && projectionStatus !== null) {
+      if (row.status !== 'ACCEPTED' && row.status !== 'DUPLICATE') return null;
+      if (projectionStatus === 'LEGACY_NO_DECISION') {
+        if (row.status !== 'DUPLICATE' || decisionId !== null || heldReason !== null) return null;
+      } else if (projectionStatus === 'APPLIED' || projectionStatus === 'HELD') {
+        if (!bounded(decisionId, 255) || !decisionId) return null;
+        if (
+          projectionStatus === 'APPLIED'
+            ? heldReason !== null
+            : typeof heldReason !== 'string' || !heldReasons.has(heldReason)
+        )
+          return null;
+      } else return null;
+      // The guarded finite status and bounded identifiers justify the JSON narrowing.
+      projection = {
+        status: projectionStatus,
+        decisionId: decisionId as string | null,
+        heldReason: heldReason as string | null,
+      };
+    } else if (decisionId !== null || heldReason !== null) return null;
     // The finite status/code guards justify narrowing the untyped JSON scalar.
     result.push({
       index: row.index,
@@ -62,6 +103,7 @@ export function trackingOutcomes(value: unknown): TrackingUpdateOutcome[] | null
       shipmentId: row.shipmentId,
       status: row.status as TrackingUpdateOutcome['status'],
       errorCode: row.errorCode,
+      projection,
     });
   }
   return result;

package/src/movethewheels/pages/DeliveryCapturePage.tsx

@@ -15,7 +15,7 @@
  * driver app (BOFF-3991) — this page is the capture core, reachable from the
  * existing web MFE.
  */
-import { useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import {
   CheckCircle2,
   Loader2,
@@ -52,6 +52,10 @@ import {
 } from '../hooks/useEpod';
 import { formatAddress, formatDate } from '../utils/formatters';
 import type { SignatureType } from '../types';
+import { useShipmentStatusQuery } from '../hooks/useShipmentStatusAuthority';
+import { StatusAuthorityOwnedDeliveryDocument } from '../../generated/shipment-status-authority-operations';
+import type { StatusAuthorityOwnedDeliveryQuery } from '../../generated/shipment-status-authority-operations';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 
 /** Resolves the device's current position, if the browser grants it. Never blocks submission. */
 function getCurrentPosition(): Promise<GeolocationPosition | null> {
@@ -77,7 +81,25 @@ function CaptureForm({
   onCaptured: () => void;
   onCancel: () => void;
 }) {
-  const { captureEpod, isSubmitting, error: captureError } = useCaptureEpod();
+  const { captureEpod, isSubmitting, error: captureError, captureFeedback } = useCaptureEpod();
+  const [statusRefresh, setStatusRefresh] = useState(0);
+  const ownedStatus = useShipmentStatusQuery<StatusAuthorityOwnedDeliveryQuery>(
+    StatusAuthorityOwnedDeliveryDocument,
+    { deliveryJobId: job.id },
+    statusRefresh
+  );
+  const [completionAttestation, setCompletionAttestation] = useState(false);
+  const uploadedPhoto = useRef<{ file: File; id: string } | null>(null);
+  const submissionLock = useRef(false);
+  const active = useRef(true);
+  useEffect(() => {
+    active.current = true;
+    return () => {
+      active.current = false;
+    };
+  }, []);
+  const [preparing, setPreparing] = useState(false);
+  const [requiredStatusRefresh, setRequiredStatusRefresh] = useState(0);
   const { upload: uploadPhoto, isUploading, error: uploadError } = useEpodPhotoUpload();
   const signaturePadRef = useRef<SignaturePadHandle>(null);
 
@@ -89,7 +111,21 @@ function CaptureForm({
   const [validationError, setValidationError] = useState<string | null>(null);
 
   const handleSubmit = async () => {
+    if (submissionLock.current) return;
     setValidationError(null);
+    if (
+      ownedStatus.loading ||
+      ownedStatus.error ||
+      !ownedStatus.data ||
+      statusRefresh < requiredStatusRefresh ||
+      !completionAttestation ||
+      captureFeedback?.kind === 'UNKNOWN'
+    ) {
+      setValidationError(
+        'Review the current linked shipment status and confirm completion before capture. Do not resend an uncertain capture.'
+      );
+      return;
+    }
 
     const trimmedRecipient = recipientName.trim();
     if (!trimmedRecipient) {
@@ -110,16 +146,27 @@ function CaptureForm({
       return;
     }
 
+    submissionLock.current = true;
+    setPreparing(true);
     try {
       let photoFileIds: string[] | undefined;
       if (photoFile) {
-        const uploaded = await uploadPhoto(photoFile);
-        photoFileIds = [uploaded.fileId];
+        if (uploadedPhoto.current?.file === photoFile) photoFileIds = [uploadedPhoto.current.id];
+        else {
+          const uploaded = await uploadPhoto(photoFile);
+          uploadedPhoto.current = { file: photoFile, id: uploaded.fileId };
+          photoFileIds = [uploaded.fileId];
+        }
       }
 
+      if (!active.current) return;
       const position = await getCurrentPosition();
+      if (!active.current) return;
 
       await captureEpod({
+        expectedShipmentId: ownedStatus.data.myEpodShipmentStatus?.id ?? null,
+        expectedShipmentStatusRevision: ownedStatus.data.myEpodShipmentStatus?.statusRevision,
+        completionAttestation,
         deliveryJobId: job.id,
         recipientName: trimmedRecipient,
         signatureType,
@@ -133,11 +180,16 @@ function CaptureForm({
 
       onCaptured();
     } catch {
+      setCompletionAttestation(false);
+      setRequiredStatusRefresh(statusRefresh + 1);
       // captureError / uploadError already carry the message for display below.
+    } finally {
+      submissionLock.current = false;
+      setPreparing(false);
     }
   };
 
-  const submitting = isSubmitting || isUploading;
+  const submitting = isSubmitting || isUploading || preparing;
 
   return (
     <Card>
@@ -151,6 +203,47 @@ function CaptureForm({
           {job.customerName && <p>Recipient on file: {job.customerName}</p>}
           {job.deliveryAddress && <p>{formatAddress(job.deliveryAddress)}</p>}
         </div>
+        <section aria-label="Linked shipment status" className="space-y-2">
+          <p>
+            Recorded shipment:{' '}
+            {ownedStatus.data?.myEpodShipmentStatus
+              ? `${ownedStatus.data.myEpodShipmentStatus.status.toLowerCase().replaceAll('_', ' ')} · revision ${ownedStatus.data.myEpodShipmentStatus.statusRevision}`
+              : ownedStatus.data
+                ? 'No linked shipment'
+                : 'Loading current record'}
+          </p>
+          {ownedStatus.error && <p role="alert">{ownedStatus.error}</p>}
+          <Button
+            variant="outline"
+            disabled={ownedStatus.loading || submitting}
+            onClick={() => {
+              setCompletionAttestation(false);
+              setStatusRefresh((value) => value + 1);
+            }}
+          >
+            Refresh linked status
+          </Button>
+          <label className="flex items-start gap-2">
+            <input
+              type="checkbox"
+              checked={completionAttestation}
+              disabled={
+                ownedStatus.loading ||
+                !!ownedStatus.error ||
+                submitting ||
+                statusRefresh < requiredStatusRefresh ||
+                captureFeedback?.kind === 'UNKNOWN'
+              }
+              onChange={(event) => setCompletionAttestation(event.target.checked)}
+            />
+            I reviewed the recorded linked status and attest to this delivery completion.
+          </label>
+          <p>
+            This records an assigned driver's attestation; it does not independently verify physical
+            freight movement.
+          </p>
+          {captureFeedback && <p role="status">{captureFeedback.message}</p>}
+        </section>
 
         <div className="space-y-1.5">
           <Label htmlFor="epod-recipient-name">Recipient name</Label>
@@ -232,7 +325,19 @@ function CaptureForm({
           <Button type="button" variant="outline" onClick={onCancel} disabled={submitting}>
             Cancel
           </Button>
-          <Button type="button" onClick={() => void handleSubmit()} disabled={submitting}>
+          <Button
+            type="button"
+            onClick={() => void handleSubmit()}
+            disabled={
+              submitting ||
+              ownedStatus.loading ||
+              !!ownedStatus.error ||
+              !ownedStatus.data ||
+              statusRefresh < requiredStatusRefresh ||
+              !completionAttestation ||
+              captureFeedback?.kind === 'UNKNOWN'
+            }
+          >
             {submitting ? (
               <>
                 <Loader2 size={14} className="animate-spin" /> Submitting…
@@ -250,6 +355,7 @@ function CaptureForm({
 }
 
 export default function DeliveryCapturePage() {
+  const { workspaceId, tenantId, currentUser, apiGatewayUrl } = useMoveTheWheels();
   const [pageIndex, setPageIndex] = useState(0);
   const pageSize = 20;
   const { jobs, hasMore, isLoading, error, refetch } = useMyPendingEpodDeliveryJobs({
@@ -277,6 +383,7 @@ export default function DeliveryCapturePage() {
 
         {selectedJob ? (
           <CaptureForm
+            key={`${workspaceId}:${tenantId}:${currentUser?.id}:${apiGatewayUrl}:${selectedJob.id}`}
             job={selectedJob}
             onCaptured={handleCaptured}
             onCancel={() => setSelectedJob(null)}