diff --git a/INV-20260812-00005-mor.pdf b/INV-20260812-00005-mor.pdf
new file mode 100644
index 000000000..4ce89c534
Binary files /dev/null and b/INV-20260812-00005-mor.pdf differ
diff --git a/INV-20260812-00005-thermal.pdf b/INV-20260812-00005-thermal.pdf
new file mode 100644
index 000000000..21df74ca7
Binary files /dev/null and b/INV-20260812-00005-thermal.pdf differ
diff --git a/apps/edr-freight-api/package.json b/apps/edr-freight-api/package.json
index 79e350cc7..f36b36382 100644
--- a/apps/edr-freight-api/package.json
+++ b/apps/edr-freight-api/package.json
@@ -32,6 +32,7 @@
     "seed:file-upload-settings": "ts-node -r tsconfig-paths/register src/scripts/seed-file-upload-settings.ts",
     "seed:dropdown-settings": "ts-node -r tsconfig-paths/register src/scripts/seed-dropdown-settings.ts",
     "seed:gov-companies": "ts-node -r tsconfig-paths/register src/scripts/seed-gov-companies.ts",
+    "seed:mor-test-buyers": "ts-node -r tsconfig-paths/register src/scripts/seed-mor-test-buyers.ts",
     "seed:fleet-wagons": "bash ../../../docs/new/seeds/seed-fleet-wagons.sh",
     "iam:typeorm:cli": "cross-env MIGRATIONS_DIR=node_modules/@tria-plc/iamapi-common/dist/db/migrations/*.{ts,js} ts-node -r tsconfig-paths/register   ./node_modules/typeorm/cli.js -d ./node_modules/@tria-plc/api-common/dist/modules/typeorm/typeorm.config.js",
     "iam:migration:run": "pnpm run iam:typeorm:cli migration:run",
diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index 397845cb3..84e3e4b7a 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -35,6 +35,7 @@ import { ConsignmentsModule } from "./modules/consignments/consignments.module";
 import { LocomotivesModule } from "./modules/locomotives/locomotives.module";
 import { TruckTypesModule } from "./modules/truck-types/truck-types.module";
 import { TransitAgentsModule } from "./modules/transit-agents/transit-agents.module";
+import { TransitAssignmentsModule } from "./modules/transit-assignments/transit-assignments.module";
 import { WagonTypesModule } from "./modules/wagon-types/wagon-types.module";
 import { TrainSetsModule } from "./modules/train-sets/train-sets.module";
 import { TrainSchedulesModule } from "./modules/train-schedules/train-schedules.module";
@@ -95,6 +96,7 @@ import { TrainsModule } from "./modules/trains/trains.module";
 import { VerifaydaModule } from "./modules/verifayda/verifayda.module";
 import { EimsModule } from "./modules/eims/eims.module";
 import { FleetHistoryModule } from "./modules/fleet-history/fleet-history.module";
+import { WagonHistoryModule } from "./modules/wagon-history/wagon-history.module";
 import { WagonsModule } from "./modules/wagons/wagons.module";
 import { ContainersModule } from "./modules/container-management/containers.module";
 import { CargoesModule } from "./modules/cargoes/cargoes.module";
@@ -115,6 +117,7 @@ import { FacilitiesModule } from "./modules/facilities/facilities.module";
 import { GpsTrackingModule } from "./modules/gps-tracking/gps-tracking.module";
 import { FirstMileModule } from "./modules/first-mile/first-mile.module";
 import { LastMileModule } from "./modules/last-mile/last-mile.module";
+import { EmptyReturnRequestsModule } from "./modules/empty-return-requests/empty-return-requests.module";
 import { LastMileRequestsModule } from "./modules/last-mile-requests/last-mile-requests.module";
 import { InterchangeDocumentsModule } from "./modules/interchange-documents/interchange-documents.module";
 import { ImportOperationsModule } from "./modules/import-operations/import-operations.module";
@@ -205,6 +208,7 @@ if (!process.env.APPLICATION_NAME) {
     LocomotivesModule,
     TruckTypesModule,
     TransitAgentsModule,
+    TransitAssignmentsModule,
     WagonTypesModule,
     TrainSetsModule,
     TrainSchedulesModule,
@@ -256,11 +260,13 @@ if (!process.env.APPLICATION_NAME) {
     FirstMileModule,
     LastMileModule,
     LastMileRequestsModule,
+    EmptyReturnRequestsModule,
     InterchangeDocumentsModule,
     ImportOperationsModule,
     VerifaydaModule,
     EimsModule,
     FleetHistoryModule,
+    WagonHistoryModule,
     AiModule,
     AuditModule,
     ChatModule,
diff --git a/apps/edr-freight-api/src/common/freight-jwt.guard.spec.ts b/apps/edr-freight-api/src/common/freight-jwt.guard.spec.ts
new file mode 100644
index 000000000..817e967f8
--- /dev/null
+++ b/apps/edr-freight-api/src/common/freight-jwt.guard.spec.ts
@@ -0,0 +1,148 @@
+import {
+  collectAllPositions,
+  resolveActiveEmployee,
+  type SnapshotEmployee,
+} from './freight-jwt.guard';
+
+// Shapes and ids taken from the real dev session for `test_dj_gl_director`
+// (iam.sessions 800ad793-…), an employee holding two posts on one row.
+const CHIEF = {
+  id: '990189f1-e872-4b8c-9f6a-36259a0df480',
+  employeePositionId: 'd0d527f6-f344-49aa-ab8b-25a448a770b6',
+  name: { en: 'Djibouti GL Chief' },
+  isDelegate: false,
+};
+const DIRECTOR = {
+  id: '258a8d82-28c4-401f-bf88-78f58bb6bd0e',
+  employeePositionId: 'b97aa265-5de8-4ffe-95bf-01f94d38a2df',
+  name: { en: 'Djibouti GL Director' },
+  isDelegate: false,
+};
+
+const EMPLOYEE_ID = '70545ee5-c7d7-4196-af7e-a7eb7e76b21b';
+const oneRow: SnapshotEmployee[] = [
+  { id: EMPLOYEE_ID, positions: [CHIEF, DIRECTOR] },
+];
+
+describe('resolveActiveEmployee', () => {
+  it('leaves the parent guard alone when no position header is sent', () => {
+    const { owner, active } = resolveActiveEmployee(
+      oneRow,
+      undefined,
+      EMPLOYEE_ID,
+    );
+
+    expect(owner).toBe(oneRow[0]);
+    expect(active).toBeUndefined();
+  });
+
+  it("resolves freight's header value (employeePositionId)", () => {
+    const { active } = resolveActiveEmployee(
+      oneRow,
+      DIRECTOR.employeePositionId,
+      EMPLOYEE_ID,
+    );
+
+    expect(active).toBe(DIRECTOR);
+  });
+
+  // The regression this guard exists for: the stock IAM guard matches the
+  // header against employeePositionId only, so Smart Office's position.id
+  // matched nothing and every request silently ran as positions[0].
+  it("resolves Smart Office's header value (position.id)", () => {
+    const { active } = resolveActiveEmployee(oneRow, DIRECTOR.id, EMPLOYEE_ID);
+
+    expect(active).toBe(DIRECTOR);
+    expect(active).not.toBe(CHIEF);
+  });
+
+  it('falls back to the parent row when the header names nothing', () => {
+    const { owner, active } = resolveActiveEmployee(
+      oneRow,
+      'not-a-position-id',
+      EMPLOYEE_ID,
+    );
+
+    expect(owner).toBe(oneRow[0]);
+    expect(active).toBeUndefined();
+  });
+
+  describe('when the two posts sit on different employee rows', () => {
+    const smartOfficeRow: SnapshotEmployee = {
+      id: 'emp-smart-office',
+      positions: [CHIEF],
+    };
+    const freightRow: SnapshotEmployee = {
+      id: 'emp-freight',
+      positions: [DIRECTOR],
+    };
+    const twoRows = [smartOfficeRow, freightRow];
+
+    it('selects the row that owns the requested position', () => {
+      const { owner, active } = resolveActiveEmployee(
+        twoRows,
+        DIRECTOR.employeePositionId,
+        // The parent guard matches the header against position.id only, so it
+        // matched neither row and fell through to the first.
+        smartOfficeRow.id,
+      );
+
+      expect(owner).toBe(freightRow);
+      expect(active).toBe(DIRECTOR);
+    });
+
+    it('keeps the parent row when no header is sent', () => {
+      const { owner } = resolveActiveEmployee(twoRows, undefined, freightRow.id);
+
+      expect(owner).toBe(freightRow);
+    });
+
+    it('falls back to the first row when the parent row is unknown', () => {
+      const { owner } = resolveActiveEmployee(twoRows, undefined, undefined);
+
+      expect(owner).toBe(smartOfficeRow);
+    });
+  });
+});
+
+describe('collectAllPositions', () => {
+  it('unions posts held across separate employee rows', () => {
+    // The real shape: IAM keeps one employee row per organization, and "EDR"
+    // and "EDR Freight" are separate orgs, so a user holding a Smart Office
+    // post and a freight post owns one row each.
+    const smartOfficeRow: SnapshotEmployee = {
+      id: 'emp-edr',
+      organizationId: 'org-edr',
+      positions: [CHIEF],
+    };
+    const freightRow: SnapshotEmployee = {
+      id: 'emp-edr-freight',
+      organizationId: 'org-edr-freight',
+      positions: [DIRECTOR],
+    };
+
+    expect(collectAllPositions([smartOfficeRow, freightRow])).toEqual([
+      CHIEF,
+      DIRECTOR,
+    ]);
+  });
+
+  it('keeps every post when they share one row', () => {
+    expect(collectAllPositions(oneRow)).toEqual([CHIEF, DIRECTOR]);
+  });
+
+  it('de-duplicates a post repeated across rows', () => {
+    const rows: SnapshotEmployee[] = [
+      { id: 'a', positions: [CHIEF] },
+      { id: 'b', positions: [CHIEF, DIRECTOR] },
+    ];
+
+    expect(collectAllPositions(rows)).toEqual([CHIEF, DIRECTOR]);
+  });
+
+  it('tolerates rows carrying no positions', () => {
+    const rows: SnapshotEmployee[] = [{ id: 'a' }, { id: 'b', positions: [] }];
+
+    expect(collectAllPositions(rows)).toEqual([]);
+  });
+});
diff --git a/apps/edr-freight-api/src/common/freight-jwt.guard.ts b/apps/edr-freight-api/src/common/freight-jwt.guard.ts
index 68b842217..9dbc36b73 100644
--- a/apps/edr-freight-api/src/common/freight-jwt.guard.ts
+++ b/apps/edr-freight-api/src/common/freight-jwt.guard.ts
@@ -3,29 +3,124 @@ import { Reflector } from '@nestjs/core';
 import { InjectDataSource } from '@nestjs/typeorm';
 import { JwtGuard as IamJwtGuard } from '@tria-plc/api-common/modules/auth/services/jwt.guard';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+import { CURRENT_POSITION_ID } from '@tria-plc/api-common/utils/constants/tenant.constant';
 import { DataSource } from 'typeorm';
 
 /** One position as the login snapshot stores it (`iam.sessions.userInfo`). */
-type SnapshotPosition = { id?: string; [key: string]: unknown };
+export type SnapshotPosition = {
+  id?: string;
+  employeePositionId?: string;
+  isDelegate?: boolean;
+  [key: string]: unknown;
+};
 
-type SessionUserInfo = {
-  employee?: { id?: string; positions?: SnapshotPosition[] }[];
+/** One employee row as the snapshot stores it. A user may hold several. */
+export type SnapshotEmployee = {
+  id?: string;
+  positions?: SnapshotPosition[];
+  [key: string]: unknown;
+};
+
+type SessionUserInfo = { employee?: SnapshotEmployee[] };
+
+/**
+ * `x-current-position-id` is sent with two different meanings by two different
+ * frontends, and the IAM guard reads it both ways in the same function: it
+ * picks the EMPLOYEE row by `position.id` but the POSITION by
+ * `employeePositionId`. Freight sends `employeePositionId`, Smart Office sends
+ * `position.id` — so whichever value arrives, one of the two lookups silently
+ * matches nothing and falls back to the first entry.
+ *
+ * Matching both fields is what makes the header mean one thing again.
+ */
+const identifies = (position: SnapshotPosition, id: string): boolean =>
+  position?.id === id || position?.employeePositionId === id;
+
+/**
+ * Every post the user holds, across every employee row, first occurrence kept.
+ *
+ * IAM keeps one employee row per ORGANIZATION, and "EDR" and "EDR Freight" are
+ * separate organizations — so a user given a freight post and a Smart Office
+ * post owns two rows, one post on each. Only one row can be the active one, and
+ * a permission check that reads only that row cannot see the other post at all.
+ */
+export const collectAllPositions = (
+  employees: SnapshotEmployee[],
+): SnapshotPosition[] => {
+  const seen = new Set<string>();
+  const all: SnapshotPosition[] = [];
+
+  for (const employee of employees) {
+    for (const position of employee.positions ?? []) {
+      const key = position.employeePositionId ?? position.id;
+      if (key) {
+        if (seen.has(key)) continue;
+        seen.add(key);
+      }
+      all.push(position);
+    }
+  }
+
+  return all;
 };
 
 /**
- * Like the IAM JwtGuard, but keeps the caller's SECONDARY positions.
+ * Which employee row the caller is acting as, and which of its positions the
+ * request selected. Pure so it can be tested without a session or a token.
  *
- * IAM models an employee as holding many positions, and the login snapshot in
- * `iam.sessions.userInfo` carries all of them. `JwtGuard.parseToken` then
- * collapses that to a single `employee.position` — whichever the request
- * headers select, else `positions[0]` — and drops the rest. Non-delegate
- * secondary positions vanish entirely, so staff holding two posts resolve to
- * only one post's permissions and every check on the other one rejects them.
+ * `owner` is the row holding the requested position; failing that the row the
+ * parent guard already picked; failing that the first. `active` is undefined
+ * when no header was sent or it names nothing — the caller then leaves the
+ * parent's choice of `employee.position` alone.
+ */
+export const resolveActiveEmployee = (
+  employees: SnapshotEmployee[],
+  requestedId: string | undefined,
+  parentEmployeeId: string | undefined,
+): { owner: SnapshotEmployee | undefined; active: SnapshotPosition | undefined } => {
+  const owner =
+    (requestedId &&
+      employees.find((candidate) =>
+        (candidate.positions ?? []).some((position) =>
+          identifies(position, requestedId),
+        ),
+      )) ||
+    employees.find(
+      (candidate) => candidate.id && candidate.id === parentEmployeeId,
+    ) ||
+    employees[0];
+
+  const active = requestedId
+    ? (owner?.positions ?? []).find((position) =>
+        identifies(position, requestedId),
+      )
+    : undefined;
+
+  return { owner, active };
+};
+
+/**
+ * Like the IAM JwtGuard, but resolves the caller's position honestly.
  *
- * This re-attaches the full list as `employee.positions`. `employee.position`
- * is left exactly as the parent set it, so everything reading the single
- * position today (audit log, delegation deadline) is unaffected; only the
- * permission utils, which prefer the array, see the difference.
+ * IAM models an employee as holding many positions — and a user as possibly
+ * holding several employee rows — and the login snapshot in
+ * `iam.sessions.userInfo` carries all of them. `JwtGuard.parseToken` collapses
+ * that to a single `employee.position` and drops the rest, so staff holding two
+ * posts resolve to one post's permissions and every check on the other one
+ * rejects them.
+ *
+ * This guard re-reads the snapshot and fixes three things the parent gets wrong:
+ *
+ *  1. re-attaches the full position list as `employee.positions`, which is what
+ *     the permission utils union over;
+ *  2. selects the employee row that actually owns the requested position, so a
+ *     post held on a second employee row is reachable at all;
+ *  3. sets `employee.position` to the requested position when the parent's
+ *     one-sided id match missed it, keeping `auditUser` in step.
+ *
+ * Every correction is skipped unless the snapshot positively resolves it, so an
+ * unreadable session degrades to the parent's single-position behaviour rather
+ * than to no position at all.
  */
 @Injectable()
 export class FreightJwtGuard extends IamJwtGuard implements CanActivate {
@@ -35,7 +130,7 @@ export class FreightJwtGuard extends IamJwtGuard implements CanActivate {
   private static readonly CACHE_MAX_ENTRIES = 5_000;
   private readonly cache = new Map<
     string,
-    { positions: SnapshotPosition[]; expiresAt: number }
+    { employees: SnapshotEmployee[]; expiresAt: number }
   >();
 
   constructor(
@@ -48,44 +143,78 @@ export class FreightJwtGuard extends IamJwtGuard implements CanActivate {
   async canActivate(context: ExecutionContext): Promise<boolean> {
     if (!(await super.canActivate(context))) return false;
 
-    const user = context.switchToHttp().getRequest().user as
-      | TCurrentUser
-      | undefined;
-    const employee = user?.employee;
+    const request = context.switchToHttp().getRequest();
+    const user = request.user as TCurrentUser | undefined;
+    const employee = user?.employee as SnapshotEmployee | undefined;
     if (!employee || !user?.sessionId) return true;
 
-    const positions = await this.positionsForSession(
-      user.sessionId,
+    const employees = await this.employeesForSession(user.sessionId);
+    if (!employees.length) return true;
+
+    const requestedId = request.headers?.[CURRENT_POSITION_ID] as
+      | string
+      | undefined;
+
+    const { owner, active } = resolveActiveEmployee(
+      employees,
+      requestedId,
       employee.id,
     );
-    // Never blank out what the parent resolved: an unreadable session or a
-    // snapshot without positions must degrade to the single-position
-    // behaviour, not to no positions at all.
-    if (positions.length) {
-      (employee as { positions?: SnapshotPosition[] }).positions = positions;
+
+    const ownerPositions = owner?.positions ?? [];
+    // Never blank out what the parent resolved: a snapshot without positions
+    // must degrade to the single-position behaviour, not to no positions.
+    if (!ownerPositions.length) return true;
+
+    // Carries the owning row's id / unitId / organizationId too, which unit
+    // scoping downstream reads — a swapped row must be swapped whole.
+    Object.assign(employee, owner);
+
+    // `collectPermissionKeys` / `collectPositionTypeKeys` union over this, and
+    // a user's posts can span several employee rows (one per organization), so
+    // it carries every row's — otherwise a freight post is invisible whenever
+    // another organization's row wins the active slot.
+    employee.positions = collectAllPositions(employees);
+
+    // Delegation stays scoped to the active desk: yard scope widens on
+    // `delegatedPositions`, and someone standing in on another organization's
+    // row is not this desk's stand-in.
+    employee.delegatedPositions = ownerPositions.filter(
+      (position) => position.isDelegate,
+    );
+
+    // The full set, for `/auth/me` — the position picker has to be able to
+    // offer a desk on a row that is not the active one.
+    (user as { employeeRows?: SnapshotEmployee[] }).employeeRows = employees;
+
+    if (active) {
+      employee.position = active;
+      // The parent already built `auditUser` from the position it guessed.
+      if (request.auditUser) {
+        request.auditUser.employeeId = employee.id;
+        request.auditUser.positionId = active.id;
+        request.auditUser.employeePositionId = active.employeePositionId;
+      }
     }
+
     return true;
   }
 
-  /** Every position the login snapshot holds for this employee. */
-  private async positionsForSession(
+  /** Every employee row the login snapshot holds for this session. */
+  private async employeesForSession(
     sessionId: string,
-    employeeId: string | undefined,
-  ): Promise<SnapshotPosition[]> {
+  ): Promise<SnapshotEmployee[]> {
     const now = Date.now();
     const hit = this.cache.get(sessionId);
-    if (hit && hit.expiresAt > now) return hit.positions;
+    if (hit && hit.expiresAt > now) return hit.employees;
 
-    let positions: SnapshotPosition[] = [];
+    let employees: SnapshotEmployee[] = [];
     try {
       const rows: { userInfo: SessionUserInfo | null }[] = await this.ds.query(
         `SELECT "userInfo" FROM iam.sessions WHERE id = $1`,
         [sessionId],
       );
-      const employees = rows[0]?.userInfo?.employee ?? [];
-      const match =
-        employees.find((e) => e?.id && e.id === employeeId) ?? employees[0];
-      positions = match?.positions ?? [];
+      employees = rows[0]?.userInfo?.employee ?? [];
     } catch {
       return []; // iam unreachable — caller keeps the parent's single position
     }
@@ -93,9 +222,9 @@ export class FreightJwtGuard extends IamJwtGuard implements CanActivate {
     if (this.cache.size >= FreightJwtGuard.CACHE_MAX_ENTRIES)
       this.cache.clear();
     this.cache.set(sessionId, {
-      positions,
+      employees,
       expiresAt: now + FreightJwtGuard.CACHE_TTL_MS,
     });
-    return positions;
+    return employees;
   }
 }
diff --git a/apps/edr-freight-api/src/common/mile-haulage.util.spec.ts b/apps/edr-freight-api/src/common/mile-haulage.util.spec.ts
index 8c3310321..c060130cd 100644
--- a/apps/edr-freight-api/src/common/mile-haulage.util.spec.ts
+++ b/apps/edr-freight-api/src/common/mile-haulage.util.spec.ts
@@ -1,4 +1,4 @@
-import { usesEdrMileService } from './mile-haulage.util';
+import { edrHaulsThisBooking, usesEdrMileService } from './mile-haulage.util';
 
 /**
  * The road legs are chosen on the contract and copied onto the booking. EDR
@@ -26,27 +26,76 @@ describe('usesEdrMileService', () => {
   });
 
   it('an export that chose collection uses EDR haulage', () => {
-    expect(
-      usesEdrMileService(booking({ tradeDirection: 'EXPORT', firstMile: 'Modjo' })),
-    ).toBe(true);
+    expect(usesEdrMileService(booking({ tradeDirection: 'EXPORT', firstMile: 'Modjo' }))).toBe(
+      true,
+    );
   });
 
   it('ignores the delivery address on an export — delivery is the import leg', () => {
-    expect(
-      usesEdrMileService(booking({ tradeDirection: 'EXPORT', lastMile: 'Djibouti' })),
-    ).toBe(false);
+    expect(usesEdrMileService(booking({ tradeDirection: 'EXPORT', lastMile: 'Djibouti' }))).toBe(
+      false,
+    );
   });
 
   it('a domestic booking counts either leg', () => {
-    expect(
-      usesEdrMileService(booking({ tradeDirection: 'DOMESTIC', firstMile: 'Adama' })),
-    ).toBe(true);
-    expect(
-      usesEdrMileService(booking({ tradeDirection: 'DOMESTIC', lastMile: 'Dire Dawa' })),
-    ).toBe(true);
+    expect(usesEdrMileService(booking({ tradeDirection: 'DOMESTIC', firstMile: 'Adama' }))).toBe(
+      true,
+    );
+    expect(usesEdrMileService(booking({ tradeDirection: 'DOMESTIC', lastMile: 'Dire Dawa' }))).toBe(
+      true,
+    );
   });
 
   it('treats a whitespace-only address as no choice', () => {
     expect(usesEdrMileService(booking({ lastMile: '   ' }))).toBe(false);
   });
 });
+
+/**
+ * Self-haul is closed only once EDR has committed to the leg. Delivery chosen
+ * on the contract is a request the chief still has to approve; collection has
+ * no approval step.
+ */
+describe('edrHaulsThisBooking', () => {
+  const booking = (over: Partial<Parameters<typeof edrHaulsThisBooking>[0]> = {}) => ({
+    tradeDirection: 'IMPORT',
+    firstMile: null,
+    lastMile: null,
+    lastMileCommitted: false,
+    ...over,
+  });
+
+  it('an import whose last-mile request is not yet approved may still self-haul', () => {
+    expect(edrHaulsThisBooking(booking({ lastMile: 'Bole, Addis Ababa' }))).toBe(false);
+  });
+
+  it('an import whose last-mile request was approved is hauled by EDR', () => {
+    expect(
+      edrHaulsThisBooking(booking({ lastMile: 'Bole, Addis Ababa', lastMileCommitted: true })),
+    ).toBe(true);
+  });
+
+  it('an import that chose no delivery self-hauls, whatever the leg tables say', () => {
+    expect(edrHaulsThisBooking(booking({ lastMileCommitted: true }))).toBe(false);
+  });
+
+  it('an export that chose collection is hauled by EDR — no approval step on that leg', () => {
+    expect(edrHaulsThisBooking(booking({ tradeDirection: 'EXPORT', firstMile: 'Modjo' }))).toBe(
+      true,
+    );
+  });
+
+  it('a domestic booking is blocked by collection, or by an approved delivery', () => {
+    expect(edrHaulsThisBooking(booking({ tradeDirection: 'DOMESTIC', firstMile: 'Adama' }))).toBe(
+      true,
+    );
+    expect(
+      edrHaulsThisBooking(booking({ tradeDirection: 'DOMESTIC', lastMile: 'Dire Dawa' })),
+    ).toBe(false);
+    expect(
+      edrHaulsThisBooking(
+        booking({ tradeDirection: 'DOMESTIC', lastMile: 'Dire Dawa', lastMileCommitted: true }),
+      ),
+    ).toBe(true);
+  });
+});
diff --git a/apps/edr-freight-api/src/common/mile-haulage.util.ts b/apps/edr-freight-api/src/common/mile-haulage.util.ts
index 1ca83d06e..c9382d45c 100644
--- a/apps/edr-freight-api/src/common/mile-haulage.util.ts
+++ b/apps/edr-freight-api/src/common/mile-haulage.util.ts
@@ -39,7 +39,60 @@ export const SELF_HAUL_CONFLICT_MESSAGE =
   'This booking is delivered by the customer’s own truck — an EDR mile leg cannot also be assigned.';
 
 export const EDR_HAULAGE_CONFLICT_MESSAGE =
-  'Customer truck assignment is only allowed when first/last mile delivery is not selected';
+  'Customer truck assignment is only allowed when first/last mile delivery is not selected, or when the EDR last-mile request has not been approved';
+
+/** The booking fields that decide whether the customer may still bring their own truck. */
+export interface MileCommitmentRow extends MileHaulageRow {
+  /**
+   * EDR has actually committed to the delivery leg: the booking's last-mile
+   * request was approved, or a `freight.last_mile` leg row exists for it.
+   * Selecting delivery on the contract is only a request — see
+   * `edrHaulsThisBooking`.
+   */
+  lastMileCommitted: boolean;
+}
+
+/**
+ * SQL for `MileCommitmentRow.lastMileCommitted`, to be selected alongside the
+ * booking row aliased `b`. Both services that gate self-haul read the same
+ * fragment so the rule cannot drift between them.
+ */
+export const LAST_MILE_COMMITTED_SQL = `(
+  EXISTS (SELECT 1
+            FROM freight.last_mile lm
+           WHERE lm.booking_id = b.id AND lm.deleted_at IS NULL)
+  OR EXISTS (SELECT 1
+               FROM freight.last_mile_requests lmr
+              WHERE lmr.booking_id = b.id
+                AND lmr.deleted_at IS NULL
+                AND lmr.status = 'APPROVED')
+)`;
+
+/**
+ * Whether EDR is hauling this booking's road leg, such that the customer may
+ * NOT assign their own truck. Stricter than `usesEdrMileService` on the
+ * delivery side: choosing last-mile delivery on the contract opens a request
+ * that the Truck & Machinery chief still has to approve, and until that
+ * approval the customer is free to self-haul instead. Collection (the export
+ * leg) has no approval step, so the contract choice alone decides it.
+ *
+ * `usesEdrMileService` keeps answering the other question — whether the booking
+ * belongs in the EDR mile queues at all — and the queue side still refuses a
+ * booking that already carries a customer truck, so the two paths remain
+ * mutually exclusive whichever acts first.
+ */
+export function edrHaulsThisBooking(booking: MileCommitmentRow): boolean {
+  const hasFirstMile = Boolean(booking.firstMile?.trim());
+  const lastMileApproved = Boolean(booking.lastMile?.trim()) && booking.lastMileCommitted;
+  switch (booking.tradeDirection) {
+    case 'IMPORT':
+      return lastMileApproved;
+    case 'EXPORT':
+      return hasFirstMile;
+    default:
+      return hasFirstMile || lastMileApproved;
+  }
+}
 
 /**
  * The road legs are chosen on the contract. A booking whose contract bought
diff --git a/apps/edr-freight-api/src/common/truck-load.util.spec.ts b/apps/edr-freight-api/src/common/truck-load.util.spec.ts
index fbb3a436a..de5ec9550 100644
--- a/apps/edr-freight-api/src/common/truck-load.util.spec.ts
+++ b/apps/edr-freight-api/src/common/truck-load.util.spec.ts
@@ -45,6 +45,16 @@ describe('assertTruckLoad', () => {
     ).toThrow(BadRequestException);
   });
 
+  it('allows two containers only when both are explicitly 20ft', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['ABCD1234567', 'ABCD7654321'],
+        bookingContainers: booking,
+        sizes: ['20ft', '45ft'],
+      }),
+    ).toThrow(BadRequestException);
+  });
+
   it('rejects more than two containers', () => {
     expect(() =>
       assertTruckLoad({
diff --git a/apps/edr-freight-api/src/common/truck-load.util.ts b/apps/edr-freight-api/src/common/truck-load.util.ts
index b65bc12fb..6380786bd 100644
--- a/apps/edr-freight-api/src/common/truck-load.util.ts
+++ b/apps/edr-freight-api/src/common/truck-load.util.ts
@@ -54,10 +54,11 @@ export function assertTruckLoad({
     }
   }
 
-  // A 40ft fills the bed, so it travels alone.
-  if (containers.length > 1 && sizes.some((size) => size.includes('40'))) {
+  // A truck may pair containers only when BOTH are explicitly 20ft. A 40ft
+  // (and any legacy/unknown larger size) fills the bed and travels alone.
+  if (containers.length > 1 && sizes.some((size) => !size.includes('20'))) {
     throw new BadRequestException(
-      'A 40ft container fills the truck — assign only 1 container to this truck',
+      'Truck capacity is either 1 x 40ft container or up to 2 x 20ft containers',
     );
   }
 }
diff --git a/apps/edr-freight-api/src/common/validators/is-phone-number.validator.ts b/apps/edr-freight-api/src/common/validators/is-phone-number.validator.ts
index 4f060ca11..c4588af07 100644
--- a/apps/edr-freight-api/src/common/validators/is-phone-number.validator.ts
+++ b/apps/edr-freight-api/src/common/validators/is-phone-number.validator.ts
@@ -4,25 +4,29 @@ import {
   ValidationOptions,
   ValidatorConstraint,
   ValidatorConstraintInterface,
-} from 'class-validator';
-import { isValidPhoneNumber, parsePhoneNumberFromString } from 'libphonenumber-js';
+} from "class-validator";
+import {
+  isValidPhoneNumber,
+  parsePhoneNumberFromString,
+} from "libphonenumber-js";
 
 /**
  * Country-aware phone validation. The value is expected as a full international
- * number (E.164, e.g. "+251911223344"), so the country is derived from the
- * value itself — no separate country field needed.
+ * number (E.164, e.g. "+25377834567" for Djibouti or "+251911223344" for
+ * Ethiopia), so the country is derived from the value itself — no separate
+ * country field needed.
  */
-@ValidatorConstraint({ name: 'IsValidPhone', async: false })
+@ValidatorConstraint({ name: "IsValidPhone", async: false })
 export class IsValidPhoneConstraint implements ValidatorConstraintInterface {
   validate(value: unknown): boolean {
     // Empty is allowed here; pair with @IsOptional / @IsNotEmpty as needed.
-    if (value === undefined || value === null || value === '') return true;
-    if (typeof value !== 'string') return false;
+    if (value === undefined || value === null || value === "") return true;
+    if (typeof value !== "string") return false;
     return isValidPhoneNumber(value);
   }
 
   defaultMessage(args: ValidationArguments): string {
-    return `${args.property} must be a valid international phone number (E.164, e.g. +251911223344)`;
+    return `${args.property} must be a complete international phone number (E.164, e.g. +25377834567 or +251911223344)`;
   }
 }
 
@@ -53,7 +57,7 @@ export function IsValidPhone(validationOptions?: ValidationOptions) {
 export function normalizeE164(
   value: string | null | undefined,
 ): string | null | undefined {
-  if (value === undefined || value === null || value === '') return value;
-  const parsed = parsePhoneNumberFromString(value, 'ET');
+  if (value === undefined || value === null || value === "") return value;
+  const parsed = parsePhoneNumberFromString(value, "ET");
   return parsed?.isValid() ? parsed.number : value.trim();
 }
diff --git a/apps/edr-freight-api/src/config/eims.config.spec.ts b/apps/edr-freight-api/src/config/eims.config.spec.ts
index a6aa3895d..5e89822f4 100644
--- a/apps/edr-freight-api/src/config/eims.config.spec.ts
+++ b/apps/edr-freight-api/src/config/eims.config.spec.ts
@@ -26,6 +26,20 @@ const withEnv = (vars: Record<string, string | undefined>, fn: () => void) => {
 };
 
 describe("eims.config — private key / certificate resolution", () => {
+  it("requires EIMS_API_KEY when EIMS is enabled without exposing a value", () => {
+    withEnv(
+      {
+        ...REQUIRED,
+        EIMS_API_KEY: undefined,
+        EIMS_PRIVATE_KEY: "private-key-present",
+        EIMS_CERTIFICATE: "certificate-present",
+      },
+      () => {
+        expect(() => eimsConfigFactory()).toThrow(/env vars are missing: EIMS_API_KEY/);
+      },
+    );
+  });
+
   it("unescapes a literal \\n when the PEM was pasted without real newlines", () => {
     withEnv(
       { ...REQUIRED, EIMS_PRIVATE_KEY: "line1\\nline2", EIMS_CERTIFICATE_PATH: "/dev/null" },
diff --git a/apps/edr-freight-api/src/config/mor-location.resolver.spec.ts b/apps/edr-freight-api/src/config/mor-location.resolver.spec.ts
index 0fc2607e2..77d230583 100644
--- a/apps/edr-freight-api/src/config/mor-location.resolver.spec.ts
+++ b/apps/edr-freight-api/src/config/mor-location.resolver.spec.ts
@@ -29,6 +29,8 @@ const FIXTURE: MorLocationTuple[] = [
   [70, "Ethiopia", 2, "OROMIA", 86, "FINFINE VIC SPEC", 976, "Wal-Mera"],
   [70, "Ethiopia", 2, "OROMIA", 86, "FINFINE VIC SPEC", 909, "Akaki woreda"],
   [70, "Ethiopia", 13, "ADDIS ABABA", 78, "BOLE", 1100, "WOREDA 1"],
+  [70, "Ethiopia", 13, "ADDIS ABABA", 78, "BOLE", 1102, "WOREDA 3"],
+  [70, "Ethiopia", 13, "ADDIS ABABA", 81, "KOLFIE KERANIYO", 1139, "WOREDA 7"],
   [253, "Djibouti", 1, "DJIBOUTI", 1, "DJIBOUTI VILLE", 1, "BALBALA"],
 ];
 
@@ -181,6 +183,93 @@ describe("resolveMorGeo", () => {
     });
   });
 
+  describe("Addis Ababa, where MoR has no zone tier", () => {
+    // e-Trade's real shape for a chartered city: `zone` repeats the region, the sub-city sits in
+    // `woreda`, and the numbered woreda sits in `kebele`. This is how every company imported from
+    // e-Trade stores an Addis Ababa address, and it is the shape that blocked INV-20260829-00011.
+    const ETRADE_SHAPE = {
+      country: "Ethiopia",
+      region: "Addis Ababa",
+      zone: "Addis Ababa",
+      woreda: "Kolfe-Keraniyo",
+      kebele: "07",
+    };
+
+    it("reads the sub-city and woreda one level down when the zone repeats the region", () => {
+      expect(resolveMorGeo(ETRADE_SHAPE, FIXTURE)).toEqual({
+        Country: "70",
+        Region: "13",
+        City: "81",
+        Wereda: "1139",
+      });
+    });
+
+    it("matches MoR's own 'KOLFIE KERANIYO' spelling of the sub-city", () => {
+      expect(resolveMorGeo({ ...ETRADE_SHAPE, woreda: "Kolfe Keranio" }, FIXTURE).City).toBe("81");
+    });
+
+    it("reads a zero-padded number as MoR's 'WOREDA n' locality, in either slot", () => {
+      const bole = { country: "Ethiopia", region: "Addis Ababa", zone: "Bole" };
+      expect(resolveMorGeo({ ...bole, woreda: "03" }, FIXTURE).Wereda).toBe("1102");
+      expect(resolveMorGeo({ ...bole, woreda: "Woreda 03" }, FIXTURE).Wereda).toBe("1102");
+      expect(resolveMorGeo({ ...bole, woreda: "WOREDA 3" }, FIXTURE).Wereda).toBe("1102");
+    });
+
+    it("still resolves the already-correct shape without shifting", () => {
+      expect(
+        resolveMorGeo(
+          { country: "Ethiopia", region: "ADDIS ABABA", zone: "BOLE", woreda: "WOREDA 1" },
+          FIXTURE,
+        ),
+      ).toEqual({ Country: "70", Region: "13", City: "78", Wereda: "1100" });
+    });
+
+    it("reports the zone failure, not the shifted one, when the shift does not resolve", () => {
+      // LEMI KURA is a 2020 sub-city the Ministry sheet does not list. The shift must not turn
+      // that into a confusing locality error, and must never land on a neighbouring sub-city.
+      expect(() =>
+        resolveMorGeo({ ...ETRADE_SHAPE, woreda: "Lemi Kura", kebele: "02" }, FIXTURE),
+      ).toThrow(/no MoR CITY_NAME match for country="Ethiopia", region="Addis Ababa"/);
+    });
+
+    it("does not shift when the zone is simply an unknown zone", () => {
+      expect(() =>
+        resolveMorGeo(
+          {
+            country: "Ethiopia",
+            region: "OROMIA",
+            zone: "East Zone",
+            woreda: "KERSA",
+            kebele: "01",
+          },
+          FIXTURE,
+        ),
+      ).toThrow(/no MoR CITY_NAME match/);
+    });
+  });
+
+  it("resolves the regions and zones MoR spells differently from e-Trade", () => {
+    // Guards the reviewed alias table: MoR's PARISH_NAME is "AMAHARA", and it keeps the Amharic
+    // compass words for the Oromia zones ("MISRAK SHOA" for East Shewa).
+    const rows: MorLocationTuple[] = [
+      ...FIXTURE,
+      [70, "Ethiopia", 2, "OROMIA", 16, "MISRAK SHOA", 21, "ADAMA"],
+      [70, "Ethiopia", 11, "AMAHARA", 53, "WEST GOJAM", 149, "MECHA"],
+    ];
+    expect(
+      resolveMorGeo(
+        { country: "Ethiopia", region: "Oromia", zone: "East Shewa", woreda: "Adama" },
+        rows,
+      ),
+    ).toEqual({ Country: "70", Region: "2", City: "16", Wereda: "21" });
+    expect(
+      resolveMorGeo(
+        { country: "Ethiopia", region: "Amhara", zone: "West Gojjam", woreda: "Mecha" },
+        rows,
+      ),
+    ).toEqual({ Country: "70", Region: "11", City: "53", Wereda: "149" });
+  });
+
   describe("failures happen locally, before anything is filed", () => {
     const cases: Array<[string, Record<string, string>, RegExp]> = [
       ["unknown country", { ...JIJIGA, country: "Wakanda" }, /no MoR COUNTRY_NAME match/],
diff --git a/apps/edr-freight-api/src/config/mor-location.resolver.ts b/apps/edr-freight-api/src/config/mor-location.resolver.ts
index 72459db9b..0b0cef6e2 100644
--- a/apps/edr-freight-api/src/config/mor-location.resolver.ts
+++ b/apps/edr-freight-api/src/config/mor-location.resolver.ts
@@ -43,6 +43,11 @@ export interface MorAddressInput {
   region?: string | null;
   zone?: string | null;
   woreda?: string | null;
+  /**
+   * Only read for the city-region shift below — in Addis Ababa e-Trade stores the numbered woreda
+   * here. Never consulted for an ordinary region/zone/woreda address.
+   */
+  kebele?: string | null;
 }
 
 type Level = "country" | "region" | "zone" | "woreda";
@@ -115,6 +120,24 @@ const ALIASES: MorAlias[] = [
     from: "Jigjiga",
     to: "JIJIGA",
   },
+  // MoR misspells the region itself — PARISH_NO 11 is "AMAHARA". No other parish is close to it.
+  { level: "region", from: "Amhara", to: "AMAHARA" },
+  // Addis Ababa sub-cities, where MoR's sheet and e-Trade disagree on spelling. Each confirmed by
+  // CITY_NO under PARISH_NO 13; the seven that already agree (ARADA, ADDIS KETEMA, LIDETA, KIRKOS,
+  // YEKA, BOLE, GULLELE) need no entry. LEMI KURA is deliberately absent — the Ministry sheet does
+  // not list the 2020 split at all, so it must keep failing rather than be mapped onto a neighbour.
+  { level: "zone", region: "ADDIS ABABA", from: "Kolfe Keraniyo", to: "KOLFIE KERANIYO" }, // 81
+  { level: "zone", region: "ADDIS ABABA", from: "Kolfe Keranio", to: "KOLFIE KERANIYO" }, // 81
+  { level: "zone", region: "ADDIS ABABA", from: "Nifas Silk Lafto", to: "NEFAS SILK LAFTO" }, // 80
+  { level: "zone", region: "ADDIS ABABA", from: "Akaki Kality", to: "AKAKI KALITI" }, // 79
+  // MoR keeps the Amharic compass words for the Oromia zones; e-Trade stores the English ones.
+  // Each pair confirmed by the zone's own localities in the sheet: MISRAK SHOA holds ADAMA and
+  // BISHOFTU, MIRAB SHOA holds AMBO and WELMERA, MIRAB HARARGE holds CHIRO and GEMMECHIS.
+  { level: "zone", region: "OROMIA", from: "East Shewa", to: "MISRAK SHOA" }, // 16
+  { level: "zone", region: "OROMIA", from: "West Shewa", to: "MIRAB SHOA" }, // 62
+  { level: "zone", region: "OROMIA", from: "West Hararge", to: "MIRAB HARARGE" }, // 7
+  // MoR drops a J. Confirmed by BAHIRDAR ZURIA / MECHA / BURIE sitting under CITY_NO 53.
+  { level: "zone", region: "AMAHARA", from: "West Gojjam", to: "WEST GOJAM" }, // 53
 ];
 
 /**
@@ -127,6 +150,20 @@ const ALIASES: MorAlias[] = [
 const zoneSuffixCandidates = (normalized: string): string[] =>
   normalized.endsWith(" ZONE") ? [] : [`${normalized} ZONE`];
 
+/**
+ * In the chartered cities MoR names each locality "WOREDA 7", while e-Trade stores the bare,
+ * zero-padded number ("07") and EDR's own forms sometimes store "Woreda 05". All three mean the
+ * same locality, so the MoR spelling is tried as a second exact-match candidate — MoR writes no
+ * leading zero, hence the strip. Applied to the locality level only.
+ *
+ * This runs ahead of the numeric LOCALITY_NO fallback below, and can never mask it: no city in the
+ * Ministry sheet contains both a "WOREDA n" locality and a locality whose LOCALITY_NO is n.
+ */
+const woredaNumberCandidates = (normalized: string): string[] => {
+  const match = /^(?:WOREDA )?0*([0-9]{1,2})$/.exec(normalized);
+  return match ? [`WOREDA ${match[1]}`] : [];
+};
+
 export class MorGeoMappingError extends BadRequestException {
   constructor(code: "EIMS_GEO_MAPPING_FAILED" | "EIMS_GEO_AMBIGUOUS", message: string) {
     super({ code, message });
@@ -158,6 +195,7 @@ function matchLevel(
       if (normalizeName(alias.from) === wanted) candidates.push(normalizeName(alias.to));
     }
     if (level === "zone") candidates.push(...zoneSuffixCandidates(wanted));
+    if (level === "woreda") candidates.push(...woredaNumberCandidates(wanted));
   }
 
   let matched: MorLocationTuple[] = [];
@@ -221,25 +259,46 @@ export function resolveMorGeo(
   const inCountry = matchLevel(rows, "country", country, {}, input);
   const inRegion = matchLevel(inCountry.rows, "region", input.region, {}, input);
   const regionScope = normalizeName(inRegion.rows[0][SLOTS.region.name] as string);
-  const inZone = matchLevel(inRegion.rows, "zone", input.zone, { region: regionScope }, input);
-  const zoneScope = normalizeName(inZone.rows[0][SLOTS.zone.name] as string);
-  const inWoreda = matchLevel(
-    inZone.rows,
-    "woreda",
-    input.woreda,
-    {
-      region: regionScope,
-      zone: zoneScope,
-    },
-    input,
-  );
 
-  return {
-    Country: String(inCountry.no),
-    Region: String(inRegion.no),
-    City: String(inZone.no),
-    Wereda: String(inWoreda.no),
+  type Name = string | null | undefined;
+  const below = (zone: Name, woreda: Name): MorGeoCodes => {
+    const inZone = matchLevel(inRegion.rows, "zone", zone, { region: regionScope }, input);
+    const zoneScope = normalizeName(inZone.rows[0][SLOTS.zone.name] as string);
+    const inWoreda = matchLevel(
+      inZone.rows,
+      "woreda",
+      woreda,
+      {
+        region: regionScope,
+        zone: zoneScope,
+      },
+      input,
+    );
+    return {
+      Country: String(inCountry.no),
+      Region: String(inRegion.no),
+      City: String(inZone.no),
+      Wereda: String(inWoreda.no),
+    };
   };
+
+  try {
+    return below(input.zone, input.woreda);
+  } catch (err) {
+    // Addis Ababa (and every other chartered city) has no zone tier: MoR's CITY level *is* the
+    // sub-city and its LOCALITY level is the numbered woreda. e-Trade fills the missing tier by
+    // repeating the region in `zone`, which pushes the sub-city into `woreda` and the woreda
+    // number into `kebele` — one level down the whole way. Retry with that reading, but only when
+    // `zone` genuinely repeats the region, and only accept it when *both* shifted levels resolve
+    // exactly. A zone MoR simply does not list still fails with its own message, unreinterpreted.
+    const zone = normalizeName(input.zone);
+    if (!zone || (zone !== regionScope && zone !== normalizeName(input.region))) throw err;
+    try {
+      return below(input.woreda, input.kebele);
+    } catch {
+      throw err;
+    }
+  }
 }
 
 /** Non-throwing variant for callers that already have a working fallback (the seller identity). */
diff --git a/apps/edr-freight-api/src/migrations/3790000000000-TransitAgentAccount.ts b/apps/edr-freight-api/src/migrations/3790000000000-TransitAgentAccount.ts
new file mode 100644
index 000000000..eedf8b149
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3790000000000-TransitAgentAccount.ts
@@ -0,0 +1,55 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Give a transit agent a portal login.
+ *
+ * Every column is NULLABLE and nothing is backfilled: production already holds
+ * transit agents that exist only as a GL-assignable roster entry, and they must
+ * keep working untouched. An agent gains an account when staff invite it — at
+ * which point `user_id` is filled in — so "has a login" is exactly
+ * `user_id IS NOT NULL`, and the assignment flow never has to care.
+ *
+ * The unique indexes are partial (`WHERE ... IS NOT NULL`) because Postgres
+ * treats NULLs as distinct in a plain unique index only per-row; being explicit
+ * documents that many account-less agents are expected to coexist.
+ */
+export class TransitAgentAccount3790000000000 implements MigrationInterface {
+  name = "TransitAgentAccount3790000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.transit_agents
+         ADD COLUMN IF NOT EXISTS user_id uuid,
+         ADD COLUMN IF NOT EXISTS email varchar(150),
+         ADD COLUMN IF NOT EXISTS phone_number varchar(30)`,
+    );
+    // One IAM account can back at most one transit agent — otherwise a single
+    // login would resolve to two agents in `findByUserId`.
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS ux_transit_agents_user_id
+         ON freight.transit_agents (user_id)
+       WHERE user_id IS NOT NULL AND deleted_at IS NULL`,
+    );
+    // Case-insensitive, matching how the repository checks for duplicates.
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS ux_transit_agents_email
+         ON freight.transit_agents (lower(email))
+       WHERE email IS NOT NULL AND deleted_at IS NULL`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.ux_transit_agents_email`,
+    );
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.ux_transit_agents_user_id`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.transit_agents
+         DROP COLUMN IF EXISTS phone_number,
+         DROP COLUMN IF EXISTS email,
+         DROP COLUMN IF EXISTS user_id`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3800000000000-BookingCancellationWagons.ts b/apps/edr-freight-api/src/migrations/3800000000000-BookingCancellationWagons.ts
new file mode 100644
index 000000000..df994d832
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3800000000000-BookingCancellationWagons.ts
@@ -0,0 +1,35 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Wagon footprint pinned for cancellation pricing. `wagons_required` is a LIVE
+ * scheduling field — unassign clears it to NULL — so a paid booking pulled off
+ * a train had nothing left to price a cancellation fee or credit against
+ * ("This booking has no wagon requirement to cancel from."). This column is
+ * stamped once, at first allocation, and never cleared: cancellation reads it
+ * (falling back to a computed count for bookings never allocated).
+ */
+export class BookingCancellationWagons3800000000000 implements MigrationInterface {
+  name = 'BookingCancellationWagons3800000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        ADD COLUMN IF NOT EXISTS cancellation_wagons numeric(6,2)
+    `);
+    // Backfill the bookings that still carry a live stamp.
+    await queryRunner.query(`
+      UPDATE freight.bookings
+         SET cancellation_wagons = wagons_required
+       WHERE cancellation_wagons IS NULL
+         AND wagons_required IS NOT NULL
+         AND wagons_required > 0
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        DROP COLUMN IF EXISTS cancellation_wagons
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3810000000000-TransitAssignments.ts b/apps/edr-freight-api/src/migrations/3810000000000-TransitAssignments.ts
new file mode 100644
index 000000000..9d0116681
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3810000000000-TransitAssignments.ts
@@ -0,0 +1,72 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Transit assignments — one row per (booking × transit agent), so an agent
+ * handles many bookings.
+ *
+ * Deliberately NOT the existing transit-assignee handshake on bookings
+ * (`/bookings/:id/clearance/transit-assignee/...`, which stores its answer on
+ * the booking itself): that is a pre-declaration agreement between GL Ethiopia
+ * and GL Djibouti about WHO will handle customs. This is the work record —
+ * status, timings and documents — and nothing here reads or writes that flow.
+ *
+ * There is no duration column on purpose. The time taken after the train
+ * arrives is `finished_at − bookings.arrived_at`, and both halves already
+ * exist; storing the difference would be a third source of truth that goes
+ * stale the moment either timestamp is corrected. It is computed on read.
+ *
+ * Documents hang off `freight.files` with `resource = 'transit_assignments'`
+ * and `resource_id = transit_assignments.id`. That table already carries the
+ * MinIO object, the upload time (`created_at`), the uploader, the edit time
+ * (`updated_at`) and the supersede history, so no file table is added here.
+ */
+export class TransitAssignments3810000000000 implements MigrationInterface {
+  name = "TransitAssignments3810000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.transit_assignments (
+        id uuid NOT NULL DEFAULT gen_random_uuid(),
+        booking_id uuid NOT NULL,
+        transit_agent_id uuid NOT NULL,
+        status varchar(32) NOT NULL DEFAULT 'NOT_STARTED',
+        started_at timestamptz,
+        finished_at timestamptz,
+        assigned_by_user_id uuid,
+        assigned_at timestamptz NOT NULL DEFAULT now(),
+        note text,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz,
+        CONSTRAINT pk_transit_assignments PRIMARY KEY (id),
+        CONSTRAINT fk_transit_assignments_booking
+          FOREIGN KEY (booking_id) REFERENCES freight.bookings (id),
+        CONSTRAINT fk_transit_assignments_agent
+          FOREIGN KEY (transit_agent_id) REFERENCES freight.transit_agents (id)
+      )
+    `);
+
+    // One live assignment per (booking, agent). Partial so a soft-deleted row
+    // never blocks re-assigning the same agent to the same booking later.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS ux_transit_assignments_booking_agent
+        ON freight.transit_assignments (booking_id, transit_agent_id)
+        WHERE deleted_at IS NULL
+    `);
+
+    // The two list directions: a booking's assignments, and an agent's workload.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS ix_transit_assignments_booking
+        ON freight.transit_assignments (booking_id) WHERE deleted_at IS NULL
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS ix_transit_assignments_agent_status
+        ON freight.transit_assignments (transit_agent_id, status)
+        WHERE deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.transit_assignments`);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3820000000000-WagonEvents.ts b/apps/edr-freight-api/src/migrations/3820000000000-WagonEvents.ts
new file mode 100644
index 000000000..014df7491
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3820000000000-WagonEvents.ts
@@ -0,0 +1,60 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Unified per-wagon history ledger. One append-only row per transition
+ * (yard move, coupling, schedule pin/dispatch/release, status flip, cargo
+ * load/unload, container placement, lifecycle edits), written in the same
+ * transaction as the change. No foreign keys: history must survive the wagon,
+ * train, schedule or booking it points at. The two composite indexes back
+ * keyset pagination of a single wagon's timeline (optionally per category);
+ * the partial ones answer "what happened on this schedule / booking".
+ */
+export class WagonEvents3820000000000 implements MigrationInterface {
+  name = 'WagonEvents3820000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.wagon_events (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        wagon_id uuid NOT NULL,
+        wagon_number varchar,
+        event_type varchar(40) NOT NULL,
+        category varchar(20) NOT NULL,
+        occurred_at timestamptz NOT NULL DEFAULT now(),
+        actor_user_id uuid,
+        from_yard_id uuid,
+        to_yard_id uuid,
+        train_id uuid,
+        train_schedule_id uuid,
+        booking_id uuid,
+        from_value varchar(120),
+        to_value varchar(120),
+        reason text,
+        metadata jsonb,
+        created_at timestamptz NOT NULL DEFAULT now()
+      )
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagon_events_wagon_time
+        ON freight.wagon_events (wagon_id, occurred_at DESC, id DESC)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagon_events_wagon_cat_time
+        ON freight.wagon_events (wagon_id, category, occurred_at DESC, id DESC)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagon_events_schedule
+        ON freight.wagon_events (train_schedule_id)
+        WHERE train_schedule_id IS NOT NULL
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagon_events_booking
+        ON freight.wagon_events (booking_id)
+        WHERE booking_id IS NOT NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.wagon_events`);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3840000000000-EmptyReturnRequests.ts b/apps/edr-freight-api/src/migrations/3840000000000-EmptyReturnRequests.ts
new file mode 100644
index 000000000..157b95570
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3840000000000-EmptyReturnRequests.ts
@@ -0,0 +1,67 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Customer-initiated empty container return, for a booking that did NOT buy
+ * the return service up front. The customer names the containers coming back,
+ * operations approves and prices it off the contract's WITH_RETURN rate, the
+ * customer pays that invoice and then books the date and truck. The empty
+ * itself is still recorded through `empty_container_returns` when the truck
+ * actually arrives — this table only carries the request up to that point.
+ */
+export class EmptyReturnRequests3840000000000 implements MigrationInterface {
+  name = 'EmptyReturnRequests3840000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.empty_return_requests (
+        id                    uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
+        booking_id            uuid NOT NULL,
+        company_id            uuid,
+        status                varchar(30) NOT NULL DEFAULT 'SUBMITTED',
+        container_numbers     text[] NOT NULL DEFAULT '{}',
+        container_count       smallint NOT NULL DEFAULT 0,
+        quoted_unit_amount    numeric(14,2),
+        quoted_total_amount   numeric(14,2),
+        currency              varchar(8),
+        invoice_id            uuid,
+        paid_at               timestamptz,
+        requested_return_date date,
+        truck_plate_number    varchar(32),
+        truck_driver_name     varchar(120),
+        truck_type            varchar(60),
+        scheduled_at          timestamptz,
+        submitted_by_user_id  uuid,
+        submitted_at          timestamptz NOT NULL DEFAULT now(),
+        reviewed_by_staff_id  uuid,
+        reviewed_at           timestamptz,
+        rejection_reason      text,
+        completed_at          timestamptz,
+        created_at            timestamptz NOT NULL DEFAULT now(),
+        updated_at            timestamptz NOT NULL DEFAULT now(),
+        deleted_at            timestamptz
+      )
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_empty_return_requests_booking
+        ON freight.empty_return_requests (booking_id)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_empty_return_requests_status
+        ON freight.empty_return_requests (status)
+    `);
+
+    // A container number may only be owed back once at a time. That guard is
+    // per array element, so it lives in the service (see assertContainersFree)
+    // rather than in a unique index — this GIN index is what makes the check
+    // cheap.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_empty_return_requests_containers
+        ON freight.empty_return_requests USING gin (container_numbers)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.empty_return_requests`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.interceptor.ts b/apps/edr-freight-api/src/modules/audit/audit.interceptor.ts
index cf12fd4d3..8b5c82e9c 100644
--- a/apps/edr-freight-api/src/modules/audit/audit.interceptor.ts
+++ b/apps/edr-freight-api/src/modules/audit/audit.interceptor.ts
@@ -4,24 +4,17 @@ import {
   HttpException,
   Injectable,
   NestInterceptor,
-} from '@nestjs/common';
-import { Observable, tap } from 'rxjs';
-import type { Request, Response } from 'express';
+} from "@nestjs/common";
+import { Observable, tap } from "rxjs";
+import type { Request, Response } from "express";
 
-import { AuditService } from './audit.service';
-import {
-  auditEndpointMatcher,
-  type MatchedAuditEndpoint,
-} from './audit-endpoint-matcher';
-import {
-  isAuditableActor,
-  resolveAuditActor,
-  type AuditActorSource,
-} from './audit-actor';
-import { redactUrlQuery, sanitizeRequestPayload } from './audit.sanitizer';
+import { AuditService } from "./audit.service";
+import { auditEndpointMatcher, type MatchedAuditEndpoint } from "./audit-endpoint-matcher";
+import { isAuditableActor, resolveAuditActor, type AuditActorSource } from "./audit-actor";
+import { redactUrlQuery, sanitizeRequestPayload } from "./audit.sanitizer";
 
 /** Methods that can change state. Everything else is never audited. */
-const AUDITED_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const AUDITED_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 
 /** `error_message` ceiling — stack traces do not belong in this column. */
 const MAX_ERROR_LENGTH = 2_000;
@@ -52,7 +45,7 @@ export class AuditInterceptor implements NestInterceptor {
 
   intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
     // Non-HTTP contexts (the RabbitMQ microservice transport) have no request.
-    if (context.getType() !== 'http') return next.handle();
+    if (context.getType() !== "http") return next.handle();
 
     const httpContext = context.switchToHttp();
     const request = httpContext.getRequest<RequestWithUser>();
@@ -72,10 +65,7 @@ export class AuditInterceptor implements NestInterceptor {
     const startedAt = Date.now();
     // The body is captured up front: handlers are free to mutate the DTO they
     // are given, so reading it after the fact can record post-mutation values.
-    const requestPayload = sanitizeRequestPayload(
-      request.body,
-      request.files ?? request.file,
-    );
+    const requestPayload = sanitizeRequestPayload(request.body, request.files ?? request.file);
 
     return next.handle().pipe(
       tap({
@@ -137,7 +127,6 @@ export class AuditInterceptor implements NestInterceptor {
       resourceId: matched.resourceId,
       request: requestPayload,
       ipAddress: resolveIp(request),
-      userAgent: request.headers['user-agent'] ?? null,
       requestId: resolveRequestId(request),
       durationMs: Date.now() - startedAt,
     });
@@ -154,10 +143,10 @@ function resolveErrorMessage(error: unknown): string | null {
   if (error instanceof HttpException) {
     const response = error.getResponse();
     const message =
-      typeof response === 'string'
+      typeof response === "string"
         ? response
         : ((response as { message?: unknown })?.message ?? error.message);
-    const text = Array.isArray(message) ? message.join('; ') : String(message);
+    const text = Array.isArray(message) ? message.join("; ") : String(message);
     return text.slice(0, MAX_ERROR_LENGTH);
   }
 
@@ -171,19 +160,19 @@ function resolveErrorMessage(error: unknown): string | null {
  * entry (the original client) taken.
  */
 function resolveIp(request: Request): string | null {
-  const forwarded = request.headers['x-forwarded-for'];
+  const forwarded = request.headers["x-forwarded-for"];
   const raw = Array.isArray(forwarded) ? forwarded[0] : forwarded;
-  const candidate = raw?.split(',')[0]?.trim() || request.ip;
+  const candidate = raw?.split(",")[0]?.trim() || request.ip;
   if (!candidate) return null;
 
   // Normalize IPv4-mapped IPv6 (`::ffff:10.0.0.1`), which the `inet` column
   // accepts but which reads badly and breaks grouping by address.
-  return candidate.startsWith('::ffff:') ? candidate.slice(7) : candidate;
+  return candidate.startsWith("::ffff:") ? candidate.slice(7) : candidate;
 }
 
 /** Correlation id from the proxy/tracing layer, when present. */
 function resolveRequestId(request: RequestWithUser): string | null {
-  const header = request.headers['x-request-id'] ?? request.headers['x-correlation-id'];
+  const header = request.headers["x-request-id"] ?? request.headers["x-correlation-id"];
   const value = Array.isArray(header) ? header[0] : header;
   return (value ?? request.id ?? null)?.toString().slice(0, 64) ?? null;
 }
diff --git a/apps/edr-freight-api/src/modules/auth/freight-me.service.ts b/apps/edr-freight-api/src/modules/auth/freight-me.service.ts
index b897c5fef..0195bba47 100644
--- a/apps/edr-freight-api/src/modules/auth/freight-me.service.ts
+++ b/apps/edr-freight-api/src/modules/auth/freight-me.service.ts
@@ -3,6 +3,7 @@ import { InjectDataSource } from '@nestjs/typeorm';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
 import { DataSource } from 'typeorm';
 
+import type { SnapshotEmployee } from '../../common/freight-jwt.guard';
 import {
   collectPermissionKeys,
   isSuperAdmin,
@@ -82,8 +83,26 @@ export class FreightMeService {
         ? [employeeRecord.position]
         : [];
 
-    const enrichedPositions = await Promise.all(
-      rawPositions.map(async (position) => {
+    // IAM keeps one employee row per organization, so a user holding a freight
+    // post and a Smart Office post owns two rows. The backoffice reads
+    // `employee` as an array and the position picker lists what it finds there
+    // — returning only the active row hides the other desk and makes it
+    // unselectable. `FreightJwtGuard` leaves the full set here.
+    const employeeRows = (user as { employeeRows?: SnapshotEmployee[] })
+      .employeeRows;
+
+    // Active row first: the backoffice reads `employee[0]` for
+    // unitId/organizationId, so the desk the caller is acting as must lead.
+    const rows: SnapshotEmployee[] = employeeRows?.length
+      ? [
+          ...employeeRows.filter((row) => row.id === employeeRecord?.id),
+          ...employeeRows.filter((row) => row.id !== employeeRecord?.id),
+        ]
+      : employeeRecord
+        ? [{ ...employeeRecord, positions: rawPositions } as SnapshotEmployee]
+        : [];
+
+    const enrichPosition = async (position: TokenPosition) => {
         const [positionType, positionTypePermissionKeys] = await Promise.all([
           this.lookupPositionType(position.id),
           this.lookupPositionTypePermissions(position.id),
@@ -114,20 +133,24 @@ export class FreightMeService {
             positionType,
           },
         };
-      }),
+    };
+
+    const enrichedRows = await Promise.all(
+      rows.map(async (row) => ({
+        row,
+        positions: await Promise.all(
+          ((row.positions ?? []) as TokenPosition[]).map(enrichPosition),
+        ),
+      })),
     );
 
-    const employee = employeeRecord
-      ? [
-          {
-            id: employeeRecord.id,
-            organizationId: employeeRecord.organizationId,
-            unitId: employeeRecord.unitId,
-            name: employeeRecord.name,
-            positions: enrichedPositions.map((p) => p.position),
-          },
-        ]
-      : [];
+    const employee = enrichedRows.map(({ row, positions }) => ({
+      id: row.id as string,
+      organizationId: row.organizationId as string,
+      unitId: row.unitId as string,
+      name: row.name,
+      positions: positions.map((p) => p.position),
+    }));
 
     // `collectPermissionKeys` reads the raw token (position-level only), so
     // union the type-level grants in — the backoffice prefers this flat list
@@ -135,7 +158,9 @@ export class FreightMeService {
     const permissionKeys = [
       ...new Set([
         ...collectPermissionKeys(user),
-        ...enrichedPositions.flatMap((p) => p.positionTypePermissionKeys),
+        ...enrichedRows.flatMap(({ positions }) =>
+          positions.flatMap((p) => p.positionTypePermissionKeys),
+        ),
       ]),
     ];
 
diff --git a/apps/edr-freight-api/src/modules/billing/billing.module.ts b/apps/edr-freight-api/src/modules/billing/billing.module.ts
index 06849d560..d29d52c42 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.module.ts
@@ -14,6 +14,8 @@ import { InvoiceLineRepository } from "./invoice-line.repository";
 import { PaymentModule } from "../payment/payment.module";
 import { CompaniesModule } from "../companies/companies.module";
 import { FilesModule } from "../files/files.module";
+import { NotificationsModule } from "../notifications/notifications.module";
+import { NotificationInboxModule } from "../notification-inbox/notification-inbox.module";
 
 @Module({
   imports: [
@@ -24,6 +26,10 @@ import { FilesModule } from "../files/files.module";
     DocumentsModule,
     UserTradeAccessModule,
     FilesModule,
+    // Customer notice when Finance confirms a manual payment. The inbox module
+    // reaches this one back through CompaniesModule, hence forwardRef.
+    NotificationsModule,
+    forwardRef(() => NotificationInboxModule),
   ],
   controllers: [BillingController, PortalBillingController, PaymentController],
   providers: [BillingService, InvoiceRepository, InvoiceLineRepository],
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index f07e6d50f..9a34516aa 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -83,6 +83,8 @@ describe("BillingService.generateInvoice", () => {
       {} as never, // files
       { get: () => undefined } as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
   });
 
@@ -166,6 +168,8 @@ describe("BillingService.issueMemo", () => {
       {} as never,
       { get: () => undefined } as never,
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, manager, savedLines };
   }
@@ -301,6 +305,8 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never, // files
       { get: () => undefined } as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -357,6 +363,8 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never, // files
       { get: () => undefined } as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -403,6 +411,8 @@ describe("BillingService.settleByPaymentId", () => {
       {} as never, // files
       { get: () => undefined } as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, mg, events };
   }
@@ -517,6 +527,8 @@ describe("BillingService.recordPayment", () => {
       {} as never, // files
       { get: () => undefined } as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, mg, events };
   }
@@ -635,6 +647,8 @@ describe("BillingService.expirePayable — locked write runs in a transaction",
       {} as never,
       {} as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, defaultManager, txManager, transaction };
   };
@@ -709,6 +723,8 @@ describe("BillingService.issuePayable", () => {
       {} as never,
       {} as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, manager };
   };
@@ -801,6 +817,8 @@ describe("BillingService — CAC Bank (OTP debit)", () => {
       {} as never,
       {} as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, repo };
   };
@@ -885,6 +903,8 @@ describe("BillingService — CBE bill amounts carry cents, never rounded", () =>
       {} as never,
       {} as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, repo };
   };
@@ -959,6 +979,8 @@ describe("BillingService.document", () => {
             : undefined,
       } as never, // config
       { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
+      { directSend: jest.fn() } as never, // notifications
+      { notify: jest.fn() } as never, // inbox
     );
     return { service, render, renderThermal };
   };
@@ -1079,6 +1101,8 @@ describe("BillingService.confirmOfflinePayment pay-window guard", () => {
   function makeService(invoiceType: string) {
     const invoice = {
       id: "inv-1",
+      invoiceNumber: "INV-001",
+      companyId: "company-1",
       source: Freight.InvoiceSource.Booking,
       sourceId: "booking-1",
       type: invoiceType,
@@ -1089,9 +1113,16 @@ describe("BillingService.confirmOfflinePayment pay-window guard", () => {
     const recordPayment = jest.fn().mockResolvedValue(invoice);
     const dataSource = {
       getRepository: () => ({
-        findOne: async () => ({ id: "booking-1", paymentDeadline: PAST }),
+        findOne: async () => ({
+          id: "booking-1",
+          reference: "BK-001",
+          paymentDeadline: PAST,
+        }),
       }),
+      query: async () => [{ phone: "+251900000000", email: "c@x.com" }],
     };
+    const directSend = jest.fn().mockResolvedValue(undefined);
+    const notify = jest.fn().mockResolvedValue(undefined);
     const service = new BillingService(
       dataSource as never,
       { findById: async () => invoice } as never,
@@ -1103,10 +1134,12 @@ describe("BillingService.confirmOfflinePayment pay-window guard", () => {
       { upload: async () => ({ id: "file-1", name: "slip.pdf" }) } as never,
       { get: () => undefined } as never,
       { isEnabled: async () => true } as never,
+      { directSend } as never,
+      { notify } as never,
     );
     (service as unknown as { recordPayment: unknown }).recordPayment =
       recordPayment;
-    return { service, recordPayment };
+    return { service, recordPayment, directSend, notify };
   }
 
   const slip = { originalname: "slip.pdf" } as never;
@@ -1129,6 +1162,42 @@ describe("BillingService.confirmOfflinePayment pay-window guard", () => {
     );
   });
 
+  it("notifies the customer (inbox + SMS + email) once the payment is confirmed", async () => {
+    const { service, notify, directSend } = makeService(
+      WAGON_CANCEL_FEE_INVOICE_TYPE,
+    );
+    await service.confirmOfflinePayment("inv-1", slip, {});
+    expect(notify).toHaveBeenCalledWith(
+      expect.objectContaining({
+        recipients: { companyId: "company-1" },
+        type: "PAYMENT_RECEIVED",
+        link: "/billing/inv-1",
+        body: expect.stringMatching(/500 ETB .*INV-001 \(booking BK-001\)/),
+      }),
+    );
+    expect(directSend).toHaveBeenCalledWith(
+      "sms",
+      "+251900000000",
+      expect.stringContaining("INV-001"),
+    );
+    expect(directSend).toHaveBeenCalledWith(
+      "email",
+      "c@x.com",
+      expect.stringContaining("INV-001"),
+    );
+  });
+
+  it("still settles when the customer notice fails", async () => {
+    const { service, notify, recordPayment } = makeService(
+      WAGON_CANCEL_FEE_INVOICE_TYPE,
+    );
+    notify.mockRejectedValueOnce(new Error("inbox down"));
+    await expect(
+      service.confirmOfflinePayment("inv-1", slip, {}),
+    ).resolves.toBeDefined();
+    expect(recordPayment).toHaveBeenCalled();
+  });
+
   it("still requires the bank slip for a cancellation fee", async () => {
     const { service } = makeService(WAGON_CANCEL_FEE_INVOICE_TYPE);
     await expect(
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 1dd4c5656..ce8c95f40 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,4 +1,9 @@
-import { Freight, PaymentReferenceType } from "@edr/types";
+import {
+  Freight,
+  NotificationAudience,
+  NotificationType,
+  PaymentReferenceType,
+} from "@edr/types";
 import { ConfigService } from "@nestjs/config";
 import {
   BadRequestException,
@@ -20,6 +25,10 @@ import { WAGON_CANCEL_FEE_INVOICE_TYPE } from "../bookings/entities/booking-wago
 import { ShippingLineCompany } from "../shipping-lines/entities/shipping-line-company.entity";
 import { ShippingLineCredit } from "../shipping-lines/entities/shipping-line-credit.entity";
 import { ManualPaymentSettingsService } from "../payment-settings/manual-payment-settings.service";
+import { NotificationInboxService } from "../notification-inbox/notification-inbox.service";
+import { NotificationsService } from "../notifications/notifications.service";
+import { sendCompanyChannels } from "../notifications/notify-company.util";
+import { resolveShippingLineNotifyTarget } from "../notifications/resolve-shipping-line-contact.util";
 import { EimsConfig } from "../../config/eims.config";
 import { CompaniesService } from "../companies/companies.service";
 import { EimsInvoiceStatus } from "../eims/eims-registration.types";
@@ -33,6 +42,8 @@ import {
   InvoiceDocumentService,
   pngDataUrl,
 } from "./documents/invoice-document.service";
+import { amountInWords } from "./documents/mor-document.util";
+import { buildEimsSeller, resolveLineTax } from "../eims/eims-invoice-context";
 import { INVOICE_SORT_COLUMNS } from "./dto/filter-invoice.dto";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { Invoice, InvoicePayment } from "./entities/invoice.entity";
@@ -271,7 +282,9 @@ export class BillingService {
     private readonly files: FilesService,
     private readonly config: ConfigService,
     private readonly manualPaymentSettings: ManualPaymentSettingsService,
-  ) {}
+    private readonly notifications: NotificationsService,
+    private readonly inbox: NotificationInboxService,
+  ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
 
@@ -830,8 +843,9 @@ export class BillingService {
       uploadedByName: input.userName ?? null,
     });
 
-    return this.recordPayment(invoiceId, {
-      amount: Number(invoice.balanceAmount),
+    const amount = Number(invoice.balanceAmount);
+    const paid = await this.recordPayment(invoiceId, {
+      amount,
       method: "BANK_TRANSFER",
       reference: input.reference || slip.name,
       metadata: {
@@ -841,6 +855,104 @@ export class BillingService {
         confirmedByName: input.userName ?? null,
       },
     });
+
+    // The customer did not pay through the portal, so nothing else tells them
+    // Finance has settled their invoice — this is their only confirmation.
+    await this.notifyCustomerManualPaymentConfirmed(paid, amount);
+    return paid;
+  }
+
+  /**
+   * Tell the customer Finance confirmed their manual (bank transfer / counter)
+   * payment: portal inbox entry plus SMS and email to the company's contact
+   * (or the shipping line's own contact for a credit invoice). Best-effort —
+   * a notification failure never undoes the settlement, it is only logged.
+   */
+  private async notifyCustomerManualPaymentConfirmed(
+    invoice: Invoice,
+    amount: number,
+  ): Promise<void> {
+    try {
+      const bookingRef =
+        invoice.source === Freight.InvoiceSource.Booking
+          ? await this.bookingReferenceFor(invoice.sourceId)
+          : null;
+      const body =
+        `Your payment of ${round2(amount)} ${invoice.currency} for invoice ${invoice.invoiceNumber}` +
+        (bookingRef ? ` (booking ${bookingRef})` : "") +
+        ` has been received and confirmed. Thank you.`;
+      const title = "Payment confirmed";
+      const data = {
+        invoiceId: invoice.id,
+        invoiceNumber: invoice.invoiceNumber,
+        bookingId: bookingRef ? invoice.sourceId : null,
+      };
+
+      if (invoice.companyId || invoice.companyProfileId) {
+        await this.inbox.notify({
+          recipients: invoice.companyId
+            ? { companyId: invoice.companyId }
+            : { companyProfileId: invoice.companyProfileId! },
+          audience: NotificationAudience.PORTAL,
+          type: NotificationType.PAYMENT_RECEIVED,
+          title,
+          body,
+          link: `/billing/${invoice.id}`,
+          data,
+        });
+        if (invoice.companyId) {
+          await sendCompanyChannels(
+            this.dataSource,
+            this.notifications,
+            invoice.companyId,
+            body,
+          );
+        }
+        return;
+      }
+
+      if (invoice.shippingLineCompanyId) {
+        const target = await resolveShippingLineNotifyTarget(
+          this.dataSource,
+          invoice.shippingLineCompanyId,
+        );
+        if (target.userId) {
+          await this.inbox.notify({
+            recipients: { userIds: [target.userId] },
+            audience: NotificationAudience.PORTAL,
+            type: NotificationType.PAYMENT_RECEIVED,
+            title,
+            body,
+            link: `/shipping-line/invoices/${invoice.id}`,
+            data,
+          });
+        }
+        for (const [method, to] of [
+          ["sms", target.phone],
+          ["email", target.email],
+        ] as const) {
+          if (!to) continue;
+          try {
+            await this.notifications.directSend(method, to, body);
+          } catch {
+            /* best-effort: provider unavailable */
+          }
+        }
+      }
+    } catch (err) {
+      this.logger.warn(
+        `Manual payment confirmed notify failed for invoice ${invoice.id}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /** Booking reference for a booking id, or null when the booking is gone. */
+  private async bookingReferenceFor(bookingId: string): Promise<string | null> {
+    const booking = await this.dataSource.getRepository(Booking).findOne({
+      where: { id: bookingId },
+      select: ["id", "reference"],
+    });
+    return booking?.reference ?? null;
   }
 
   /** Invoice header plus its line items. */
@@ -1021,18 +1133,133 @@ export class BillingService {
       currency: invoice.currency,
       summary,
       categoryHeader: "Charge type",
-      lines: invoice.lines.map((l) => ({
-        description: l.description ?? l.chargeType,
-        category: l.chargeType,
-        quantity: l.quantity,
-        unitRate: l.unitRate,
-        amount: l.amount,
-        currency: l.currency,
-      })),
+      lines: invoice.lines.map((l) => {
+        // Same resolver the filing used, so the printed Tax Code / Excise / Discount columns
+        // state what MoR actually holds for this line.
+        const tax = eimsCfg?.invoice ? resolveLineTax(eimsCfg, l.chargeType) : null;
+        return {
+          description: l.description ?? l.chargeType,
+          category: l.chargeType,
+          quantity: l.quantity,
+          unitRate: l.unitRate,
+          amount: l.amount,
+          currency: l.currency,
+          nature: eimsCfg?.invoice?.natureOfSupplies ?? null,
+          uom: eimsCfg?.invoice?.unitDefault ?? null,
+          taxCode: tax?.code ?? null,
+          excise: tax?.exciseTaxValue ?? null,
+          discount: tax?.discount ?? null,
+        };
+      }),
       totals,
       qrImageUrl: invoice.eimsSignedQr
         ? pngDataUrl(invoice.eimsSignedQr)
         : null,
+      mor: eimsCfg?.invoice ? this.buildMorDetails(invoice, eimsCfg) : null,
+    };
+  }
+
+  /**
+   * The MoR tax-document view of an invoice (ADD-P001) — the bilingual layout a customer also sees
+   * when they scan the QR on the Ministry's portal.
+   *
+   * Built from the invoice plus EIMS configuration alone, never from a live EIMS call: a document
+   * has to print whether or not it is registered yet, and printing must not depend on the gateway
+   * being up. Per-line tax comes from `resolveLineTax`, the same resolver that decided what was
+   * actually filed, so the paper and the filing cannot disagree.
+   */
+  private buildMorDetails(
+    invoice: Invoice & { lines: InvoiceLine[] },
+    cfg: EimsConfig,
+  ): InvoiceDocumentModel["mor"] {
+    const seller = buildEimsSeller(cfg);
+    const company = invoice.company;
+    const documentType = (invoice.eimsDocumentType as "INV" | "DEB" | "CRE" | undefined) ?? "INV";
+    // CREDIT until the money is in: the title states the sale's payment nature, not its status.
+    const isCash = Number(invoice.paidAmount) >= Number(invoice.totalAmount);
+
+    const TITLES: Record<string, { am: string; en: string }> = {
+      INV: isCash
+        ? { am: "የእጅ በእጅ ሽያጭ ደረሰኝ / ተ.እ.ታ / ኤክሳይዝ ታክስ", en: "Cash sales invoice / VAT / Excise Tax" }
+        : { am: "የዱቤ ሽያጭ ደረሰኝ / ተ.እ.ታ / ኤክሳይዝ ታክስ", en: "Credit sales invoice / VAT / Excise Tax" },
+      CRE: { am: "የታክስ ክሬዲት ሰነድ", en: "Tax Credit Note" },
+      DEB: { am: "የታክስ ዴቢት ሰነድ", en: "Tax Debit Note" },
+    };
+
+    let total = 0;
+    let excise = 0;
+    let discount = 0;
+    let vatAmount = 0;
+    let vatTaxable = 0;
+    for (const line of invoice.lines) {
+      const tax = resolveLineTax(cfg, line.chargeType);
+      const lineTotal = Number(line.amount);
+      total += lineTotal;
+      excise += tax.exciseTaxValue;
+      discount += tax.discount;
+      if (tax.ratePercent > 0) {
+        vatTaxable += lineTotal;
+        vatAmount += (lineTotal * tax.ratePercent) / 100;
+      }
+    }
+    const totalIncludingTax = Number(invoice.totalAmount);
+    const rate = cfg.invoice.taxRatePercent ?? 0;
+
+    const title = TITLES[documentType] ?? TITLES.INV;
+
+    return {
+      titleAm: title.am,
+      titleEn: title.en,
+      saleType: cfg.invoice.transactionType,
+      irn: invoice.eimsIrn,
+      systemNumber: cfg.systemNumber || null,
+      referenceNumber: invoice.eimsDocumentNumber ?? null,
+      relatedDocumentIrn: invoice.relatedInvoice?.eimsIrn ?? null,
+      seller: {
+        name: cfg.invoice.sellerLegalName || seller.LegalName,
+        city: seller.City,
+        subCity: seller.SubCity,
+        woreda: seller.Wereda,
+        kebele: seller.Locality,
+        houseNo: seller.HouseNumber,
+        tin: seller.Tin,
+        vatNumber: seller.VatNumber,
+      },
+      buyer: {
+        name: company?.name ?? "N/A",
+        city: company?.zone ?? null,
+        subCity: company?.zone ?? null,
+        woreda: company?.woreda ?? null,
+        kebele: company?.kebele ?? null,
+        houseNo: company?.houseNo ?? null,
+        tin: company?.tin ?? null,
+        vatNumber: company?.vatNumber ?? null,
+      },
+      tax: {
+        total: round2(total),
+        discount: round2(discount),
+        taxableTotal: round2(vatTaxable),
+        excise: round2(excise),
+        vatTaxableAmount: round2(vatTaxable),
+        // An exempt seller still prints the row, labelled the way the Ministry's portal labels it.
+        vatLabel: rate > 0 ? `ተ.እ.ታ / VAT ${rate}%` : `${cfg.invoice.taxCode} ታክስ / ${cfg.invoice.taxCode} Tax rate (N/A%)`,
+        vatAmount: round2(vatAmount),
+        incomeWithholding: cfg.invoice.incomeWithholdValue ?? 0,
+        vatWithholding: cfg.invoice.transactionWithholdValue ?? 0,
+        totalIncludingTax: round2(totalIncludingTax),
+        amountInWords: amountInWords(totalIncludingTax),
+      },
+      payment: {
+        mode: isCash ? "CASH" : "CREDIT",
+        typeMethod: cfg.invoice.paymentTerm,
+        receiverName: company?.name ?? null,
+      },
+      // A memo is an amendment to a filed document; MoR's layout carries the sign-off that
+      // authorised it. Names come from the recorded reason until an approval chain exists.
+      approval:
+        documentType === "INV"
+          ? null
+          : { requestedBy: invoice.eimsReason ?? null, checkedBy: null, approvedBy: null },
     };
   }
 
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
index c443fad7e..609518eef 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
@@ -122,3 +122,168 @@ describe("sameCompanyName", () => {
     expect(sameCompanyName("ABIJOEL P L C", undefined)).toBe(false);
   });
 });
+
+describe("InvoiceDocumentService.buildHtml — MoR tax-document layout (ADD-P001)", () => {
+  const service = new InvoiceDocumentService({} as never, {} as never, {} as never);
+
+  const mor = (over: Partial<NonNullable<InvoiceDocumentModel["mor"]>> = {}) =>
+    ({
+      titleAm: "የዱቤ ሽያጭ ደረሰኝ / ተ.እ.ታ / ኤክሳይዝ ታክስ",
+      titleEn: "Credit sales invoice / VAT / Excise Tax",
+      saleType: "B2B",
+      irn: "IRN-123",
+      systemNumber: "2B6E48BB75",
+      seller: { name: "Ethio-Djibouti Railway SC", tin: "0053481357" },
+      buyer: { name: "Afri Software Solutions", tin: "0089238373" },
+      tax: {
+        total: 904008.15,
+        discount: 0,
+        taxableTotal: 0,
+        excise: 0,
+        vatTaxableAmount: 0,
+        vatLabel: "VATEX ታክስ / VATEX Tax rate (N/A%)",
+        vatAmount: 0,
+        incomeWithholding: 0,
+        vatWithholding: 0,
+        totalIncludingTax: 904008.15,
+        amountInWords: "Nine hundred and four thousand and eight Birr and fifteen Cents",
+      },
+      payment: { mode: "CREDIT", typeMethod: "IMMIDIATE", receiverName: "Afri Software Solutions" },
+      ...over,
+    }) as NonNullable<InvoiceDocumentModel["mor"]>;
+
+  it("switches layout only when the mor block is present", () => {
+    expect(service.buildHtml(model())).not.toContain("Total including Tax");
+    expect(service.buildHtml(model({ mor: mor() }))).toContain("Total including Tax");
+  });
+
+  it("prints the bilingual title, sale type, IRN and system number", () => {
+    const html = service.buildHtml(model({ mor: mor() }));
+    expect(html).toContain("Credit sales invoice / VAT / Excise Tax");
+    expect(html).toContain("የዱቤ ሽያጭ ደረሰኝ");
+    expect(html).toContain("(B2B)");
+    expect(html).toContain("IRN-123");
+    expect(html).toContain("2B6E48BB75");
+  });
+
+  it("prints every totals row even when the figure is zero", () => {
+    const html = service.buildHtml(model({ mor: mor() }));
+    for (const label of [
+      "Discount Amount",
+      "Taxable Total",
+      "Excise Tax",
+      "Total VAT Taxable Amount",
+      "Total Withheld Amount",
+      "Total VAT Withheld Amount",
+      "Total including Tax (in words)",
+    ]) {
+      expect(html).toContain(label);
+    }
+  });
+
+  it("renders amounts bare, with the currency named once in the total label", () => {
+    const html = service.buildHtml(model({ mor: mor() }));
+    expect(html).toContain("904,008.15");
+    expect(html).toContain("Total (ETB)");
+    // The generic "1 Birr (ETB)" per-cell format must not leak into the tax layout.
+    expect(html).not.toContain("904,008.15 Birr (ETB)");
+  });
+
+  it("carries the MoR item columns", () => {
+    const html = service.buildHtml(
+      model({
+        mor: mor(),
+        lines: [
+          {
+            description: "Container Import",
+            quantity: 3,
+            unitRate: 5223,
+            amount: 15670,
+            nature: "service",
+            uom: "PCS",
+            taxCode: "VATEX",
+            excise: 0,
+            discount: 0,
+          },
+        ],
+      }),
+    );
+    expect(html).toContain("Tax Code");
+    expect(html).toContain("VATEX");
+    expect(html).toContain("service");
+    expect(html).toContain("PCS");
+  });
+
+  it("shows the related document and approval block on a credit/debit note", () => {
+    const html = service.buildHtml(
+      model({
+        mor: mor({
+          titleEn: "Tax Credit Note",
+          relatedDocumentIrn: "ORIGINAL-IRN",
+          approval: { requestedBy: "biruk", checkedBy: "ermias", approvedBy: "kassahun" },
+        }),
+      }),
+    );
+    expect(html).toContain("Related Document");
+    expect(html).toContain("ORIGINAL-IRN");
+    expect(html).toContain("INVOICE AMENDMENT AUTHORIZATION");
+    expect(html).toContain("kassahun");
+  });
+
+  it("renders the sales receipt's linked-invoice table", () => {
+    const html = service.buildHtml(
+      model({
+        mor: mor({
+          titleEn: "Cash Receipt Voucher",
+          receipt: {
+            rrn: "RRN-9",
+            reason: "Payment for goods purchased",
+            collectedAmount: 950,
+            invoices: [
+              {
+                irn: "INV-IRN-1",
+                paymentCoverage: "PARTIAL",
+                totalAmount: 1200,
+                remainingAmount: 250,
+                paidAmount: 950,
+              },
+            ],
+          },
+        }),
+      }),
+    );
+    expect(html).toContain("RRN-9");
+    expect(html).toContain("Payment Coverage");
+    expect(html).toContain("PARTIAL");
+    expect(html).toContain("Remaining Amount");
+  });
+
+  it("renders the withholding receipt without an item table", () => {
+    const html = service.buildHtml(
+      model({
+        mor: mor({
+          titleEn: "Withholding tax on payment",
+          tax: null,
+          withholding: {
+            receiptNumber: "WH-26-574705075",
+            counter: "574705075",
+            reason: "Tax Withholding",
+            type: "TWTH",
+            invoiceCurrency: "ETB",
+            preTaxAmount: 8640000,
+            withheldAmount: 259200,
+            systemType: "MAN",
+            systemNumber: "2B6E48BB75",
+          },
+        }),
+        lines: [{ description: "ignored", amount: 1 }],
+      }),
+    );
+    expect(html).toContain("WH-26-574705075");
+    expect(html).toContain("TWTH");
+    expect(html).toContain("Pre Tax Amount");
+    expect(html).toContain("259,200.00");
+    // A withholding receipt has no billed items — the item table must be suppressed entirely.
+    expect(html).not.toContain("Unit Price");
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
index d85facc0f..ac5da6203 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -5,6 +5,11 @@ import { LogoSettingsService } from "../../logo-settings/logo-settings.service";
 import { PdfRenderService } from "./pdf-render.service";
 import { sealClass, sealImageCss, sealMarkup } from "./seal-markup.util";
 import { logoImageCss, logoMarkup } from "./logo-markup.util";
+import {
+  formatDocumentTime,
+  formatEthiopianDate,
+  formatGregorianDate,
+} from "./mor-document.util";
 import {
   PdfColor,
   assembleSinglePagePdf,
@@ -44,6 +49,21 @@ function money(amount: unknown, currency: string): string {
   return `${Number(amount ?? 0).toLocaleString()} ${currency === "ETB" ? "Birr (ETB)" : currency}`;
 }
 
+/**
+ * Bare fixed-2 amount for the MoR tax layout — `1,304,228.00`, no currency suffix.
+ *
+ * The Ministry's own documents name the currency once, in the `ድምር (ETB) / Total (ETB)` label, and
+ * keep every figure a plain right-aligned number. Repeating "Birr (ETB)" in each cell (what the
+ * generic `money` helper does) both breaks that column alignment and reads as a different
+ * document from the one the customer sees when they scan the QR.
+ */
+function amount2(value: unknown): string {
+  return Number(value ?? 0).toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  });
+}
+
 function formatDate(value: unknown): string {
   return value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
 }
@@ -85,6 +105,115 @@ export interface InvoiceDocumentLine {
   unitRate?: number | null;
   amount?: number | null;
   currency?: string | null;
+  /**
+   * MoR tax-document columns (ADD-P001). Populated only for documents that carry a
+   * {@link MorDocumentDetails}; the generic EDR layout ignores them.
+   */
+  nature?: string | null;
+  uom?: string | null;
+  taxCode?: string | null;
+  excise?: number | null;
+  discount?: number | null;
+}
+
+/** One party block (`ከ / From`, `ለ / To`) of a MoR tax document. */
+export interface MorPartyDetails {
+  name: string;
+  city?: string | null;
+  /** `ዞን / ክ/ከተማ` — Zone/Sub city. */
+  subCity?: string | null;
+  woreda?: string | null;
+  kebele?: string | null;
+  houseNo?: string | null;
+  tin?: string | null;
+  subTin?: string | null;
+  vatNumber?: string | null;
+}
+
+/**
+ * The Ministry's totals block, in its printed order. Every row prints even at zero — a tax
+ * document states each figure explicitly rather than omitting the ones that happen to be nil.
+ */
+export interface MorTaxSummary {
+  total: number;
+  discount: number;
+  taxableTotal: number;
+  excise: number;
+  vatTaxableAmount: number;
+  /** e.g. `ተ.እ.ታ / VAT 15%`, or `VATEX ታክስ / VATEX Tax rate (N/A%)` for an exempt seller. */
+  vatLabel: string;
+  vatAmount: number;
+  incomeWithholding: number;
+  vatWithholding: number;
+  totalIncludingTax: number;
+  amountInWords: string;
+}
+
+export interface MorPaymentDetails {
+  /** `CASH` / `CREDIT` — also selects the document title. */
+  mode: string;
+  /** `IMMEDIATE` and friends. */
+  typeMethod: string;
+  receiverName?: string | null;
+}
+
+/** Credit/debit memo authorisation block. */
+export interface MorApprovalDetails {
+  requestedBy?: string | null;
+  checkedBy?: string | null;
+  approvedBy?: string | null;
+}
+
+/** Sales receipt (CRV) specifics. */
+export interface MorReceiptDetails {
+  rrn: string;
+  reason: string;
+  collectedAmount: number;
+  invoices: Array<{
+    irn: string;
+    paymentCoverage: string;
+    totalAmount: number;
+    remainingAmount: number;
+    paidAmount: number;
+  }>;
+}
+
+/** Withholding receipt specifics — a different document shape, with no item table. */
+export interface MorWithholdingDetails {
+  receiptNumber: string;
+  counter: string;
+  reason: string;
+  /** MoR withholding type, e.g. `TWTH`. */
+  type: string;
+  invoiceCurrency: string;
+  preTaxAmount: number;
+  withheldAmount: number;
+  systemType: string;
+  systemNumber: string;
+}
+
+/**
+ * Everything the MoR (ADD-P001) print layout needs beyond the generic model. Present ⇒ the
+ * document renders in the Ministry's bilingual tax-document format instead of the plain EDR one.
+ */
+export interface MorDocumentDetails {
+  /** Bilingual heading, e.g. `የእጅ በእጅ ሽያጭ ደረሰኝ / ተ.እ.ታ / ኤክሳይዝ ታክስ` + `Cash sales invoice / VAT / Excise Tax`. */
+  titleAm: string;
+  titleEn: string;
+  /** `B2B` / `B2C` / `B2G`. */
+  saleType?: string | null;
+  irn?: string | null;
+  systemNumber?: string | null;
+  referenceNumber?: string | null;
+  /** Original document's IRN — credit and debit notes only. */
+  relatedDocumentIrn?: string | null;
+  seller: MorPartyDetails;
+  buyer: MorPartyDetails;
+  tax?: MorTaxSummary | null;
+  payment?: MorPaymentDetails | null;
+  approval?: MorApprovalDetails | null;
+  receipt?: MorReceiptDetails | null;
+  withholding?: MorWithholdingDetails | null;
 }
 
 /** A labelled total row in the totals box; mark `grand` for the headline total. */
@@ -129,6 +258,12 @@ export interface InvoiceDocumentModel {
    * itself goes through the ordinary `summary` rows, not a dedicated field.
    */
   qrImageUrl?: string | null;
+  /**
+   * Present ⇒ render the Ministry's bilingual tax-document layout (ADD-P001) rather than the
+   * generic EDR one. Set for every document EIMS knows about: invoice, credit/debit note, sales
+   * receipt and withholding receipt.
+   */
+  mor?: MorDocumentDetails | null;
 }
 
 /**
@@ -232,12 +367,38 @@ export class InvoiceDocumentService {
       })
       .join("");
 
-    const totalRows = model.totals
-      .map(
-        (total) =>
-          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount, model.currency))}</strong></div>`,
-      )
-      .join("");
+    // A thermal receipt is a compact derivative of the A4 tax document, not a different document:
+    // the tax breakdown, the amount in words and the payment mode are the legally load-bearing
+    // parts and must survive the narrower page. Only the item-table columns are dropped.
+    const tax = model.mor?.tax;
+    const totalRows = tax
+      ? [
+          ["Total", money(tax.total, model.currency)],
+          ["Discount", money(tax.discount, model.currency)],
+          ["Taxable Total", money(tax.taxableTotal, model.currency)],
+          ["Excise Tax", money(tax.excise, model.currency)],
+          [tax.vatLabel, money(tax.vatAmount, model.currency)],
+          ["Withheld", money(tax.incomeWithholding, model.currency)],
+          ["VAT Withheld", money(tax.vatWithholding, model.currency)],
+        ]
+          .map(
+            ([label, value]) =>
+              `<div class="total-row"><span>${esc(label)}</span><strong>${esc(value)}</strong></div>`,
+          )
+          .join("") +
+        `<div class="total-row grand"><span>Total incl. Tax</span><strong>${esc(money(tax.totalIncludingTax, model.currency))}</strong></div>` +
+        `<div class="words">${esc(tax.amountInWords)}</div>`
+      : model.totals
+          .map(
+            (total) =>
+              `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount, model.currency))}</strong></div>`,
+          )
+          .join("");
+
+    const payMarkup = model.mor?.payment
+      ? `<div class="rule"></div><div class="row"><span class="label">Mode of Payment</span><span class="value">${esc(model.mor.payment.mode)}</span></div>
+         <div class="row"><span class="label">Type/Method</span><span class="value">${esc(model.mor.payment.typeMethod)}</span></div>`
+      : "";
 
     const qrMarkup = model.qrImageUrl
       ? `<div class="qr"><img src="${esc(model.qrImageUrl)}" alt="EIMS verification QR" /><div class="qr-caption">Scan to verify (MoR EIMS)</div></div>`
@@ -264,6 +425,7 @@ export class InvoiceDocumentService {
     .item-calc { text-align: right; font-family: monospace; font-size: 8.5px; }
     .total-row { display: flex; justify-content: space-between; font-size: 9px; padding: 2px 0; }
     .total-row.grand { font-size: 11px; font-weight: 800; border-top: 1px solid #0f172a; margin-top: 3px; padding-top: 4px; }
+    .words { font-size: 8px; text-align: center; margin-top: 4px; font-style: italic; }
     .qr { text-align: center; margin: 8px 0; }
     .qr img { width: 150px; height: 150px; }
     .qr-caption { font-size: 7px; color: #64748b; margin-top: 2px; }
@@ -282,6 +444,7 @@ export class InvoiceDocumentService {
     ${itemBlocks}
     <div class="rule"></div>
     ${totalRows}
+    ${payMarkup}
     ${qrMarkup}
     <div class="footer">Thank you</div>
   </div>
@@ -414,6 +577,10 @@ export class InvoiceDocumentService {
   }
 
   buildHtml(model: InvoiceDocumentModel): string {
+    // A MoR-registered document prints in the Ministry's own bilingual format (ADD-P001). Anything
+    // else — internal fee notes, statements — keeps the plain EDR layout below.
+    if (model.mor) return this.buildMorHtml(model, model.mor);
+
     const date = formatDate;
     const showCategory = Boolean(model.categoryHeader);
     const sealText =
@@ -531,7 +698,317 @@ export class InvoiceDocumentService {
 </html>`;
   }
 
+  /**
+   * MoR EIMS tax-document layout (ADD-P001) — invoice, credit/debit note, sales receipt and
+   * withholding receipt share this one template, differing only in which optional blocks appear.
+   *
+   * Field labels and their order come from the Ministry's own portal rendering of a registered EDR
+   * invoice, so a printout and the page a customer reaches by scanning the QR read the same way.
+   * Every totals row prints even at zero: a tax document states each figure rather than hiding the
+   * nil ones.
+   */
+  buildMorHtml(model: InvoiceDocumentModel, mor: MorDocumentDetails): string {
+    const currency = model.currency;
+    const party = (p: MorPartyDetails, sideAm: string, sideEn: string, tinAm: string, tinEn: string): string => `
+      <table class="party">
+        <tr><th class="side"><span class="am">${esc(sideAm)}</span><span class="en">${esc(sideEn)}</span></th>
+            <td class="pname">${esc(p.name)}</td></tr>
+        ${morRow("ከተማ", "City/Town", p.city)}
+        ${morRow("ዞን / ክ/ከተማ", "Zone/Sub city", p.subCity)}
+        ${morRow("ወረዳ", "Woreda", p.woreda)}
+        ${morRow("ቀበሌ", "Kebele", p.kebele)}
+        ${morRow("የቤ/ቁ", "H/No", p.houseNo)}
+        ${morRow("የግብር ከፋይ መለያ ቁጥር", `${tinEn}'s TIN`, p.tin, tinAm)}
+        ${morRow("ንዑስ/ቁ", "Sub-TIN", p.subTin)}
+        ${morRow("ተ.እ.ታ ቁጥር", `${tinEn}'s VAT`, p.vatNumber)}
+      </table>`;
+
+    const itemRows = model.lines
+      .map(
+        (item, i) => `<tr>
+            <td class="num">${i + 1}</td>
+            <td>${esc(item.description)}</td>
+            <td>${esc(item.nature ?? "-")}</td>
+            <td>${esc(item.uom ?? "-")}</td>
+            <td class="num">${esc(item.quantity ?? 0)}</td>
+            <td class="num">${esc(amount2(item.unitRate))}</td>
+            <td>${esc(item.taxCode ?? "-")}</td>
+            <td class="num">${esc(amount2(item.excise ?? 0))}</td>
+            <td class="num">${esc(amount2(item.discount ?? 0))}</td>
+            <td class="num strong">${esc(amount2(item.amount))}</td>
+          </tr>`,
+      )
+      .join("");
+
+    const tax = mor.tax;
+    const taxRows = tax
+      ? [
+          totalRow("ድምር", `Total (${currency})`, amount2(tax.total)),
+          totalRow("የቅናሽ መጠን", "Discount Amount", amount2(tax.discount)),
+          totalRow("ታክስ የሚከፈልበት ድምር", "Taxable Total", amount2(tax.taxableTotal)),
+          totalRow("ኤክሳይዝ ታክስ", "Excise Tax", amount2(tax.excise)),
+          totalRow("ተ.እ.ታ የሚከፈልበት ድምር", "Total VAT Taxable Amount", amount2(tax.vatTaxableAmount)),
+          totalRow("", tax.vatLabel, amount2(tax.vatAmount)),
+          totalRow("ጠቅላላ የተያዘ መጠን", "Total Withheld Amount", amount2(tax.incomeWithholding)),
+          totalRow("ጠቅላላ የተያዘ መጠን ተ.እ", "Total VAT Withheld Amount", amount2(tax.vatWithholding)),
+          totalRow("ጠቅላላ ዋጋ ከታክስ ጋር", "Total including Tax", amount2(tax.totalIncludingTax), true),
+        ].join("")
+      : "";
+
+    const wordsRow = tax
+      ? `<tr class="words"><td class="wl"><span class="am">ጠቅላላ ዋጋ ከታክስ ጋር (በፊደል)</span><span class="en">Total including Tax (in words)</span></td>
+           <td class="wv">${esc(tax.amountInWords)}</td></tr>`
+      : "";
+
+    const receipt = mor.receipt;
+    const receiptBlock = receipt
+      ? `<table class="kv">
+          ${morRow("የክፍያ ምክንያት", "Payment Reason", receipt.reason)}
+          ${morRow("የተሰበሰበ መጠን", "Collected Amount", amount2(receipt.collectedAmount))}
+        </table>
+        <div class="sec">የደረሰኞች ዝርዝር / Invoices</div>
+        <table class="items">
+          <thead><tr>
+            <th>IRN</th>
+            <th>${esc("የክፍያ ሽፋን / Payment Coverage")}</th>
+            <th class="num">${esc("ጠቅላላ ዋጋ / Total Amount")}</th>
+            <th class="num">${esc("ቀሪ / Remaining Amount")}</th>
+            <th class="num">${esc("የተከፈለ / Paid Amount")}</th>
+          </tr></thead>
+          <tbody>${receipt.invoices
+            .map(
+              (inv) => `<tr>
+                <td class="irn">${esc(inv.irn)}</td>
+                <td>${esc(inv.paymentCoverage)}</td>
+                <td class="num">${esc(amount2(inv.totalAmount))}</td>
+                <td class="num">${esc(amount2(inv.remainingAmount))}</td>
+                <td class="num strong">${esc(amount2(inv.paidAmount))}</td>
+              </tr>`,
+            )
+            .join("")}</tbody>
+        </table>
+        <div class="paid-total">ጠቅላላ የተከፈለ መጠን / Total Paid: <strong>${esc(amount2(receipt.collectedAmount))}</strong></div>`
+      : "";
+
+    const wh = mor.withholding;
+    const withholdingBlock = wh
+      ? `<table class="kv">
+          ${morRow("የደረሰኝ ቁጥር", "Receipt #", wh.receiptNumber)}
+          ${morRow("ቆጣሪ", "Counter", wh.counter)}
+          ${morRow("ምክንያት", "Reason", wh.reason)}
+          ${morRow("አይነት", "Type", wh.type)}
+        </table>
+        <table class="items">
+          <thead><tr>
+            <th>${esc("የደረሰኝ ቁጥር / Invoice Doc. Number")}</th>
+            <th>${esc("የገንዘብ ዓይነት / Invoice Currency")}</th>
+            <th class="num">${esc("ከታክስ በፊት ያለው ዋጋ / Pre Tax Amount")}</th>
+            <th class="num">${esc("ተይዞ የቀረ መጠን / Withheld Amount")}</th>
+          </tr></thead>
+          <tbody><tr>
+            <td>${esc(wh.receiptNumber)}</td>
+            <td>${esc(wh.invoiceCurrency)}</td>
+            <td class="num">${esc(amount2(wh.preTaxAmount))}</td>
+            <td class="num strong">${esc(amount2(wh.withheldAmount))}</td>
+          </tr></tbody>
+        </table>
+        <div class="paid-total">በገዥ ተይዞ የቀረ መጠን / Withheld Amount: <strong>${esc(amount2(wh.withheldAmount))}</strong></div>
+        <table class="kv sys">
+          ${morRow("የስርዓት አይነት", "System Type", wh.systemType)}
+          ${morRow("የስርዓት ቁጥር", "System Number", wh.systemNumber)}
+        </table>`
+      : "";
+
+    const payment = mor.payment;
+    const paymentBlock = payment
+      ? `<table class="pay">
+          <tr>
+            <td><span class="am">የክፍያ ሁኔታ</span><span class="en">Mode of Payment</span><strong>${esc(payment.mode)}</strong></td>
+            <td><span class="am">አይነት</span><span class="en">Type/Method</span><strong>${esc(payment.typeMethod)}</strong></td>
+            <td><span class="am">የተቀባይ ስምና ፊርማ</span><span class="en">Receiver Name &amp; Signature</span><strong>${esc(payment.receiverName ?? "")}</strong></td>
+          </tr>
+        </table>`
+      : "";
+
+    const approval = mor.approval;
+    const approvalBlock = approval
+      ? `<div class="amend">INVOICE AMENDMENT AUTHORIZATION</div>
+        <div class="amend-note">This amendment has been reviewed and approved in accordance with the company's approval matrix.</div>
+        <table class="pay">
+          <tr>
+            <td><span class="am">የጠየቀው</span><span class="en">Requested By</span><strong>${esc(approval.requestedBy ?? "")}</strong></td>
+            <td><span class="am">ያረጋገጠው</span><span class="en">Checked By</span><strong>${esc(approval.checkedBy ?? "")}</strong></td>
+            <td><span class="am">ያፀደቀው</span><span class="en">Approved By</span><strong>${esc(approval.approvedBy ?? "")}</strong></td>
+          </tr>
+        </table>`
+      : "";
+
+    const qrBlock = model.qrImageUrl
+      ? `<img class="qr" src="${esc(model.qrImageUrl)}" alt="EIMS verification QR" />`
+      : "";
+
+    return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>${esc(mor.titleEn)} ${esc(model.documentNumber)}</title>
+  <style>
+    @page { size: A4; margin: 10mm 9mm 12mm; }
+    body { font-family: "Noto Sans Ethiopic", "Abyssinica SIL", Arial, sans-serif; color: #111827; margin: 0; font-size: 9.5px; }
+    .doc { position: relative; }
+    .am { display: block; font-size: 8px; color: #374151; }
+    .en { display: block; font-size: 8.5px; color: #6b7280; }
+    /* Header ------------------------------------------------------------- */
+    .hdr { display: flex; justify-content: space-between; align-items: flex-start; border-bottom: 2px solid #0f766e; padding-bottom: 6px; }
+    .hdr-logo { max-height: 42px; max-width: 150px; object-fit: contain; display: block; margin-bottom: 4px; }
+    .org { font-size: 12px; font-weight: 700; color: #0f172a; }
+    .org-sub { font-size: 8.5px; color: #4b5563; line-height: 1.45; }
+    .hdr-meta { text-align: right; font-size: 8.5px; }
+    .hdr-meta div { margin-bottom: 2px; }
+    .hdr-meta b { display: inline-block; min-width: 92px; text-align: right; color: #111827; }
+    /* Title -------------------------------------------------------------- */
+    .title { text-align: center; margin: 8px 0 4px; }
+    .title .t-am { font-size: 12px; font-weight: 700; }
+    .title .t-en { font-size: 11.5px; font-weight: 700; text-decoration: underline; }
+    .title .t-type { font-size: 9.5px; color: #4b5563; margin-top: 2px; }
+    /* Identity strip ----------------------------------------------------- */
+    .ident { display: flex; justify-content: space-between; gap: 10px; margin: 6px 0 8px; }
+    .ident table { border-collapse: collapse; }
+    .ident td { padding: 1.5px 0; vertical-align: top; font-size: 8.5px; }
+    .ident td.k { color: #6b7280; padding-right: 8px; white-space: nowrap; }
+    .ident td.v { font-weight: 600; word-break: break-all; max-width: 330px; }
+    .qr { width: 96px; height: 96px; flex: none; }
+    /* Parties ------------------------------------------------------------ */
+    .parties { display: flex; gap: 8px; }
+    .parties > div { flex: 1; min-width: 0; }
+    table.party { width: 100%; border-collapse: collapse; border: 1px solid #9ca3af; }
+    table.party th, table.party td { border: 1px solid #d1d5db; padding: 2.5px 5px; text-align: left; vertical-align: top; font-weight: normal; }
+    table.party th.side { width: 42%; background: #f9fafb; }
+    table.party td.pname { font-weight: 700; font-size: 10px; }
+    table.party td.pv { font-weight: 600; word-break: break-all; }
+    /* Items -------------------------------------------------------------- */
+    .sec { margin: 8px 0 3px; font-size: 9px; font-weight: 700; color: #374151; }
+    table.items { width: 100%; border-collapse: collapse; margin-top: 6px; table-layout: fixed; }
+    table.items th { background: #f3f4f6; font-size: 7.5px; color: #374151; }
+    table.items th, table.items td { border: 1px solid #9ca3af; padding: 3px 4px; text-align: left; word-wrap: break-word; }
+    table.items td { font-size: 8.5px; }
+    table.items .num { text-align: right; }
+    table.items .strong { font-weight: 700; }
+    table.items td.irn { font-size: 7px; word-break: break-all; }
+    /* Totals ------------------------------------------------------------- */
+    table.totals { width: 100%; border-collapse: collapse; margin-top: -1px; }
+    table.totals td { border: 1px solid #9ca3af; padding: 3px 6px; font-size: 8.5px; }
+    table.totals td.tl { text-align: right; }
+    table.totals td.tv { text-align: right; width: 130px; font-weight: 600; }
+    table.totals tr.grand td { font-weight: 800; font-size: 10px; background: #f9fafb; }
+    table.totals tr.words td { padding: 4px 6px; }
+    table.totals td.wl { width: 240px; }
+    table.totals td.wv { font-weight: 700; text-align: center; }
+    /* Key/value + payment ------------------------------------------------ */
+    table.kv { width: 100%; border-collapse: collapse; margin-top: 6px; }
+    table.kv td { border: 1px solid #9ca3af; padding: 3px 6px; font-size: 8.5px; }
+    table.kv td.k { width: 220px; background: #f9fafb; }
+    table.kv td.v { font-weight: 600; }
+    table.kv.sys { margin-top: 10px; }
+    .paid-total { text-align: right; font-size: 9px; margin-top: 4px; }
+    table.pay { width: 100%; border-collapse: collapse; margin-top: 10px; }
+    table.pay td { border: 1px solid #9ca3af; padding: 4px 6px; width: 33.33%; }
+    table.pay strong { display: block; font-size: 10px; margin-top: 2px; }
+    .amend { margin-top: 12px; text-align: center; font-weight: 800; font-size: 10px; color: #b91c1c; letter-spacing: .04em; }
+    .amend-note { text-align: center; font-size: 8px; color: #6b7280; }
+    /* Footer ------------------------------------------------------------- */
+    .foot { margin-top: 14px; border-top: 1px solid #d1d5db; padding-top: 4px; display: flex; justify-content: space-between; font-size: 7.5px; color: #6b7280; }
+  </style>
+</head>
+<body>
+  <div class="doc">
+    <div class="hdr">
+      <div>
+        ${model.logoImageUrl ? `<img class="hdr-logo" src="${esc(model.logoImageUrl)}" alt="EDR" />` : ""}
+        <div class="org">${esc(mor.seller.name)}</div>
+        <div class="org-sub">Ethio-Djibouti Railway S.C.</div>
+      </div>
+      <div class="hdr-meta">
+        <div><span class="am">የደረሰኝ ቁጥር</span><span class="en">Document No</span><b>${esc(model.documentNumber)}</b></div>
+        <div><span class="am">ቀን</span><span class="en">Date</span><b>${esc(formatEthiopianDate(model.issuedAt))}</b></div>
+        <div><b>${esc(formatGregorianDate(model.issuedAt))}</b></div>
+        <div><span class="am">ሰአት</span><span class="en">Time</span><b>${esc(formatDocumentTime(model.issuedAt))}</b></div>
+      </div>
+    </div>
+
+    <div class="title">
+      <div class="t-am">${esc(mor.titleAm)}</div>
+      <div class="t-en">${esc(mor.titleEn)}</div>
+      ${mor.saleType ? `<div class="t-type">የሽያጭ አይነት (${esc(mor.saleType)})</div>` : ""}
+    </div>
+
+    <div class="ident">
+      <table>
+        ${mor.irn ? `<tr><td class="k">IRN</td><td class="v">${esc(mor.irn)}</td></tr>` : ""}
+        ${mor.receipt ? `<tr><td class="k">RRN</td><td class="v">${esc(mor.receipt.rrn)}</td></tr>` : ""}
+        ${mor.systemNumber ? `<tr><td class="k">System Number</td><td class="v">${esc(mor.systemNumber)}</td></tr>` : ""}
+        ${mor.referenceNumber ? `<tr><td class="k">Reference Number</td><td class="v">${esc(mor.referenceNumber)}</td></tr>` : ""}
+        ${mor.relatedDocumentIrn ? `<tr><td class="k">Related Document</td><td class="v">${esc(mor.relatedDocumentIrn)}</td></tr>` : ""}
+      </table>
+      ${qrBlock}
+    </div>
+
+    <div class="parties">
+      <div>${party(mor.seller, "ከ", "From", "የሻጭ", "Seller")}</div>
+      <div>${party(mor.buyer, "ለ", "To", "የገዢ", "Customer")}</div>
+    </div>
+
+    ${withholdingBlock}
+    ${receiptBlock}
+
+    ${
+      model.lines.length > 0 && !mor.withholding
+        ? `<table class="items">
+      <thead>
+        <tr>
+          <th style="width:4%">${esc("ተ/ቁ")}<br/>No.</th>
+          <th style="width:24%">${esc("የዕቃው / አገልግሎት አይነት")}<br/>Description</th>
+          <th style="width:9%">${esc("ምድብ")}<br/>Nature</th>
+          <th style="width:7%">${esc("መለኪያ")}<br/>UoM</th>
+          <th style="width:7%" class="num">${esc("ብዛት")}<br/>Qty</th>
+          <th style="width:12%" class="num">${esc("የአንዱ ዋጋ")}<br/>Unit Price</th>
+          <th style="width:9%">${esc("ታክስ ኮድ")}<br/>Tax Code</th>
+          <th style="width:9%" class="num">${esc("ኤክሳይዝ")}<br/>Excise</th>
+          <th style="width:9%" class="num">${esc("ቅናሽ")}<br/>Discount</th>
+          <th style="width:14%" class="num">${esc("ጠቅላላ ዋጋ")}<br/>Total Amount</th>
+        </tr>
+      </thead>
+      <tbody>${itemRows}</tbody>
+    </table>`
+        : ""
+    }
+
+    ${tax ? `<table class="totals">${taxRows}${wordsRow}</table>` : ""}
+    ${paymentBlock}
+    ${approvalBlock}
+
+    <div class="foot">
+      <div>Ethio-Djibouti Railway S.C. — ${esc(mor.titleEn)}</div>
+      <div>Page 1 of 1 &nbsp;·&nbsp; Printed ${esc(formatGregorianDate(new Date()))} ${esc(formatDocumentTime(new Date()))}</div>
+    </div>
+  </div>
+</body>
+</html>`;
+  }
+
   safeFilename(value: string): string {
     return value.replace(/[^a-zA-Z0-9_-]+/g, "-");
   }
 }
+
+/** One bilingual label/value row inside a party or key-value table. */
+function morRow(am: string, en: string, value: unknown, amOverride?: string): string {
+  return `<tr><td class="k"><span class="am">${esc(amOverride ? `${amOverride} ${am}` : am)}</span><span class="en">${esc(en)}</span></td><td class="v pv">${esc(
+    value === null || value === undefined || value === "" ? "N/A" : value,
+  )}</td></tr>`;
+}
+
+/** One row of the Ministry's totals block. */
+function totalRow(am: string, en: string, value: string, grand = false): string {
+  return `<tr class="${grand ? "grand" : ""}"><td class="tl">${esc(am ? `${am} / ${en}` : en)}</td><td class="tv">${esc(value)}</td></tr>`;
+}
diff --git a/apps/edr-freight-api/src/modules/billing/documents/mor-document.util.spec.ts b/apps/edr-freight-api/src/modules/billing/documents/mor-document.util.spec.ts
new file mode 100644
index 000000000..ab9ad6791
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/mor-document.util.spec.ts
@@ -0,0 +1,65 @@
+import {
+  amountInWords,
+  formatEthiopianDate,
+  formatGregorianDate,
+  gregorianToEthiopian,
+  numberToWords,
+} from "./mor-document.util";
+
+describe("gregorianToEthiopian", () => {
+  it("matches the MoR portal's own rendering of a registered EDR invoice", () => {
+    // portal.mor.gov.et printed `25-12-2018 ዓ/ም` beside `31-08-2026 G.C` for INV document no. 3.
+    expect(gregorianToEthiopian(new Date(2026, 7, 31))).toEqual({ year: 2018, month: 12, day: 25 });
+    expect(formatEthiopianDate(new Date(2026, 7, 31))).toBe("25-12-2018 ዓ/ም");
+    expect(formatGregorianDate(new Date(2026, 7, 31))).toBe("31-08-2026 G.C");
+  });
+
+  it("rolls the year on Ethiopian new year, not on the Gregorian one", () => {
+    // 11 Sep 2026 is 1 መስከረም 2019; the day before is still 2018.
+    expect(gregorianToEthiopian(new Date(2026, 8, 10))).toMatchObject({ year: 2018, month: 13 });
+    expect(gregorianToEthiopian(new Date(2026, 8, 11))).toEqual({ year: 2019, month: 1, day: 1 });
+  });
+
+  it("returns a placeholder rather than throwing on a missing date", () => {
+    expect(formatEthiopianDate(null)).toBe("-");
+    expect(formatGregorianDate(undefined)).toBe("-");
+  });
+});
+
+describe("amountInWords", () => {
+  it("spells an amount with cents the way the reference tax invoice does", () => {
+    // WISCOM's certified printout: 3,759.93 -> "three thousand seven hundred and fifty-nine Birr
+    // and ninety-three Cents".
+    expect(amountInWords(3759.93)).toBe(
+      "Three thousand seven hundred and fifty-nine Birr and ninety-three Cents",
+    );
+  });
+
+  it("keeps the 'and' inside a scale group, as the reference printouts do", () => {
+    // 407,422.98 on the reference credit-sales invoice reads "Four Hundred And Seven Thousand Four
+    // Hundred And Twenty-Two Birr and Ninety-Eight Cents". Note the MoR portal itself uses the
+    // other convention ("nine hundred four thousand"); the printed document follows the reference.
+    expect(amountInWords(407422.98)).toBe(
+      "Four hundred and seven thousand four hundred and twenty-two Birr and ninety-eight Cents",
+    );
+  });
+
+  it("omits the cents clause on a whole amount", () => {
+    expect(amountInWords(880)).toBe("Eight hundred and eighty Birr");
+  });
+
+  it("carries rounded cents into the Birr instead of printing 100 Cents", () => {
+    expect(amountInWords(9.999)).toBe("Ten Birr");
+  });
+
+  it("handles zero and sub-Birr amounts", () => {
+    expect(amountInWords(0)).toBe("Zero Birr");
+    expect(amountInWords(0.5)).toBe("Zero Birr and fifty Cents");
+  });
+
+  it("spells the scale words", () => {
+    expect(numberToWords(1_000_000)).toBe("one million");
+    expect(numberToWords(21)).toBe("twenty-one");
+    expect(numberToWords(115)).toBe("one hundred and fifteen");
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/documents/mor-document.util.ts b/apps/edr-freight-api/src/modules/billing/documents/mor-document.util.ts
new file mode 100644
index 000000000..ba74737b1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/mor-document.util.ts
@@ -0,0 +1,178 @@
+/**
+ * Presentation helpers for MoR EIMS tax documents (ADD-P001 print layout).
+ *
+ * The layout these serve is modelled on the Ministry's own portal rendering of a registered EDR
+ * invoice (portal.mor.gov.et), which is the authoritative source for the bilingual field labels —
+ * not on any one vendor's template.
+ */
+
+/** Ethiopian month names, index 0 = መስከረም. */
+const ETHIOPIAN_MONTHS = [
+  "መስከረም",
+  "ጥቅምት",
+  "ኅዳር",
+  "ታኅሣሥ",
+  "ጥር",
+  "የካቲት",
+  "መጋቢት",
+  "ሚያዝያ",
+  "ግንቦት",
+  "ሰኔ",
+  "ሐምሌ",
+  "ነሐሴ",
+  "ጳጉሜ",
+] as const;
+
+export interface EthiopianDate {
+  year: number;
+  month: number;
+  day: number;
+}
+
+/**
+ * Gregorian → Ethiopian, via Julian Day Number.
+ *
+ * JDN rather than day-of-year arithmetic because the Ethiopian new year drifts against September
+ * 11/12 on the Gregorian leap cycle; JDN is the same conversion the passenger portal already uses.
+ */
+export function gregorianToEthiopian(date: Date): EthiopianDate {
+  const year = date.getFullYear();
+  const month = date.getMonth() + 1;
+  const day = date.getDate();
+
+  const a = Math.floor((14 - month) / 12);
+  const y = year + 4800 - a;
+  const m = month + 12 * a - 3;
+  const jdn =
+    day +
+    Math.floor((153 * m + 2) / 5) +
+    365 * y +
+    Math.floor(y / 4) -
+    Math.floor(y / 100) +
+    Math.floor(y / 400) -
+    32045;
+
+  // 1723856 is the JDN of 1 መስከረም 1 E.C.
+  const r = (jdn - 1723856) % 1461;
+  const n = (r % 365) + 365 * Math.floor(r / 1460);
+  const ethYear = 4 * Math.floor((jdn - 1723856) / 1461) + Math.floor(r / 365) - Math.floor(r / 1460);
+  const ethMonth = Math.floor(n / 30) + 1;
+  const ethDay = (n % 30) + 1;
+
+  return { year: ethYear, month: ethMonth, day: ethDay };
+}
+
+/** `25-12-2018 ዓ/ም` — the numeric form the MoR portal prints beside the Gregorian date. */
+export function formatEthiopianDate(value: Date | string | null | undefined): string {
+  const date = value ? new Date(value) : null;
+  if (!date || Number.isNaN(date.getTime())) return "-";
+  const { year, month, day } = gregorianToEthiopian(date);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${pad(day)}-${pad(month)}-${year} ዓ/ም`;
+}
+
+/** `ሐምሌ 25, 2018` — the long form, when a document has room for it. */
+export function formatEthiopianDateLong(value: Date | string | null | undefined): string {
+  const date = value ? new Date(value) : null;
+  if (!date || Number.isNaN(date.getTime())) return "-";
+  const { year, month, day } = gregorianToEthiopian(date);
+  return `${ETHIOPIAN_MONTHS[month - 1] ?? ""} ${day}, ${year}`;
+}
+
+/** `31-08-2026 G.C` — Gregorian, labelled the way the MoR portal labels it. */
+export function formatGregorianDate(value: Date | string | null | undefined): string {
+  const date = value ? new Date(value) : null;
+  if (!date || Number.isNaN(date.getTime())) return "-";
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${pad(date.getDate())}-${pad(date.getMonth() + 1)}-${date.getFullYear()} G.C`;
+}
+
+/** `10:58:30`, 24-hour, to match the portal's `ሰአት/Time` row. */
+export function formatDocumentTime(value: Date | string | null | undefined): string {
+  const date = value ? new Date(value) : null;
+  if (!date || Number.isNaN(date.getTime())) return "-";
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+const ONES = [
+  "",
+  "one",
+  "two",
+  "three",
+  "four",
+  "five",
+  "six",
+  "seven",
+  "eight",
+  "nine",
+  "ten",
+  "eleven",
+  "twelve",
+  "thirteen",
+  "fourteen",
+  "fifteen",
+  "sixteen",
+  "seventeen",
+  "eighteen",
+  "nineteen",
+];
+const TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"];
+const SCALES: [number, string][] = [
+  [1_000_000_000, "billion"],
+  [1_000_000, "million"],
+  [1_000, "thousand"],
+];
+
+/** 0-999 in words. */
+function underThousand(value: number): string {
+  if (value < 20) return ONES[value];
+  if (value < 100) {
+    const rest = value % 10;
+    return TENS[Math.floor(value / 10)] + (rest ? `-${ONES[rest]}` : "");
+  }
+  const rest = value % 100;
+  return `${ONES[Math.floor(value / 100)]} hundred${rest ? ` and ${underThousand(rest)}` : ""}`;
+}
+
+/** Whole number in words. Returns "zero" for 0. */
+export function numberToWords(value: number): string {
+  const n = Math.floor(Math.abs(value));
+  if (n === 0) return "zero";
+
+  const parts: string[] = [];
+  let remaining = n;
+  for (const [scale, name] of SCALES) {
+    const count = Math.floor(remaining / scale);
+    if (count > 0) {
+      parts.push(`${numberToWords(count)} ${name}`);
+      remaining %= scale;
+    }
+  }
+  if (remaining > 0) {
+    // "and" only before a trailing sub-hundred group, matching how the amount reads aloud
+    // ("three thousand seven hundred and fifty-nine", not "three thousand and seven hundred").
+    parts.push(parts.length > 0 && remaining < 100 ? `and ${underThousand(remaining)}` : underThousand(remaining));
+  }
+  return parts.join(" ");
+}
+
+/**
+ * `Total including Tax (in words)` — the legally required spelling-out of the payable amount.
+ *
+ * Computed here rather than read back from MoR: the Ministry renders its own copy on the portal,
+ * but returns nothing carrying it on `/v1/register`, and the line has to print on a document that
+ * may not be registered yet.
+ */
+export function amountInWords(value: number, currencyLabel = "Birr", fractionLabel = "Cents"): string {
+  const amount = Number.isFinite(value) ? Math.abs(value) : 0;
+  const birr = Math.floor(amount);
+  // Round the remainder rather than truncate: 0.155 must read as sixteen cents, not fifteen.
+  const cents = Math.round((amount - birr) * 100);
+  // Rounding cents can carry into the next Birr (x.999 -> 100 cents).
+  const [wholeBirr, wholeCents] = cents === 100 ? [birr + 1, 0] : [birr, cents];
+
+  const head = `${numberToWords(wholeBirr)} ${currencyLabel}`;
+  const text = wholeCents > 0 ? `${head} and ${numberToWords(wholeCents)} ${fractionLabel}` : head;
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index 264ffb811..7324da975 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -370,7 +370,21 @@ export class BookingTransitionService {
 
   async startTransit(bookingId: string): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
-    assertBookingStatus(booking, ["PAID"]);
+    // Paid is read from the PAYMENT status only; the booking status merely
+    // guards against re-entering transit from a later stage.
+    if (booking.paymentStatus !== "PAID") {
+      throw new ConflictException(
+        `Booking must be paid before it can start transit (payment status "${booking.paymentStatus ?? "PENDING"}")`,
+      );
+    }
+    assertBookingStatus(booking, [
+      "PAID",
+      "FULLY_EXECUTED",
+      "PNR_GENERATED",
+      "WAGON_ASSIGNED",
+      "READY_FOR_ASSIGNMENT",
+      "APPROVED",
+    ]);
 
     const updated = await this.bookingsRepository.update(bookingId, {
       status: "IN_TRANSIT",
@@ -1739,6 +1753,7 @@ export class BookingTransitionService {
     // (portal and backoffice). Degrades to null like every fragile field here.
     let trainSchedule: {
       trainNumber: string | null;
+      voyageNumber: string | null;
       reference: string | null;
       scheduledDepartureDate: Date | null;
     } | null = null;
@@ -1750,6 +1765,8 @@ export class BookingTransitionService {
         if (s) {
           trainSchedule = {
             trainNumber: s.trainNumber ?? null,
+            // The schedule's own voyage (sailing) number shown to the customer.
+            voyageNumber: s.voyageNumber ?? null,
             reference: s.reference ?? null,
             scheduledDepartureDate: s.scheduledDepartureDate ?? null,
           };
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts
index 66ee2cbbb..b08b7e8c5 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts
@@ -17,6 +17,7 @@ describe('BookingWagonCancellationService.resolveRequestedCut (bulk)', () => {
       wagons: number;
       weightTons: number;
       quantities: { bulkTons?: number };
+      totalWagons: number;
     }>;
   };
   const booking = {
@@ -29,7 +30,39 @@ describe('BookingWagonCancellationService.resolveRequestedCut (bulk)', () => {
 
   it('cancels every wagon with the exact total tonnage', async () => {
     const cut = await svc.resolveRequestedCut(booking, { wagons: 4 });
-    expect(cut).toEqual({ wagons: 4, weightTons: 250.5, quantities: { bulkTons: 250.5 } });
+    expect(cut).toEqual({
+      wagons: 4,
+      weightTons: 250.5,
+      quantities: { bulkTons: 250.5 },
+      totalWagons: 4,
+    });
+  });
+
+  /**
+   * Unassigning a paid booking from a train clears `wagonsRequired` to NULL, so
+   * cancellation used to reject it outright ("no wagon requirement to cancel
+   * from"). The pinned `cancellationWagons`, stamped at first allocation, keeps
+   * the footprint through the unassign.
+   */
+  it('falls back to the pinned cancellation footprint when wagonsRequired is cleared', async () => {
+    const unassigned = { ...booking, wagonsRequired: null, cancellationWagons: 4 };
+    const cut = await svc.resolveRequestedCut(unassigned, { wagons: 4 });
+    expect(cut.wagons).toBe(4);
+    expect(cut.totalWagons).toBe(4);
+    expect(cut.weightTons).toBe(250.5);
+  });
+
+  /** NUMBER_OF_WAGONS bulk never allocated: the customer's pinned count sizes it. */
+  it('sizes a never-allocated NUMBER_OF_WAGONS booking from bulkRequestedWagons', async () => {
+    const fresh = {
+      ...booking,
+      wagonsRequired: null,
+      cancellationWagons: null,
+      bulkRequestedWagons: 3,
+    };
+    const cut = await svc.resolveRequestedCut(fresh, { wagons: 3 });
+    expect(cut.totalWagons).toBe(3);
+    expect(cut.weightTons).toBe(250.5);
   });
 
   it('rejects more wagons than the booking has', async () => {
@@ -91,6 +124,8 @@ describe('BookingWagonCancellationService.rebook (odd-20ft consolidation)', () =
   };
 
   it('refuses an odd-20ft rebook without a GL-picked partner', async () => {
+    // An odd credit always leaves a half-empty wagon, so GL must name who fills
+    // it — the rebook is refused rather than shipping a half-empty wagon.
     await expect(
       makeSvc().rebook('wc1', { scheduledDate: '2026-09-01' }),
     ).rejects.toThrow(/pick a consolidation partner/i);
@@ -110,6 +145,74 @@ describe('BookingWagonCancellationService.rebook (odd-20ft consolidation)', () =
       }),
     ).rejects.toThrow(/already shares a wagon/i);
   });
+
+  /**
+   * An EXPIRED partner has no pay window left, so pairing the PAID rebook
+   * straight onto it strands the shared wagon: neither half can board and
+   * nothing ever breaks the pair (BK-2026-001114). Its cargo must move to a
+   * fresh booking that carries its own invoice.
+   */
+  it('clones an EXPIRED partner into a new booking instead of pairing the dead one', async () => {
+    const dead = {
+      id: 'p1',
+      reference: 'BK-2026-001114',
+      status: 'EXPIRED',
+      contractId: 'c1',
+      consolidationPartnerId: null,
+      paymentCurrency: 'USD',
+      originYardId: 'y1',
+      destinationYardId: 'y2',
+      tradeDirection: 'IMPORT',
+      scheduledDate: '2026-09-01',
+      bookingContainers: [
+        {
+          containerSize: '20ft',
+          quantity: 1,
+          hazardousQuantity: 0,
+          reeferQuantity: 0,
+          containerType: { sizeFt: 20 },
+          units: [
+            {
+              containerNumber: 'PCONT0',
+              sealNumber: null,
+              vgmTons: 9,
+              isHazardous: false,
+              isReefer: false,
+            },
+          ],
+        },
+      ],
+    };
+    const clone = { ...dead, id: 'p1-clone', reference: 'BK-2026-001116', status: 'SUBMITTED' };
+
+    const svc = makeSvc(dead) as Record<string, unknown>;
+    let createdUnderContract: string | null = null;
+    let pairedWith: string | null = null;
+    (svc as { bookingsRepository: Record<string, unknown> }).bookingsRepository = {
+      findById: async () => source,
+      findByIdWithFiles: async (id: string) => (id === 'p1-clone' ? clone : dead),
+      hasSpentCancellationCredit: async () => false,
+    };
+    (svc as { contractBooking: unknown }).contractBooking = {
+      createUnderContract: async (contractId: string) => {
+        createdUnderContract = contractId;
+        return { booking: { id: 'p1-clone' } };
+      },
+    };
+    (svc as { notifyCustomer: unknown }).notifyCustomer = () => undefined;
+
+    const cloned = await (
+      svc as unknown as {
+        cloneDeadPartner(p: unknown, d: string): Promise<{ id: string; reference: string }>;
+      }
+    ).cloneDeadPartner(dead, '2026-09-01');
+
+    // The dead booking is left dead; the clone is what gets paired and paid.
+    expect(cloned.id).toBe('p1-clone');
+    expect(cloned.reference).toBe('BK-2026-001116');
+    expect(createdUnderContract).toBe('c1');
+    expect(pairedWith).toBeNull();
+  });
 });
 
 /**
@@ -199,3 +302,91 @@ describe('BookingWagonCancellationService.buildRebookDto (bulk wagon count)', ()
     expect(dto.requestedWagons).toBeUndefined();
   });
 });
+
+/**
+ * The cancellation fee is paid BEFORE the credit is redeemed.
+ *
+ * An at-loading cut applies immediately and opens the credit while its fee
+ * invoice stays open, so CREDIT_AVAILABLE on its own never means the fee was
+ * settled. Without the gate the customer rebooks the same wagons and the
+ * cancellation fee is simply never collected. EDR-fault cuts carry no fee and
+ * must stay freely rebookable — partial or whole, container or bulk.
+ */
+describe('BookingWagonCancellationService.rebook (cancellation fee gate)', () => {
+  const source = {
+    id: 'b1',
+    contractId: 'c1',
+    paymentCurrency: 'ETB',
+    originYardId: 'y1',
+    destinationYardId: 'y2',
+    tradeDirection: 'IMPORT',
+  };
+
+  const makeSvc = (row: Record<string, unknown>) => {
+    const svc = Object.create(BookingWagonCancellationService.prototype) as Record<
+      string,
+      unknown
+    > & { rebook(id: string, dto: unknown): Promise<unknown> };
+    svc.repo = { findById: async () => row };
+    svc.bookingsRepository = {
+      findById: async () => source,
+      findByIdWithFiles: async () => null,
+    };
+    return svc;
+  };
+
+  /** Bulk credit — no bySize, so nothing depends on container snapshots. */
+  const bulkRow = (over: Record<string, unknown>) => ({
+    id: 'wc1',
+    bookingId: 'b1',
+    status: 'CREDIT_AVAILABLE',
+    creditAmount: 5000,
+    wagonsCancelled: 2,
+    cancelledQuantities: { bulkTons: 100 },
+    feeCurrency: 'ETB',
+    ...over,
+  });
+
+  it('blocks a rebook while a customer-fault fee is unpaid', async () => {
+    const svc = makeSvc(
+      bulkRow({ fault: 'CUSTOMER', feeAmount: 1500, feePaidAt: null }),
+    );
+    await expect(svc.rebook('wc1', { scheduledDate: '2026-09-01' })).rejects.toThrow(
+      /pay the ETB 1500\.00 cancellation fee for 2 wagon\(s\)/i,
+    );
+  });
+
+  it('blocks a WHOLE-booking customer-fault cancel just the same', async () => {
+    const svc = makeSvc(
+      bulkRow({ fault: 'CUSTOMER', feeAmount: 4000, feePaidAt: null, wagonsCancelled: 4 }),
+    );
+    await expect(svc.rebook('wc1', { scheduledDate: '2026-09-01' })).rejects.toThrow(
+      /4 wagon\(s\) before rebooking/i,
+    );
+  });
+
+  it('lets the rebook through once the fee is paid', async () => {
+    const svc = makeSvc(
+      bulkRow({ fault: 'CUSTOMER', feeAmount: 1500, feePaidAt: new Date() }),
+    );
+    // Past the gate it fails later (no contract/create wiring in this harness) —
+    // what matters is that it is no longer the fee that stops it.
+    await expect(
+      svc.rebook('wc1', { scheduledDate: '2026-09-01' }),
+    ).rejects.not.toThrow(/cancellation fee/i);
+  });
+
+  it('never charges an EDR-fault cut', async () => {
+    const svc = makeSvc(bulkRow({ fault: 'EDR', feeAmount: 0, feePaidAt: null }));
+    await expect(
+      svc.rebook('wc1', { scheduledDate: '2026-09-01' }),
+    ).rejects.not.toThrow(/cancellation fee/i);
+  });
+
+  it('leaves legacy rows without a fee untouched', async () => {
+    const svc = makeSvc(bulkRow({ fault: null, feeAmount: 0, feePaidAt: null }));
+    await expect(
+      svc.rebook('wc1', { scheduledDate: '2026-09-01' }),
+    ).rejects.not.toThrow(/cancellation fee/i);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
index 86b9dedc6..983564a51 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
@@ -23,6 +23,8 @@ import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
 import { Rate } from '../rule-engine/entities/rate.entity';
 import { BookingBatchService } from '../train-scheduling/booking-batch.service';
+import { requestedBulkWagons } from '../train-scheduling/train-capacity.util';
+import { wagonsRequiredForBooking } from '../train-scheduling/utils/fleet-plan.util';
 import { TrainSchedulingService } from '../train-scheduling/services/train-scheduling.service';
 import { TrainScheduleBooking } from '../train-schedules/entities/train-schedule-booking.entity';
 import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
@@ -51,6 +53,8 @@ import {
   CancelledUnitSnapshot,
   WAGON_CANCEL_FEE_INVOICE_TYPE,
 } from './entities/booking-wagon-cancellation.entity';
+import { WagonEventType } from '@edr/types';
+import { WagonHistoryService } from '../wagon-history/wagon-history.service';
 
 export { WAGON_CANCEL_FEE_INVOICE_TYPE };
 
@@ -74,6 +78,8 @@ interface RequestedCut {
   wagons: number;
   weightTons: number;
   quantities: CancelledQuantities;
+  /** The booking's whole wagon footprint the cut came out of — credit divides by it. */
+  totalWagons: number;
 }
 
 /** The priced fee for a cut: total, currency and the rate(s) it came from. */
@@ -130,6 +136,7 @@ export class BookingWagonCancellationService {
     private readonly firstMile: FirstMileService,
     private readonly inbox: NotificationInboxService,
     private readonly events: EventEmitter2,
+    private readonly wagonHistory: WagonHistoryService,
   ) {}
 
   // ── T1: request ────────────────────────────────────────────────────────────
@@ -165,7 +172,7 @@ export class BookingWagonCancellationService {
           feePerWagon: fee.perWagon,
           feeAmount: fee.amount,
           feeCurrency: fee.currency,
-          creditAmount: this.creditFor(booking, Number(booking.wagonsRequired ?? 0)),
+          creditAmount: round2(Number(booking.totalAmount ?? 0)),
         };
       }
       this.assertCutSparesSharedWagon(cut);
@@ -177,7 +184,7 @@ export class BookingWagonCancellationService {
       feePerWagon: fee.perWagon,
       feeAmount: fee.amount,
       feeCurrency: fee.currency,
-      creditAmount: this.creditFor(booking, cut.wagons),
+      creditAmount: this.creditFor(booking, cut.wagons, cut.totalWagons),
     };
   }
 
@@ -218,7 +225,7 @@ export class BookingWagonCancellationService {
       : await this.resolveRequestedCut(booking, dto);
     const fee = await this.priceFee(booking, cut);
     const feeAmount = fee.amount;
-    const creditAmount = this.creditFor(booking, cut.wagons);
+    const creditAmount = this.creditFor(booking, cut.wagons, cut.totalWagons);
 
     const row = await this.repo.create({
       bookingId,
@@ -318,7 +325,7 @@ export class BookingWagonCancellationService {
         const rows = await this.dataSource.getRepository(WagonBookingAllocation).count({
           where: { bookingId: row.bookingId },
         });
-        if (rows < Math.round(Number(booking.wagonsRequired ?? 0))) {
+        if (rows < Math.round(await this.wagonFootprint(booking))) {
           throw new ConflictException(
             'The train has no free wagon space left to restore the cancelled wagons — the request cannot be withdrawn. Pay the cancellation fee and rebook the credit on another day instead.',
           );
@@ -363,7 +370,7 @@ export class BookingWagonCancellationService {
     const row = await this.openConsolidationBreak(
       booking,
       'ceil',
-      this.creditFor(booking, Number(booking.wagonsRequired ?? 0)),
+      round2(Number(booking.totalAmount ?? 0)),
       reason ?? 'Consolidated pair cancelled',
       userId,
     );
@@ -371,7 +378,7 @@ export class BookingWagonCancellationService {
       await this.openConsolidationBreak(
         partner,
         'floor',
-        this.creditFor(partner, Number(partner.wagonsRequired ?? 0)),
+        round2(Number(partner.totalAmount ?? 0)),
         `Cancelled with its consolidation partner ${booking.reference}`,
         userId,
       );
@@ -540,7 +547,8 @@ export class BookingWagonCancellationService {
       } as RequestWagonCancellationDto);
     }
     return this.resolveRequestedCut(booking, {
-      wagons: Number(booking.wagonsRequired ?? 0),
+      // Footprint, not the live wagonsRequired: unassign clears that to NULL.
+      wagons: await this.wagonFootprint(booking),
     } as RequestWagonCancellationDto);
   }
 
@@ -568,7 +576,7 @@ export class BookingWagonCancellationService {
       const row = await this.openConsolidationBreak(
         booking,
         'ceil',
-        this.creditFor(booking, Number(booking.wagonsRequired ?? 0)),
+        round2(Number(booking.totalAmount ?? 0)),
         'Consolidation partner lapsed unpaid — paired booking cancelled, cancellation fee applies',
       );
       await this.dataSource.getRepository(Booking).update(booking.id, {
@@ -729,9 +737,10 @@ export class BookingWagonCancellationService {
       // Whole-booking cut: nothing is left to ship, so the booking ends
       // CANCELLED (frees the contract slot/cap for the rebook) and drops off its
       // train. The credit row still points at it for T3.
-      const wagonsLeft = round2(
-        Number(booking.wagonsRequired ?? 0) - Number(row.wagonsCancelled),
-      );
+      // Off the pinned footprint, not the live wagonsRequired — unassign
+      // clears that to NULL, which read as a full cut on any partial cancel.
+      const footprint = await this.wagonFootprint(booking);
+      const wagonsLeft = round2(footprint - Number(row.wagonsCancelled));
       const isFull = wagonsLeft <= 0;
       // NUMBER_OF_WAGONS bookings pin their count in bulkRequestedWagons, which
       // bulkTonWagonsRequired honours verbatim. Left stale it re-inflates the
@@ -745,6 +754,9 @@ export class BookingWagonCancellationService {
         : null;
       await manager.getRepository(Booking).update(booking.id, {
         wagonsRequired: Math.max(0, wagonsLeft),
+        // Keep the cancellation footprint in step, so a second partial cancel
+        // prices against what is actually left, not the original booking.
+        cancellationWagons: Math.max(0, wagonsLeft),
         ...(requestedWagonsLeft !== null
           ? { bulkRequestedWagons: requestedWagonsLeft }
           : {}),
@@ -853,14 +865,37 @@ export class BookingWagonCancellationService {
       );
     }
 
+    // Staff may cut a SUBSET of the never-loaded wagons (picked in the loading
+    // modal) instead of the whole remainder. Anything already LOADED is
+    // rejected rather than silently dropped: the operator believes they are
+    // cancelling that wagon, and it is on the train.
+    let target = remaining;
+    if (dto.wagonAllocationIds?.length) {
+      const wanted = new Set(dto.wagonAllocationIds);
+      const known = new Set(allocations.map((a) => a.id));
+      const unknown = dto.wagonAllocationIds.filter((id) => !known.has(id));
+      if (unknown.length) {
+        throw new BadRequestException(
+          'Some selected wagons are not allocated to this booking on this schedule.',
+        );
+      }
+      const loaded = allocations.filter((a) => wanted.has(a.id) && !remaining.includes(a));
+      if (loaded.length) {
+        throw new BadRequestException(
+          `${loaded.length} selected wagon(s) are already loaded and cannot be cancelled.`,
+        );
+      }
+      target = remaining.filter((a) => wanted.has(a.id));
+    }
+
     const cut = await this.resolveRequestedCut(booking, {
-      wagonAllocationIds: remaining.map((r) => r.id),
+      wagonAllocationIds: target.map((r) => r.id),
     } as RequestWagonCancellationDto);
     if (booking.consolidationPartnerId) this.assertCutSparesSharedWagon(cut);
 
     const edrFault = !!dto.edrFault;
     const fee = edrFault ? null : await this.priceFee(booking, cut);
-    const creditAmount = this.creditFor(booking, cut.wagons);
+    const creditAmount = this.creditFor(booking, cut.wagons, cut.totalWagons);
 
     const row = await this.repo.create({
       bookingId,
@@ -971,6 +1006,18 @@ export class BookingWagonCancellationService {
         'This cancellation has no rebooking credit — the booking was never paid. Create a new booking instead.',
       );
     }
+    // Customer-fault fee settles BEFORE the credit is redeemed. An at-loading
+    // cut applies immediately and opens the credit while its invoice stays
+    // open, so CREDIT_AVAILABLE alone does not mean the fee was paid — without
+    // this the customer rebooks the wagons and never pays the cancellation
+    // fee the notice already promised. EDR fault carries no fee and is
+    // unaffected; onFeePaid stamps feePaidAt and the gate opens by itself.
+    if (row.fault === 'CUSTOMER' && Number(row.feeAmount) > 0 && !row.feePaidAt) {
+      throw new BadRequestException(
+        `Pay the ${row.feeCurrency} ${Number(row.feeAmount).toFixed(2)} cancellation fee for ` +
+          `${Math.ceil(Number(row.wagonsCancelled))} wagon(s) before rebooking this credit.`,
+      );
+    }
     const source = await this.bookingsRepository.findById(row.bookingId);
     if (!source) throw new NotFoundException(`Booking ${row.bookingId} not found.`);
     if (!source.contractId) {
@@ -988,6 +1035,9 @@ export class BookingWagonCancellationService {
     let partner: Booking | null = null;
     if (oddFt20) {
       createDto.skipAutoConsolidation = true;
+      // An odd credit always leaves a half-empty wagon, so GL names who fills
+      // it. The candidate list is wide enough (any unpaired, unspent booking on
+      // the day) that a partner is expected to exist.
       if (!dto.partnerBookingId) {
         throw new BadRequestException(
           'This credit carries an odd 20ft container — pick a consolidation partner booking to share its wagon (see the rebook-partners list).',
@@ -998,6 +1048,15 @@ export class BookingWagonCancellationService {
         dto.partnerBookingId,
         dto.scheduledDate,
       );
+      // A dead partner cannot be paid where it stands — its cargo moves to a
+      // fresh booking that can carry its own invoice and pay window.
+      if (['EXPIRED', 'CANCELLED'].includes(partner.status)) {
+        partner = await this.cloneDeadPartner(
+          partner,
+          dto.scheduledDate,
+          userId,
+        );
+      }
     }
     const created = await this.contractBooking.createUnderContract(
       source.contractId,
@@ -1032,6 +1091,15 @@ export class BookingWagonCancellationService {
       );
     }
     if (partner) {
+      // Corrections GL made to the partner's own containers while pairing —
+      // scoped to that booking by the repository, so a stray id cannot touch
+      // another booking's cargo.
+      if (dto.partnerUnits?.length) {
+        await this.bookingsRepository.patchContainerUnitsForBooking(
+          partner.id,
+          dto.partnerUnits,
+        );
+      }
       // Consolidated rebook: never allocate the half-wagon booking alone. It
       // rides PAID and the batch engine settles the pair atomically once the
       // partner's own invoice is paid.
@@ -1083,6 +1151,13 @@ export class BookingWagonCancellationService {
       status: string;
       scheduledDate: string | null;
       ft20Quantity: number;
+      units: Array<{
+        id: string;
+        containerSize: string;
+        containerNumber: string;
+        sealNumber: string | null;
+        vgmTons: number;
+      }>;
     }>
   > {
     const row = await this.mustFind(cancellationId);
@@ -1103,6 +1178,18 @@ export class BookingWagonCancellationService {
       ft20Quantity: (b.bookingContainers ?? [])
         .filter((line) => Number(line.containerType?.sizeFt) === 20)
         .reduce((sum, line) => sum + Number(line.quantity || 0), 0),
+      // Editable while pairing — GL corrects these on the rebook form.
+      units: (b.bookingContainers ?? []).flatMap((line) =>
+        (line.units ?? []).map((u) => ({
+          id: u.id,
+          containerSize: line.containerType?.sizeFt
+            ? `${line.containerType.sizeFt}ft`
+            : '',
+          containerNumber: u.containerNumber,
+          sealNumber: u.sealNumber ?? null,
+          vgmTons: Number(u.vgmTons ?? 0),
+        })),
+      ),
     }));
   }
 
@@ -1121,11 +1208,29 @@ export class BookingWagonCancellationService {
         `Booking ${partner.reference} already shares a wagon with another booking.`,
       );
     }
-    if (!['SUBMITTED', 'PENDING_CONSOLIDATION'].includes(partner.status)) {
+    // Mirrors findRebookConsolidationCandidates: a partner need not be a live
+    // committed shipment. One that lost its slot or was called off still has
+    // cargo to move, and the rebooked wagon is how it moves.
+    if (
+      ![
+        'SUBMITTED',
+        'PENDING_CONSOLIDATION',
+        'CLEARANCE_READY',
+        'OPERATION_CHANGES_REQUESTED',
+        'EXPIRED',
+        'CANCELLED',
+      ].includes(partner.status)
+    ) {
       throw new BadRequestException(
         `Booking ${partner.reference} cannot be consolidated (status ${partner.status}).`,
       );
     }
+    // A booking whose own credit was already rebooked elsewhere is spent.
+    if (await this.bookingsRepository.hasSpentCancellationCredit(partner.id)) {
+      throw new BadRequestException(
+        `Booking ${partner.reference} has already been rebooked from its cancellation credit.`,
+      );
+    }
     if (
       partner.originYardId !== source.originYardId ||
       partner.destinationYardId !== source.destinationYardId ||
@@ -1153,6 +1258,74 @@ export class BookingWagonCancellationService {
     return partner;
   }
 
+  /**
+   * A dead (EXPIRED/CANCELLED) partner still has cargo to move, but it can no
+   * longer be paid: its pay window is gone and finalizing it issues nothing a
+   * customer can settle, so pairing the PAID rebook with it strands the shared
+   * wagon forever (BK-2026-001114: EXPIRED/PENDING, paired to a PAID rebook,
+   * no payment_deadline — neither half could ever board). So the cargo is
+   * cloned into a fresh booking under the same contract, which finalizes
+   * normally into its own invoice and pay window; the dead booking stays dead.
+   */
+  private async cloneDeadPartner(
+    partner: Booking,
+    scheduledDate: string,
+    userId?: string,
+  ): Promise<Booking> {
+    if (!partner.contractId) {
+      throw new BadRequestException(
+        `Booking ${partner.reference} has no contract to rebook its cargo under — pick a live partner instead.`,
+      );
+    }
+    const dto: CreateBookingUnderContractDto = {
+      scheduledDate,
+      paymentCurrency: partner.paymentCurrency ?? undefined,
+      // GL already chose this pairing — the auto-matcher must not re-home the
+      // clone behind their back (same reasoning as the rebooked side).
+      skipAutoConsolidation: true,
+      containers: (partner.bookingContainers ?? []).map((line) => {
+        const units = line.units ?? [];
+        return {
+          containerSize: line.containerSize ?? undefined,
+          quantity: Number(line.quantity),
+          units: units.map((u) => ({
+            containerNumber: u.containerNumber,
+            sealNumber: u.sealNumber ?? '',
+            vgmTons: u.vgmTons,
+            isHazardous: u.isHazardous,
+            isReefer: u.isReefer,
+          })),
+          hazardousQuantity: Number(line.hazardousQuantity ?? 0),
+          reeferQuantity: Number(line.reeferQuantity ?? 0),
+        };
+      }) as CreateBookingUnderContractDto['containers'],
+    };
+    const created = await this.contractBooking.createUnderContract(
+      partner.contractId,
+      dto,
+      { id: userId ?? partner.createdByUserId ?? undefined },
+      { permissions: [{ key: FREIGHT_PERMS.contracts.createBooking }] },
+      // The dead partner's own contract may have lapsed while it sat expired;
+      // its cargo is still the cargo GL picked to fill the shared wagon.
+      { allowExpiredContract: true },
+    );
+    const clone = await this.bookingsRepository.findByIdWithFiles(
+      created.booking.id,
+    );
+    if (!clone) {
+      throw new NotFoundException(
+        `Replacement booking for ${partner.reference} could not be loaded.`,
+      );
+    }
+    this.notifyCustomer(
+      partner,
+      'Replacement booking created',
+      `${partner.reference} had expired, so its cargo moved to ${clone.reference} to share a wagon with a rebooked shipment. Pay ${clone.reference} to board.`,
+      clone.id,
+    );
+    return clone;
+  }
+
   /**
    * Link the rebooked (already PAID) booking with the GL-picked partner. A
    * parked partner is resumed the way pairConsolidation would resume it —
@@ -1253,7 +1426,7 @@ export class BookingWagonCancellationService {
     booking: Booking,
     dto: RequestWagonCancellationDto,
   ): Promise<RequestedCut> {
-    const totalWagons = Number(booking.wagonsRequired ?? 0);
+    const totalWagons = await this.wagonFootprint(booking);
     if (totalWagons <= 0) {
       throw new BadRequestException('This booking has no wagon requirement to cancel from.');
     }
@@ -1335,6 +1508,7 @@ export class BookingWagonCancellationService {
         weightTons: weightShare,
         // Bookings without unit records fall back to the T2 LIFO trim.
         quantities: { bySize, ...(units.length === requested ? { units } : {}) },
+        totalWagons,
       };
     }
 
@@ -1360,7 +1534,7 @@ export class BookingWagonCancellationService {
     if (tons <= 0) {
       throw new BadRequestException('The requested cut is too small to release cargo.');
     }
-    return { wagons, weightTons: tons, quantities: { bulkTons: tons } };
+    return { wagons, weightTons: tons, quantities: { bulkTons: tons }, totalWagons };
   }
 
   /**
@@ -1416,6 +1590,7 @@ export class BookingWagonCancellationService {
         wagons,
         weightTons: tons,
         quantities: { bulkTons: tons, allocationIds },
+        totalWagons,
       };
     }
 
@@ -1460,12 +1635,54 @@ export class BookingWagonCancellationService {
       wagons,
       weightTons: round3(units.reduce((s, u) => s + Number(u.vgmTons || 0), 0)),
       quantities: { bySize, units, allocationIds },
+      totalWagons,
     };
   }
 
+  /**
+   * The booking's wagon footprint for cancellation pricing.
+   *
+   * `wagonsRequired` is a LIVE scheduling field: unassign clears it to NULL, so
+   * a paid booking pulled off a train read 0 wagons and could not be cancelled
+   * at all. `cancellationWagons` is stamped once at first allocation and never
+   * cleared — read it first. A booking never allocated has neither, so size it
+   * from the cargo the same way the scheduler would: TEU geometry for
+   * containers, the customer's pinned count for NUMBER_OF_WAGONS bulk, tonnage
+   * ÷ wagon capacity for PER_TON bulk.
+   */
+  private async wagonFootprint(booking: Booking): Promise<number> {
+    const pinned = Number(booking.cancellationWagons ?? 0);
+    if (pinned > 0) return round2(pinned);
+    const stored = Number(booking.wagonsRequired ?? 0);
+    if (stored > 0) return round2(stored);
+
+    const requested = requestedBulkWagons(booking);
+    if (requested > 0) return requested;
+
+    // Cargo relations drive the sizing — reload when the caller passed a bare
+    // booking (findById does not always hydrate them).
+    const full =
+      booking.bookingContainers || booking.cargoType
+        ? booking
+        : ((await this.dataSource.getRepository(Booking).findOne({
+            where: { id: booking.id },
+            relations: {
+              bookingContainers: { containerType: true },
+              cargoType: { wagonTypes: true },
+            },
+          })) ?? booking);
+    const capacities = (full.cargoType?.wagonTypes ?? [])
+      .map((wt) => Number(wt.capacityTons))
+      .filter((c) => c > 0);
+    const bulkCapacity =
+      full.freightType === 'BULK' && capacities.length
+        ? Math.max(...capacities)
+        : undefined;
+    return round2(wagonsRequiredForBooking(full, bulkCapacity));
+  }
+
   /** Credit = the cancelled share of the ORIGINAL price (old-price rebooking). */
-  private creditFor(booking: Booking, wagons: number): number {
-    const totalWagons = Number(booking.wagonsRequired ?? 0);
+  private creditFor(booking: Booking, wagons: number, totalWagons: number): number {
     if (totalWagons <= 0) return 0;
     return round2(Number(booking.totalAmount) * (wagons / totalWagons));
   }
@@ -1759,6 +1976,7 @@ export class BookingWagonCancellationService {
         .getRepository(WagonAllocationContainerItem)
         .delete(cut.map((i) => i.id));
       if (cut.length === items.length) {
+        await this.recordAllocationRelease(manager, [alloc.id], bookingId, 'Containers cancelled from booking');
         await manager.getRepository(WagonBookingAllocation).delete(alloc.id);
       } else {
         const cutWeight = cut.reduce((s, i) => s + Number(i.grossWeightTons ?? 0), 0);
@@ -1805,9 +2023,66 @@ export class BookingWagonCancellationService {
     await manager
       .getRepository(WagonAllocationBulkLoad)
       .delete({ wagonBookingAllocationId: In(ids) });
+    await this.recordAllocationRelease(manager, ids, bookingId, 'Wagons cancelled from booking');
     await manager.getRepository(WagonBookingAllocation).delete(ids);
   }
 
+  /**
+   * BOOKING_CANCELLED history row for every physical wagon behind the released
+   * allocations — resolved through the slot BEFORE the allocation rows go, one
+   * query for the whole batch. Slots with no wagon pinned yet leave no row.
+   */
+  private async recordAllocationRelease(
+    manager: EntityManager,
+    allocationIds: string[],
+    bookingId: string,
+    reason: string,
+  ): Promise<void> {
+    if (!allocationIds.length) return;
+    const rows: Array<{
+      allocationId: string;
+      wagonId: string;
+      wagonNumber: string;
+      yardId: string | null;
+      trainId: string | null;
+      scheduleId: string | null;
+      weightTons: string | null;
+      loadType: string | null;
+    }> = await manager.query(
+      `SELECT a.id                     AS "allocationId",
+              w.id                     AS "wagonId",
+              w.wagon_number           AS "wagonNumber",
+              w.current_yard_id        AS "yardId",
+              w.train_id               AS "trainId",
+              w.current_train_schedule_id AS "scheduleId",
+              a.allocated_weight_tons  AS "weightTons",
+              a.load_type              AS "loadType"
+         FROM freight.wagon_booking_allocations a
+         JOIN freight.train_set_wagons tsw ON tsw.id = a.train_set_wagon_id
+         JOIN freight.wagons w ON w.id = tsw.physical_wagon_id
+        WHERE a.id = ANY($1::uuid[])`,
+      [allocationIds],
+    );
+    await this.wagonHistory.record(
+      manager,
+      rows.map((r) => ({
+        wagonId: r.wagonId,
+        wagonNumber: r.wagonNumber,
+        type: WagonEventType.BookingCancelled,
+        fromYardId: r.yardId,
+        trainId: r.trainId,
+        trainScheduleId: r.scheduleId,
+        bookingId,
+        reason,
+        metadata: {
+          allocationId: r.allocationId,
+          loadType: r.loadType,
+          weightTons: r.weightTons == null ? null : Number(r.weightTons),
+        },
+      })),
+    );
+  }
+
   /** Pre-reduction quantities snapshot (only when the booking was never split before). */
   private async currentQuantities(
     manager: EntityManager,
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
index 9655a9603..66958bc38 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
@@ -6,6 +6,7 @@ import {
   ForbiddenException,
   Get,
   HttpCode,
+  NotFoundException,
   Param,
   ParseUUIDPipe,
   Patch,
@@ -86,6 +87,7 @@ import {
 import { ContractViewDto } from "./dto/contract-view.dto";
 import { CustomerTruckAssignmentDto } from "./dto/customer-truck-assignment.dto";
 import { AddCustomerTruckDto } from "./dto/add-customer-truck.dto";
+import { BulkCustomerTrucksDto } from "./dto/bulk-customer-truck.dto";
 import { DepartCustomerTruckDto } from "./dto/depart-customer-truck.dto";
 import { LoadCustomerTruckDto } from "./dto/load-customer-truck.dto";
 import { CustomerTruckService } from "./customer-truck.service";
@@ -597,6 +599,34 @@ export class BookingsController {
     return this.bookingsService.wagonAllocations(id);
   }
 
+  @Get(":id/wagons/export")
+  @MixedAudience(FREIGHT_PERMS.bookings.view)
+  @ApiOperation({
+    summary:
+      "Download the booking's allocated wagons as an Excel workbook (customer name + one row per wagon)",
+  })
+  async wagonAllocationsExport(
+    @Param("id", ParseUUIDPipe) id: string,
+    @CurrentUser() user: TCurrentUser,
+    @Res() res: Response,
+  ) {
+    const booking = await this.bookingsService.findById(id);
+    if (!hasFreightPermission(user, FREIGHT_PERMS.bookings.view)) {
+      await this.bookingsService.assertCustomerCanAccessBooking(
+        user?.id,
+        booking,
+      );
+    }
+    const { filename, buffer } =
+      await this.bookingsService.wagonAllocationsWorkbook(id);
+    res.setHeader(
+      "Content-Type",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    );
+    res.setHeader("Content-Disposition", `attachment; filename="${filename}"`);
+    res.send(buffer);
+  }
+
   // ── Partial wagon cancellation (paid bookings) ────────────────────────────
   // Customer endpoints are ownership-scoped (no portal permission keys); the
   // staff history/void/rebook variants are permission-gated below.
@@ -664,9 +694,11 @@ export class BookingsController {
     @CurrentUser() user: TCurrentUser,
   ) {
     const booking = await this.bookingsService.findById(id);
+    // GL (createBooking) rebooks credits and must see the ledger for that.
     const staff =
       hasFreightPermission(user, FREIGHT_PERMS.bookings.view) ||
-      hasFreightPermission(user, FREIGHT_PERMS.bookings.wagonCancellationView);
+      hasFreightPermission(user, FREIGHT_PERMS.bookings.wagonCancellationView) ||
+      hasFreightPermission(user, FREIGHT_PERMS.contracts.createBooking);
     if (!staff) {
       await this.bookingsService.assertCustomerCanAccessBooking(
         user?.id,
@@ -783,12 +815,78 @@ export class BookingsController {
   }
 
   /** Owner-or-staff gate shared by the per-cancellation actions. */
+  /**
+   * Scope a clearance READ that a transit agent may be making.
+   *
+   * Transit agents are portal accounts holding no permission and belonging to
+   * no company, so the audience guards admit them but the usual company-based
+   * ownership check would 404 every booking. This narrows them to the shipments
+   * assigned to them and leaves every other caller — staff and owning customers
+   * — on the path they already had. Purely widening: nothing that passed before
+   * starts failing here.
+   */
+  private async assertTransitAgentScope(
+    bookingId: string,
+    user: TCurrentUser,
+  ): Promise<void> {
+    const userId = user?.id;
+    if (!userId) return;
+    if (!(await this.bookingsService.isTransitAgent(userId))) return;
+    if (
+      !(await this.bookingsService.isTransitAgentForBooking(userId, bookingId))
+    ) {
+      // Hidden behind a NotFound so booking ids stay unprobeable, matching the
+      // customer-ownership failure mode.
+      throw new NotFoundException(`Booking ${bookingId} not found`);
+    }
+  }
+
+  /**
+   * Gate a formerly staff-only clearance route that is now MixedAudience.
+   *
+   * Staff still pass on their permission. A portal caller must be a transit
+   * agent assigned to THIS booking — an ordinary customer is rejected, because
+   * relaxing the guard must not hand the whole customer base a route that was
+   * previously staff-only.
+   *
+   * Used for the Djibouti-desk WRITES too (DO/RO upload, RO amendment): the
+   * assigned agent files them in the desk's place, and the assignment is the
+   * only thing standing between a portal token and the customs record.
+   */
+  private async assertPortalClearanceAccess(
+    bookingId: string,
+    user: TCurrentUser,
+  ): Promise<void> {
+    if (
+      hasFreightPermission(user, FREIGHT_PERMS.contracts.clearanceEtActions) ||
+      hasFreightPermission(user, FREIGHT_PERMS.contracts.clearanceDjActions)
+    ) {
+      return;
+    }
+    if (
+      !(await this.bookingsService.isTransitAgentForBooking(
+        user?.id,
+        bookingId,
+      ))
+    ) {
+      throw new NotFoundException(`Booking ${bookingId} not found`);
+    }
+  }
+
   private async assertWagonCancellationActor(
     cancellationId: string,
     user: TCurrentUser,
     staffPermission: string,
   ): Promise<void> {
     if (hasFreightPermission(user, staffPermission)) return;
+    // Rebooking a credit creates a booking under the contract — GL's booking
+    // creation key covers it even where the dedicated rebook key was never granted.
+    if (
+      staffPermission === FREIGHT_PERMS.bookings.wagonCancellationRebook &&
+      hasFreightPermission(user, FREIGHT_PERMS.contracts.createBooking)
+    ) {
+      return;
+    }
     const row = await this.wagonCancellationService.findById(cancellationId);
     const booking = await this.bookingsService.findById(row.bookingId);
     await this.bookingsService.assertCustomerCanAccessBooking(
@@ -848,7 +946,7 @@ export class BookingsController {
   })
   async bulkAddCustomerTrucks(
     @Param("id", ParseUUIDPipe) id: string,
-    @Body() payload: { trucks: AddCustomerTruckDto[] },
+    @Body() payload: BulkCustomerTrucksDto,
     @CurrentUser() user: TCurrentUser,
   ) {
     const booking = await this.bookingsService.findById(id);
@@ -1128,6 +1226,9 @@ export class BookingsController {
   }
 
   @Get(":id/clearance")
+  // A transit agent is a portal account, so MixedAudience admits them without a
+  // permission; `assertTransitAgentScope` below narrows them to the shipments
+  // actually assigned to them.
   @MixedAudience([
     FREIGHT_PERMS.bookings.clearanceView,
     FREIGHT_PERMS.bookings.reviewDocuments,
@@ -1136,7 +1237,11 @@ export class BookingsController {
     summary:
       "Document-clearance grid (required docs + upload + GL review status)",
   })
-  getClearance(@Param("id", ParseUUIDPipe) id: string) {
+  async getClearance(
+    @Param("id", ParseUUIDPipe) id: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    await this.assertTransitAgentScope(id, user);
     return this.transitionService.getClearanceView(id);
   }
 
@@ -1278,8 +1383,11 @@ export class BookingsController {
     return { success: true };
   }
 
+  // Was staff-only. Opened to the transit agent assigned to the shipment, who
+  // needs the clearance trail for the bookings they handle; every other portal
+  // account is still rejected by the scope check below.
   @Get(":id/clearance/history")
-  @BookingStaff([
+  @MixedAudience([
     FREIGHT_PERMS.contracts.clearanceEtActions,
     FREIGHT_PERMS.contracts.clearanceDjActions,
   ])
@@ -1287,7 +1395,11 @@ export class BookingsController {
     summary:
       "Clearance action history for the booking — reviews, workflow steps, charges (newest first)",
   })
-  getClearanceHistory(@Param("id", ParseUUIDPipe) id: string) {
+  async getClearanceHistory(
+    @Param("id", ParseUUIDPipe) id: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    await this.assertPortalClearanceAccess(id, user);
     return this.clearanceEventService.list(id);
   }
 
@@ -1310,6 +1422,12 @@ export class BookingsController {
       hasFreightPermission(user, FREIGHT_PERMS.contracts.clearanceEtActions) ||
       hasFreightPermission(user, FREIGHT_PERMS.contracts.clearanceDjActions);
     if (isStaff) return this.clearanceChargeService.list(id);
+    // The transit agent handling this shipment sees the same customer-facing
+    // slice the customer does — charges actually sent, never the internal
+    // draft/billing view `list()` returns.
+    if (await this.bookingsService.isTransitAgentForBooking(user?.id, id)) {
+      return this.clearanceChargeService.listForCustomer(id);
+    }
     const booking = await this.bookingsService.findById(id);
     await this.bookingsService.assertCustomerCanAccessBooking(
       user?.id,
@@ -1777,8 +1895,10 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  // Djibouti-desk write, also filed by the transit agent assigned to this
+  // shipment — `assertPortalClearanceAccess` rejects every other portal caller.
   @Post(":id/clearance/delivery-order")
-  @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @MixedAudience(FREIGHT_PERMS.contracts.clearanceDjActions)
   @UseInterceptors(AnyFilesInterceptor())
   @ApiConsumes("multipart/form-data")
   async uploadBookingDeliveryOrder(
@@ -1788,6 +1908,7 @@ export class BookingsController {
     @Body("doCollectedDate") doCollectedDate: string | undefined,
     @CurrentUser() user: TCurrentUser,
   ) {
+    await this.assertPortalClearanceAccess(id, user);
     const booking = await this.bookingClearanceService.uploadDeliveryOrder(
       id,
       files ?? [],
@@ -1798,7 +1919,7 @@ export class BookingsController {
   }
 
   @Post(":id/clearance/release-order")
-  @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @MixedAudience(FREIGHT_PERMS.contracts.clearanceDjActions)
   @UseInterceptors(AnyFilesInterceptor())
   @ApiConsumes("multipart/form-data")
   async uploadBookingReleaseOrder(
@@ -1807,6 +1928,7 @@ export class BookingsController {
     @Body("vesselDepartureDate") vesselDepartureDate: string,
     @CurrentUser() user: TCurrentUser,
   ) {
+    await this.assertPortalClearanceAccess(id, user);
     const result = await this.bookingClearanceService.uploadReleaseOrder(
       id,
       files ?? [],
@@ -1820,13 +1942,69 @@ export class BookingsController {
     };
   }
 
+  // Transit-agent arrival paperwork (export): gate pass and Djibouti T1 sets.
+  // Same audience rule as the DO/RO uploads above — the desk, or the agent
+  // assigned to this shipment.
+  @Post(":id/clearance/gate-pass-documents")
+  @MixedAudience(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @UseInterceptors(AnyFilesInterceptor())
+  @ApiConsumes("multipart/form-data")
+  async uploadBookingGatePassDocuments(
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFiles() files: Express.Multer.File[],
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    await this.assertPortalClearanceAccess(id, user);
+    return this.bookingClearanceService.uploadTransitArrivalDocuments(
+      id,
+      "gate_pass",
+      files ?? [],
+      resolveAuthUserId(user),
+    );
+  }
+
+  @Post(":id/clearance/djibouti-t1-documents")
+  @MixedAudience(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @UseInterceptors(AnyFilesInterceptor())
+  @ApiConsumes("multipart/form-data")
+  async uploadBookingDjiboutiT1Documents(
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFiles() files: Express.Multer.File[],
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    await this.assertPortalClearanceAccess(id, user);
+    return this.bookingClearanceService.uploadTransitArrivalDocuments(
+      id,
+      "djibouti_t1",
+      files ?? [],
+      resolveAuthUserId(user),
+    );
+  }
+
+  @Delete(":id/clearance/transit-documents/:fileId")
+  @MixedAudience(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @HttpCode(204)
+  async removeBookingTransitDocument(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("fileId", ParseUUIDPipe) fileId: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    await this.assertPortalClearanceAccess(id, user);
+    await this.bookingClearanceService.removeTransitArrivalDocument(
+      id,
+      fileId,
+      resolveAuthUserId(user),
+    );
+  }
+
   @Post(":id/clearance/ro-amendment")
-  @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @MixedAudience(FREIGHT_PERMS.contracts.clearanceDjActions)
   async requestBookingRoAmendment(
     @Param("id", ParseUUIDPipe) id: string,
     @Body() dto: RoAmendmentDto,
     @CurrentUser() user: TCurrentUser,
   ) {
+    await this.assertPortalClearanceAccess(id, user);
     const booking = await this.bookingClearanceService.requestRoAmendment(
       id,
       dto.note,
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index e119af52e..6146da711 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -6,6 +6,7 @@ import { registerExchangeModule } from "../exchange-settings/exchange-module-opt
 
 // import { CustomersModule } from '../customers/customers.module';
 import { CompaniesModule } from '../companies/companies.module';
+import { ExportsModule } from '../exports/exports.module';
 import { FilesModule } from '../files/files.module';
 import { MinioModule } from '../minio/minio.module';
 import { RuleEngineModule } from '../rule-engine/rule-engine.module';
@@ -105,6 +106,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
     // CustomersModule,
     RuleEngineModule,
     FileUploadSettingsModule,
+    ExportsModule,
     SignaturesModule,
     registerExchangeModule(),
   ],
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index 5e0e3c994..21428c77d 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -34,10 +34,12 @@ import {
   DocumentReviewStatus,
 } from './entities/booking-document-review.entity';
 import { BookingContainer } from './entities/booking-container.entity';
+import { BookingWagonCancellation } from './entities/booking-wagon-cancellation.entity';
 import { BookingContainerUnit } from './entities/booking-container-unit.entity';
 import { BookingRateSnapshot } from './entities/booking-rate-snapshot.entity';
 import { BookingReviewNote, ReviewNoteType } from './entities/booking-review-note.entity';
 import { TrainScheduleBooking } from '../train-schedules/entities/train-schedule-booking.entity';
+import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
 import { Booking } from './entities/booking.entity';
 import {
   BookingContractSignature,
@@ -332,21 +334,22 @@ export class BookingsRepository extends BaseRepository<Booking> {
    * Bookings a GL operator may manually link to `booking` as its odd-20ft
    * consolidation partner (Path B customs flow). Unlike
    * {@link findComplementaryConsolidationPartner} — which auto-pairs on an exact
-   * quantity complement — this lists CANDIDATES for a human to choose from, so
-   * the filter is deliberately looser: any other customs booking on the same
-   * route/direction that is itself carrying an odd 20ft count. Two odd counts
-   * always sum to even, so any pick fills the shared wagon.
+   * quantity complement — this lists CANDIDATES for a human to choose from, but
+   * every row must still be a legal pick: another customs booking on the same
+   * route/direction, riding the same booking day, that is itself carrying an odd
+   * 20ft count. Two odd counts always sum to even, so any pick fills the shared
+   * wagon.
    *
-   * Bare instances awaiting completion have no persisted containers yet, so the
-   * odd-count test runs on the requested container lines when they exist and the
-   * booking is offered as a candidate when they do not (GL enters its cargo on
-   * the split form).
+   * A booking whose cargo is not entered yet is NOT a candidate: with no
+   * container lines its 20ft count is unknown, so pairing with it cannot be
+   * shown to fill the wagon. Same rule as
+   * {@link findRebookConsolidationCandidates}.
    */
   async findManualConsolidationCandidates(
     booking: Booking,
     limit = 50,
   ): Promise<Booking[]> {
-    const rows = await this.repository
+    const qb = this.repository
       .createQueryBuilder('b')
       .leftJoinAndSelect('b.bookingContainers', 'bc')
       .leftJoinAndSelect('bc.containerType', 'ct')
@@ -376,17 +379,27 @@ export class BookingsRepository extends BaseRepository<Booking> {
           'OPERATION_CHANGES_REQUESTED',
           'PENDING_CONSOLIDATION',
         ],
-      })
-      .orderBy('b.createdAt', 'ASC')
-      .take(limit)
-      .getMany();
+      });
 
-    // Odd-20ft test in memory: a bare instance has no containers yet (GL fills
-    // them on the split form) and stays a candidate; one that already carries
-    // cargo qualifies only when its 20ft total is odd.
+    // Same EAT booking day — the pair shares one physical wagon, so it must
+    // board one train. Applied only when this booking has a date of its own;
+    // without one there is no day to match against and route/direction stand
+    // alone, mirroring findComplementaryConsolidationPartner.
+    if (booking.scheduledDate) {
+      qb.andWhere(
+        `DATE(b.scheduled_date AT TIME ZONE 'Africa/Addis_Ababa') = DATE(:bookingDate AT TIME ZONE 'Africa/Addis_Ababa')`,
+        { bookingDate: booking.scheduledDate },
+      );
+    }
+
+    const rows = await qb.orderBy('b.createdAt', 'ASC').take(limit).getMany();
+
+    // Odd-20ft test in memory. A booking with no container lines has an unknown
+    // 20ft count, so it cannot be shown to complete the wagon and is not
+    // offered.
     return rows.filter((row) => {
       const lines = row.bookingContainers ?? [];
-      if (lines.length === 0) return true;
+      if (lines.length === 0) return false;
       const ft20 = lines
         .filter((line) => Number(line.containerType?.sizeFt) === 20)
         .reduce((sum, line) => sum + Number(line.quantity || 0), 0);
@@ -396,10 +409,16 @@ export class BookingsRepository extends BaseRepository<Booking> {
 
   /**
    * Candidate partners for rebooking an odd-20ft cancellation credit: unpaired
-   * odd-20ft bookings on the same route/direction riding the requested day —
-   * SUBMITTED (committed direct booking) or parked PENDING_CONSOLIDATION.
+   * odd-20ft bookings on the same route/direction riding the requested day.
    * Unlike {@link findManualConsolidationCandidates} this is not customs-only:
    * GL picks who shares the rebooked wagon whatever the contract kind.
+   *
+   * The status set is deliberately wide. A partner here is not required to be a
+   * live, committed shipment — a booking that lost its slot (EXPIRED) or was
+   * cancelled still has cargo that GL can put back on a train, and pairing it
+   * with the rebooked credit is how both halves get moving again. What it must
+   * not be is already spoken for: a booking whose own cancellation credit has
+   * been rebooked elsewhere is excluded, as is one already paired.
    */
   async findRebookConsolidationCandidates(
     booking: Booking,
@@ -410,6 +429,9 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .createQueryBuilder('b')
       .leftJoinAndSelect('b.bookingContainers', 'bc')
       .leftJoinAndSelect('bc.containerType', 'ct')
+      // Units come back so GL can correct the partner's container numbers,
+      // seals and VGMs while pairing.
+      .leftJoinAndSelect('bc.units', 'unit')
       .leftJoinAndSelect('b.company', 'company')
       .where('b.id != :bookingId', { bookingId: booking.id })
       .andWhere('b.consolidationPartnerId IS NULL')
@@ -423,8 +445,27 @@ export class BookingsRepository extends BaseRepository<Booking> {
         tradeDirection: booking.tradeDirection,
       })
       .andWhere('b.status IN (:...statuses)', {
-        statuses: ['SUBMITTED', 'PENDING_CONSOLIDATION'],
+        statuses: [
+          'SUBMITTED',
+          'PENDING_CONSOLIDATION',
+          'CLEARANCE_READY',
+          'OPERATION_CHANGES_REQUESTED',
+          // Lost its slot or was called off — its cargo is still real and can
+          // ride the rebooked wagon.
+          'EXPIRED',
+          'CANCELLED',
+        ],
       })
+      // A cancelled booking whose own credit was already spent on a rebook is
+      // gone — pairing with it would hand the same cargo out twice.
+      .andWhere(
+        `NOT EXISTS (
+           SELECT 1 FROM freight.booking_wagon_cancellations c
+           WHERE c.booking_id = b.id
+             AND c.rebooked_booking_id IS NOT NULL
+             AND c.deleted_at IS NULL
+         )`,
+      )
       // Same EAT booking day as the rebook — the pair shares one physical
       // wagon, so it must board one train.
       .andWhere(
@@ -729,6 +770,89 @@ export class BookingsRepository extends BaseRepository<Booking> {
     return new Set(rows.map((r) => r.bookingId));
   }
 
+  /**
+   * Bookings among `bookingIds` that hold a redeemable wagon-cancellation
+   * credit — the cut is settled (CREDIT_AVAILABLE), the credit is worth
+   * something, and it has not been spent on a rebook yet. Surfaced on the GL
+   * clearance queue so a paid-for credit is visibly rebookable from the list
+   * rather than only from the booking's own page.
+   */
+  async findBookingsWithRedeemableCredit(
+    bookingIds: string[],
+  ): Promise<Map<string, string>> {
+    if (bookingIds.length === 0) return new Map();
+    const rows = (await this.dataSource
+      .getRepository(BookingWagonCancellation)
+      .createQueryBuilder('c')
+      .select('c.booking_id', 'bookingId')
+      .addSelect('c.id', 'cancellationId')
+      .where('c.booking_id IN (:...bookingIds)', { bookingIds })
+      .andWhere('c.status = :status', { status: 'CREDIT_AVAILABLE' })
+      .andWhere('c.credit_amount > 0')
+      .andWhere('c.rebooked_booking_id IS NULL')
+      .andWhere('c.deleted_at IS NULL')
+      .getRawMany()) as Array<{ bookingId: string; cancellationId: string }>;
+    return new Map(rows.map((r) => [r.bookingId, r.cancellationId]));
+  }
+
+  /**
+   * Apply container-unit corrections (number / seal / VGM) to units that belong
+   * to `bookingId`. The ownership join is the point: a unit id from another
+   * booking silently matches nothing rather than editing a stranger's cargo.
+   * Sizes and quantities are never touched — only the identifying details.
+   * Returns how many units were actually updated.
+   */
+  async patchContainerUnitsForBooking(
+    bookingId: string,
+    patches: Array<{
+      id: string;
+      containerNumber?: string;
+      sealNumber?: string;
+      vgmTons?: number;
+    }>,
+  ): Promise<number> {
+    if (patches.length === 0) return 0;
+    const unitRepo = this.dataSource.getRepository(BookingContainerUnit);
+    const owned = await unitRepo
+      .createQueryBuilder('u')
+      .innerJoin('u.bookingContainer', 'bc')
+      .where('bc.booking_id = :bookingId', { bookingId })
+      .andWhere('u.id IN (:...ids)', { ids: patches.map((p) => p.id) })
+      .select('u.id', 'id')
+      .getRawMany<{ id: string }>();
+    const ownedIds = new Set(owned.map((r) => r.id));
+
+    let updated = 0;
+    for (const patch of patches) {
+      if (!ownedIds.has(patch.id)) continue;
+      const set: Record<string, unknown> = {};
+      if (patch.containerNumber !== undefined)
+        set.containerNumber = patch.containerNumber;
+      if (patch.sealNumber !== undefined) set.sealNumber = patch.sealNumber;
+      if (patch.vgmTons !== undefined) set.vgmTons = patch.vgmTons;
+      if (Object.keys(set).length === 0) continue;
+      await unitRepo.update(patch.id, set as never);
+      updated += 1;
+    }
+    return updated;
+  }
+
+  /**
+   * Has this booking's own wagon-cancellation credit already been spent on a
+   * rebook? Such a booking must not be offered or accepted as a consolidation
+   * partner — its cargo has already moved to the rebooked booking.
+   */
+  async hasSpentCancellationCredit(bookingId: string): Promise<boolean> {
+    const count = await this.dataSource
+      .getRepository(BookingWagonCancellation)
+      .createQueryBuilder('c')
+      .where('c.booking_id = :bookingId', { bookingId })
+      .andWhere('c.rebooked_booking_id IS NOT NULL')
+      .andWhere('c.deleted_at IS NULL')
+      .getCount();
+    return count > 0;
+  }
+
   findDocumentReview(
     bookingId: string,
     settingCode: string,
@@ -1043,9 +1167,38 @@ export class BookingsRepository extends BaseRepository<Booking> {
         select: { bookingId: true, trainScheduleId: true },
       });
       const scheduleByBooking = new Map(links.map((link) => [link.bookingId, link.trainScheduleId]));
+
+      // The allocated train's own departure date — distinct from the customer's
+      // requested `booking.scheduledDate`. The list column shows this once a
+      // booking is on a train, so fetch it alongside the link ids.
+      const scheduleIds = [...new Set([...scheduleByBooking.values()].filter(Boolean))] as string[];
+      const schedules = scheduleIds.length
+        ? await this.dataSource.getRepository(TrainSchedule).find({
+            where: { id: In(scheduleIds) },
+            select: {
+              id: true,
+              reference: true,
+              trainNumber: true,
+              status: true,
+              scheduledDepartureDate: true,
+            },
+          })
+        : [];
+      const scheduleById = new Map(schedules.map((schedule) => [schedule.id, schedule]));
+
       for (const item of items) {
-        (item as Booking & { trainScheduleId?: string | null }).trainScheduleId =
-          scheduleByBooking.get(item.id) ?? null;
+        const scheduleId = scheduleByBooking.get(item.id) ?? null;
+        const enriched = item as Booking & {
+          trainScheduleId?: string | null;
+          trainScheduleReference?: string | null;
+          trainScheduleDepartureDate?: string | null;
+        };
+        enriched.trainScheduleId = scheduleId;
+        const schedule = scheduleId ? scheduleById.get(scheduleId) : undefined;
+        enriched.trainScheduleReference = schedule?.reference ?? schedule?.trainNumber ?? null;
+        enriched.trainScheduleDepartureDate = schedule?.scheduledDepartureDate
+          ? new Date(schedule.scheduledDepartureDate).toISOString()
+          : null;
       }
     }
 
@@ -1786,6 +1939,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
         Booking,
         | 'schedulingStatus'
         | 'wagonsRequired'
+        | 'cancellationWagons'
         | 'scheduledAt'
         | 'holdStartedAt'
         | 'holdExpiresAt'
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index 71107650f..ea901bb16 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -12,6 +12,7 @@ import { Freight, SchedulingStatus } from '@edr/types';
 import { insertWithGeneratedReference, logCtx } from '@edr/api-common';
 // import { CustomersService } from '../customers/customers.service';
 import { CompaniesService } from '../companies/companies.service';
+import { TabularExportService } from '../exports/tabular-export.service';
 import { CompanyKind, CompanyStatus } from '../companies/entities/company.entity';
 import { TrainSchedulingService } from '../train-scheduling/services/train-scheduling.service';
 import { eatDay } from '../train-scheduling/batch-window.util';
@@ -29,6 +30,11 @@ import { DataSource, In } from 'typeorm';
 
 import { deriveTradeDirection } from '../../common/derive-trade-direction.util';
 import { assertExportReceivedWithGrn, DIRECT_TO_TRAIN } from '../../common/export-received-gate';
+import {
+  EDR_HAULAGE_CONFLICT_MESSAGE,
+  LAST_MILE_COMMITTED_SQL,
+  edrHaulsThisBooking,
+} from '../../common/mile-haulage.util';
 import { Yard } from '../rule-engine/entities/yard.entity';
 import { ServiceType } from '../rule-engine/entities/service-type.entity';
 import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
@@ -99,6 +105,38 @@ export interface PaginatedBookings {
   };
 }
 
+/** One container on an allocated wagon (raw SQL json_agg projection). */
+export interface WagonAllocationContainer {
+  containerNumber: string | null;
+  sealNumber: string | null;
+  positionOnWagon: number | null;
+  grossWeightTons: number | null;
+  sizeFt: number | null;
+}
+
+/** One allocated wagon as returned by `wagonAllocations` (raw SQL projection). */
+export interface WagonAllocationRow {
+  allocationId: string;
+  sequenceNo: number | null;
+  wagonNumber: string | null;
+  wagonType: string | null;
+  wagonTypeCode: string | null;
+  /** numeric columns arrive as strings from pg. */
+  tareWeightTons: string | null;
+  capacityTons: string | null;
+  lengthMeters: string | null;
+  allocatedWeightTons: string | null;
+  loadType: string | null;
+  status: string | null;
+  trainNumber: string | null;
+  departureAt: string | Date | null;
+  originStation: string | null;
+  destinationStation: string | null;
+  bulkCargoDescription: string | null;
+  bulkQuantity: string | null;
+  containers: WagonAllocationContainer[];
+}
+
 /** One wagon line on the carriage acceptance sheet (raw SQL projection). */
 interface CarriageAcceptanceWagonRow {
   sequenceNo: number;
@@ -112,8 +150,13 @@ interface CarriageAcceptanceWagonRow {
   departureAt: Date | null;
   marshalledAt: string | null;
   arrivalAt: string | null;
+  /** Per-row stations: the slot's own board/alight yard, else the schedule's endpoints. */
+  departureStation: string | null;
+  arrivalStation: string | null;
   containerNumbers: string | null;
   sealNumbers: string | null;
+  /** Allocation status — LOADED/DEPARTED means EDR has the cargo. */
+  status: string | null;
 }
 
 /** A received-but-not-yet-marshalled export line, standing in for a wagon row. */
@@ -162,6 +205,7 @@ export class BookingsService {
     private readonly bookingContractService: BookingContractService,
     @Inject(forwardRef(() => BookingBatchService))
     private readonly bookingBatchService: BookingBatchService,
+    private readonly tabularExport: TabularExportService,
   ) {}
 
   async assignCustomerTruck(
@@ -169,18 +213,23 @@ export class BookingsService {
     dto: CustomerTruckAssignmentDto,
   ): Promise<Booking> {
     const booking = await this.findById(bookingId);
-    const hasFirstMile = Boolean(booking.firstMilePickupAddress?.trim());
-    const hasLastMile = Boolean(booking.lastMileDeliveryAddress?.trim());
-    const usesMileService =
-      booking.tradeDirection === 'IMPORT'
-        ? hasLastMile
-        : booking.tradeDirection === 'EXPORT'
-          ? hasFirstMile
-          : hasFirstMile || hasLastMile;
-    if (usesMileService) {
-      throw new BadRequestException(
-        'Customer truck assignment is only allowed when first/last mile delivery is not selected',
-      );
+    // Same rule as CustomerTruckService.assertSelfHaulPaid: an EDR delivery leg
+    // closes self-haul only once it has been approved.
+    const [commitment]: Array<{ lastMileCommitted: boolean }> = await this.dataSource.query(
+      `SELECT ${LAST_MILE_COMMITTED_SQL} AS "lastMileCommitted"
+         FROM freight.bookings b
+        WHERE b.id = $1`,
+      [bookingId],
+    );
+    if (
+      edrHaulsThisBooking({
+        tradeDirection: booking.tradeDirection ?? null,
+        firstMile: booking.firstMilePickupAddress ?? null,
+        lastMile: booking.lastMileDeliveryAddress ?? null,
+        lastMileCommitted: Boolean(commitment?.lastMileCommitted),
+      })
+    ) {
+      throw new BadRequestException(EDR_HAULAGE_CONFLICT_MESSAGE);
     }
     if (booking.customerTruckAssignedAt) {
       throw new ConflictException('Customer truck assignment is already submitted and locked');
@@ -263,9 +312,13 @@ export class BookingsService {
 
   /**
    * Carriage acceptance sheet — one per booking, listing every wagon the booking
-   * occupies. Handed to the customer when EDR accepts the cargo (export) and when
-   * the wagons are allocated before marshalling (import), so it is only available
-   * once the booking has wagon allocations.
+   * occupies. A booking is routinely loaded in parts (some containers go, the
+   * rest wait for the next train), so each row carries a Status of Loaded or
+   * Not loaded and the totals count only the loaded ones: the customer sees the
+   * whole plan on one page without the sheet overstating what EDR has taken.
+   *
+   * Handed to the customer when EDR accepts the cargo (export) and when the
+   * wagons are allocated before marshalling (import).
    */
   async carriageAcceptanceSheet(bookingId: string): Promise<{ filename: string; buffer: Buffer }> {
     const booking = await this.findById(bookingId);
@@ -285,6 +338,9 @@ export class BookingsService {
               s.scheduled_departure_date       AS "departureAt",
               so.label                         AS "marshalledAt",
               sd.label                         AS "arrivalAt",
+              COALESCE(by_.label, so.label)    AS "departureStation",
+              COALESCE(ay.label, sd.label)     AS "arrivalStation",
+              a.status                         AS "status",
               string_agg(DISTINCT ci.container_number, ', ') AS "containerNumbers",
               string_agg(DISTINCT ci.seal_number, ', ')      AS "sealNumbers"
          FROM freight.wagon_booking_allocations a
@@ -296,13 +352,31 @@ export class BookingsService {
            ON s.train_set_id = tsw.train_set_id AND s.deleted_at IS NULL
          LEFT JOIN freight.yards so ON so.id = s.origin_station_id
          LEFT JOIN freight.yards sd ON sd.id = s.destination_station_id
+         LEFT JOIN freight.yards by_ ON by_.id = tsw.board_yard_id
+         LEFT JOIN freight.yards ay ON ay.id = tsw.alight_yard_id
          LEFT JOIN freight.wagon_allocation_container_items ci
            ON ci.wagon_booking_allocation_id = a.id AND ci.deleted_at IS NULL
+          AND (
+            $2 <> 'EXPORT' OR $3 <> 'CONTAINER' OR EXISTS (
+              SELECT 1
+                FROM freight.booking_container_units received_unit
+                JOIN freight.booking_container received_line
+                  ON received_line.id = received_unit.booking_container_id
+                 AND received_line.deleted_at IS NULL
+               WHERE received_line.booking_id = a.booking_id
+                 AND received_unit.container_number = ci.container_number
+                 AND received_unit.received_to_port = true
+                 AND NULLIF(TRIM(received_unit.grn_number), '') IS NOT NULL
+                 AND received_unit.deleted_at IS NULL
+            )
+          )
         WHERE a.booking_id = $1 AND a.deleted_at IS NULL
-        GROUP BY tsw.id, a.id, wt.code, wt.name, w.wagon_number, wt.tare_weight_tons,
-                 s.train_number, s.scheduled_departure_date, so.label, sd.label
+        GROUP BY tsw.id, a.id, a.status, wt.code, wt.name, w.wagon_number, wt.tare_weight_tons,
+                 s.train_number, s.scheduled_departure_date, so.label, sd.label,
+                 by_.label, ay.label
+        HAVING $2 <> 'EXPORT' OR $3 <> 'CONTAINER' OR COUNT(ci.id) > 0
         ORDER BY tsw.sequence_no`,
-      [bookingId],
+      [bookingId, booking.tradeDirection, booking.freightType],
     );
     // Export acceptance happens at the warehouse gate, not at marshalling: EDR
     // takes custody of the cargo when it receives it, and the customer is handed
@@ -337,17 +411,17 @@ export class BookingsService {
           )
         : booking.tradeDirection === 'EXPORT'
           ? await this.dataSource.query(
-              `SELECT inv.weight         AS "allocatedWeightTons",
-                      c.container_number AS "containerNumbers"
-                 FROM freight.warehouse_inventory inv
-                 LEFT JOIN freight.containers c
-                   ON c.id = inv.container_id AND c.deleted_at IS NULL
-                WHERE inv.booking_id = $1 AND inv.deleted_at IS NULL
-                  AND COALESCE(
-                        NULLIF(TRIM(inv.grn_number), ''),
-                        substring(inv.notes FROM 'GRN Number: ([^\\n\\r]+)')
-                      ) IS NOT NULL
-                ORDER BY inv.created_at`,
+              `SELECT unit.vgm_tons       AS "allocatedWeightTons",
+                      unit.container_number AS "containerNumbers",
+                      unit.seal_number      AS "sealNumbers"
+                 FROM freight.booking_container_units unit
+                 JOIN freight.booking_container line
+                   ON line.id = unit.booking_container_id AND line.deleted_at IS NULL
+                WHERE line.booking_id = $1
+                  AND unit.deleted_at IS NULL
+                  AND unit.received_to_port = true
+                  AND NULLIF(TRIM(unit.grn_number), '') IS NOT NULL
+                ORDER BY unit.received_at, unit.container_number`,
               [bookingId],
             )
           : [];
@@ -381,8 +455,12 @@ export class BookingsService {
         departureAt: null,
         marshalledAt: null,
         arrivalAt: null,
+        departureStation: null,
+        arrivalStation: null,
         containerNumbers: row.containerNumbers,
         sealNumbers: row.sealNumbers ?? null,
+        // A received line has no allocation; it is cargo EDR already holds.
+        status: null,
       }));
     }
 
@@ -403,7 +481,7 @@ export class BookingsService {
    * an array per wagon, bulk load description when the wagon carries bulk).
    * Empty array until the booking has been allocated onto a train.
    */
-  async wagonAllocations(bookingId: string): Promise<unknown[]> {
+  async wagonAllocations(bookingId: string): Promise<WagonAllocationRow[]> {
     return this.dataSource.query(
       `SELECT a.id                             AS "allocationId",
               tsw.sequence_no                  AS "sequenceNo",
@@ -457,6 +535,103 @@ export class BookingsService {
     );
   }
 
+  /**
+   * The Wagons tab's Excel export: the booking's customer identity in the KPI
+   * header, then one row per allocated wagon.
+   *
+   * Container numbers are flattened into a single cell rather than exploded
+   * into one row per container — the sheet is a wagon manifest, and a reader
+   * counting rows must get the wagon count.
+   */
+  async wagonAllocationsWorkbook(
+    bookingId: string,
+  ): Promise<{ filename: string; buffer: Buffer }> {
+    const booking = await this.findById(bookingId);
+    const wagons = await this.wagonAllocations(bookingId);
+
+    // Same precedence the booking list uses: a shipping line owns its bookings
+    // directly, a government booking names its institution, everyone else is
+    // the customer company.
+    // `shippingLineCompany` is attached by `findById` (attachShippingLineCompanies),
+    // not a declared relation on the entity — hence the cast, matching that helper.
+    const shippingLine = (booking as Booking & { shippingLineCompany?: { name?: string } })
+      .shippingLineCompany;
+    const customerName =
+      shippingLine?.name ??
+      (booking.isGovernment ? booking.governmentInstitution : null) ??
+      booking.company?.name ??
+      '—';
+
+    const rows = wagons.map((w) => ({
+      sequenceNo: w.sequenceNo,
+      wagonNumber: w.wagonNumber ?? '—',
+      wagonType: w.wagonType ?? '—',
+      loadType: w.loadType ?? '—',
+      status: w.status ?? '—',
+      tareWeightTons: w.tareWeightTons === null ? null : Number(w.tareWeightTons),
+      capacityTons: w.capacityTons === null ? null : Number(w.capacityTons),
+      allocatedWeightTons:
+        w.allocatedWeightTons === null ? null : Number(w.allocatedWeightTons),
+      lengthMeters: w.lengthMeters === null ? null : Number(w.lengthMeters),
+      containerCount: w.containers?.length ?? 0,
+      containerNumbers:
+        (w.containers ?? []).map((c) => c.containerNumber).filter(Boolean).join(', ') || '—',
+      sealNumbers:
+        (w.containers ?? []).map((c) => c.sealNumber).filter(Boolean).join(', ') || '—',
+      bulkCargo: w.bulkCargoDescription ?? '—',
+      bulkQuantity: w.bulkQuantity === null ? null : Number(w.bulkQuantity),
+      trainNumber: w.trainNumber ?? '—',
+      departureAt: w.departureAt ? new Date(w.departureAt).toISOString().slice(0, 10) : '—',
+      originStation: w.originStation ?? '—',
+      destinationStation: w.destinationStation ?? '—',
+      // Repeated on every row so the sheet survives being filtered, sorted or
+      // pasted into a combined workbook, where the header block is lost.
+      customerName,
+      bookingReference: booking.reference,
+    }));
+
+    const totalAllocated = rows.reduce(
+      (sum, r) => sum + (r.allocatedWeightTons ?? 0),
+      0,
+    );
+
+    const buffer = await this.tabularExport.toXlsx({
+      title: `Wagons ${booking.reference}`.slice(0, 31),
+      description: `Wagons allocated to booking ${booking.reference} — ${customerName}`,
+      label: 'booking:wagon-allocations',
+      kpis: [
+        { label: 'Wagons', value: rows.length },
+        { label: 'Containers', value: rows.reduce((sum, r) => sum + r.containerCount, 0) },
+        { label: 'Allocated weight', value: Number(totalAllocated.toFixed(3)), unit: 't' },
+      ],
+      columns: [
+        { key: 'bookingReference', label: 'Booking', type: 'string' },
+        { key: 'customerName', label: 'Customer', type: 'string' },
+        { key: 'sequenceNo', label: 'Seq', type: 'number' },
+        { key: 'wagonNumber', label: 'Wagon number', type: 'string' },
+        { key: 'wagonType', label: 'Wagon type', type: 'string' },
+        { key: 'loadType', label: 'Load type', type: 'string' },
+        { key: 'status', label: 'Status', type: 'string' },
+        { key: 'tareWeightTons', label: 'Tare', type: 'tons' },
+        { key: 'capacityTons', label: 'Capacity', type: 'tons' },
+        { key: 'allocatedWeightTons', label: 'Allocated', type: 'tons' },
+        { key: 'lengthMeters', label: 'Length (m)', type: 'number' },
+        { key: 'containerCount', label: 'Containers', type: 'number' },
+        { key: 'containerNumbers', label: 'Container numbers', type: 'string' },
+        { key: 'sealNumbers', label: 'Seal numbers', type: 'string' },
+        { key: 'bulkCargo', label: 'Bulk cargo', type: 'string' },
+        { key: 'bulkQuantity', label: 'Bulk quantity', type: 'number' },
+        { key: 'trainNumber', label: 'Train', type: 'string' },
+        { key: 'departureAt', label: 'Departure', type: 'date' },
+        { key: 'originStation', label: 'Origin', type: 'string' },
+        { key: 'destinationStation', label: 'Destination', type: 'string' },
+      ],
+      rows,
+    });
+
+    return { filename: `wagons-${booking.reference}.xlsx`, buffer };
+  }
+
   /**
    * Split the booking amount across its wagons, proportional to allocated weight
    * (equal shares when no weights are recorded). The last row absorbs the rounding
@@ -497,7 +672,17 @@ export class BookingsService {
     const header = wagons[0];
     const sheetDate = header.departureAt ? new Date(header.departureAt) : new Date();
 
-    const totals = wagons.reduce(
+    // Loaded = EDR has the cargo. A booking is routinely loaded in parts, so the
+    // totals count only those: the sheet shows the whole plan, but must never
+    // total up cargo still sitting in the yard. A received-line sheet
+    // (pendingWagons) has no allocation status, and every line on it is cargo
+    // already accepted, so it counts in full.
+    const isLoaded = (w: CarriageAcceptanceWagonRow) =>
+      pendingWagons || w.status === 'LOADED' || w.status === 'DEPARTED';
+    const loadedWagons = wagons.filter(isLoaded);
+    const notLoadedCount = wagons.length - loadedWagons.length;
+
+    const totals = loadedWagons.reduce(
       (acc, w) => ({
         tare: acc.tare + (Number(w.tareWeightTons) || 0),
         capacity: acc.capacity + (Number(w.loadCapacityTons) || 0),
@@ -507,7 +692,7 @@ export class BookingsService {
       { tare: 0, capacity: 0, load: 0, length: 0 },
     );
     // A wagon carrying no weight and no container is running empty under this booking.
-    const fullWagons = wagons.filter(
+    const fullWagons = loadedWagons.filter(
       (w) => (Number(w.allocatedWeightTons) || 0) > 0 || Boolean(w.containerNumbers),
     ).length;
 
@@ -520,11 +705,14 @@ export class BookingsService {
           <td class="num">${num(w.tareWeightTons, 2)}</td>
           <td class="num">${num(w.equatedLength)}</td>
           <td class="num">${num(w.loadCapacityTons)}</td>
-          <td>${esc(arrivalStation)}</td>
+          <td>${esc(w.arrivalStation ?? arrivalStation)}</td>
           <td>${esc(cargoName)}</td>
-          <td>${esc(departureStation)}</td>
+          <td>${esc(w.departureStation ?? departureStation)}</td>
           <td>${esc(w.containerNumbers)}</td>
           <td>${esc(w.sealNumbers)}</td>
+          <td class="${isLoaded(w) ? 'loaded' : 'pending'}">${
+            pendingWagons ? 'Accepted' : isLoaded(w) ? 'Loaded' : 'Not loaded'
+          }</td>
           <td class="num">${money(prices[i])}</td>
         </tr>`,
       )
@@ -535,23 +723,37 @@ export class BookingsService {
     // figure from the printed sheet.
     const totalsRow = `<tr class="totals">
         <td>TOT</td>
-        <td>${wagons.length} ${pendingWagons ? 'received lines' : 'wagons'}</td>
-        <td>${
-          pendingWagons
-            ? 'pending marshalling'
-            : `full ${fullWagons} / empty ${wagons.length - fullWagons}`
-        }</td>
+        <td>${loadedWagons.length} ${pendingWagons ? 'received lines' : 'wagons loaded'}</td>
+        <td></td>
         <td class="num">${num(totals.tare, 2)}</td>
         <td class="num">${num(totals.length)}</td>
         <td class="num">${num(totals.capacity)}</td>
         <td></td>
-        <td>Gross ${num(totals.tare + totals.load)} T</td>
         <td></td>
         <td></td>
         <td></td>
+        <td></td>
+        <td>${notLoadedCount > 0 ? `loaded only (${notLoadedCount} not loaded)` : ''}</td>
         <td class="num">${money(totalAmount)}</td>
       </tr>`;
 
+    // The signed footer of the paper sheet. Rendered as .tile so the
+    // Chromium-less fallback (buildTabularFallbackPdf parses .tile, not
+    // arbitrary divs) still prints every figure.
+    const footer = `
+  <div class="summary footer-summary">
+    <div class="tile"><span>In Total Wagon No.</span><strong>${loadedWagons.length}</strong></div>
+    <div class="tile"><span>Tare Weight (T)</span><strong>${num(totals.tare, 2)}</strong></div>
+    <div class="tile"><span>Load Capacity (T)</span><strong>${num(totals.capacity)}</strong></div>
+    <div class="tile"><span>Gross Weight (T)</span><strong>${num(totals.tare + totals.load)}</strong></div>
+    <div class="tile"><span>Equated Length</span><strong>${num(totals.length)}</strong></div>
+    <div class="tile"><span>Full Wagon</span><strong>${pendingWagons ? '-' : fullWagons}</strong></div>
+    <div class="tile"><span>Empty Wagon</span><strong>${
+      pendingWagons ? '-' : loadedWagons.length - fullWagons
+    }</strong></div>
+    <div class="tile"><span>Total Amount (${esc(currency)})</span><strong>${money(totalAmount)}</strong></div>
+  </div>`;
+
     return `<!doctype html>
 <html>
 <head>
@@ -568,6 +770,8 @@ export class BookingsService {
     .meta { text-align: right; font-size: 11px; color: #475569; min-width: 210px; }
     .meta strong { display: block; margin-top: 4px; color: #0f172a; font-size: 15px; }
     .summary { display: grid; grid-template-columns: repeat(6, 1fr); gap: 8px; margin: 14px 0; }
+    .footer-summary { grid-template-columns: repeat(8, 1fr); margin: 10px 0 0; }
+    .footer-summary .tile { background: #f8fafc; }
     .tile { border: 1px solid #cbd5e1; padding: 8px; min-height: 50px; }
     .tile span { display: block; color: #64748b; font-size: 9px; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 4px; }
     .tile strong { font-size: 11px; }
@@ -575,6 +779,8 @@ export class BookingsService {
     th { background: #f8fafc; color: #475569; text-align: left; }
     th, td { border: 1px solid #cbd5e1; padding: 5px 6px; font-size: 9.5px; vertical-align: top; }
     .num { text-align: right; }
+    .loaded { color: #0f766e; font-weight: 700; }
+    .pending { color: #b45309; font-weight: 700; }
     tr.totals td { background: #f8fafc; font-weight: 700; }
     .notice { margin-top: 10px; border-left: 4px solid #0f766e; background: #f0fdfa; padding: 8px 10px; font-size: 10px; color: #134e4a; }
     .signatures { display: grid; grid-template-columns: repeat(3, 1fr); gap: 18px; margin-top: 34px; }
@@ -618,6 +824,7 @@ export class BookingsService {
         <th>Departure Station</th>
         <th>Container No.</th>
         <th>Seal No.</th>
+        <th>Status</th>
         <th class="num">Price (${esc(currency)})</th>
       </tr>
     </thead>
@@ -626,6 +833,7 @@ export class BookingsService {
       ${totalsRow}
     </tbody>
   </table>
+${footer}
 
   <div class="notice">
     ${
@@ -1988,6 +2196,65 @@ export class BookingsService {
     }
   }
 
+  /**
+   * True when `userId` is a transit agent currently assigned to this booking.
+   *
+   * Deliberately NOT folded into {@link assertCustomerCanAccessBooking}: that
+   * assertion guards ~29 call sites, including wagon cancellations, rebooking
+   * and customer-truck writes. A transit agent must reach the clearance READS
+   * for the shipments they handle and nothing else, so the two ownership rules
+   * stay separate and each caller opts in explicitly.
+   *
+   * Queried directly rather than through TransitAssignmentsService: that module
+   * imports BookingsModule, so injecting it here would close an import cycle.
+   */
+  /** Is this portal account a transit agent at all? */
+  async isTransitAgent(userId: string | undefined): Promise<boolean> {
+    if (!userId) return false;
+    const rows: { one: number }[] = await this.dataSource.query(
+      `SELECT 1 AS one
+         FROM freight.transit_agents a
+        WHERE a.user_id = $1 AND a.deleted_at IS NULL
+        LIMIT 1`,
+      [userId],
+    );
+    return rows.length > 0;
+  }
+
+  async isTransitAgentForBooking(
+    userId: string | undefined,
+    bookingId: string,
+  ): Promise<boolean> {
+    if (!userId) return false;
+    const rows: { one: number }[] = await this.dataSource.query(
+      `SELECT 1 AS one
+         FROM freight.transit_assignments ta
+         JOIN freight.transit_agents a ON a.id = ta.transit_agent_id
+        WHERE a.user_id = $1
+          AND ta.booking_id = $2
+          AND ta.deleted_at IS NULL
+          AND a.deleted_at IS NULL
+        LIMIT 1`,
+      [userId, bookingId],
+    );
+    return rows.length > 0;
+  }
+
+  /**
+   * Authorize a clearance READ on one booking for either audience a portal
+   * account can be: the owning customer, or a transit agent assigned to it.
+   *
+   * Read-only by contract — every caller is a GET. Writes keep using
+   * {@link assertCustomerCanAccessBooking}, which a transit agent never passes.
+   */
+  async assertCanReadBookingClearance(
+    userId: string | undefined,
+    booking: Booking,
+  ): Promise<void> {
+    if (await this.isTransitAgentForBooking(userId, booking.id)) return;
+    await this.assertCustomerCanAccessBooking(userId, booking);
+  }
+
   /**
    * Build the customer-facing shipment tracking payload for a booking from the
    * train schedule it is assigned to and the live checkpoint log. The caller is
diff --git a/apps/edr-freight-api/src/modules/bookings/carriage-acceptance-price-split.spec.ts b/apps/edr-freight-api/src/modules/bookings/carriage-acceptance-price-split.spec.ts
index 195e0cab0..45907c09a 100644
--- a/apps/edr-freight-api/src/modules/bookings/carriage-acceptance-price-split.spec.ts
+++ b/apps/edr-freight-api/src/modules/bookings/carriage-acceptance-price-split.spec.ts
@@ -24,3 +24,84 @@ describe('carriage acceptance sheet — price split', () => {
     expect(shares).toEqual([33.33, 33.33, 33.34]);
   });
 });
+
+// The HTML builder only reaches `this` for two prototype helpers (escapeHtml,
+// splitAmountAcrossWagons), so the prototype itself serves as `this`.
+const buildSheet = (wagons: unknown[], booking: Record<string, unknown> = {}): string =>
+  (
+    BookingsService.prototype as unknown as {
+      buildCarriageAcceptanceSheetHtml(
+        b: unknown,
+        w: unknown[],
+        o: { pendingWagons: boolean },
+      ): string;
+    }
+  ).buildCarriageAcceptanceSheetHtml.call(
+    BookingsService.prototype,
+    {
+      reference: 'BK-1',
+      tradeDirection: 'EXPORT',
+      totalAmount: 100,
+      paymentCurrency: 'ETB',
+      originYard: { label: 'Booking Origin' },
+      destinationYard: { label: 'Booking Destination' },
+      ...booking,
+    },
+    wagons,
+    { pendingWagons: false },
+  );
+
+const wagon = (over: Record<string, unknown> = {}) => ({
+  sequenceNo: 1,
+  wagonType: 'FLAT',
+  wagonNumber: 'W-001',
+  tareWeightTons: '20',
+  equatedLength: '14',
+  loadCapacityTons: '60',
+  allocatedWeightTons: '40',
+  trainNumber: '8302',
+  departureAt: null,
+  marshalledAt: 'DCT/SGTD',
+  arrivalAt: 'GMP',
+  departureStation: null,
+  arrivalStation: null,
+  containerNumbers: 'CN-1',
+  sealNumbers: 'SL-1',
+  status: 'LOADED',
+  ...over,
+});
+
+describe('carriage acceptance sheet — rows and footer', () => {
+  it('prints each row its own Departure/Arrival Station, falling back to the booking yards', () => {
+    const html = buildSheet([
+      wagon({ departureStation: 'Dire Dawa Port', arrivalStation: 'Adama' }),
+      wagon({ sequenceNo: 2, wagonNumber: 'W-002' }),
+    ]);
+    expect(html).toContain('<td>Dire Dawa Port</td>');
+    expect(html).toContain('<td>Adama</td>');
+    expect(html).toContain('<td>Booking Origin</td>');
+    expect(html).toContain('<td>Booking Destination</td>');
+  });
+
+  it('totals the footer over loaded wagons only', () => {
+    const html = buildSheet([
+      wagon(),
+      wagon({ sequenceNo: 2, wagonNumber: 'W-002', status: 'ALLOCATED' }),
+      wagon({
+        sequenceNo: 3,
+        wagonNumber: 'W-003',
+        allocatedWeightTons: '0',
+        containerNumbers: null,
+      }),
+    ]);
+    // 2 loaded of 3: tare 40, capacity 120, equated length 28, gross 40 + 40 load.
+    expect(html).toContain('<span>In Total Wagon No.</span><strong>2</strong>');
+    expect(html).toContain('<span>Tare Weight (T)</span><strong>40.00</strong>');
+    expect(html).toContain('<span>Load Capacity (T)</span><strong>120.000</strong>');
+    expect(html).toContain('<span>Gross Weight (T)</span><strong>80.000</strong>');
+    expect(html).toContain('<span>Equated Length</span><strong>28.000</strong>');
+    expect(html).toContain('<span>Full Wagon</span><strong>1</strong>');
+    expect(html).toContain('<span>Empty Wagon</span><strong>1</strong>');
+    expect(html).toContain('<span>Total Amount (ETB)</span><strong>100.00</strong>');
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts b/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
index 3df681d9c..88df3d80e 100644
--- a/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
@@ -9,12 +9,17 @@ import { DataSource, EntityManager, IsNull } from 'typeorm';
 import { NotificationAudience, NotificationType } from '@edr/types';
 
 import { AddCustomerTruckDto } from './dto/add-customer-truck.dto';
+import type {
+  BulkTruckUploadError,
+  BulkTruckUploadResult,
+} from './dto/bulk-customer-truck.dto';
 import { DepartCustomerTruckDto } from './dto/depart-customer-truck.dto';
 import { CustomerTruckAssignment } from './entities/customer-truck-assignment.entity';
 import { CustomerTruckContainer } from './entities/customer-truck-container.entity';
 import {
   EDR_HAULAGE_CONFLICT_MESSAGE,
-  usesEdrMileService,
+  LAST_MILE_COMMITTED_SQL,
+  edrHaulsThisBooking,
 } from '../../common/mile-haulage.util';
 import {
   assertBulkTonnageRemains,
@@ -35,6 +40,9 @@ interface BookingGuardRow {
   lastMile: string | null;
   paymentStatus: string | null;
   status: string | null;
+  trainScheduleStatus: string | null;
+  /** See `MileCommitmentRow` — an approved EDR last-mile leg closes self-haul. */
+  lastMileCommitted: boolean;
 }
 
 /**
@@ -294,19 +302,16 @@ export class CustomerTruckService {
     }
 
     const requested = (dto.containerNumbers ?? []).map((n) => n.trim().toUpperCase());
+    if (booking.freightType === 'CONTAINER' && !requested.length) {
+      throw new BadRequestException('Select the containers loaded on this truck');
+    }
     if (requested.length) {
-      const bookingNumbers = await this.bookingContainerNumbers(bookingId);
-      for (const n of requested) {
-        if (!bookingNumbers.includes(n)) {
-          throw new BadRequestException(`Container ${n} is not one of this booking's containers`);
-        }
-      }
-      const elsewhere = await this.assignedContainerNumbersExcept(bookingId, assignmentId);
-      for (const n of requested) {
-        if (elsewhere.includes(n)) {
-          throw new ConflictException(`Container ${n} is already loaded onto another truck`);
-        }
-      }
+      assertTruckLoad({
+        containers: requested,
+        bookingContainers: await this.bookingContainerNumbers(bookingId),
+        sizes: await bookingContainerSizes(this.dataSource, bookingId, requested),
+        assignedElsewhere: await this.assignedContainerNumbersExcept(bookingId, assignmentId),
+      });
     }
 
     await this.dataSource.transaction(async (manager) => {
@@ -542,9 +547,17 @@ export class CustomerTruckService {
               first_mile_pickup_address AS "firstMile",
               last_mile_delivery_address AS "lastMile",
               payment_status AS "paymentStatus",
-              status
-         FROM freight.bookings
-        WHERE id = $1 AND deleted_at IS NULL`,
+              b.status,
+              (SELECT ts.status
+                 FROM freight.train_schedule_bookings tsb
+                 JOIN freight.train_schedules ts
+                   ON ts.id = tsb.train_schedule_id AND ts.deleted_at IS NULL
+                WHERE tsb.booking_id = b.id AND tsb.deleted_at IS NULL
+                ORDER BY ts.updated_at DESC
+                LIMIT 1) AS "trainScheduleStatus",
+              ${LAST_MILE_COMMITTED_SQL} AS "lastMileCommitted"
+         FROM freight.bookings b
+        WHERE b.id = $1 AND b.deleted_at IS NULL`,
       [bookingId],
     );
     if (!row) throw new NotFoundException(`Booking ${bookingId} not found`);
@@ -552,10 +565,12 @@ export class CustomerTruckService {
   }
 
   private assertSelfHaulPaid(booking: BookingGuardRow): void {
-    // Shared with the EDR side (LastMileService.assertNoCustomerTruck) so the two
-    // halves of this rule cannot drift apart — they did, and a booking ended up
-    // with a customer truck and an EDR leg at once.
-    if (usesEdrMileService(booking)) {
+    // Mirrors the EDR side (LastMileService.assertEdrHaulsThisBooking) so the
+    // two halves of this rule cannot drift apart — they did, and a booking ended
+    // up with a customer truck and an EDR leg at once. A last-mile leg only
+    // blocks self-haul once it is approved; until then the customer may still
+    // bring their own truck, and doing so makes the pending request unapprovable.
+    if (edrHaulsThisBooking(booking)) {
       throw new BadRequestException(EDR_HAULAGE_CONFLICT_MESSAGE);
     }
     if (booking.paymentStatus !== 'PAID') {
@@ -575,7 +590,7 @@ export class CustomerTruckService {
   private assertAssignmentWindow(booking: BookingGuardRow): void {
     const status = booking.status ?? '';
     if (booking.tradeDirection === 'IMPORT') {
-      if (status !== 'ARRIVED') {
+      if (status !== 'ARRIVED' && booking.trainScheduleStatus !== 'ARRIVED') {
         throw new BadRequestException(
           'Import pickup trucks can only be assigned after the train has arrived',
         );
@@ -626,26 +641,29 @@ export class CustomerTruckService {
 
   /** Contract container sizes (e.g. "20ft" / "40ft") for the given container numbers. */
 
+  /**
+   * Add trucks one at a time, keeping the good ones. Partial success is the
+   * right shape here: one mistyped plate in a twenty-row spreadsheet should not
+   * discard the other nineteen trucks. Every row still goes through `addTruck`,
+   * so no guard is skipped.
+   */
   async addBulkTrucks(
     bookingId: string,
     dtos: AddCustomerTruckDto[],
-  ): Promise<{
-    success: number;
-    failed: number;
-    errors: Array<{ row: number; truck: string; reason: string }>;
-  }> {
-    const errors: Array<{ row: number; truck: string; reason: string }> = [];
+  ): Promise<BulkTruckUploadResult> {
+    const errors: BulkTruckUploadError[] = [];
     let successCount = 0;
 
     for (let i = 0; i < dtos.length; i++) {
       try {
         await this.addTruck(bookingId, dtos[i]);
         successCount++;
-      } catch (err: any) {
+      } catch (err) {
         errors.push({
-          row: i + 2, // Row 1 is header
+          index: i,
+          row: i + 2, // Row 1 is the header
           truck: dtos[i].truckPlateNumber,
-          reason: err.message || 'Unknown error',
+          reason: err instanceof Error ? err.message : 'Unknown error',
         });
       }
     }
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/add-customer-truck.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/add-customer-truck.dto.ts
index 9816b3405..1085f954a 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/add-customer-truck.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/add-customer-truck.dto.ts
@@ -12,7 +12,7 @@ import {
   Min,
 } from 'class-validator';
 
-import { CUSTOMER_TRUCK_TYPES } from './customer-truck-assignment.dto';
+import { CUSTOMER_TRUCK_TYPES, ISO_CONTAINER_NUMBER } from '@edr/types';
 
 /**
  * Add one external customer truck to a booking.
@@ -41,7 +41,7 @@ export class AddCustomerTruckDto {
   @IsArray()
   @ArrayMaxSize(2)
   @ArrayUnique()
-  @Matches(/^[A-Z]{4}\d{7}$/, {
+  @Matches(ISO_CONTAINER_NUMBER, {
     each: true,
     message: 'each container number must match ISO container format, e.g. ABCD1234567',
   })
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/bulk-customer-truck.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/bulk-customer-truck.dto.ts
index 5e03c7bc4..e3249e684 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/bulk-customer-truck.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/bulk-customer-truck.dto.ts
@@ -1,48 +1,41 @@
-import { IsString, IsNotEmpty, IsIn, IsArray, ArrayMaxSize, ArrayUnique, Matches, IsOptional } from 'class-validator';
-import { CUSTOMER_TRUCK_TYPES } from './customer-truck-assignment.dto';
+import { ArrayMaxSize, ArrayMinSize, IsArray, ValidateNested } from 'class-validator';
+import { Type } from 'class-transformer';
 
-export class BulkCustomerTruckRow {
-  @IsString()
-  @IsNotEmpty()
-  truckPlateNumber!: string;
-
-  @IsString()
-  @IsNotEmpty()
-  driverName!: string;
-
-  @IsString()
-  @IsNotEmpty()
-  @IsIn(CUSTOMER_TRUCK_TYPES)
-  truckType!: string;
-
-  @IsOptional()
-  @IsArray()
-  @ArrayMaxSize(2)
-  @ArrayUnique()
-  @Matches(/^[A-Z]{4}\d{7}$/, {
-    each: true,
-    message: 'each container must be ISO format (e.g. ABCD1234567)',
-  })
-  containerNumbers?: (string | null)[];
-}
+import { AddCustomerTruckDto } from './add-customer-truck.dto';
 
+/**
+ * Bulk self-haul truck assignment, parsed from the customer's Excel upload in
+ * the browser and posted as JSON (the house pattern — the API never receives an
+ * .xlsx for import).
+ *
+ * Rows reuse `AddCustomerTruckDto` verbatim rather than redeclaring the fields:
+ * the earlier copy drifted, missing `plannedTons` / `plannedQuantity`, so bulk
+ * cargo could not be uploaded at all.
+ */
 export class BulkCustomerTrucksDto {
   @IsArray()
+  @ArrayMinSize(1)
   @ArrayMaxSize(100)
-  trucks!: BulkCustomerTruckRow[];
+  @ValidateNested({ each: true })
+  @Type(() => AddCustomerTruckDto)
+  trucks!: AddCustomerTruckDto[];
+}
+
+export interface BulkTruckUploadError {
+  /**
+   * Position in the submitted array. The client knows which spreadsheet line it
+   * read each entry from, so it maps this back to the row number the customer
+   * actually sees.
+   */
+  index: number;
+  /** 1-based row assuming a single header line — a fallback for non-Excel callers. */
+  row: number;
+  truck: string;
+  reason: string;
 }
 
 export interface BulkTruckUploadResult {
   success: number;
   failed: number;
-  errors: Array<{
-    row: number;
-    truck: string;
-    reason: string;
-  }>;
-  created: Array<{
-    truckPlateNumber: string;
-    driverName: string;
-    containers: number;
-  }>;
+  errors: BulkTruckUploadError[];
 }
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/customer-truck-assignment.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/customer-truck-assignment.dto.ts
index 9daf7523e..e4655a739 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/customer-truck-assignment.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/customer-truck-assignment.dto.ts
@@ -1,12 +1,12 @@
 import { IsIn, IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
+import { CUSTOMER_TRUCK_TYPES, ISO_CONTAINER_NUMBER } from '@edr/types';
 
-export const CUSTOMER_TRUCK_TYPES = [
-  'Flatbed',
-  'Container Chassis',
-  'Lowboy',
-  'Box Truck',
-  'Tipper',
-] as const;
+/**
+ * Re-exported for the DTOs that already import it from here. The list itself
+ * lives in `@edr/types` so the portal's dropdown and its Excel template read the
+ * same values this validator enforces.
+ */
+export { CUSTOMER_TRUCK_TYPES };
 
 export class CustomerTruckAssignmentDto {
   @IsString()
@@ -27,7 +27,7 @@ export class CustomerTruckAssignmentDto {
   @IsString()
   @IsNotEmpty()
   @MaxLength(16)
-  @Matches(/^[A-Z]{4}\d{7}$/, {
+  @Matches(ISO_CONTAINER_NUMBER, {
     message: 'containerNumberToLoad must match ISO container format, e.g. ABCD1234567',
   })
   containerNumberToLoad!: string;
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/depart-customer-truck.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/depart-customer-truck.dto.ts
index 31ab1b5bd..d3e73267d 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/depart-customer-truck.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/depart-customer-truck.dto.ts
@@ -8,6 +8,7 @@ import {
   Matches,
   Min,
 } from 'class-validator';
+import { ISO_CONTAINER_NUMBER } from '@edr/types';
 
 /**
  * Register an import self-haul truck leaving the port: the containers it actually
@@ -20,7 +21,7 @@ export class DepartCustomerTruckDto {
   @IsArray()
   @ArrayMaxSize(2)
   @ArrayUnique()
-  @Matches(/^[A-Z]{4}\d{7}$/, {
+  @Matches(ISO_CONTAINER_NUMBER, {
     each: true,
     message: 'each container number must match ISO container format, e.g. ABCD1234567',
   })
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/load-customer-truck.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/load-customer-truck.dto.ts
index 1386e5bd4..35a4f7e0e 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/load-customer-truck.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/load-customer-truck.dto.ts
@@ -1,4 +1,5 @@
 import { ArrayMaxSize, ArrayMinSize, ArrayUnique, IsArray, Matches } from 'class-validator';
+import { ISO_CONTAINER_NUMBER } from '@edr/types';
 
 /** Containers loaded onto a truck at Truck_dispatch (after arrival, before it leaves). */
 export class LoadCustomerTruckDto {
@@ -7,7 +8,7 @@ export class LoadCustomerTruckDto {
   // A truck carries at most 2 containers (two 20ft, or one 40ft).
   @ArrayMaxSize(2)
   @ArrayUnique()
-  @Matches(/^[A-Z]{4}\d{7}$/, {
+  @Matches(ISO_CONTAINER_NUMBER, {
     each: true,
     message: 'each container number must match ISO container format, e.g. ABCD1234567',
   })
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/wagon-cancellation.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/wagon-cancellation.dto.ts
index f86c3e4bf..eda4b6386 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/wagon-cancellation.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/wagon-cancellation.dto.ts
@@ -105,6 +105,31 @@ export class RebookContainerLineDto {
   units!: RebookUnitDto[];
 }
 
+/** One edited container unit on the consolidation partner booking. */
+export class PartnerUnitPatchDto {
+  @ApiProperty({ description: 'Id of the partner booking container unit being edited' })
+  @IsUUID()
+  id!: string;
+
+  @ApiPropertyOptional({ description: 'Container number' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  containerNumber?: string;
+
+  @ApiPropertyOptional({ description: 'Seal number' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  sealNumber?: string;
+
+  @ApiPropertyOptional({ description: 'VGM (tons) of the unit' })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  vgmTons?: number;
+}
+
 export class RebookCancelledWagonsDto {
   @ApiProperty({ description: 'Shipment day the credit is rebooked onto (ISO date)' })
   @IsDateString()
@@ -132,6 +157,19 @@ export class RebookCancelledWagonsDto {
   @IsOptional()
   @IsUUID()
   partnerBookingId?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Corrections to the partner booking\'s own container units (number / seal ' +
+      '/ VGM). Only the units listed are touched; sizes and quantities are never ' +
+      'changed. Ignored unless partnerBookingId is set.',
+    type: [PartnerUnitPatchDto],
+  })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => PartnerUnitPatchDto)
+  partnerUnits?: PartnerUnitPatchDto[];
 }
 
 export class FilterWagonCancellationsDto {
@@ -183,6 +221,19 @@ export class CancelRemainingWagonsDto {
   @IsUUID('4')
   scheduleId!: string;
 
+  @ApiPropertyOptional({
+    description:
+      'Cancel only THESE never-loaded wagons (wagon_booking_allocation ids from ' +
+      'GET /bookings/:id/wagons). Omit to cancel the whole unloaded remainder. ' +
+      'Already-loaded wagons are rejected — they are riding.',
+    type: [String],
+  })
+  @IsOptional()
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsUUID('4', { each: true })
+  wagonAllocationIds?: string[];
+
   @ApiProperty({ description: 'Why the remaining wagons are not riding' })
   @IsString()
   @IsNotEmpty()
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
index b86e1c3f3..9cf728a0d 100644
--- a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
+++ b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
@@ -543,6 +543,13 @@ export class Booking extends BaseEntity {
   @Column({ name: 'wagons_required', type: 'numeric', precision: 6, scale: 2, nullable: true })
   wagonsRequired?: number | null;
 
+  // Wagon footprint pinned for cancellation pricing. `wagonsRequired` above is
+  // a LIVE scheduling field that unassign clears; this one is stamped once at
+  // first allocation and never cleared, so a paid booking pulled off a train
+  // can still price its cancellation fee and credit.
+  @Column({ name: 'cancellation_wagons', type: 'numeric', precision: 6, scale: 2, nullable: true })
+  cancellationWagons?: number | null;
+
   @Column({ name: 'scheduling_status', type: 'varchar', length: 30, default: 'NOT_SCHEDULED' })
   schedulingStatus!: string;
 
diff --git a/apps/edr-freight-api/src/modules/chat/chat-bridge.service.spec.ts b/apps/edr-freight-api/src/modules/chat/chat-bridge.service.spec.ts
new file mode 100644
index 000000000..05dc84b29
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/chat-bridge.service.spec.ts
@@ -0,0 +1,78 @@
+import 'reflect-metadata';
+
+import { NotificationType, type NotifyInput } from '@edr/types';
+
+import type { ChatConfig } from '../../config/chat.config';
+import { ChatBridgeService } from './chat-bridge.service';
+import type { MatrixClient } from './matrix.client';
+
+const config: ChatConfig = {
+  enabled: true,
+  baseUrl: 'https://matrix.test',
+  publicBaseUrl: 'https://matrix.test',
+  webUrl: 'https://chat.test',
+  serverName: 'matrix.test',
+  jwtSecret: 'secret',
+  adminToken: 'syt_whatever',
+};
+
+function harness(overrides: Partial<ChatConfig> = {}) {
+  const matrix = {
+    ensureRoom: jest.fn(async (alias: string) => `!${alias}:matrix.test`),
+    sendMessage: jest.fn(
+      async (_roomId: string, _body: string, _html?: string) => undefined,
+    ),
+  };
+  const service = new ChatBridgeService(
+    { ...config, ...overrides },
+    matrix as unknown as MatrixClient,
+  );
+  return { service, matrix };
+}
+
+const notification = (type: NotificationType): NotifyInput =>
+  ({ type, title: 'Booking BK-1', body: 'needs review' }) as unknown as NotifyInput;
+
+describe('ChatBridgeService', () => {
+  it('posts every notification type into #freight-alerts', async () => {
+    // This used to route REQUEST_SUBMITTED and CLEARANCE_REVIEW to a hardcoded
+    // `dept-operation` alias, but the reconcile derives dept aliases from the
+    // IAM position key (`edr_freight_app/opn` shaped), so nothing it created
+    // ever matched. The bridge made its own empty room and posted there, where
+    // no employee was a member.
+    const { service, matrix } = harness();
+
+    for (const type of [
+      NotificationType.REQUEST_SUBMITTED,
+      NotificationType.CLEARANCE_REVIEW,
+      NotificationType.GENERIC,
+    ]) {
+      await service.bridge(notification(type));
+    }
+
+    expect(new Set(matrix.ensureRoom.mock.calls.map(([alias]) => alias))).toEqual(
+      new Set(['freight-alerts']),
+    );
+    expect(matrix.sendMessage).toHaveBeenCalledTimes(3);
+  });
+
+  it('does nothing at all when chat is switched off', async () => {
+    const { service, matrix } = harness({ enabled: false });
+
+    await service.bridge(notification(NotificationType.GENERIC));
+
+    expect(matrix.ensureRoom).not.toHaveBeenCalled();
+    expect(matrix.sendMessage).not.toHaveBeenCalled();
+  });
+
+  it('never lets a chat failure escape into the notification that triggered it', async () => {
+    // Same contract as NotificationInboxService.notify(): bridging is
+    // best-effort and must not roll back the caller's transaction.
+    const { service, matrix } = harness();
+    matrix.ensureRoom.mockRejectedValueOnce(new Error('Matrix POST ... -> 429'));
+
+    await expect(
+      service.bridge(notification(NotificationType.GENERIC)),
+    ).resolves.toBeUndefined();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts b/apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts
index 75bbe9a29..55c98b897 100644
--- a/apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts
+++ b/apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts
@@ -1,28 +1,11 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
 import type { ConfigType } from '@nestjs/config';
-import { NotificationType, type NotifyInput } from '@edr/types';
+import type { NotifyInput } from '@edr/types';
 
 import chatConfig from '../../config/chat.config';
+import { ALERTS_ROOM } from './chat-provisioning.service';
 import { MatrixClient } from './matrix.client';
 
-const FALLBACK_ROOM = { alias: 'freight-alerts', name: 'Freight Alerts' };
-
-/**
- * Best-effort per-type routing to an existing dept room. Anything not listed
- * (including GENERIC) falls through to #freight-alerts — safer than a wrong
- * guess at which department a type belongs to. Extend as real usage shows
- * which types actually want a dept room instead of the shared feed.
- *
- * `name` matters only if this bridge is the very first thing to touch that
- * alias (normally the nightly/on-demand reconcile creates dept rooms first,
- * with the position's real name) — ensureRoom never renames an existing
- * room, so this must match what ChatProvisioningService would have used.
- */
-const ROOM_FOR_TYPE: Partial<Record<NotificationType, { alias: string; name: string }>> = {
-  [NotificationType.REQUEST_SUBMITTED]: { alias: 'dept-operation', name: 'Operation' },
-  [NotificationType.CLEARANCE_REVIEW]: { alias: 'dept-operation', name: 'Operation' },
-};
-
 /**
  * Mirrors BACKOFFICE-audience notifications into chat so staff see them
  * without having the inbox open. Hooked once into
@@ -31,6 +14,15 @@ const ROOM_FOR_TYPE: Partial<Record<NotificationType, { alias: string; name: str
  *
  * Gated on BACKOFFICE only: notify() also serves PORTAL (customer)
  * notifications, which must never land in an internal staff room.
+ *
+ * Everything goes to one room. This used to route REQUEST_SUBMITTED and
+ * CLEARANCE_REVIEW to a hardcoded `dept-operation` alias — but the reconcile
+ * derives dept aliases from the IAM position key, which is `edr_freight_app/opn`
+ * shaped, so `#dept-operation` matched nothing it creates. The bridge quietly
+ * created its own empty room and posted every notification into it, where no
+ * employee was a member. A single room the reconcile actually populates beats
+ * per-type routing that silently misses; add routing back when real usage asks
+ * for it, keyed off the same derivation the reconcile uses.
  */
 @Injectable()
 export class ChatBridgeService {
@@ -46,8 +38,9 @@ export class ChatBridgeService {
     if (!this.config.enabled) return;
 
     try {
-      const room = ROOM_FOR_TYPE[input.type] ?? FALLBACK_ROOM;
-      const roomId = await this.matrix.ensureRoom(room.alias, room.name);
+      // get-or-create as a safety net only: the reconcile creates this room
+      // inside the space and joins every position holder to it.
+      const roomId = await this.matrix.ensureRoom(ALERTS_ROOM.alias, ALERTS_ROOM.name);
       const body = input.link ? `${input.title}\n${input.body}\n${input.link}` : `${input.title}\n${input.body}`;
       const html = `<strong>${escapeHtml(input.title)}</strong><br/>${escapeHtml(input.body)}${
         input.link ? `<br/><a href="${escapeHtml(input.link)}">${escapeHtml(input.link)}</a>` : ''
diff --git a/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.spec.ts b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.spec.ts
new file mode 100644
index 000000000..3b06cc518
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.spec.ts
@@ -0,0 +1,194 @@
+import 'reflect-metadata';
+
+import type { DataSource } from 'typeorm';
+
+import { ChatProvisioningService } from './chat-provisioning.service';
+import type { MatrixClient } from './matrix.client';
+
+const NAA = '03f5eb9e-23a0-4413-8d98-8de4b98b1be2';
+const SUPER_ADMIN = 'f1534714-fa4a-4780-a081-05d4c1f6c25f';
+const BOT = '@edrbot:m.test';
+
+interface Holder {
+  positionKey: string;
+  positionName: string;
+  userId: string;
+  userName: string;
+}
+
+const holder = (
+  userId: string,
+  userName: string,
+  positionKey: string,
+  positionName = positionKey,
+): Holder => ({ positionKey, positionName, userId, userName });
+
+/**
+ * `members` maps a room id to who Matrix currently reports as joined, so a
+ * test can put a leaver in a room and watch what the reconcile does about it.
+ */
+function harness(holders: Holder[], members: Record<string, string[]> = {}) {
+  const matrix = {
+    mxidFor: jest.fn(
+      (userId: string, name: string) => `@${name}.${userId.slice(0, 6)}:m.test`,
+    ),
+    whoami: jest.fn(async () => BOT),
+    ensureUser: jest.fn(async (_mxid: string, _name?: string) => undefined),
+    ensureRoom: jest.fn(
+      async (alias: string, _name?: string, _opts?: unknown) => `!${alias}:m.test`,
+    ),
+    ensureJoined: jest.fn(async (_roomId: string, _mxid: string) => undefined),
+    joinedMembers: jest.fn(async (roomId: string) => members[roomId] ?? [BOT]),
+    kick: jest.fn(async (_roomId: string, _mxid: string, _reason: string) => undefined),
+    lockUser: jest.fn(async (_mxid: string) => undefined),
+  };
+  const dataSource = { query: jest.fn(async () => holders) };
+  const service = new ChatProvisioningService(
+    dataSource as unknown as DataSource,
+    matrix as unknown as MatrixClient,
+  );
+  return { service, matrix, dataSource };
+}
+
+/**
+ * `joinUserRooms` is the only thing standing between a first sign-in and an
+ * empty Element — the reconcile that would otherwise fill the room list runs
+ * nightly.
+ */
+describe('ChatProvisioningService.joinUserRooms', () => {
+  it('creates nothing for a user holding no current position', async () => {
+    // Super Admin on dev: three iam.employees rows, zero employee_positions.
+    // Synapse still auto-registers the account on JWT login, so the only
+    // symptom is a working sign-in into a client with no rooms in it.
+    const { service, matrix } = harness([]);
+
+    await expect(service.joinUserRooms(SUPER_ADMIN, 'Super Admin')).resolves.toBe(0);
+
+    expect(matrix.ensureUser).not.toHaveBeenCalled();
+    expect(matrix.ensureRoom).not.toHaveBeenCalled();
+    expect(matrix.ensureJoined).not.toHaveBeenCalled();
+  });
+
+  it('joins a holder to the space, #general, #freight-alerts and their dept room', async () => {
+    const { service, matrix } = harness([
+      holder(NAA, 'naa', 'edr_freight_app/marketer', 'Marketer'),
+    ]);
+
+    await expect(service.joinUserRooms(NAA, 'naa')).resolves.toBe(4);
+
+    // The account has to exist before the admin join API will touch it — JWT
+    // auto-registration happens after this runs.
+    expect(matrix.ensureUser).toHaveBeenCalledWith('@naa.03f5eb:m.test', 'naa');
+
+    expect(matrix.ensureRoom.mock.calls.map(([alias]) => alias)).toEqual([
+      'edr-freight',
+      'general',
+      'freight-alerts',
+      'dept-edr_freight_app/marketer',
+    ]);
+
+    // The space itself is joined, not only the rooms under it: Element shows a
+    // space in the left rail only to its members, so dropping this scatters
+    // every dept room loose into Home. #freight-alerts is joined here too, or
+    // a new hire sees no bridged notification until the nightly reconcile.
+    expect(matrix.ensureJoined.mock.calls.map(([roomId]) => roomId)).toEqual([
+      '!edr-freight:m.test',
+      '!general:m.test',
+      '!freight-alerts:m.test',
+      '!dept-edr_freight_app/marketer:m.test',
+    ]);
+  });
+
+  it('scopes the position lookup to the one user', async () => {
+    const { service, dataSource } = harness([]);
+    await service.joinUserRooms(NAA, 'naa');
+    // Without the third parameter this would reconcile the whole unit on every
+    // click of "Open EDR Chat".
+    const [sql, params] = dataSource.query.mock.calls[0] as unknown as [
+      string,
+      unknown[],
+    ];
+    expect(sql).toContain('AND e.user_id = $3');
+    expect(params).toEqual(['edr_freight', 'edr_freight_app', NAA]);
+  });
+});
+
+describe('ChatProvisioningService.reconcile', () => {
+  it('aborts instead of emptying every room when the holder query returns nothing', async () => {
+    // Zero holders never means "every employee left at once" — it means the
+    // query failed, the org/unit keys drifted, or a migration is mid-flight.
+    // Acting on it would kick every member of every room and lock every
+    // account, which is exactly the outage this guard exists to prevent.
+    const { service, matrix } = harness([]);
+
+    await expect(service.reconcile()).rejects.toThrow(/no current position holders/i);
+
+    expect(matrix.kick).not.toHaveBeenCalled();
+    expect(matrix.lockUser).not.toHaveBeenCalled();
+  });
+
+  it('locks a departed member rather than deactivating them', async () => {
+    const leaver = '@gone.999999:m.test';
+    const { service, matrix } = harness(
+      [holder(NAA, 'naa', 'marketer', 'Marketer')],
+      {
+        '!edr-freight:m.test': [BOT, '@naa.03f5eb:m.test', leaver],
+        '!general:m.test': [BOT, '@naa.03f5eb:m.test', leaver],
+        '!freight-alerts:m.test': [BOT, '@naa.03f5eb:m.test'],
+        '!dept-marketer:m.test': [BOT, '@naa.03f5eb:m.test'],
+      },
+    );
+
+    const result = await service.reconcile();
+
+    expect(matrix.kick.mock.calls.map(([, mxid]) => mxid)).toEqual([leaver, leaver]);
+    // Locking is reversible; deactivation is not, and on a homeserver with no
+    // password login it cannot be undone at all.
+    expect(matrix.lockUser).toHaveBeenCalledTimes(1);
+    expect(matrix.lockUser).toHaveBeenCalledWith(leaver);
+    expect(result.locked).toBe(1);
+  });
+
+  it('does not lock someone who only moved between positions', async () => {
+    const naaMxid = '@naa.03f5eb:m.test';
+    // naa holds `marketer` now; the room for their old position still lists them.
+    const { service, matrix } = harness(
+      [
+        holder(NAA, 'naa', 'marketer', 'Marketer'),
+        holder('aaa04914-b7ee-47b3-9c63-4324046a26bd', 'nati', 'opn', 'Operation'),
+      ],
+      { '!dept-opn:m.test': [BOT, naaMxid, '@nati.aaa049:m.test'] },
+    );
+
+    const result = await service.reconcile();
+
+    expect(matrix.kick).toHaveBeenCalledWith(
+      '!dept-opn:m.test',
+      naaMxid,
+      expect.any(String),
+    );
+    // Kicked from one room, still current elsewhere — their account stays open.
+    expect(matrix.lockUser).not.toHaveBeenCalled();
+    expect(result.locked).toBe(0);
+  });
+
+  it('refuses to empty a populated room when its desired set is empty', async () => {
+    // Per-room backstop for the paths the unit-level guard above cannot see.
+    const { service, matrix } = harness([holder(NAA, 'naa', 'marketer')], {
+      '!room:m.test': [BOT, '@naa.03f5eb:m.test', '@nati.aaa049:m.test'],
+    });
+
+    const diff = await (
+      service as unknown as {
+        syncMembership: (
+          roomId: string,
+          desired: Set<string>,
+          bot: string,
+        ) => Promise<{ joined: number; kicked: string[] }>;
+      }
+    ).syncMembership('!room:m.test', new Set<string>(), BOT);
+
+    expect(diff).toEqual({ joined: 0, kicked: [] });
+    expect(matrix.kick).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
index b122d8073..102cb071a 100644
--- a/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
+++ b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
@@ -13,6 +13,11 @@ const UNIT_KEY = 'edr_freight_app';
 const SPACE_ALIAS = 'edr-freight';
 const GENERAL_ALIAS = 'general';
 
+/** Where ChatBridgeService mirrors backoffice notifications. Provisioned here,
+ *  with every position holder in it, so bridged messages land somewhere staff
+ *  actually are — the bridge only ever get-or-creates it as a safety net. */
+export const ALERTS_ROOM = { alias: 'freight-alerts', name: 'Freight Alerts' };
+
 interface PositionHolder {
   positionKey: string;
   positionName: string;
@@ -24,7 +29,8 @@ export interface ReconcileResult {
   rooms: number;
   joined: number;
   kicked: number;
-  deactivated: number;
+  /** Departed accounts locked — reversible. See {@link MatrixClient.lockUser}. */
+  locked: number;
 }
 
 /**
@@ -55,7 +61,7 @@ export class ChatProvisioningService {
       const result = await this.reconcile();
       this.logger.log(
         `Chat reconcile: ${result.rooms} room(s), ${result.joined} joined, ` +
-          `${result.kicked} kicked, ${result.deactivated} deactivated`,
+          `${result.kicked} kicked, ${result.locked} locked`,
       );
     } catch (err) {
       // Never throws into the scheduler — chat provisioning must not be able
@@ -113,10 +119,23 @@ export class ChatProvisioningService {
     const spaceId = await this.matrix.ensureRoom(SPACE_ALIAS, 'EDR Freight', {
       isSpace: true,
     });
+    // The space itself, not only the rooms under it: Element lists a space in
+    // the left rail only for members of that space, so skipping this scatters
+    // every dept room loose into Home and the "EDR Freight" grouping never
+    // appears at all.
+    await this.matrix.ensureJoined(spaceId, mxid);
     const generalRoomId = await this.matrix.ensureRoom(GENERAL_ALIAS, 'General', {
       parentSpaceId: spaceId,
     });
     await this.matrix.ensureJoined(generalRoomId, mxid);
+    // Without this a new hire sees no bridged notification until the nightly
+    // reconcile puts them in the alerts room.
+    const alertsRoomId = await this.matrix.ensureRoom(
+      ALERTS_ROOM.alias,
+      ALERTS_ROOM.name,
+      { parentSpaceId: spaceId },
+    );
+    await this.matrix.ensureJoined(alertsRoomId, mxid);
 
     for (const position of positions) {
       const roomId = await this.matrix.ensureRoom(
@@ -127,10 +146,10 @@ export class ChatProvisioningService {
       await this.matrix.ensureJoined(roomId, mxid);
     }
 
-    return positions.length + 1;
+    return positions.length + 3; // space + general + alerts
   }
 
-  /** Force-joins additions, kicks+deactivates users no longer entitled anywhere. */
+  /** Force-joins additions, kicks users no longer entitled to this room. */
   private async syncMembership(
     roomId: string,
     desiredUserIds: Set<string>,
@@ -139,6 +158,19 @@ export class ChatProvisioningService {
     const current = await this.matrix.joinedMembers(roomId);
     const currentSet = new Set(current.filter((id) => id !== botMxid));
 
+    // An empty desired set against a populated room is not "everyone left" —
+    // it is a query that failed, a key that drifted, or a migration caught
+    // mid-flight. Acting on it would clear the room and then lock every
+    // account that was in it. {@link reconcile} guards the same shape at the
+    // unit level; this is the per-room backstop for the paths it cannot see.
+    if (desiredUserIds.size === 0 && currentSet.size > 0) {
+      this.logger.warn(
+        `Refusing to empty room ${roomId}: desired membership is empty while ` +
+          `${currentSet.size} member(s) are joined. Left untouched.`,
+      );
+      return { joined: 0, kicked: [] };
+    }
+
     let joined = 0;
     for (const userId of desiredUserIds) {
       if (!currentSet.has(userId)) {
@@ -160,6 +192,17 @@ export class ChatProvisioningService {
 
   async reconcile(): Promise<ReconcileResult> {
     const holders = await this.currentHolders();
+    // The desired state for the whole unit. Empty means the IAM query failed,
+    // the org/unit keys drifted, or a migration is mid-flight — it never means
+    // every employee left at once. Continuing would kick every member of every
+    // room and lock every account, so refuse the run and keep yesterday's
+    // state, which is wrong at worst by a day.
+    if (holders.length === 0) {
+      throw new Error(
+        `Chat reconcile aborted: no current position holders for ${ORG_KEY}/${UNIT_KEY}. ` +
+          'Refusing to read that as "remove everyone".',
+      );
+    }
     const botMxid = await this.matrix.whoami();
 
     const spaceId = await this.matrix.ensureRoom(SPACE_ALIAS, 'EDR Freight', {
@@ -168,6 +211,11 @@ export class ChatProvisioningService {
     const generalRoomId = await this.matrix.ensureRoom(GENERAL_ALIAS, 'General', {
       parentSpaceId: spaceId,
     });
+    const alertsRoomId = await this.matrix.ensureRoom(
+      ALERTS_ROOM.alias,
+      ALERTS_ROOM.name,
+      { parentSpaceId: spaceId },
+    );
 
     const allUserIds = new Set(
       holders.map((h) => this.matrix.mxidFor(h.userId, h.userName)),
@@ -184,19 +232,32 @@ export class ChatProvisioningService {
       await this.matrix.ensureUser(mxid, h.userName);
     }
 
-    let rooms = 2; // space + general
+    let rooms = 3; // space + general + alerts
     let joined = 0;
     let kicked = 0;
     // A user kicked from anything while holding zero current positions
     // anywhere in the unit (allUserIds spans every position) is a full
-    // leaver, not just moved between positions — deactivate their account.
+    // leaver, not just moved between positions — lock their account.
     const kickedUserIds = new Set<string>();
 
+    // Space membership follows the org tree exactly like room membership —
+    // see the ensureJoined in joinUserRooms for why the space needs joining
+    // at all.
+    const spaceDiff = await this.syncMembership(spaceId, allUserIds, botMxid);
+    joined += spaceDiff.joined;
+    kicked += spaceDiff.kicked.length;
+    spaceDiff.kicked.forEach((uid) => kickedUserIds.add(uid));
+
     const generalDiff = await this.syncMembership(generalRoomId, allUserIds, botMxid);
     joined += generalDiff.joined;
     kicked += generalDiff.kicked.length;
     generalDiff.kicked.forEach((uid) => kickedUserIds.add(uid));
 
+    const alertsDiff = await this.syncMembership(alertsRoomId, allUserIds, botMxid);
+    joined += alertsDiff.joined;
+    kicked += alertsDiff.kicked.length;
+    alertsDiff.kicked.forEach((uid) => kickedUserIds.add(uid));
+
     const byPosition = new Map<string, { name: string; userIds: Set<string> }>();
     for (const h of holders) {
       const entry = byPosition.get(h.positionKey) ?? {
@@ -219,19 +280,19 @@ export class ChatProvisioningService {
       diff.kicked.forEach((uid) => kickedUserIds.add(uid));
     }
 
-    let deactivated = 0;
+    let locked = 0;
     for (const userId of kickedUserIds) {
       if (allUserIds.has(userId)) continue; // moved position, still current elsewhere
       try {
-        await this.matrix.deactivateUser(userId);
-        deactivated += 1;
+        await this.matrix.lockUser(userId);
+        locked += 1;
       } catch (err) {
         this.logger.warn(
-          `Failed to deactivate departed user ${userId}: ${(err as Error).message}`,
+          `Failed to lock departed user ${userId}: ${(err as Error).message}`,
         );
       }
     }
 
-    return { rooms, joined, kicked, deactivated };
+    return { rooms, joined, kicked, locked };
   }
 }
diff --git a/apps/edr-freight-api/src/modules/chat/chat.module.ts b/apps/edr-freight-api/src/modules/chat/chat.module.ts
index 8df827339..db2e9c44c 100644
--- a/apps/edr-freight-api/src/modules/chat/chat.module.ts
+++ b/apps/edr-freight-api/src/modules/chat/chat.module.ts
@@ -11,6 +11,8 @@ import { MatrixClient } from './matrix.client';
   providers: [MatrixClient, ChatSsoService, ChatProvisioningService, ChatBridgeService],
   // ChatBridgeService: consumed by NotificationInboxModule to mirror
   // BACKOFFICE notifications into chat — see notification-inbox.module.ts.
-  exports: [ChatBridgeService],
+  // MatrixClient: HealthModule's readiness probe reports whether
+  // MATRIX_ADMIN_TOKEN really carries server-admin rights.
+  exports: [ChatBridgeService, MatrixClient],
 })
 export class ChatModule {}
diff --git a/apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts b/apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts
index ea5faa978..22cf8afd8 100644
--- a/apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts
+++ b/apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts
@@ -1,4 +1,5 @@
-import { chatLocalpart } from './matrix.client';
+import type { ChatConfig } from '../../config/chat.config';
+import { MatrixClient, chatLocalpart } from './matrix.client';
 
 describe('chatLocalpart', () => {
   it('reads from the name, not the id', () => {
@@ -33,3 +34,180 @@ describe('chatLocalpart', () => {
     }
   });
 });
+
+const config: ChatConfig = {
+  enabled: true,
+  baseUrl: 'https://matrix.test',
+  publicBaseUrl: 'https://matrix.test',
+  webUrl: 'https://chat.test',
+  serverName: 'matrix.test',
+  jwtSecret: 'secret',
+  adminToken: 'syt_whatever',
+};
+
+type FetchFn = typeof globalThis.fetch;
+
+/** Just enough of a Response for {@link MatrixClient}'s fetch wrappers. */
+function response(status: number, body: unknown) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  };
+}
+
+const realFetch: FetchFn = globalThis.fetch;
+const fetchMock = jest.fn();
+
+beforeEach(() => {
+  fetchMock.mockReset();
+  globalThis.fetch = fetchMock as unknown as FetchFn;
+});
+
+afterAll(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('MatrixClient.verifyServerAdmin', () => {
+  it('accepts a token that can actually call the Synapse admin API', async () => {
+    fetchMock
+      .mockResolvedValueOnce(response(200, { user_id: '@edrbot:matrix.test' }))
+      .mockResolvedValueOnce(response(200, { users: [], total: 1 }));
+
+    const check = await new MatrixClient(config).verifyServerAdmin();
+
+    expect(check).toEqual({ ok: true, actingAs: '@edrbot:matrix.test' });
+    // The admin ping is the check. If this ever regresses to whoami alone,
+    // the assertion below is what catches it.
+    expect(String(fetchMock.mock.calls[1][0])).toContain('/_synapse/admin/');
+  });
+
+  it('rejects a valid token that is not a server admin', async () => {
+    // The dev outage, exactly: MATRIX_ADMIN_TOKEN held @super-admin's own
+    // token. whoami answered 200, every /_synapse/admin call answered 403,
+    // ensureUser threw, ChatSsoService swallowed it, and every employee got a
+    // working sign-in into an Element with no rooms in it.
+    fetchMock
+      .mockResolvedValueOnce(
+        response(200, { user_id: '@super-admin.f15347:matrix.test' }),
+      )
+      .mockResolvedValueOnce(
+        response(403, {
+          errcode: 'M_FORBIDDEN',
+          error: 'You are not a server admin',
+        }),
+      );
+
+    const check = await new MatrixClient(config).verifyServerAdmin();
+
+    expect(check.ok).toBe(false);
+    // Naming the account the token belongs to is the whole point — it is what
+    // turns "chat is broken" into "wrong token in the env".
+    expect(check.actingAs).toBe('@super-admin.f15347:matrix.test');
+    expect(check.error).toContain('403');
+  });
+
+  it('rejects a token that is not valid at all', async () => {
+    fetchMock.mockResolvedValueOnce(
+      response(401, { errcode: 'M_UNKNOWN_TOKEN', error: 'Invalid access token' }),
+    );
+
+    const check = await new MatrixClient(config).verifyServerAdmin();
+
+    expect(check.ok).toBe(false);
+    expect(check.actingAs).toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledTimes(1); // no point pinging admin after this
+  });
+});
+
+describe('MatrixClient.ensureUser', () => {
+  it('lifts the lock on a returning employee', async () => {
+    // A previous reconcile locked them as a leaver. Force-joining them back
+    // into rooms while they still cannot log in is a silent half-restore.
+    fetchMock
+      .mockResolvedValueOnce(
+        response(200, { name: '@naa.03f5eb:matrix.test', locked: true }),
+      )
+      .mockResolvedValueOnce(response(200, {}));
+
+    await new MatrixClient(config).ensureUser('@naa.03f5eb:matrix.test', 'naa');
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const [url, init] = fetchMock.mock.calls[1] as [string, { body: string }];
+    expect(String(url)).toContain('/_synapse/admin/v2/users/');
+    expect(JSON.parse(init.body)).toEqual({ locked: false });
+  });
+
+  it('leaves an account that is not locked alone', async () => {
+    fetchMock.mockResolvedValueOnce(
+      response(200, { name: '@naa.03f5eb:matrix.test', locked: false }),
+    );
+
+    await new MatrixClient(config).ensureUser('@naa.03f5eb:matrix.test', 'naa');
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('MatrixClient rate limiting', () => {
+  it('retries a 429 after the delay Synapse asks for', async () => {
+    // The dev outage: a reconcile is a burst of writes, Synapse throttled an
+    // m.space.child PUT, and one un-retried 429 threw the whole run away.
+    fetchMock
+      .mockResolvedValueOnce(response(200, { user_id: '@edrbot:matrix.test' }))
+      .mockResolvedValueOnce(
+        response(429, {
+          errcode: 'M_LIMIT_EXCEEDED',
+          error: 'Too Many Requests',
+          retry_after_ms: 1,
+        }),
+      )
+      .mockResolvedValueOnce(response(200, { users: [] }));
+
+    const check = await new MatrixClient(config).verifyServerAdmin();
+
+    expect(check.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  it('gives up rather than hanging on a homeserver that only ever 429s', async () => {
+    fetchMock.mockResolvedValue(
+      response(429, { errcode: 'M_LIMIT_EXCEEDED', retry_after_ms: 1 }),
+    );
+
+    const check = await new MatrixClient(config).verifyServerAdmin();
+
+    expect(check.ok).toBe(false);
+    expect(check.error).toContain('429');
+  });
+});
+
+describe('MatrixClient.adminCheck', () => {
+  it('does not re-hit Synapse on every readiness probe', async () => {
+    fetchMock
+      .mockResolvedValueOnce(response(200, { user_id: '@edrbot:matrix.test' }))
+      .mockResolvedValueOnce(response(200, { users: [] }));
+
+    const client = new MatrixClient(config);
+    const first = await client.adminCheck();
+    const second = await client.adminCheck();
+
+    expect(second).toBe(first);
+    expect(fetchMock).toHaveBeenCalledTimes(2); // whoami + admin ping, once
+  });
+
+  it('re-checks when forced, so boot never reads a stale verdict', async () => {
+    fetchMock
+      .mockResolvedValueOnce(response(200, { user_id: '@edrbot:matrix.test' }))
+      .mockResolvedValueOnce(response(200, { users: [] }))
+      .mockResolvedValueOnce(response(200, { user_id: '@edrbot:matrix.test' }))
+      .mockResolvedValueOnce(response(200, { users: [] }));
+
+    const client = new MatrixClient(config);
+    await client.adminCheck();
+    await client.adminCheck(true);
+
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/chat/matrix.client.ts b/apps/edr-freight-api/src/modules/chat/matrix.client.ts
index 1cd09ac33..4da85b339 100644
--- a/apps/edr-freight-api/src/modules/chat/matrix.client.ts
+++ b/apps/edr-freight-api/src/modules/chat/matrix.client.ts
@@ -1,4 +1,5 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import type { OnApplicationBootstrap } from '@nestjs/common';
 import type { ConfigType } from '@nestjs/config';
 
 import chatConfig from '../../config/chat.config';
@@ -40,8 +41,27 @@ export function chatLocalpart(userId: string, displayName: string): string {
   return `${slug || 'user'}.${userId.replace(/-/g, '').slice(0, 6)}`;
 }
 
+/** Result of {@link MatrixClient.verifyServerAdmin}. */
+export interface AdminCheck {
+  ok: boolean;
+  /** Who MATRIX_ADMIN_TOKEN belongs to — present whenever the token is valid
+   *  at all, including when it is valid but carries no admin rights. */
+  actingAs?: string;
+  error?: string;
+}
+
 @Injectable()
-export class MatrixClient {
+export class MatrixClient implements OnApplicationBootstrap {
+  private readonly logger = new Logger(MatrixClient.name);
+
+  /** The token is a deploy-time fact and the readiness probe runs every few
+   *  seconds, so {@link adminCheck} memoises for this long. */
+  private static readonly ADMIN_CHECK_TTL_MS = 5 * 60_000;
+  /** Enough to ride out Synapse's limiter; short enough that a genuinely
+   *  wedged homeserver still fails the run rather than hanging it. */
+  private static readonly MAX_RATE_LIMIT_RETRIES = 5;
+  private adminCheckCache?: { at: number; result: AdminCheck };
+
   constructor(
     @Inject(chatConfig.KEY)
     private readonly config: ConfigType<typeof chatConfig>,
@@ -73,13 +93,48 @@ export class MatrixClient {
     return this.config.serverName;
   }
 
+  /** MATRIX_ENABLED — read by the readiness probe to tell "off" from "broken". */
+  get enabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * Synapse answers a burst of writes with 429 + `retry_after_ms`, and a
+   * reconcile is nothing but a burst of writes — one run creates the space,
+   * #general and a room per position, then force-joins every holder into each.
+   * The first run against dev tripped the limiter on an `m.space.child` PUT,
+   * and because nothing retried, that single 429 threw the whole reconcile
+   * away mid-flight. On the sign-in path ChatSsoService swallows the throw, so
+   * the only visible symptom was an empty Element.
+   *
+   * Honour the delay Synapse asks for rather than guessing at one.
+   */
+  private async fetchWithRetry(
+    url: string,
+    init: Parameters<typeof fetch>[1],
+  ): Promise<Awaited<ReturnType<typeof fetch>>> {
+    for (let attempt = 0; ; attempt++) {
+      const res = await fetch(url, init);
+      if (res.status !== 429 || attempt >= MatrixClient.MAX_RATE_LIMIT_RETRIES) {
+        return res;
+      }
+      // Body is discarded either way — this response is being retried.
+      const body = (await res.json().catch(() => ({}))) as {
+        retry_after_ms?: number;
+      };
+      await new Promise((resolve) =>
+        setTimeout(resolve, (Number(body.retry_after_ms) || 1000) + 100),
+      );
+    }
+  }
+
   private async request<T>(
     method: string,
     path: string,
     body?: unknown,
     token: string = this.config.adminToken,
   ): Promise<T> {
-    const res = await fetch(`${this.config.baseUrl}${path}`, {
+    const res = await this.fetchWithRetry(`${this.config.baseUrl}${path}`, {
       method,
       headers: {
         'Content-Type': 'application/json',
@@ -103,7 +158,7 @@ export class MatrixClient {
     path: string,
     body: unknown,
   ): Promise<T> {
-    const res = await fetch(`${this.config.baseUrl}${path}`, {
+    const res = await this.fetchWithRetry(`${this.config.baseUrl}${path}`, {
       method,
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
@@ -123,7 +178,7 @@ export class MatrixClient {
     path: string,
     token?: string,
   ): Promise<T | null> {
-    const res = await fetch(`${this.config.baseUrl}${path}`, {
+    const res = await this.fetchWithRetry(`${this.config.baseUrl}${path}`, {
       method,
       headers: { Authorization: `Bearer ${token ?? this.config.adminToken}` },
     });
@@ -157,6 +212,68 @@ export class MatrixClient {
     return res.user_id;
   }
 
+  /**
+   * Is MATRIX_ADMIN_TOKEN actually a *server admin* token?
+   *
+   * `whoami` cannot answer this: it returns 200 for any valid user token at
+   * all. Dev shipped with MATRIX_ADMIN_TOKEN holding an ordinary staff
+   * account's token — whoami said 200, every `/_synapse/admin/*` call said
+   * 403 "You are not a server admin", `ensureUser` threw, ChatSsoService
+   * swallowed it (by design — a failed room join must not deny anyone a
+   * sign-in link), and every employee got a working sign-in into a client
+   * with no rooms in it. Nothing else in the system noticed.
+   *
+   * So this pings an endpoint only a server admin may call, and reports who
+   * the token belongs to — the one fact that makes the mix-up obvious.
+   */
+  async verifyServerAdmin(): Promise<AdminCheck> {
+    let actingAs: string | undefined;
+    try {
+      actingAs = await this.whoami();
+      await this.request('GET', '/_synapse/admin/v2/users?limit=1');
+      return { ok: true, actingAs };
+    } catch (err) {
+      return { ok: false, actingAs, error: (err as Error).message };
+    }
+  }
+
+  /** {@link verifyServerAdmin}, memoised for {@link ADMIN_CHECK_TTL_MS}. */
+  async adminCheck(force = false): Promise<AdminCheck> {
+    const cached = this.adminCheckCache;
+    if (
+      !force &&
+      cached &&
+      Date.now() - cached.at < MatrixClient.ADMIN_CHECK_TTL_MS
+    ) {
+      return cached.result;
+    }
+    const result = await this.verifyServerAdmin();
+    this.adminCheckCache = { at: Date.now(), result };
+    return result;
+  }
+
+  /**
+   * Fail loud at boot instead of silently on every sign-in. Logged, never
+   * thrown: chat provisioning must not be able to stop the API from starting,
+   * the same contract the reconcile cron and the notification bridge hold to.
+   */
+  async onApplicationBootstrap(): Promise<void> {
+    if (!this.config.enabled) return;
+    const check = await this.adminCheck(true);
+    if (check.ok) {
+      this.logger.log(
+        `MATRIX_ADMIN_TOKEN verified — server admin as ${check.actingAs}`,
+      );
+      return;
+    }
+    this.logger.error(
+      'MATRIX_ADMIN_TOKEN is not a server-admin token' +
+        (check.actingAs ? ` (it belongs to ${check.actingAs})` : '') +
+        `: ${check.error}. Chat provisioning will create no rooms, and every ` +
+        'employee who opens chat will land in an empty Element.',
+    );
+  }
+
   /** Currently-joined user ids for a room (not full member-event state). */
   async joinedMembers(roomId: string): Promise<string[]> {
     const res = await this.request<{ joined: Record<string, unknown> }>(
@@ -249,11 +366,18 @@ export class MatrixClient {
    * ("User not found") on an account that doesn't exist yet.
    */
   async ensureUser(userId: string, displayName?: string): Promise<void> {
-    const existing = await this.requestOrNull<{ name: string }>(
+    const existing = await this.requestOrNull<{ name: string; locked?: boolean }>(
       'GET',
       `/_synapse/admin/v2/users/${encodeURIComponent(userId)}`,
     );
-    if (existing) return;
+    if (existing) {
+      // A returning employee is still locked from the reconcile that saw them
+      // leave. Force-joining them into rooms while they cannot log in is a
+      // silent half-restore, and this is the one call that already knows the
+      // flag — so undo it here rather than making the caller ask again.
+      if (existing.locked) await this.setLocked(userId, false);
+      return;
+    }
     await this.request(
       'PUT',
       `/_synapse/admin/v2/users/${encodeURIComponent(userId)}`,
@@ -293,12 +417,30 @@ export class MatrixClient {
     );
   }
 
-  /** Deactivating (rather than just kicking) a leaver's account revokes all their sessions. */
-  deactivateUser(userId: string): Promise<void> {
+  /**
+   * Lock a departed employee out of chat — reversible, unlike deactivation.
+   *
+   * This used to call `/_synapse/admin/v1/deactivate`. That revokes sessions
+   * the same way but cannot be undone in any useful sense on this deployment:
+   * reactivation wants a password, and `password_config.enabled: false` means
+   * there is none to set. Room memberships do not come back either. One bad
+   * reconcile — a half-applied IAM migration, a renamed org key — would have
+   * destroyed every staff account that way, permanently.
+   *
+   * Locking blocks exactly the same access (Synapse rejects the account's
+   * tokens with M_USER_LOCKED and refuses new logins) and is undone with a
+   * single PUT — see {@link ensureUser}, which lifts it automatically when
+   * someone comes back.
+   */
+  lockUser(userId: string): Promise<void> {
+    return this.setLocked(userId, true);
+  }
+
+  private setLocked(userId: string, locked: boolean): Promise<void> {
     return this.request(
-      'POST',
-      `/_synapse/admin/v1/deactivate/${encodeURIComponent(userId)}`,
-      { erase: false },
+      'PUT',
+      `/_synapse/admin/v2/users/${encodeURIComponent(userId)}`,
+      { locked },
     );
   }
 
diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index 000b0733f..733b6e441 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -57,8 +57,10 @@ import { CompanyInfoResponseDto } from "./dto/company-info-response.dto";
 import {
   AccountInfoResponse,
   ShippingLineInfoResponseDto,
+  TransitAgentInfoResponseDto,
 } from "./dto/account-info-response.dto";
 import { ShippingLineCompaniesService } from "../shipping-lines/shipping-line-companies.service";
+import { TransitAgentsService } from "../transit-agents/transit-agents.service";
 import { UpdateProfileDto } from "./dto/update-profile.dto";
 import { ProfileResponseDto } from "./dto/profile-response.dto";
 import { DashboardSummaryResponseDto } from "./dto/dashboard-summary-response.dto";
@@ -104,6 +106,7 @@ export class CompaniesController {
     private readonly companiesService: CompaniesService,
     private readonly filesService: FilesService,
     private readonly shippingLineCompaniesService: ShippingLineCompaniesService,
+    private readonly transitAgentsService: TransitAgentsService,
   ) { }
 
   /**
@@ -133,10 +136,10 @@ export class CompaniesController {
   async getInfo(
     @CurrentUser() user: CurrentIamUser,
   ): Promise<AccountInfoResponse> {
-    // A shipping line has no company and no external profile, so the customer
-    // lookup below would 404. Checked first, and reported with an explicit
-    // `accountKind` so the portal can skip onboarding for shipping lines
-    // without inferring it from a missing company.
+    // Neither a shipping line nor a transit agent has a company or an external
+    // profile, so the customer lookup below would 404 for both. Checked first,
+    // and reported with an explicit `accountKind` so the portal can skip
+    // onboarding for them without inferring it from a missing company.
     const shippingLine = await this.shippingLineCompaniesService.findByUserId(
       user.id,
     );
@@ -144,6 +147,11 @@ export class CompaniesController {
       return new ShippingLineInfoResponseDto(shippingLine);
     }
 
+    const transitAgent = await this.transitAgentsService.findByUserId(user.id);
+    if (transitAgent) {
+      return new TransitAgentInfoResponseDto(transitAgent);
+    }
+
     const { profile, company } =
       await this.companiesService.getCompanyInfoByUserId(user.id);
     const review = await this.companiesService.getOpenChangeRequestForCompany(
diff --git a/apps/edr-freight-api/src/modules/companies/companies.module.ts b/apps/edr-freight-api/src/modules/companies/companies.module.ts
index 666634cb8..3a3d6c1c4 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.module.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.module.ts
@@ -18,6 +18,7 @@ import { CompanyChangeRequest } from "./entities/company-change-request.entity";
 import { CompanyRevision } from "./entities/company-revision.entity";
 import { Booking } from "../bookings/entities/booking.entity";
 import { ShippingLineCompaniesModule } from "../shipping-lines/shipping-line-companies.module";
+import { TransitAgentsModule } from "../transit-agents/transit-agents.module";
 import { CompanyProfileRepository } from "./company-profile.repository";
 import { CompanyChangeRequestRepository } from "./company-change-request.repository";
 import { CompanyRevisionRepository } from "./company-revision.repository";
@@ -49,6 +50,10 @@ import { VerifaydaModule } from "../verifayda/verifayda.module";
     // shipping-line session, which has no company row to look up. forwardRef
     // because that module imports BillingModule, which imports this one.
     forwardRef(() => ShippingLineCompaniesModule),
+    // `GET /companies/getInfo` resolves a transit-agent session before falling
+    // through to the customer lookup. TransitAgentsModule is a leaf here — it
+    // does not import CompaniesModule — so no forwardRef is needed.
+    TransitAgentsModule,
   ],
   controllers: [CompaniesController],
   providers: [
diff --git a/apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts
index ab680f8f3..9a43e65d4 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts
@@ -1,6 +1,7 @@
 import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
 
 import { ShippingLineCompany } from "../../shipping-lines/entities/shipping-line-company.entity";
+import { TransitAgent } from "../../transit-agents/entities/transit-agent.entity";
 import { CompanyInfoResponseDto } from "./company-info-response.dto";
 
 /**
@@ -9,10 +10,10 @@ import { CompanyInfoResponseDto } from "./company-info-response.dto";
  * The portal keys its onboarding gate off this rather than off "is `company`
  * missing?": a failed or slow company fetch also leaves `company` empty, and
  * treating that as "no onboarding needed" would let customers skip onboarding
- * whenever the request failed. A shipping line is identified positively, and
- * anything else defaults to `customer`.
+ * whenever the request failed. A shipping line and a transit agent are each
+ * identified positively, and anything else defaults to `customer`.
  */
-export type AccountKind = "customer" | "shipping_line";
+export type AccountKind = "customer" | "shipping_line" | "transit_agent";
 
 /** The signed-in shipping line. No company, no profile, no onboarding. */
 export class ShippingLineInfoResponseDto {
@@ -61,6 +62,62 @@ export class ShippingLineInfoResponseDto {
   }
 }
 
+/**
+ * The signed-in transit agent. Like a shipping line: no company, no profile, no
+ * onboarding — but a separate account kind because the two share nothing beyond
+ * that, and the portal shows each a different (much smaller) set of tabs.
+ */
+export class TransitAgentInfoResponseDto {
+  @ApiProperty({ enum: ["transit_agent"] })
+  accountKind: "transit_agent" = "transit_agent";
+
+  @ApiProperty()
+  id: string;
+
+  @ApiProperty()
+  name: string;
+
+  @ApiPropertyOptional()
+  email?: string | null;
+
+  @ApiPropertyOptional()
+  phoneNumber?: string | null;
+
+  @ApiProperty()
+  isActive: boolean;
+
+  @ApiProperty({
+    description: "Start of the agent's validity window (yyyy-MM-dd)",
+  })
+  validFrom: string;
+
+  @ApiProperty({
+    description: "End of the agent's validity window (yyyy-MM-dd)",
+  })
+  validTo: string;
+
+  /** Always null — see {@link ShippingLineInfoResponseDto.company}. */
+  @ApiProperty({ nullable: true })
+  company: null = null;
+
+  @ApiProperty({ nullable: true })
+  profile: null = null;
+
+  @ApiProperty({ nullable: true })
+  review: null = null;
+
+  constructor(entity: TransitAgent) {
+    this.id = entity.id;
+    this.name = entity.name;
+    this.email = entity.email ?? null;
+    this.phoneNumber = entity.phoneNumber ?? null;
+    this.isActive = entity.isActive;
+    this.validFrom = entity.validFrom;
+    this.validTo = entity.validTo;
+  }
+}
+
 export type AccountInfoResponse =
   | (CompanyInfoResponseDto & { accountKind: "customer" })
-  | ShippingLineInfoResponseDto;
+  | ShippingLineInfoResponseDto
+  | TransitAgentInfoResponseDto;
diff --git a/apps/edr-freight-api/src/modules/container-management/containers.service.ts b/apps/edr-freight-api/src/modules/container-management/containers.service.ts
index 2f9d984e6..61cdacd79 100644
--- a/apps/edr-freight-api/src/modules/container-management/containers.service.ts
+++ b/apps/edr-freight-api/src/modules/container-management/containers.service.ts
@@ -8,6 +8,8 @@ import { AssignContainerToWagonDto } from './dto/assign-container-to-wagon.dto';
 import { Container } from './entities/container.entity';
 import { Wagon } from '../wagons/entities/wagon.entity';
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
+import { WagonEventType } from '@edr/types';
+import { WagonHistoryService } from '../wagon-history/wagon-history.service';
 
 @Injectable()
 export class ContainersService {
@@ -19,6 +21,7 @@ export class ContainersService {
     @InjectRepository(ContainerType)
     private readonly containerTypeRepo: Repository<ContainerType>,
     private readonly dataSource: DataSource,
+    private readonly wagonHistory: WagonHistoryService,
   ) {}
 
   async create(dto: CreateContainerDto): Promise<Container> {
@@ -150,7 +153,16 @@ export class ContainersService {
       // Placing a container on a wagon does not make it AVAILABLE. The status enum
       // (AVAILABLE, LOADED, IN_TRANSIT, MAINTENANCE, DAMAGED) has no ASSIGNED/ON_WAGON
       // state, so leave the existing status unchanged rather than forcing AVAILABLE.
-      return containerRepo.save(container);
+      const saved = await containerRepo.save(container);
+      await this.wagonHistory.record(manager, {
+        wagonId: wagon.id,
+        wagonNumber: wagon.wagonNumber,
+        type: WagonEventType.ContainerPlaced,
+        toYardId: wagon.currentYardId ?? null,
+        toValue: container.containerNumber,
+        metadata: { containerId: container.id, position },
+      });
+      return saved;
     });
   }
 
@@ -159,9 +171,23 @@ export class ContainersService {
     if (container.status === 'LOADED') {
       throw new ConflictException('Cannot unassign a loaded container');
     }
+    const previousWagonId = container.wagonId;
+    const previousPosition = container.position ?? null;
     container.wagonId = null;
     container.position = null;
     container.status = 'AVAILABLE';
-    return this.containerRepo.save(container);
+    const saved = await this.containerRepo.save(container);
+    if (previousWagonId) {
+      const wagon = await this.wagonRepo.findOne({ where: { id: previousWagonId } });
+      await this.wagonHistory.record(null, {
+        wagonId: previousWagonId,
+        wagonNumber: wagon?.wagonNumber ?? null,
+        type: WagonEventType.ContainerRemoved,
+        fromYardId: wagon?.currentYardId ?? null,
+        fromValue: container.containerNumber,
+        metadata: { containerId: container.id, position: previousPosition },
+      });
+    }
+    return saved;
   }
 }
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
index 5cee12d3b..faa59e802 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
@@ -43,6 +43,9 @@ function makeService(overrides?: {
     findBookingsWithUnreviewedDocuments: jest
       .fn()
       .mockResolvedValue(new Set<string>()),
+    findBookingsWithRedeemableCredit: jest
+      .fn()
+      .mockResolvedValue(new Map<string, string>()),
   };
   const bookingsService = {
     findById: jest.fn().mockResolvedValue(booking),
@@ -116,6 +119,7 @@ function makeService(overrides?: {
         .fn()
         .mockResolvedValue({ id: 'ta-1', name: 'Ahmed Bourhan' }),
     } as never, // transit agents
+    { ensureAssignment: jest.fn() } as never, // transit assignments
     { findAll: jest.fn().mockResolvedValue([]) } as never, // contracts repository
     { getScopedYardIds: jest.fn().mockResolvedValue(overrides?.yardScope ?? null) } as never, // yard scope
     { record: jest.fn() } as never, // clearanceEvents
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
index b4cead816..5d0943fe6 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
@@ -1,4 +1,4 @@
-import { BadRequestException, Injectable } from '@nestjs/common';
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
 import { In } from 'typeorm';
 import {
   ContractDocPhase,
@@ -30,10 +30,12 @@ import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { GlOperationsService } from './gl-operations.service';
 import { GlExchangeService } from './gl-exchange.service';
 import { TransitAgentsService } from '../transit-agents/transit-agents.service';
+import { TransitAssignmentsService } from '../transit-assignments/transit-assignments.service';
 import { YardScopeService } from '../rule-engine/services/yard-scope.service';
 import { ContractsRepository } from './contracts.repository';
 import { AdviseContractDutyDto } from './dto/phased-clearance.dto';
-import { buildWorkflowFiles, belongsOnDjClearanceQueue, belongsOnEtClearanceQueue, DJ_BOOKING_QUEUE_STATUSES, persistDeclarationUploads, persistDeliveryOrderUploads, persistDraftDeclarationUploads, persistReleaseOrderUploads, persistTransitPermitUploads, PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES } from './phased-clearance.util';
+import { buildWorkflowFiles, belongsOnDjClearanceQueue, belongsOnEtClearanceQueue, DJ_BOOKING_QUEUE_STATUSES, persistDeclarationUploads, persistDeliveryOrderUploads, persistDraftDeclarationUploads, persistReleaseOrderUploads, persistTransitArrivalUploads, persistTransitPermitUploads, PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES, transitArrivalDocumentMatcher } from './phased-clearance.util';
+import type { TransitArrivalDocumentKind } from '@edr/types';
 
 import {
   buildClearanceDocHistory,
@@ -45,6 +47,8 @@ import { clearanceDocumentsOpen } from '../bookings/clearance.util';
 const RO_VESSEL_MIN_DAYS_CODE = 'ro_vessel_min_days';
 
 export interface BookingClearanceView {
+  /** Booking creation stamp — the import DO is timed from it. */
+  bookingCreatedAt?: string | null;
   bookingId: string;
   status: string;
   includesCustoms: boolean;
@@ -176,6 +180,7 @@ export class BookingClearanceService {
     private readonly notifier: BookingLifecycleNotifierService,
     private readonly glExchangeService: GlExchangeService,
     private readonly transitAgentsService: TransitAgentsService,
+    private readonly transitAssignmentsService: TransitAssignmentsService,
     private readonly contractsRepository: ContractsRepository,
     private readonly yardScope: YardScopeService,
     private readonly clearanceEvents: ClearanceEventService,
@@ -365,6 +370,7 @@ export class BookingClearanceService {
     return {
       bookingId,
       status: booking.status,
+      bookingCreatedAt: booking.createdAt ? new Date(booking.createdAt).toISOString() : null,
       includesCustoms,
       inputCode,
       outputCode,
@@ -385,6 +391,7 @@ export class BookingClearanceService {
         status: m.status,
         ownerRegion: m.ownerRegion,
         metadata: (m.metadata ?? null) as Record<string, unknown> | null,
+        triggeredAt: m.triggeredAt ? new Date(m.triggeredAt).toISOString() : null,
         sortOrder: m.sortOrder,
       })),
       nextAction,
@@ -593,6 +600,17 @@ export class BookingClearanceService {
       transitAssigneeName: agent.name,
       transitAssigneeAssignedAt: new Date(),
     } as never);
+
+    // The booking only stores the officer's NAME, which is what the clearance
+    // UI reads. The agent's own portal works off `transit_assignments` rows, so
+    // without this the shipment never reaches the officer's work list — the
+    // desk believes it handed the job over and nothing arrives.
+    await this.transitAssignmentsService.ensureAssignment(
+      bookingId,
+      transitAgentId,
+      userId,
+    );
+
     await this.clearanceEvents.record({
       bookingId,
       action: 'TRANSIT_ASSIGNEE_ASSIGNED',
@@ -1161,6 +1179,83 @@ export class BookingClearanceService {
     return { booking: await this.bookingsService.findById(bookingId), hold: false };
   }
 
+  // ── Transit-agent arrival paperwork (export) ────────────────────────────
+  // Gate pass and Djibouti T1 documents the assigned transit officer files at
+  // Djibouti around train arrival. Append-only sets with per-file removal — see
+  // `persistTransitArrivalUploads`. The clearance view stamps every file with
+  // its upload time, so the portal can measure it against train departure and
+  // arrival without a separate ledger.
+
+  private static readonly TRANSIT_ARRIVAL_LABELS: Record<
+    TransitArrivalDocumentKind,
+    { name: string; uploaded: string; removed: string }
+  > = {
+    gate_pass: {
+      name: 'gate pass',
+      uploaded: 'GATE_PASS_DOCUMENTS_UPLOADED',
+      removed: 'GATE_PASS_DOCUMENT_REMOVED',
+    },
+    djibouti_t1: {
+      name: 'Djibouti T1',
+      uploaded: 'DJIBOUTI_T1_DOCUMENTS_UPLOADED',
+      removed: 'DJIBOUTI_T1_DOCUMENT_REMOVED',
+    },
+  };
+
+  async uploadTransitArrivalDocuments(
+    bookingId: string,
+    kind: TransitArrivalDocumentKind,
+    files: Express.Multer.File[],
+    userId?: string,
+  ): Promise<{ uploaded: number }> {
+    const booking = await this.loadBooking(bookingId);
+    if (booking.tradeDirection !== 'EXPORT') {
+      throw new BadRequestException(
+        'Gate pass and Djibouti T1 documents apply only to export bookings.',
+      );
+    }
+    const labels = BookingClearanceService.TRANSIT_ARRIVAL_LABELS[kind];
+    await persistTransitArrivalUploads(this.filesService, bookingId, kind, files ?? [], userId);
+    await this.clearanceEvents.record({
+      bookingId,
+      action: labels.uploaded,
+      label: `Uploaded ${files.length} ${labels.name} document(s)`,
+      actorId: userId ?? null,
+      metadata: { kind, fileNames: (files ?? []).map((f) => f.originalname) },
+    });
+    return { uploaded: files.length };
+  }
+
+  /**
+   * Remove ONE gate pass / Djibouti T1 file. Only those two code families are
+   * removable here: the route is reachable by the transit agent, and it must
+   * never become a way to delete a declaration or a Release Order.
+   */
+  async removeTransitArrivalDocument(
+    bookingId: string,
+    fileId: string,
+    userId?: string,
+  ): Promise<void> {
+    await this.loadBooking(bookingId);
+    const files = await this.filesService.findByResource(bookingId, 'bookings');
+    const file = files.find((f) => f.id === fileId);
+    const kind = (['gate_pass', 'djibouti_t1'] as const).find((k) =>
+      transitArrivalDocumentMatcher(k)(file?.code),
+    );
+    if (!file || !kind) {
+      throw new NotFoundException('Document not found on this booking.');
+    }
+    await this.filesService.remove(fileId);
+    const labels = BookingClearanceService.TRANSIT_ARRIVAL_LABELS[kind];
+    await this.clearanceEvents.record({
+      bookingId,
+      action: labels.removed,
+      label: `Removed ${labels.name} document ${file.name}`,
+      actorId: userId ?? null,
+      metadata: { kind, fileName: file.name },
+    });
+  }
+
   async requestRoAmendment(
     bookingId: string,
     note?: string,
@@ -1252,6 +1347,17 @@ export class BookingClearanceService {
         .hasDocumentsAwaitingReview = pending.has(b.id);
     }
 
+    // A cancelled booking may still hold a paid-for wagon-cancellation credit.
+    // GL redeems it from this queue, so the row carries the cancellation id the
+    // rebook action needs.
+    const credits = await this.bookingsRepository.findBookingsWithRedeemableCredit(
+      filtered.map((b) => b.id),
+    );
+    for (const b of filtered) {
+      (b as Booking & { rebookableCancellationId?: string | null })
+        .rebookableCancellationId = credits.get(b.id) ?? null;
+    }
+
     const rows = await this.attachContractSummary(filtered);
     return this.narrowToYardScope(rows, user);
   }
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
index 49e77627f..b601e1c3e 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
@@ -183,8 +183,8 @@ describe('ContractBookingService — manual odd-20ft consolidation', () => {
           { quantity: 4, containerType: { sizeFt: 20 } },
         ],
       },
-      // A bare instance has no cargo yet — GL enters it on the split form, so it
-      // stays a candidate.
+      // Cargo not entered yet — its 20ft count is unknown, so it cannot be
+      // shown to fill the wagon and is not offered.
       { id: 'bare', reference: 'BK-BARE', bookingContainers: [] },
     ];
 
@@ -198,7 +198,7 @@ describe('ContractBookingService — manual odd-20ft consolidation', () => {
           rows.filter((row) => {
             void booking;
             const lines = row.bookingContainers ?? [];
-            if (lines.length === 0) return true;
+            if (lines.length === 0) return false;
             const ft20 = lines
               .filter((l) => Number(l.containerType?.sizeFt) === 20)
               .reduce((sum, l) => sum + Number(l.quantity || 0), 0);
@@ -209,8 +209,8 @@ describe('ContractBookingService — manual odd-20ft consolidation', () => {
     });
 
     const candidates = await service.listConsolidationCandidates('c-1', 'b-1');
-    expect(candidates.map((c) => c.reference)).toEqual(['BK-ODD', 'BK-BARE']);
+    expect(candidates.map((c) => c.reference)).toEqual(['BK-ODD']);
     expect(candidates[0].ft20Quantity).toBe(3);
-    expect(candidates[1].hasCargo).toBe(false);
+    expect(candidates[0].hasCargo).toBe(true);
   });
 });
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
index c95eb73b7..c15d20800 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
@@ -31,6 +31,7 @@ import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { ContractNotifierService } from './contract-notifier.service';
 import { GlOperationsService } from './gl-operations.service';
 import { TransitAgentsService } from '../transit-agents/transit-agents.service';
+import { TransitAssignmentsService } from '../transit-assignments/transit-assignments.service';
 import {
   ClearanceMilestone,
   type RiskAssignmentRecord,
@@ -185,6 +186,7 @@ export class ContractClearanceService {
     private readonly glOperationsService: GlOperationsService,
     private readonly notifier: ContractNotifierService,
     private readonly transitAgentsService: TransitAgentsService,
+    private readonly transitAssignmentsService: TransitAssignmentsService,
     private readonly dataSource: DataSource,
   ) {}
 
@@ -480,6 +482,7 @@ export class ContractClearanceService {
         status: m.status,
         ownerRegion: m.ownerRegion,
         metadata: (m.metadata ?? null) as Record<string, unknown> | null,
+        triggeredAt: m.triggeredAt ? new Date(m.triggeredAt).toISOString() : null,
         sortOrder: m.sortOrder,
       })),
       nextAction,
@@ -1230,6 +1233,18 @@ export class ContractClearanceService {
       transitAssigneeAssignedByUserId: userId ?? null,
     });
 
+    // Mirror the name onto the officer's own work list, exactly as the
+    // per-booking path does. Contract-level clearance can be assigned before a
+    // booking exists; in that case there is nothing for the officer to work on
+    // yet, and the booking picks the assignment up when it is created.
+    if (cycle.bookingId) {
+      await this.transitAssignmentsService.ensureAssignment(
+        cycle.bookingId,
+        transitAgentId,
+        userId,
+      );
+    }
+
     const updated = await this.contractsService.findById(contractId);
     this.notifier.transitAssigneeAssigned(updated, agent.name, previous);
     return updated;
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-duty-dispute.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-duty-dispute.spec.ts
index a7bd3cd7d..b35f9d844 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-duty-dispute.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-duty-dispute.spec.ts
@@ -63,6 +63,7 @@ describe('ContractClearanceService — duty dispute', () => {
       {} as never, // glOperationsService
       notifier as never,
       {} as never, // transitAgentsService
+      {} as never, // transitAssignmentsService
       {} as never, // dataSource
     );
     build([
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-notifier.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-notifier.service.ts
index 477724839..10b6afd37 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-notifier.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-notifier.service.ts
@@ -176,6 +176,18 @@ export class ContractNotifierService {
     this.inApp(c, 'Contract suspension lifted', msg);
   }
 
+  /**
+   * Backoffice cancelled the contract. Terminal — the customer is told they may
+   * submit a new contract with the same details if they still need the service.
+   */
+  cancelledByStaff(c: Contract, reason: string): void {
+    const msg =
+      `Your contract ${c.reference} has been cancelled. Reason: ${reason}. ` +
+      `If you still need this service you can submit a new contract request with the same details.`;
+    void this.notifyContact(c, msg, 'CANCELLED');
+    this.inApp(c, 'Contract cancelled', msg);
+  }
+
   /** Customer cancelled their own contract — staff-side record. */
   cancelledByCustomer(c: Contract, reason: string): void {
     this.inAppStaff(
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-pricing.lane-scope.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-pricing.lane-scope.spec.ts
index 96a8a26ac..c535c909e 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-pricing.lane-scope.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-pricing.lane-scope.spec.ts
@@ -120,3 +120,34 @@ describe('contract base freight is priced on the contract lane only', () => {
     ]);
   });
 });
+
+describe('contract base freight ignores shipping-line rates', () => {
+  it("never prices a customer contract off a line's negotiated rate (CTR-2026-00049)", async () => {
+    // Both LIVE on the contract's own lane: the line rate sorted first and won,
+    // so the contract quoted 32 USD/wagon instead of the standard 1690.
+    const breakdown = await service([
+      rate({
+        containerTypeId: CT20,
+        rateValue: 32,
+        rateUnit: 'PER_WAGON',
+        shippingLineCompanyId: 'line-1',
+      }),
+      rate({ containerTypeId: CT20, rateValue: 1690, rateUnit: 'PER_WAGON' }),
+    ]).buildBreakdown(contract({}));
+    expect(breakdown.lineItems).toEqual([
+      expect.objectContaining({ code: 'CONTAINER_20FT', unitPrice: 1690 }),
+    ]);
+  });
+
+  it('blocks when the only rate on the lane belongs to a shipping line', async () => {
+    await expect(
+      service([
+        rate({
+          containerTypeId: CT20,
+          rateValue: 32,
+          shippingLineCompanyId: 'line-1',
+        }),
+      ]).buildBreakdown(contract({})),
+    ).rejects.toThrow(UnprocessableEntityException);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
index 0af09a5f8..04be6460f 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
@@ -85,7 +85,15 @@ export class ContractPricingService {
    * commodity rate) — NO totals or quantities (doc §9.1).
    */
   async buildBreakdown(contract: Contract): Promise<ContractPricingBreakdown> {
-    const liveRates = await this.ratesService.findLiveRates();
+    // Contracts belong to a customer company — there is no shipping-line
+    // contract (no shipping_line_company_id on the entity), so a contract may
+    // only ever price off the standard rates. Without this filter a line's
+    // negotiated rate on the same lane matched first and the contract froze it
+    // for a customer: CTR-2026-00049 quoted a line's 32 USD/wagon 20ft and
+    // 23 USD/container 40ft instead of the standard 1690 / 1676.
+    const liveRates = (await this.ratesService.findLiveRates()).filter(
+      (r) => !r.shippingLineCompanyId,
+    );
     const currency = contract.paymentCurrency;
     const isEtb = currency === 'ETB';
     const usdToEtb = isEtb ? await this.exchangeService.getRate('USD', 'ETB') : 1;
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-staff-cancel.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-staff-cancel.spec.ts
new file mode 100644
index 000000000..06a406bf1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/contracts/contract-staff-cancel.spec.ts
@@ -0,0 +1,113 @@
+import { ContractTransitionService } from './contract-transition.service';
+import type { Contract } from './entities/contract.entity';
+
+/**
+ * Staff cancel is terminal, so the rules that matter are: it needs its own
+ * permission (suspend must NOT imply it), it refuses to strand live shipments,
+ * it works on a suspended contract, and it cannot be applied twice.
+ */
+describe('ContractTransitionService — staff cancel', () => {
+  const contract = (over: Partial<Contract> = {}): Contract =>
+    ({
+      id: 'c-1',
+      reference: 'CTR-2026-00042',
+      companyId: 'co-1',
+      status: 'CONTRACT_ACTIVE',
+      freightType: 'CONTAINER',
+      ...over,
+    }) as Contract;
+
+  let current: Contract;
+  let repo: {
+    update: jest.Mock;
+    createReviewNote: jest.Mock;
+    countActiveBookings: jest.Mock;
+  };
+  let notifier: { cancelledByStaff: jest.Mock };
+  let service: ContractTransitionService;
+
+  const staff = {
+    permissions: [{ key: 'edr_freight_app:contracts:cancel' }],
+  };
+
+  beforeEach(() => {
+    current = contract();
+    repo = {
+      update: jest.fn().mockImplementation((_id: string, patch: object) => {
+        current = { ...current, ...patch } as Contract;
+        return Promise.resolve(current);
+      }),
+      createReviewNote: jest.fn().mockResolvedValue(undefined),
+      countActiveBookings: jest.fn().mockResolvedValue(0),
+    };
+    notifier = { cancelledByStaff: jest.fn() };
+    service = Object.create(
+      ContractTransitionService.prototype,
+    ) as ContractTransitionService;
+    Object.assign(service, {
+      contractsRepository: repo,
+      contractsService: { findById: () => Promise.resolve(current) },
+      notifier,
+    });
+  });
+
+  it('cancels, records the reason as a staff note, and notifies the customer', async () => {
+    await service.cancelByStaff('c-1', 'Duplicate request', 'staff-1', staff as never);
+
+    expect(repo.update).toHaveBeenCalledWith('c-1', {
+      status: 'CANCELLED',
+      statusBeforeSuspension: null,
+    });
+    expect(repo.createReviewNote).toHaveBeenCalledWith(
+      'c-1',
+      'Duplicate request',
+      'CANCELLATION',
+      'staff-1',
+      'STAFF',
+    );
+    expect(notifier.cancelledByStaff).toHaveBeenCalled();
+  });
+
+  it('cancels a suspended contract — freezing it is exactly when staff kill it', async () => {
+    current = contract({
+      status: 'SUSPENDED',
+      statusBeforeSuspension: 'CONTRACT_ACTIVE',
+    } as Partial<Contract>);
+
+    await service.cancelByStaff('c-1', 'Customer withdrew', 'staff-1', staff as never);
+
+    expect(repo.update).toHaveBeenCalledWith('c-1', {
+      status: 'CANCELLED',
+      statusBeforeSuspension: null,
+    });
+  });
+
+  it('refuses while a shipment is still running', async () => {
+    repo.countActiveBookings.mockResolvedValue(2);
+
+    await expect(
+      service.cancelByStaff('c-1', 'Change of plan', 'staff-1', staff as never),
+    ).rejects.toThrow('2 active shipments');
+    expect(repo.update).not.toHaveBeenCalled();
+  });
+
+  it('refuses to cancel an already-terminal contract', async () => {
+    current = contract({ status: 'CANCELLED' });
+
+    await expect(
+      service.cancelByStaff('c-1', 'Again', 'staff-1', staff as never),
+    ).rejects.toThrow(/already cancelled/i);
+    expect(repo.update).not.toHaveBeenCalled();
+  });
+
+  it('rejects a user holding only the suspend key — cancel is a separate permission', async () => {
+    const suspender = {
+      permissions: [{ key: 'edr_freight_app:contracts:suspend' }],
+    };
+
+    await expect(
+      service.cancelByStaff('c-1', 'Not allowed', 'staff-1', suspender as never),
+    ).rejects.toThrow();
+    expect(repo.update).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
index 936176f86..ac400d9d3 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
@@ -1452,6 +1452,54 @@ export class ContractTransitionService {
     return updated;
   }
 
+  /**
+   * Staff cancel — terminal, unlike suspend. The contract is dead; a fresh one
+   * with the same parameters can be submitted afterwards (references are minted
+   * per contract, so nothing about the old row blocks the new one).
+   *
+   * Cancellable from ANY non-terminal status, including SUSPENDED: a frozen
+   * contract is exactly the one staff most often need to kill outright.
+   */
+  async cancelByStaff(
+    contractId: string,
+    reason: string,
+    actorId: string,
+    user?: TCurrentUser | null,
+  ): Promise<Contract> {
+    const contract = await this.contractsService.findById(contractId);
+    assertFreightPermission(user, FREIGHT_PERMS.contracts.cancel);
+    if ((TERMINAL_CONTRACT_STATUSES as readonly string[]).includes(contract.status)) {
+      throw new ConflictException(
+        `Contract is already ${contract.status.toLowerCase().replace(/_/g, ' ')}.`,
+      );
+    }
+
+    // Same guard as the customer path: live shipments must be settled first,
+    // otherwise cancelling the contract orphans cargo already in motion.
+    const active = await this.contractsRepository.countActiveBookings(contractId);
+    if (active > 0) {
+      throw new BadRequestException(
+        `This contract has ${active} active shipment${active === 1 ? '' : 's'}. ` +
+          'Cancel or complete them before cancelling the contract.',
+      );
+    }
+
+    await this.contractsRepository.createReviewNote(
+      contractId,
+      reason,
+      'CANCELLATION',
+      actorId,
+      'STAFF',
+    );
+    await this.contractsRepository.update(contractId, {
+      status: 'CANCELLED',
+      statusBeforeSuspension: null,
+    } as never);
+    const updated = await this.contractsService.findById(contractId);
+    this.notifier.cancelledByStaff(updated, reason);
+    return updated;
+  }
+
   async renew(contractId: string, userId?: string): Promise<Contract> {
     const source = await this.contractsService.findById(contractId);
 
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
index 1dc083934..7cf7a8398 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
@@ -4,6 +4,7 @@ import {
   Delete,
   Get,
   HttpCode,
+  NotFoundException,
   Param,
   ParseUUIDPipe,
   Patch,
@@ -72,6 +73,7 @@ import {
   RequestChangesDto,
   ResumeContractDto,
   SuspendContractDto,
+  CancelContractByStaffDto,
 } from './dto/approve-step.dto';
 import { SignContractDto } from './dto/sign-contract.dto';
 import { ReviewClearanceDocumentDto } from './dto/review-clearance-document.dto';
@@ -552,6 +554,25 @@ export class ContractsController {
     );
   }
 
+  @Post(':id/staff/cancel')
+  @BookingStaff(FREIGHT_PERMS.contracts.cancel)
+  @ApiOperation({
+    summary:
+      'Staff cancel a contract (terminal — a new contract with the same details may be submitted after)',
+  })
+  cancelByStaff(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: CancelContractByStaffDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.transitionService.cancelByStaff(
+      id,
+      dto.reason,
+      resolveAuthUserId(user),
+      user,
+    );
+  }
+
   @Post(':id/approval-steps/:stepId/approve')
   @BookingStaff(FREIGHT_PERMS.contracts.view)
   @ApiOperation({ summary: 'Approve one approval step in sequence' })
@@ -1339,19 +1360,35 @@ export class ContractsController {
     return this.glOperationsService.uploadTransportDocument(bookingId, files ?? []);
   }
 
+  // Also filed by the transit agent assigned to the shipment — T1 is their own
+  // transit paperwork. Any other portal caller is rejected below.
   @Post('bookings/:bookingId/t1-documents')
-  @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @MixedAudience(FREIGHT_PERMS.contracts.clearanceDjActions)
   @UseInterceptors(AnyFilesInterceptor())
   @ApiConsumes('multipart/form-data')
   @ApiOperation({
     summary:
       'GL Djibouti uploads T1 transit documents (multi-file) after wagon allocation; locked once the train departs',
   })
-  uploadT1Documents(
+  async uploadT1Documents(
     @Param('bookingId', ParseUUIDPipe) bookingId: string,
     @UploadedFiles() files: Express.Multer.File[],
+    @CurrentUser() user: TCurrentUser,
   ) {
-    return this.glOperationsService.uploadT1Documents(bookingId, files ?? []);
+    if (
+      !hasFreightPermission(user, FREIGHT_PERMS.contracts.clearanceDjActions) &&
+      !(await this.bookingsService.isTransitAgentForBooking(
+        user?.id,
+        bookingId,
+      ))
+    ) {
+      throw new NotFoundException(`Booking ${bookingId} not found`);
+    }
+    return this.glOperationsService.uploadT1Documents(
+      bookingId,
+      files ?? [],
+      resolveAuthUserId(user),
+    );
   }
 
   @Post('bookings/:bookingId/t1-close')
@@ -1514,6 +1551,8 @@ export class ContractsController {
   @MixedAudience(FREIGHT_PERMS.contracts.view)
   @ApiOperation({ summary: 'List cargo exception/damage reports for a shipment' })
   listIncidents(@Param('bookingId', ParseUUIDPipe) bookingId: string) {
+    // Reads are open to both audiences (a transit agent assigned to the
+    // shipment included); reporting an incident stays staff-only below.
     return this.glOperationsService.listIncidents(bookingId);
   }
 
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.module.ts b/apps/edr-freight-api/src/modules/contracts/contracts.module.ts
index 2a07b02e5..a198a0282 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.module.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.module.ts
@@ -18,6 +18,7 @@ import { BookingsModule } from '../bookings/bookings.module';
 import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.module';
 import { ContractTemplatesModule } from '../contract-templates/contract-templates.module';
 import { TransitAgentsModule } from '../transit-agents/transit-agents.module';
+import { TransitAssignmentsModule } from '../transit-assignments/transit-assignments.module';
 
 import { ContractsController } from './contracts.controller';
 import { ContractsService } from './contracts.service';
@@ -94,6 +95,10 @@ import { ContractDocumentViewModelBuilder } from '../../contracts/contract-docum
     // ContractDocumentViewModelBuilder when rendering contract PDFs.
     ContractTemplatesModule,
     TransitAgentsModule,
+    // Assigning a transit assignee must also land a row in the officer's own
+    // work list. This module is a leaf (it registers Booking as an entity
+    // rather than importing BookingsModule), so no cycle is closed here.
+    TransitAssignmentsModule,
     // BookingsModule provides BookingsRepository/BookingPricingService used by the
     // contract PDF builders (they read a Booking today — see docs/new-doc.md §3.3).
     forwardRef(() => BookingsModule),
diff --git a/apps/edr-freight-api/src/modules/contracts/dto/approve-step.dto.ts b/apps/edr-freight-api/src/modules/contracts/dto/approve-step.dto.ts
index 6aa36b13d..63057978c 100644
--- a/apps/edr-freight-api/src/modules/contracts/dto/approve-step.dto.ts
+++ b/apps/edr-freight-api/src/modules/contracts/dto/approve-step.dto.ts
@@ -51,6 +51,14 @@ export class CancelContractDto {
   reason?: string;
 }
 
+/** Staff cancel is terminal, so the reason is mandatory — it is the audit record. */
+export class CancelContractByStaffDto {
+  @ApiProperty({ description: 'Why the contract is being cancelled — shown to the customer' })
+  @IsString()
+  @MinLength(1)
+  reason!: string;
+}
+
 export class SuspendContractDto {
   @ApiProperty({ description: 'Why the contract is being frozen — shown to the customer' })
   @IsString()
diff --git a/apps/edr-freight-api/src/modules/contracts/final-invoice-approval.spec.ts b/apps/edr-freight-api/src/modules/contracts/final-invoice-approval.spec.ts
index 4875d9e24..25f798e68 100644
--- a/apps/edr-freight-api/src/modules/contracts/final-invoice-approval.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/final-invoice-approval.spec.ts
@@ -50,6 +50,7 @@ describe('GlOperationsService — final invoice approval', () => {
       {} as never, // milestoneService
       billingService as never,
       notifier as never,
+      { record: jest.fn() } as never, // clearanceEvents
     );
   });
 
diff --git a/apps/edr-freight-api/src/modules/contracts/gl-exchange.controller.ts b/apps/edr-freight-api/src/modules/contracts/gl-exchange.controller.ts
index 6ea0dacbe..b387d9370 100644
--- a/apps/edr-freight-api/src/modules/contracts/gl-exchange.controller.ts
+++ b/apps/edr-freight-api/src/modules/contracts/gl-exchange.controller.ts
@@ -4,6 +4,7 @@ import {
   Delete,
   Get,
   HttpCode,
+  NotFoundException,
   Param,
   ParseUUIDPipe,
   Patch,
@@ -17,10 +18,11 @@ import { FileInterceptor } from '@nestjs/platform-express';
 import { ApiBearerAuth, ApiConsumes, ApiOperation, ApiTags } from '@nestjs/swagger';
 
 import { actorLabel } from '../warehouses/current-actor.util';
-import { BookingStaff } from '../../common/booking-guards';
+import { BookingStaff, MixedAudience } from '../../common/booking-guards';
 import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
 import { hasFreightPermission } from '../../common/freight-permission.util';
 import { resolveAuthUserId } from '../../common/resolve-auth-user-id';
+import { BookingsService } from '../bookings/bookings.service';
 
 import {
   GlExchangeService,
@@ -42,37 +44,61 @@ const asBool = (raw: string | boolean | undefined): boolean =>
 @ApiBearerAuth()
 @Controller('gl-exchange')
 export class GlExchangeController {
-  constructor(private readonly exchangeService: GlExchangeService) {}
+  constructor(
+    private readonly exchangeService: GlExchangeService,
+    private readonly bookingsService: BookingsService,
+  ) {}
 
+  // Read opened to the transit agent assigned to the shipment; the POST/PATCH/
+  // DELETE below stay staff-only, so an agent can read the desks' thread but
+  // never post to it.
   @Get(':entityId')
-  @BookingStaff(GL_EXCHANGE_PERMS)
+  @MixedAudience(GL_EXCHANGE_PERMS)
   @ApiOperation({
     summary: 'GL ET ↔ GL DJ shared documents for a booking or contract',
   })
-  list(
+  async list(
     @Param('entityId', ParseUUIDPipe) entityId: string,
     @CurrentUser() user: TCurrentUser,
   ) {
+    const isStaff = GL_EXCHANGE_PERMS.some((p) =>
+      hasFreightPermission(user, p),
+    );
+    if (
+      !isStaff &&
+      !(await this.bookingsService.isTransitAgentForBooking(
+        user?.id,
+        entityId,
+      ))
+    ) {
+      throw new NotFoundException(`Entity ${entityId} not found`);
+    }
     return this.exchangeService.list(entityId, resolveAuthUserId(user));
   }
 
+  // Open to the transit agent assigned to the shipment as well as both desks:
+  // the officer on the ground is often the one holding the scan either desk
+  // needs. Their post is attributed to the TRANSIT side, never to a desk.
   @Post(':entityId')
-  @BookingStaff(GL_EXCHANGE_PERMS)
+  @MixedAudience(GL_EXCHANGE_PERMS)
   @UseInterceptors(FileInterceptor('file'))
   @ApiConsumes('multipart/form-data')
-  @ApiOperation({ summary: 'Share a document with the other GL desk' })
-  upload(
+  @ApiOperation({
+    summary: 'Share a document with the GL desks (either desk, or the assigned transit agent)',
+  })
+  async upload(
     @Param('entityId', ParseUUIDPipe) entityId: string,
     @UploadedFile() file: Express.Multer.File | undefined,
     @Body('title') title: string,
     @Body('visibleToCustomer') visibleToCustomer: string | undefined,
     @CurrentUser() user: TCurrentUser,
   ) {
+    const actor = await this.resolveActor(entityId, user);
     return this.exchangeService.upload(
       entityId,
       file,
       { title, visibleToCustomer: asBool(visibleToCustomer) },
-      this.actor(user),
+      actor,
     );
   }
 
@@ -118,6 +144,36 @@ export class GlExchangeController {
    * is Djibouti; everyone else (GL Ethiopia, and super admins who hold both)
    * posts as Ethiopia.
    */
+  /**
+   * Who is posting, for a route both desks and the assigned transit agent may
+   * call. Staff keep the desk attribution below; a portal caller must be the
+   * agent assigned to this shipment and posts as TRANSIT, so a document is
+   * never credited to a desk that did not send it.
+   */
+  private async resolveActor(
+    entityId: string,
+    user: TCurrentUser,
+  ): Promise<GlExchangeActor> {
+    const isStaff = GL_EXCHANGE_PERMS.some((p) =>
+      hasFreightPermission(user, p),
+    );
+    if (isStaff) return this.actor(user);
+
+    if (
+      !(await this.bookingsService.isTransitAgentForBooking(
+        user?.id,
+        entityId,
+      ))
+    ) {
+      throw new NotFoundException(`Entity ${entityId} not found`);
+    }
+    return {
+      userId: resolveAuthUserId(user),
+      name: actorLabel(user) ?? null,
+      side: 'TRANSIT',
+    };
+  }
+
   private actor(user: TCurrentUser): GlExchangeActor {
     const side: GlExchangeSide =
       !hasFreightPermission(user, FREIGHT_PERMS.contracts.clearanceEtActions) &&
diff --git a/apps/edr-freight-api/src/modules/contracts/gl-exchange.service.ts b/apps/edr-freight-api/src/modules/contracts/gl-exchange.service.ts
index 1b0d88b2a..e76b26efd 100644
--- a/apps/edr-freight-api/src/modules/contracts/gl-exchange.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/gl-exchange.service.ts
@@ -17,7 +17,7 @@ import type { FileRecord } from '../files/entities/file.entity';
  */
 export const GL_EXCHANGE_RESOURCE = 'gl_exchange';
 
-export type GlExchangeSide = 'ET' | 'DJ';
+export type GlExchangeSide = 'ET' | 'DJ' | 'TRANSIT';
 
 export interface GlExchangeActor {
   userId: string;
@@ -180,7 +180,14 @@ export class GlExchangeService {
       // Pre-title rows (none in practice) fall back to the filename so a list
       // never renders a blank row.
       title: record.title ?? record.name,
-      side: record.code === 'DJ' ? 'DJ' : 'ET',
+      // `files.code` carries the poster's side. Anything unrecognised reads as
+      // ET, which is how every pre-TRANSIT row was written.
+      side:
+        record.code === 'DJ'
+          ? 'DJ'
+          : record.code === 'TRANSIT'
+            ? 'TRANSIT'
+            : 'ET',
       visibleToCustomer: record.visibleToCustomer,
       uploadedById: record.uploadedByUserId,
       uploadedByName: record.uploadedByName,
diff --git a/apps/edr-freight-api/src/modules/contracts/gl-operations.service.ts b/apps/edr-freight-api/src/modules/contracts/gl-operations.service.ts
index 6516ff9ce..70b42a9aa 100644
--- a/apps/edr-freight-api/src/modules/contracts/gl-operations.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/gl-operations.service.ts
@@ -12,6 +12,7 @@ import { InvoiceLine } from '../billing/entities/invoice-line.entity';
 import { FilesService } from '../files/files.service';
 import { Booking } from '../bookings/entities/booking.entity';
 import { BookingLifecycleNotifierService } from '../bookings/booking-lifecycle-notifier.service';
+import { ClearanceEventService } from '../bookings/clearance-event.service';
 import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
 import { ImportDjiboutiOperation } from '../train-scheduling/entities/import-djibouti-operation.entity';
 import {
@@ -55,6 +56,7 @@ export class GlOperationsService {
     private readonly milestoneService: ClearanceMilestoneService,
     private readonly billingService: BillingService,
     private readonly notifier: BookingLifecycleNotifierService,
+    private readonly clearanceEvents: ClearanceEventService,
   ) {}
 
   private get bookings() {
@@ -362,13 +364,15 @@ export class GlOperationsService {
   }
 
   /**
-   * GL Djibouti uploads T1 transport documents (multi-file) once the gate pass
-   * is secured on the train schedule (which itself follows wagon allocation).
-   * Replaces the previous batch; locked only once GL Ethiopia closes the T1.
+   * GL Djibouti / the transit agent uploads T1 transport documents (multi-file)
+   * once the train has DEPARTED Djibouti. Replaces the previous batch, so the
+   * batch's file stamps are always the last update; locked only once GL
+   * Ethiopia closes the T1.
    */
   async uploadT1Documents(
     bookingId: string,
     files: Express.Multer.File[],
+    userId?: string,
   ): Promise<{ uploaded: number }> {
     const booking = await this.getBooking(bookingId);
     if (booking.tradeDirection !== 'IMPORT') {
@@ -376,24 +380,24 @@ export class GlOperationsService {
     }
 
     const state = await this.t1State(bookingId);
-    if (!state.wagonAllocated) {
+    if (!state.trainDepartedAt) {
       throw new BadRequestException(
-        'Wagons must be allocated before T1 transport documents can be uploaded.',
-      );
-    }
-    const gatepass = await this.gatepassForBooking(bookingId);
-    if (!gatepass.granted) {
-      throw new BadRequestException(
-        'Secure the Djibouti gate pass on the train schedule before uploading T1 transport documents.',
+        'T1 transport documents can be uploaded once the train has departed.',
       );
     }
     if (state.closed) {
       throw new BadRequestException('T1 has been closed by GL Ethiopia — documents are final.');
     }
-    // Departure no longer locks T1 docs — GL DJ may replace them any time until
-    // GL Ethiopia closes/accepts the T1.
 
     await persistT1TransportUploads(this.filesService, bookingId, files);
+    // History row so the portal can tell a first upload from a replacement.
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'T1_DOCUMENTS_UPLOADED',
+      label: `Uploaded T1 transport documents (${files.length} file(s))`,
+      actorId: userId ?? null,
+      metadata: { fileNames: files.map((f) => f.originalname) },
+    });
     return { uploaded: files.length };
   }
 
diff --git a/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts b/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts
index ab2a2b2d4..05edb9cab 100644
--- a/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts
+++ b/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts
@@ -12,10 +12,17 @@ import {
   isImportTransitPermitFileCode,
   isExportTransportFileCode,
   isT1TransportFileCode,
+  isGatePassFileCode,
+  isDjiboutiT1FileCode,
   exportTransportFileLabel,
   t1TransportFileLabel,
   transitPermitFileLabel,
+  gatePassFileLabel,
+  djiboutiT1FileLabel,
+  GATE_PASS_FILE_PREFIX,
+  DJIBOUTI_T1_FILE_PREFIX,
   type ClearanceWorkflowFile,
+  type TransitArrivalDocumentKind,
 } from '@edr/types';
 
 /** Require at least one declaration file in the upload batch. */
@@ -46,6 +53,7 @@ type DeclarationFileStore = {
     resource: string;
     code: string;
     file: Express.Multer.File;
+    uploadedByUserId?: string | null;
   }): Promise<unknown>;
 };
 
@@ -445,9 +453,88 @@ export const PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES = [
 /** Booking statuses that may appear on the GL Djibouti clearance list (includes post-clearance). */
 export const DJ_BOOKING_QUEUE_STATUSES = PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES;
 
+/** Prefix + matcher + label for each transit-agent arrival document set. */
+const TRANSIT_ARRIVAL_DOCUMENT_SETS: Record<
+  TransitArrivalDocumentKind,
+  { prefix: string; matches: (code: string | null | undefined) => boolean; label: (i?: number) => string }
+> = {
+  gate_pass: { prefix: GATE_PASS_FILE_PREFIX, matches: isGatePassFileCode, label: gatePassFileLabel },
+  djibouti_t1: { prefix: DJIBOUTI_T1_FILE_PREFIX, matches: isDjiboutiT1FileCode, label: djiboutiT1FileLabel },
+};
+
+export function transitArrivalDocumentMatcher(
+  kind: TransitArrivalDocumentKind,
+): (code: string | null | undefined) => boolean {
+  return TRANSIT_ARRIVAL_DOCUMENT_SETS[kind].matches;
+}
+
+/**
+ * APPEND a batch of transit-agent arrival documents (gate pass / Djibouti T1)
+ * to a booking. Unlike the DO/RO persisters this never deletes what is already
+ * there: the officer collects these one at a time as the paperwork comes in,
+ * and each file is removed individually. Codes continue from the highest
+ * existing index so a removed file's slot is never reused.
+ */
+export async function persistTransitArrivalUploads(
+  store: DeclarationFileStore,
+  bookingId: string,
+  kind: TransitArrivalDocumentKind,
+  files: Express.Multer.File[],
+  uploadedByUserId?: string | null,
+): Promise<void> {
+  if (files.length === 0) {
+    throw new BadRequestException('No documents uploaded');
+  }
+  const set = TRANSIT_ARRIVAL_DOCUMENT_SETS[kind];
+  const existing = await store.findByResource(bookingId, 'bookings');
+  const nextIndex =
+    existing
+      .filter((f) => set.matches(f.code))
+      .map((f) => Number.parseInt((f.code ?? '').slice(set.prefix.length), 10))
+      .filter((n) => Number.isFinite(n))
+      .reduce((max, n) => Math.max(max, n + 1), 0);
+
+  await Promise.all(
+    files.map((file, index) =>
+      store.upload({
+        resourceId: bookingId,
+        resource: 'bookings',
+        code: `${set.prefix}${nextIndex + index}`,
+        file: { ...file, fieldname: `${set.prefix}${nextIndex + index}` },
+        uploadedByUserId: uploadedByUserId ?? null,
+      }),
+    ),
+  );
+}
+
+type WorkflowFileInput = {
+  code?: string | null;
+  id: string;
+  name: string;
+  url: string;
+  createdAt?: Date | string | null;
+  updatedAt?: Date | string | null;
+  size?: number | null;
+  mimeType?: string | null;
+};
+
+function toWorkflowFileRef(file: WorkflowFileInput): NonNullable<ClearanceWorkflowFile['file']> {
+  const iso = (v: Date | string | null | undefined) =>
+    v ? new Date(v).toISOString() : null;
+  return {
+    id: file.id,
+    name: file.name,
+    url: file.url,
+    uploadedAt: iso(file.createdAt),
+    updatedAt: iso(file.updatedAt),
+    size: file.size ?? null,
+    mimeType: file.mimeType ?? null,
+  };
+}
+
 /** Build labeled phased-customs file rows from resource files. */
 export function buildWorkflowFiles(
-  files: Array<{ code?: string | null; id: string; name: string; url: string }>,
+  files: WorkflowFileInput[],
   tradeDirection: string,
 ): ClearanceWorkflowFile[] {
   const fileByCode = new Map(
@@ -465,7 +552,7 @@ export function buildWorkflowFiles(
       label: entry.label,
       uploadedBy: entry.uploadedBy,
       category: entry.category,
-      file: { id: file.id, name: file.name, url: file.url },
+      file: toWorkflowFileRef(file),
     });
   }
 
@@ -481,7 +568,7 @@ export function buildWorkflowFiles(
       label: declarationFileLabel(file.code, index),
       uploadedBy: 'gl_et',
       category: 'declaration',
-      file: { id: file.id, name: file.name, url: file.url },
+      file: toWorkflowFileRef(file),
     });
   });
 
@@ -497,7 +584,7 @@ export function buildWorkflowFiles(
       label: draftDeclarationFileLabel(index),
       uploadedBy: 'gl_et',
       category: 'draft_declaration',
-      file: { id: file.id, name: file.name, url: file.url },
+      file: toWorkflowFileRef(file),
     });
   });
 
@@ -514,7 +601,7 @@ export function buildWorkflowFiles(
         label: transitPermitFileLabel(file.code, index),
         uploadedBy: 'gl_et',
         category: 'transit',
-        file: { id: file.id, name: file.name, url: file.url },
+        file: toWorkflowFileRef(file),
       });
     });
 
@@ -530,7 +617,7 @@ export function buildWorkflowFiles(
         label: deliveryOrderFileLabel(file.code, index),
         uploadedBy: 'gl_dj',
         category: 'djibouti',
-        file: { id: file.id, name: file.name, url: file.url },
+        file: toWorkflowFileRef(file),
       });
     });
 
@@ -546,7 +633,7 @@ export function buildWorkflowFiles(
         label: t1TransportFileLabel(file.code, index),
         uploadedBy: 'gl_dj',
         category: 'djibouti',
-        file: { id: file.id, name: file.name, url: file.url },
+        file: toWorkflowFileRef(file),
       });
     });
   }
@@ -564,7 +651,7 @@ export function buildWorkflowFiles(
         label: releaseOrderFileLabel(file.code, index),
         uploadedBy: 'gl_dj',
         category: 'djibouti',
-        file: { id: file.id, name: file.name, url: file.url },
+        file: toWorkflowFileRef(file),
       });
     });
 
@@ -580,9 +667,32 @@ export function buildWorkflowFiles(
         label: exportTransportFileLabel(file.code, index),
         uploadedBy: 'gl_et',
         category: 'transit',
-        file: { id: file.id, name: file.name, url: file.url },
+        file: toWorkflowFileRef(file),
       });
     });
+
+    // Transit-agent arrival paperwork, ordered by slot index (upload order).
+    const byIndex = (prefix: string) => (a: WorkflowFileInput, b: WorkflowFileInput) =>
+      Number.parseInt((a.code ?? '').slice(prefix.length), 10) -
+      Number.parseInt((b.code ?? '').slice(prefix.length), 10);
+
+    for (const kind of ['gate_pass', 'djibouti_t1'] as const) {
+      const set = TRANSIT_ARRIVAL_DOCUMENT_SETS[kind];
+      files
+        .filter((f) => f.code && set.matches(f.code) && !included.has(f.code))
+        .sort(byIndex(set.prefix))
+        .forEach((file, index) => {
+          if (!file.code) return;
+          included.add(file.code);
+          out.push({
+            code: file.code,
+            label: set.label(index),
+            uploadedBy: 'gl_dj',
+            category: 'djibouti',
+            file: toWorkflowFileRef(file),
+          });
+        });
+    }
   }
 
   return out;
diff --git a/apps/edr-freight-api/src/modules/contracts/transit-assignee.spec.ts b/apps/edr-freight-api/src/modules/contracts/transit-assignee.spec.ts
index 58c97619a..0b7de5be3 100644
--- a/apps/edr-freight-api/src/modules/contracts/transit-assignee.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/transit-assignee.spec.ts
@@ -61,6 +61,7 @@ describe('ContractClearanceService — transit assignee', () => {
       {} as never,
       notifier as never,
       transitAgentsService as never,
+      { ensureAssignment: jest.fn() } as never, // transit assignments
       {} as never, // dataSource
     );
   });
diff --git a/apps/edr-freight-api/src/modules/eims/eims-bulk-registration.service.ts b/apps/edr-freight-api/src/modules/eims/eims-bulk-registration.service.ts
index 875349b6a..e8c111b62 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-bulk-registration.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-bulk-registration.service.ts
@@ -134,6 +134,7 @@ export class EimsBulkRegistrationService {
         region: invoice.company?.region,
         zone: invoice.company?.zone,
         woreda: invoice.company?.woreda,
+        kebele: invoice.company?.kebele,
       });
       return { invoice, documentType, relatedDocument, buyerGeo };
     });
diff --git a/apps/edr-freight-api/src/modules/eims/eims-client.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-client.service.spec.ts
new file mode 100644
index 000000000..3d68e180e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-client.service.spec.ts
@@ -0,0 +1,168 @@
+import { HttpService } from "@nestjs/axios";
+import { Logger } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { AxiosError, AxiosHeaders } from "axios";
+import { of, throwError } from "rxjs";
+
+import { EimsConfig } from "../../config/eims.config";
+import { EimsAuthService } from "./eims-auth.service";
+import { EimsClientService } from "./eims-client.service";
+import { EimsSignerService } from "./eims-signer.service";
+import { eimsConfig } from "./eims-test-fixtures";
+
+const API_KEY = "super-secret-apikey";
+const CLIENT_SECRET = "super-secret-value";
+const TOKEN = "access-token-value";
+
+/** Stub signer: the real signing path has its own spec and needs no key material here. */
+const signer = {
+  signRequest: <T>(request: T) => ({ request, signature: "SIGNATURE", certificate: "CERTIFICATE" }),
+} as unknown as EimsSignerService;
+
+const build = (post: jest.Mock, config: EimsConfig = eimsConfig(), token: string = TOKEN) =>
+  new EimsClientService(
+    { post } as unknown as HttpService,
+    { get: () => config } as unknown as ConfigService,
+    {
+      getValidAccessToken: jest.fn().mockResolvedValue(token),
+      invalidate: jest.fn(),
+    } as unknown as EimsAuthService,
+    signer,
+  );
+
+const ok = (data: unknown = { statusCode: 200, body: { Irn: "irn-echoed" } }) =>
+  jest.fn().mockReturnValue(of({ data }));
+
+const axiosErr = (status: number, data: unknown) =>
+  new AxiosError("Request failed", undefined, undefined, undefined, {
+    status,
+    statusText: "",
+    data,
+    headers: new AxiosHeaders(),
+    config: { headers: new AxiosHeaders() },
+  });
+
+/** `post(url, body, config)` — the config argument every assertion below reads. */
+const sentConfig = (post: jest.Mock, call = 0) => post.mock.calls[call][2];
+const sentBody = (post: jest.Mock, call = 0) => post.mock.calls[call][1];
+
+describe("EimsClientService transport", () => {
+  const protectedHeaders = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${TOKEN}`,
+    apikey: API_KEY,
+  };
+
+  it.each([
+    ["verify", "/v1/verify", { irn: "irn-1" }],
+    ["sales receipt", "/v1/receipt/sales", { receipt: "sales" }],
+    ["withholding receipt", "/v1/receipt/withholding", { receipt: "withholding" }],
+    ["cancel", "/v1/cancel", { Irn: "irn-1" }],
+    ["bulk cancel", "/v1/bulkCancel", [{ Irn: "irn-1" }]],
+  ])("authenticates the raw %s endpoint without changing its body", async (_name, path, body) => {
+    const post = ok();
+    await build(post).postBearer(path, body);
+
+    expect(sentConfig(post).headers).toEqual(protectedHeaders);
+    expect(sentBody(post)).toBe(body);
+  });
+
+  it.each([
+    ["invoice", { DocumentDetails: { Type: "INV" } }],
+    ["credit memo", { DocumentDetails: { Type: "CRE" } }],
+    ["debit memo", { DocumentDetails: { Type: "DEB" } }],
+  ])("authenticates and signs a %s registration", async (_name, request) => {
+    const post = ok({ statusCode: 200, body: { irn: "irn-1" } });
+    await build(post).postSigned("/v1/register", request);
+
+    expect(sentConfig(post).headers).toEqual(protectedHeaders);
+    expect(JSON.parse(sentBody(post) as string)).toEqual({
+      request,
+      signature: "SIGNATURE",
+      certificate: "CERTIFICATE",
+    });
+  });
+
+  it("authenticates bulk registration through the same signed path", async () => {
+    const post = ok({ conversationId: "conversation-1", status: 202 });
+    const request = [{ DocumentDetails: { Type: "INV" } }];
+    await build(post).postSigned("/v1/bulkRegister", request);
+
+    expect(sentConfig(post).headers).toEqual(protectedHeaders);
+  });
+
+  it("wraps a signed call in the {request,signature,certificate} envelope", async () => {
+    const post = ok({ statusCode: 200, body: { irn: "irn-1" } });
+    await build(post).postSigned("/v1/register", { Invoice: 1 });
+
+    expect(JSON.parse(sentBody(post) as string)).toEqual({
+      request: { Invoice: 1 },
+      signature: "SIGNATURE",
+      certificate: "CERTIFICATE",
+    });
+  });
+
+  it("leaves an unsigned body verbatim", async () => {
+    const post = ok();
+    await build(post).postBearer("/v1/cancel", { Irn: "irn-1" });
+
+    // Raw object, not the JSON string `toSignedBody` produces.
+    expect(sentBody(post)).toEqual({ Irn: "irn-1" });
+  });
+
+  it("re-authenticates a raw verify call through the one 401 retry without changing its body", async () => {
+    const post = jest
+      .fn()
+      .mockReturnValueOnce(throwError(() => axiosErr(401, { message: "expired" })))
+      .mockReturnValueOnce(of({ data: { statusCode: 200, body: { Irn: "irn-1" } } }));
+
+    await build(post).postBearer("/v1/verify", { irn: "irn-1" });
+
+    expect(post).toHaveBeenCalledTimes(2);
+    expect(sentConfig(post, 1).headers.Authorization).toBe(`Bearer ${TOKEN}`);
+    expect(sentBody(post, 1)).toEqual({ irn: "irn-1" });
+  });
+
+  it("never leaks the api key, bearer token or client secret into a thrown failure", async () => {
+    const logError = jest.spyOn(Logger.prototype, "error").mockImplementation(() => undefined);
+    const post = jest.fn().mockReturnValue(
+      throwError(() =>
+        // A gateway rejection may echo request data; redaction must remove it before logging.
+        axiosErr(400, {
+          message: "GATEWAY ERROR",
+          code: "4001",
+          details: [
+            { field: "certificate", errorMessage: "must not be null" },
+            { field: "signature", errorMessage: "must not be null" },
+            { field: "request", errorMessage: "must not be null" },
+          ],
+          // An echoed request is exactly what redaction has to drop.
+          request: { apikey: API_KEY, clientSecret: CLIENT_SECRET },
+        }),
+      ),
+    );
+
+    const error: Error = await build(post)
+      .postBearer("/v1/verify", { irn: "irn-1" })
+      .then(() => {
+        throw new Error("expected the call to reject");
+      })
+      .catch((err: Error) => err);
+
+    const serialized = JSON.stringify({
+      message: error.message,
+      response: (error as { getResponse?: () => unknown }).getResponse?.(),
+      details: (error as { details?: unknown }).details,
+    });
+    expect(serialized).not.toContain(API_KEY);
+    expect(serialized).not.toContain(CLIENT_SECRET);
+    expect(serialized).not.toContain(TOKEN);
+    const serializedLogs = JSON.stringify(logError.mock.calls);
+    expect(serializedLogs).not.toContain(API_KEY);
+    expect(serializedLogs).not.toContain(CLIENT_SECRET);
+    expect(serializedLogs).not.toContain(TOKEN);
+    // The gateway's own reporting still survives redaction.
+    expect(error.message).toContain("4001");
+    logError.mockRestore();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/eims/eims-client.service.ts b/apps/edr-freight-api/src/modules/eims/eims-client.service.ts
index 610647b1a..4f2455c85 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-client.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-client.service.ts
@@ -8,10 +8,10 @@ import { EimsSignerService, toSignedBody } from "./eims-signer.service";
 import { toEimsApiException } from "./eims.errors";
 
 /**
- * Foundation for EIMS's bearer-authenticated endpoints (`/v1/register`, `/v1/verify`, …).
+ * Foundation for EIMS's authenticated endpoints (`/v1/register`, `/v1/verify`, …).
  *
  * Login is not routed through here: `/auth/login` carries no bearer token and lives in
- * `EimsAuthService`. Nothing calls `postSigned` yet — invoice registration is a later phase.
+ * `EimsAuthService`.
  */
 @Injectable()
 export class EimsClientService {
@@ -29,7 +29,8 @@ export class EimsClientService {
   }
 
   /**
-   * Sign `request`, POST it to `path` with a valid bearer token, and return the parsed response.
+   * Sign `request`, POST it to `path` with the shared protected-endpoint headers, and return the
+   * parsed response.
    * A 401 invalidates the cached token and retries exactly once.
    */
   async postSigned<TRequest, TResponse>(path: string, request: TRequest): Promise<TResponse> {
@@ -37,12 +38,8 @@ export class EimsClientService {
   }
 
   /**
-   * POST `request` verbatim — bearer-authenticated but **not** wrapped in a signed envelope.
-   *
-   * `/v1/verify` is the only endpoint observed to work this way: the supplied collection sends a
-   * raw `{"irn":"…"}` body with no `signature`/`certificate` siblings. Kept as its own entry point
-   * so that if the live gateway turns out to require signing after all, exactly one call site
-   * changes — `postSigned` is already the alternative.
+   * POST `request` verbatim with the shared protected-endpoint headers, but **not** wrapped in a
+   * signed envelope. This is the wire contract for verify, cancel and receipt calls.
    */
   async postBearer<TRequest, TResponse>(path: string, request: TRequest): Promise<TResponse> {
     return this.send<TRequest, TResponse>(path, request, false, false);
@@ -61,7 +58,11 @@ export class EimsClientService {
     try {
       const res = await firstValueFrom(
         this.http.post<TResponse>(`${cfg.baseUrl}${path}`, body, {
-          headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+            apikey: cfg.apiKey,
+          },
           timeout: cfg.httpTimeoutMs,
         }),
       );
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
index 2fb83dc72..030cf2fe5 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
@@ -3,6 +3,7 @@ import { EimsConfig } from "../../config/eims.config";
 import { MorGeoCodes } from "../../config/mor-location.resolver";
 import { EimsSessionContext } from "./eims-auth.service";
 import {
+  EimsLineTax,
   EimsMapperContext,
   EimsMapperLine,
   EimsSellerDetails,
@@ -172,12 +173,35 @@ export interface EimsContextInput {
   relatedDocument?: string | null;
 }
 
+/**
+ * Tax treatment of one charge type: its per-`chargeType` override when one is configured
+ * (validated symmetric in `assertChargeTypeOverrides`), else the single invoice-wide default.
+ *
+ * Exported because the printed tax document has to state the same Tax Code, Excise and Discount
+ * per line that was filed with MoR, and it must be able to do so without a live EIMS session —
+ * `buildEimsContext` needs a system number from an access token, printing does not.
+ */
+export function resolveLineTax(config: EimsConfig, chargeType: string): EimsLineTax {
+  const { invoice } = config;
+  return {
+    code: invoice.taxCodeByChargeType[chargeType] ?? invoice.taxCode,
+    ratePercent:
+      chargeType in invoice.taxRateByChargeType
+        ? Number(invoice.taxRateByChargeType[chargeType])
+        : invoice.taxRatePercent!,
+    exciseTaxValue:
+      chargeType in invoice.exciseByChargeType
+        ? Number(invoice.exciseByChargeType[chargeType])
+        : (invoice.exciseTaxValue ?? 0),
+    discount:
+      chargeType in invoice.discountByChargeType
+        ? Number(invoice.discountByChargeType[chargeType])
+        : 0,
+  };
+}
+
 export function buildEimsContext(config: EimsConfig, input: EimsContextInput): EimsMapperContext {
   const { invoice } = config;
-  // Validated by assertEimsInvoiceConfig; the non-null assertions below are safe after that call.
-  const taxCode = invoice.taxCode;
-  const ratePercent = invoice.taxRatePercent!;
-  const exciseTaxValue = invoice.exciseTaxValue ?? 0;
 
   return {
     systemNumber: input.session.systemNumber,
@@ -191,23 +215,7 @@ export function buildEimsContext(config: EimsConfig, input: EimsContextInput): E
     payment: { mode: invoice.paymentMode, term: invoice.paymentTerm },
     // Per-`chargeType` override when one is configured (validated symmetric in
     // assertChargeTypeOverrides), else the single invoice-wide default.
-    taxForLine: (line: EimsMapperLine) => {
-      const { chargeType } = line;
-      const code = invoice.taxCodeByChargeType[chargeType] ?? taxCode;
-      const rate =
-        chargeType in invoice.taxRateByChargeType
-          ? Number(invoice.taxRateByChargeType[chargeType])
-          : ratePercent;
-      const excise =
-        chargeType in invoice.exciseByChargeType
-          ? Number(invoice.exciseByChargeType[chargeType])
-          : exciseTaxValue;
-      const discount =
-        chargeType in invoice.discountByChargeType
-          ? Number(invoice.discountByChargeType[chargeType])
-          : 0;
-      return { code, ratePercent: rate, exciseTaxValue: excise, discount };
-    },
+    taxForLine: (line: EimsMapperLine) => resolveLineTax(config, line.chargeType),
     natureOfSupplies: invoice.natureOfSupplies,
     unitDefault: invoice.unitDefault,
     incomeWithholdValue: invoice.incomeWithholdValue!,
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
index 69a4d5ffd..34e654e3b 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
@@ -759,16 +759,15 @@ describe("EimsInvoiceRegistrationService staff alerting", () => {
 });
 
 describe("EimsInvoiceRegistrationService.verifyInvoiceWithEims", () => {
-  it("verifies the stored IRN over the unsigned bearer transport", async () => {
+  it("verifies the stored IRN as an unchanged raw body", async () => {
     const db = new FakeDb([invoiceRow({ eimsIrn: IRN })]);
-    const postSigned = jest.fn();
     const postBearer = jest.fn().mockResolvedValue(verifyResponse());
+    const postSigned = jest.fn();
 
     const result = await build(db, postSigned, config(), postBearer).verifyInvoiceWithEims(
       INVOICE_ID,
     );
 
-    // Lowercase `irn`, raw body — not a signed envelope. `postSigned` must stay untouched.
     expect(postBearer).toHaveBeenCalledWith("/v1/verify", { irn: IRN });
     expect(postSigned).not.toHaveBeenCalled();
     expect(result.body).toMatchObject({ Irn: IRN });
@@ -792,6 +791,27 @@ describe("EimsInvoiceRegistrationService.verifyInvoiceWithEims", () => {
     ).rejects.toThrow(/no EIMS IRN to verify/);
     expect(postBearer).not.toHaveBeenCalled();
   });
+
+  it("leaves a filed invoice and the IRN chain untouched when the gateway rejects the verify", async () => {
+    const db = new FakeDb([
+      invoiceRow({ eimsIrn: IRN, eimsStatus: EimsInvoiceStatus.Registered }),
+    ]);
+    const before = { ...db.invoices.get(INVOICE_ID)! };
+    const stateBefore = { ...db.state! };
+    // The live failure this guards: `GATEWAY ERROR code=4001`, a transport fault on a document
+    // that is already registered. Verification is a read — a failed read must never downgrade the
+    // registration or move the counter.
+    const postBearer = jest
+      .fn()
+      .mockRejectedValue(new EimsApiException("SCHEMA_VALIDATION", "GATEWAY ERROR code=4001", 400));
+
+    await expect(
+      build(db, jest.fn(), config(), postBearer).verifyInvoiceWithEims(INVOICE_ID),
+    ).rejects.toThrow(/4001/);
+
+    expect(db.invoices.get(INVOICE_ID)).toEqual(before);
+    expect(db.state).toEqual(stateBefore);
+  });
 });
 
 describe("EimsInvoiceRegistrationService.resolveEimsRegistration", () => {
@@ -886,15 +906,15 @@ describe("EimsInvoiceRegistrationService.resolveEimsRegistration", () => {
 
   it("discards the attempt, leaving the chain where it was", async () => {
     const db = blocked();
-    const postBearer = jest.fn();
+    const postSigned = jest.fn();
 
-    const view = await build(db, jest.fn(), config(), postBearer).resolveEimsRegistration(
+    const view = await build(db, postSigned, config(), jest.fn()).resolveEimsRegistration(
       INVOICE_ID,
       { discard: true },
     );
 
     expect(view).toMatchObject({ eimsStatus: EimsInvoiceStatus.Failed, eimsIrn: null });
-    expect(postBearer).not.toHaveBeenCalled(); // nothing to confirm
+    expect(postSigned).not.toHaveBeenCalled(); // nothing to confirm
     expect(db.state).toMatchObject({
       previousIrn: null,
       inFlightInvoiceId: null,
@@ -908,10 +928,10 @@ describe("EimsInvoiceRegistrationService.resolveEimsRegistration", () => {
       OTHER_INVOICE_ID,
       invoiceRow({ id: OTHER_INVOICE_ID, eimsDocumentNumber: "6" }),
     );
-    const postBearer = jest.fn().mockResolvedValue(verifyResponse());
+    const postSigned = jest.fn().mockResolvedValue(verifyResponse());
 
     await expect(
-      build(db, jest.fn(), config(), postBearer).resolveEimsRegistration(OTHER_INVOICE_ID, {
+      build(db, postSigned, config(), jest.fn()).resolveEimsRegistration(OTHER_INVOICE_ID, {
         irn: IRN,
       }),
     ).rejects.toThrow(/in-flight EIMS submission is invoice/);
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
index d5c987779..246914e1c 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
@@ -126,6 +126,7 @@ export class EimsInvoiceRegistrationService {
       region: invoice.company?.region,
       zone: invoice.company?.zone,
       woreda: invoice.company?.woreda,
+      kebele: invoice.company?.kebele,
     });
 
     // Authenticate before reserving: the source system comes from the token, and the state row is
@@ -213,7 +214,8 @@ export class EimsInvoiceRegistrationService {
    * compared — the supplied collection's own fixture uses different example values on each side,
    * so equality there would assert a property of the mock rather than of the gateway.
    *
-   * Bearer-authenticated but unsigned, via `postBearer` — see that method for why.
+   * Raw, via `postBearer`: verification accepts exactly `{"irn":"…"}` and relies on the shared
+   * transport for the bearer token and API-key header. It must not be signed or wrapped.
    */
   private async queryVerify(irn: string): Promise<EimsVerifyResponse> {
     const response = await this.client.postBearer<EimsVerifyRequest, EimsVerifyResponse>(
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts
index 841bfcc54..0d4a0fd78 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts
@@ -1,8 +1,11 @@
+import { EimsConfig } from "../../config/eims.config";
 import { Invoice } from "../billing/entities/invoice.entity";
 import {
   InvoiceDocumentModel,
+  MorPartyDetails,
   pngDataUrl,
 } from "../billing/documents/invoice-document.service";
+import { buildEimsSeller } from "./eims-invoice-context";
 import { EimsReceipt, EimsReceiptStatus } from "./entities/eims-receipt.entity";
 import { EimsSalesReceiptRequest, EimsWithholdReceiptRequest } from "./eims-receipt.types";
 
@@ -20,7 +23,11 @@ import { EimsSalesReceiptRequest, EimsWithholdReceiptRequest } from "./eims-rece
  * would read as a genuine tax document. Callers (`EimsReceiptService.document`) let this throw
  * surface as a 400 — there is nothing sensible to render instead.
  */
-export function toReceiptDocumentModel(receipt: EimsReceipt, invoice: Invoice): InvoiceDocumentModel {
+export function toReceiptDocumentModel(
+  receipt: EimsReceipt,
+  invoice: Invoice,
+  config?: EimsConfig,
+): InvoiceDocumentModel {
   if (receipt.status !== EimsReceiptStatus.Registered) {
     throw new Error(
       `Receipt ${receipt.receiptNumber} is ${receipt.status}, not REGISTERED — refusing to print an unfiled receipt.`,
@@ -45,6 +52,34 @@ export function toReceiptDocumentModel(receipt: EimsReceipt, invoice: Invoice):
       // if that default changes for an unrelated reason.
       sealText: "EDR PAID",
       extraSummary: [{ label: "Mode of payment", value: req.TransactionDetails.ModeOfPayment }],
+      mor: config?.invoice
+        ? {
+            titleAm: "የገንዘብ መቀበያ ደረሰኝ",
+            titleEn: "Cash Receipt Voucher",
+            saleType: config.invoice.transactionType,
+            systemNumber: req.SourceSystemNumber || config.systemNumber || null,
+            ...parties(config, invoice),
+            payment: {
+              mode: req.TransactionDetails.ModeOfPayment,
+              typeMethod: config.invoice.paymentTerm,
+              receiverName: invoice.company?.name ?? null,
+            },
+            receipt: {
+              rrn: receipt.rrn ?? "",
+              reason: req.Reason,
+              collectedAmount: req.CollectedAmount,
+              // One row per invoice the payment covers — MoR's receipt is invoice-linked, so the
+              // printed voucher has to show which document(s) the money was applied to.
+              invoices: req.Invoices.map((line) => ({
+                irn: line.InvoiceIRN,
+                paymentCoverage: line.PaymentCoverage,
+                totalAmount: line.TotalAmount,
+                remainingAmount: line.RemainingAmount ?? 0,
+                paidAmount: line.InvoicePaidAmount,
+              })),
+            },
+          }
+        : null,
     });
   }
 
@@ -59,9 +94,63 @@ export function toReceiptDocumentModel(receipt: EimsReceipt, invoice: Invoice):
     // wrong here, so this is the one case that MUST override it.
     sealText: "EDR",
     extraSummary: [{ label: "Withholding type", value: req.WithholdDetail.Type }],
+    mor: config?.invoice
+      ? {
+          titleAm: "ከተከፋይ ሒሳብ ላይ ለተቀነሰ ግብር የተሰጠ ደረሰኝ",
+          titleEn: "Withholding tax on payment",
+          ...parties(config, invoice),
+          systemNumber: req.SourceSystemNumber || config.systemNumber || null,
+          withholding: {
+            receiptNumber: receipt.receiptNumber,
+            counter: req.ReceiptCounter,
+            reason: req.Reason,
+            type: req.WithholdDetail.Type,
+            invoiceCurrency: req.InvoiceDetail.Currency,
+            preTaxAmount: req.WithholdDetail.PreTaxAmount,
+            withheldAmount: req.WithholdDetail.WithholdingAmount,
+            systemType: req.SourceSystemType,
+            systemNumber: req.SourceSystemNumber || config.systemNumber || "",
+          },
+        }
+      : null,
   });
 }
 
+/**
+ * `ከ / From` and `ለ / To` for a receipt. On a withholding receipt the seller is the withholding
+ * agent and the buyer the taxpayer, which is the same pair of blocks in the same order — the
+ * layout relabels them, so the mapping does not change.
+ */
+function parties(
+  config: EimsConfig,
+  invoice: Invoice,
+): { seller: MorPartyDetails; buyer: MorPartyDetails } {
+  const seller = buildEimsSeller(config);
+  const company = invoice.company;
+  return {
+    seller: {
+      name: config.invoice.sellerLegalName || seller.LegalName,
+      city: seller.City,
+      subCity: seller.SubCity,
+      woreda: seller.Wereda,
+      kebele: seller.Locality,
+      houseNo: seller.HouseNumber,
+      tin: seller.Tin,
+      vatNumber: seller.VatNumber,
+    },
+    buyer: {
+      name: company?.name ?? "N/A",
+      city: company?.zone ?? null,
+      subCity: company?.zone ?? null,
+      woreda: company?.woreda ?? null,
+      kebele: company?.kebele ?? null,
+      houseNo: company?.houseNo ?? null,
+      tin: company?.tin ?? null,
+      vatNumber: company?.vatNumber ?? null,
+    },
+  };
+}
+
 function build(
   receipt: EimsReceipt,
   invoice: Invoice,
@@ -73,6 +162,7 @@ function build(
     amount: number;
     sealText: string;
     extraSummary: Array<{ label: string; value: string | null }>;
+    mor?: InvoiceDocumentModel["mor"];
   },
 ): InvoiceDocumentModel {
   return {
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
index 55a38480b..99af6ef30 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
@@ -191,6 +191,7 @@ describe("EimsReceiptService.registerSalesReceipt", () => {
 
   it("marks the receipt FAILED on a deterministic rejection and rethrows", async () => {
     const db = new FakeDb([invoiceRow()]);
+    const invoiceBefore = { ...db.invoices.get(INVOICE_ID)! };
     const postBearer = jest
       .fn()
       .mockRejectedValue(new EimsApiException("RULE_VALIDATION", "EIMS receipt failed (406)", 406));
@@ -200,6 +201,7 @@ describe("EimsReceiptService.registerSalesReceipt", () => {
     ).rejects.toBeInstanceOf(EimsApiException);
     const [receipt] = [...db.receipts.values()];
     expect(receipt.status).toBe(EimsReceiptStatus.Failed);
+    expect(db.invoices.get(INVOICE_ID)).toEqual(invoiceBefore);
   });
 
   it("marks the receipt UNKNOWN on an ambiguous failure (never auto-retried)", async () => {
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
index f2de2937c..8c98d0293 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
@@ -196,7 +196,7 @@ export class EimsReceiptService {
 
     let model: ReturnType<typeof toReceiptDocumentModel>;
     try {
-      model = toReceiptDocumentModel(receipt, invoice);
+      model = toReceiptDocumentModel(receipt, invoice, this.cfg);
     } catch (err) {
       // Only the mapper's own refusals (not-yet-registered, missing request body) become a 400 —
       // a genuine PDF-render failure below is left to surface as whatever InvoiceDocumentService
diff --git a/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts b/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts
index 7afe644a1..ca5cb6a30 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts
@@ -116,6 +116,7 @@ export class EimsSellerCacheService implements OnModuleInit {
         region: data.region,
         zone: data.zone,
         woreda: data.woreda,
+        kebele: data.kebele,
       });
       this.cached = {
         // The *legal* entity name, not the licence's trade name that
diff --git a/apps/edr-freight-api/src/modules/empty-return-requests/dto/empty-return-request.dto.ts b/apps/edr-freight-api/src/modules/empty-return-requests/dto/empty-return-request.dto.ts
new file mode 100644
index 000000000..c588a5b03
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/empty-return-requests/dto/empty-return-request.dto.ts
@@ -0,0 +1,87 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  ArrayNotEmpty,
+  ArrayUnique,
+  IsArray,
+  IsDateString,
+  IsNumber,
+  IsOptional,
+  IsPositive,
+  IsString,
+  IsUUID,
+  MaxLength,
+  MinLength,
+} from 'class-validator';
+
+export class CreateEmptyReturnRequestDto {
+  @ApiProperty({ description: 'Booking the empties came in on.' })
+  @IsUUID()
+  bookingId!: string;
+
+  @ApiProperty({
+    type: [String],
+    description:
+      'One container number per empty being returned — the customer types as many as they said they are sending back.',
+    example: ['TEMU1234567', 'MSCU7654321'],
+  })
+  @IsArray()
+  @ArrayNotEmpty()
+  @ArrayUnique()
+  @IsString({ each: true })
+  @MinLength(4, { each: true })
+  @MaxLength(64, { each: true })
+  containerNumbers!: string[];
+}
+
+export class ApproveEmptyReturnRequestDto {
+  @ApiPropertyOptional({
+    description:
+      'Per-container price to bill. Defaults to the route WITH_RETURN rate the quote was built from.',
+  })
+  @IsOptional()
+  @IsNumber()
+  @IsPositive()
+  unitAmount?: number;
+
+  @ApiPropertyOptional({
+    description: 'Currency of `unitAmount`. Defaults to the quote currency (ETB).',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(8)
+  currency?: string;
+}
+
+export class RejectEmptyReturnRequestDto {
+  @ApiProperty({ description: 'Why the request was turned down — shown to the customer.' })
+  @IsString()
+  @MinLength(3)
+  reason!: string;
+}
+
+export class ScheduleEmptyReturnRequestDto {
+  @ApiProperty({
+    description: 'The day the customer will hand the empties over.',
+    example: '2026-09-20',
+  })
+  @IsDateString()
+  returnDate!: string;
+
+  @ApiProperty({ description: 'Plate of the truck bringing the empties back.' })
+  @IsString()
+  @MinLength(2)
+  @MaxLength(32)
+  truckPlateNumber!: string;
+
+  @ApiProperty({ description: 'Driver bringing the empties back.' })
+  @IsString()
+  @MinLength(2)
+  @MaxLength(120)
+  truckDriverName!: string;
+
+  @ApiPropertyOptional({ description: 'Truck type (flatbed, container chassis…).' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(60)
+  truckType?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.controller.ts b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.controller.ts
new file mode 100644
index 000000000..06687253b
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.controller.ts
@@ -0,0 +1,137 @@
+import { Body, Controller, Get, Param, ParseUUIDPipe, Post, Query } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+
+import { CurrentUser } from '@edr/api-common';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+
+import { BookingStaff, MixedAudience, PortalCustomer } from '../../common/booking-guards';
+import { hasFreightPermission } from '../../common/freight-permission.util';
+import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
+import {
+  ApproveEmptyReturnRequestDto,
+  CreateEmptyReturnRequestDto,
+  RejectEmptyReturnRequestDto,
+  ScheduleEmptyReturnRequestDto,
+} from './dto/empty-return-request.dto';
+import { EmptyReturnRequestsService } from './empty-return-requests.service';
+import type { EmptyReturnRequestStatus } from './entities/empty-return-request.entity';
+
+/**
+ * Reading the queue is OR'd with the warehouse-inventory key the rest of the
+ * Imports menu uses, so the staff who already run container returns can open
+ * it while the dedicated key is still being handed out. Approving and
+ * rejecting stay on the review key alone — that one is a commercial decision.
+ */
+const CAN_VIEW = [
+  FREIGHT_PERMS.emptyReturnRequests.view,
+  FREIGHT_PERMS.warehouseInventory.view,
+];
+
+@ApiTags('empty-return-requests')
+@ApiBearerAuth()
+@Controller('empty-return-requests')
+export class EmptyReturnRequestsController {
+  constructor(private readonly service: EmptyReturnRequestsService) {}
+
+  @Get()
+  @BookingStaff(CAN_VIEW)
+  @ApiOperation({ summary: 'Empty container return requests queue' })
+  findAll(@Query('status') status?: string, @Query('bookingId') bookingId?: string) {
+    return this.service.findAll({
+      status: status as EmptyReturnRequestStatus | undefined,
+      bookingId,
+    });
+  }
+
+  @Get('planned')
+  @BookingStaff(FREIGHT_PERMS.warehouseInventory.view)
+  @ApiOperation({
+    summary: 'Scheduled empty returns the warehouse is expecting, with date and truck',
+  })
+  planned() {
+    return this.service.plannedReturns();
+  }
+
+  @Get('eligibility/:bookingId')
+  @MixedAudience(CAN_VIEW)
+  @ApiOperation({
+    summary:
+      'Whether a booking may request an empty return, its free containers, and the price per container',
+  })
+  eligibility(
+    @Param('bookingId', ParseUUIDPipe) bookingId: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.eligibility(bookingId, this.portalUserId(user));
+  }
+
+  @Get('by-booking/:bookingId')
+  @MixedAudience(CAN_VIEW)
+  @ApiOperation({ summary: "A booking's empty return requests, newest first" })
+  findForBooking(@Param('bookingId', ParseUUIDPipe) bookingId: string) {
+    return this.service.findForBooking(bookingId);
+  }
+
+  @Get(':id')
+  @MixedAudience(CAN_VIEW)
+  @ApiOperation({ summary: 'Get an empty return request by ID' })
+  findOne(@Param('id', ParseUUIDPipe) id: string, @CurrentUser() user: TCurrentUser) {
+    return this.service.findById(id, this.portalUserId(user));
+  }
+
+  @Post()
+  @PortalCustomer()
+  @ApiOperation({
+    summary: 'Customer requests to return empty containers on a booking sold without return',
+  })
+  create(@Body() dto: CreateEmptyReturnRequestDto, @CurrentUser() user: TCurrentUser) {
+    return this.service.create(dto, user?.id ?? null);
+  }
+
+  @Post(':id/schedule')
+  @PortalCustomer()
+  @ApiOperation({
+    summary: 'Customer sets the return date and the truck bringing the empties back',
+  })
+  schedule(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: ScheduleEmptyReturnRequestDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.schedule(id, user?.id ?? null, dto);
+  }
+
+  @Post(':id/approve')
+  @BookingStaff(FREIGHT_PERMS.emptyReturnRequests.review)
+  @ApiOperation({
+    summary:
+      'Approve and bill the request — the price defaults to the route WITH_RETURN rate per container',
+  })
+  approve(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: ApproveEmptyReturnRequestDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.approve(id, user?.id ?? null, dto);
+  }
+
+  @Post(':id/reject')
+  @BookingStaff(FREIGHT_PERMS.emptyReturnRequests.review)
+  @ApiOperation({ summary: 'Reject the request with a reason shown to the customer' })
+  reject(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: RejectEmptyReturnRequestDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.reject(id, user?.id ?? null, dto);
+  }
+
+  /**
+   * Staff read any booking's request; a customer is held to their own. Passing
+   * the user id is what turns the ownership check on, so staff pass null.
+   */
+  private portalUserId(user: TCurrentUser): string | null {
+    if (hasFreightPermission(user, FREIGHT_PERMS.emptyReturnRequests.review)) return null;
+    return user?.id ?? null;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.module.ts b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.module.ts
new file mode 100644
index 000000000..f682f80e5
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.module.ts
@@ -0,0 +1,27 @@
+import { Module, forwardRef } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { registerExchangeModule } from '../exchange-settings/exchange-module-options';
+import { BillingModule } from '../billing/billing.module';
+import { BookingsModule } from '../bookings/bookings.module';
+import { NotificationInboxModule } from '../notification-inbox/notification-inbox.module';
+import { RuleEngineModule } from '../rule-engine/rule-engine.module';
+import { EmptyReturnRequest } from './entities/empty-return-request.entity';
+import { EmptyReturnRequestsController } from './empty-return-requests.controller';
+import { EmptyReturnRequestsRepository } from './empty-return-requests.repository';
+import { EmptyReturnRequestsService } from './empty-return-requests.service';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([EmptyReturnRequest]),
+    BillingModule,
+    forwardRef(() => BookingsModule),
+    NotificationInboxModule,
+    RuleEngineModule,
+    registerExchangeModule(),
+  ],
+  controllers: [EmptyReturnRequestsController],
+  providers: [EmptyReturnRequestsRepository, EmptyReturnRequestsService],
+  exports: [EmptyReturnRequestsService],
+})
+export class EmptyReturnRequestsModule {}
diff --git a/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.repository.ts b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.repository.ts
new file mode 100644
index 000000000..067c869ff
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.repository.ts
@@ -0,0 +1,16 @@
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { BaseRepository } from '@edr/api-common';
+
+import { EmptyReturnRequest } from './entities/empty-return-request.entity';
+
+@Injectable()
+export class EmptyReturnRequestsRepository extends BaseRepository<EmptyReturnRequest> {
+  constructor(
+    @InjectRepository(EmptyReturnRequest)
+    repository: Repository<EmptyReturnRequest>,
+  ) {
+    super(repository);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.service.spec.ts b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.service.spec.ts
new file mode 100644
index 000000000..5b358b7aa
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.service.spec.ts
@@ -0,0 +1,413 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { EmptyReturnRequestsService } from './empty-return-requests.service';
+import type { EmptyReturnRequest } from './entities/empty-return-request.entity';
+
+/**
+ * The service is mostly gates and pricing over raw SQL, so the SQL is stubbed
+ * by matching a distinctive fragment of each statement. Every stub returns the
+ * shape the real query returns.
+ */
+type QueryStub = Array<[string, unknown]>;
+
+const booking = {
+  id: 'b1',
+  reference: 'BK-2026-000300',
+  companyId: 'co1',
+  companyProfileId: 'cp1',
+  status: 'ARRIVED',
+  freightType: 'CONTAINER',
+  equipmentReturn: 'WITHOUT_RETURN',
+  tradeDirection: 'IMPORT',
+  originYardId: 'y-dj',
+  destinationYardId: 'y-mojo',
+  paymentCurrency: 'ETB',
+};
+
+function build(
+  overrides: {
+    booking?: Partial<typeof booking>;
+    request?: Partial<EmptyReturnRequest>;
+    rates?: unknown[];
+    queries?: QueryStub;
+  } = {},
+) {
+  const merged = { ...booking, ...overrides.booking };
+
+  const requestRow: EmptyReturnRequest = {
+    id: 'r1',
+    bookingId: merged.id,
+    companyId: merged.companyId,
+    status: 'SUBMITTED',
+    containerNumbers: ['TEMU1111111', 'TEMU2222222', 'TEMU3333333'],
+    containerCount: 3,
+    submittedAt: new Date(),
+    ...overrides.request,
+  } as EmptyReturnRequest;
+
+  const stubs: QueryStub = [
+    ['FROM freight.booking_container\n', [{ containerTypeId: 'ct-40' }]],
+    [
+      'upper(bcu.container_number)',
+      [{ containerNumber: 'TEMU1111111' }, { containerNumber: 'TEMU2222222' }],
+    ],
+    ['COALESCE(SUM(quantity), 0)', [{ quantity: '5' }]],
+    ['unnest(r.container_numbers)', []],
+    ['COUNT(*) AS outstanding', [{ outstanding: '0' }]],
+    ...(overrides.queries ?? []),
+  ];
+
+  const query = jest.fn(async (sql: string) => {
+    // Later stubs win, so a test can override one of the defaults.
+    for (let i = stubs.length - 1; i >= 0; i -= 1) {
+      if (sql.includes(stubs[i][0])) return stubs[i][1];
+    }
+    return [];
+  });
+
+  const requests = {
+    findById: jest.fn(async () => requestRow),
+    findAll: jest.fn(async () => [requestRow]),
+    create: jest.fn(async (data: Partial<EmptyReturnRequest>) => ({ ...requestRow, ...data })),
+    update: jest.fn(async () => requestRow),
+  };
+  const bookingsService = {
+    findById: jest.fn(async () => merged),
+    assertCustomerCanAccessBooking: jest.fn(async () => undefined),
+  };
+  const billing = { generateInvoice: jest.fn(async () => ({ id: 'inv1' })) };
+  const notifications = { notify: jest.fn(async () => undefined) };
+  const ratesService = {
+    findLiveRatesDetailed: jest.fn(
+      async () =>
+        overrides.rates ?? [
+          {
+            trigger: 'WITH_RETURN',
+            currency: 'USD',
+            tradeDirection: 'IMPORT',
+            originYardId: 'y-dj',
+            destinationYardId: 'y-mojo',
+            containerTypeId: 'ct-40',
+            rateValue: '100',
+          },
+        ],
+    ),
+  };
+  const exchange = { getRate: jest.fn(async () => 120) };
+
+  const service = new EmptyReturnRequestsService(
+    requests as never,
+    { findById: jest.fn(async () => merged) } as never,
+    bookingsService as never,
+    billing as never,
+    notifications as never,
+    ratesService as never,
+    exchange as never,
+    { query } as never,
+  );
+
+  return {
+    service,
+    requests,
+    bookingsService,
+    billing,
+    notifications,
+    query,
+    requestRow,
+    booking: merged,
+  };
+}
+
+describe('EmptyReturnRequestsService — eligibility', () => {
+  it('lets an arrived container booking sold without return ask for one', async () => {
+    const { service } = build();
+    const result = await service.eligibility('b1', 'user1');
+
+    expect(result.eligible).toBe(true);
+    expect(result.reason).toBeNull();
+    expect(result.availableContainerNumbers).toEqual(['TEMU1111111', 'TEMU2222222']);
+  });
+
+  it('refuses bulk freight — there is no equipment to give back', async () => {
+    const { service } = build({ booking: { freightType: 'BULK' } });
+    const result = await service.eligibility('b1', 'user1');
+
+    expect(result.eligible).toBe(false);
+    expect(result.reason).toMatch(/container freight only/i);
+  });
+
+  it('refuses a booking that already bought the return service', async () => {
+    const withReturn = build({ booking: { equipmentReturn: 'WITH_RETURN' } });
+    const legacy = build({ booking: { equipmentReturn: 'RETURN' } });
+
+    expect((await withReturn.service.eligibility('b1', null)).reason).toMatch(
+      /already ships with/i,
+    );
+    expect((await legacy.service.eligibility('b1', null)).reason).toMatch(/already ships with/i);
+  });
+
+  it('refuses a booking that has not shipped yet', async () => {
+    const { service } = build({ booking: { status: 'PAID' } });
+    const result = await service.eligibility('b1', null);
+
+    expect(result.eligible).toBe(false);
+    expect(result.reason).toMatch(/once the booking is in transit/i);
+  });
+
+  it('allows it after delivery, when the empty actually comes back', async () => {
+    const { service } = build({ booking: { status: 'COMPLETED' } });
+    expect((await service.eligibility('b1', null)).eligible).toBe(true);
+  });
+
+  it('refuses when every container is already on a request', async () => {
+    const { service } = build({
+      queries: [
+        [
+          'unnest(r.container_numbers)',
+          [{ containerNumber: 'TEMU1111111' }, { containerNumber: 'TEMU2222222' }],
+        ],
+      ],
+    });
+    const result = await service.eligibility('b1', null);
+
+    expect(result.eligible).toBe(false);
+    expect(result.reason).toMatch(/already on an empty return request/i);
+  });
+
+  it('refuses a booking with no container numbers to pick from', async () => {
+    const { service } = build({ queries: [['upper(bcu.container_number)', []]] });
+    const result = await service.eligibility('b1', null);
+
+    expect(result.eligible).toBe(false);
+    expect(result.reason).toMatch(/no container numbers are recorded/i);
+    expect(result.availableContainerNumbers).toEqual([]);
+  });
+
+  it('checks booking ownership for a portal caller, and skips it for staff', async () => {
+    const portal = build();
+    await portal.service.eligibility('b1', 'user1');
+    expect(portal.bookingsService.assertCustomerCanAccessBooking).toHaveBeenCalled();
+
+    const staff = build();
+    await staff.service.eligibility('b1', null);
+    expect(staff.bookingsService.assertCustomerCanAccessBooking).not.toHaveBeenCalled();
+  });
+});
+
+describe('EmptyReturnRequestsService — creating a request', () => {
+  it('accepts containers that came in on the booking', async () => {
+    const { service, requests } = build();
+    await service.create(
+      { bookingId: 'b1', containerNumbers: ['temu1111111', 'TEMU2222222'] },
+      'user1',
+    );
+
+    expect(requests.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        bookingId: 'b1',
+        containerNumbers: ['TEMU1111111', 'TEMU2222222'],
+        containerCount: 2,
+        status: 'SUBMITTED',
+      }),
+    );
+  });
+
+  it('refuses a container that is not on the booking', async () => {
+    const { service, requests } = build();
+
+    await expect(
+      service.create(
+        { bookingId: 'b1', containerNumbers: ['TEMU1111111', 'MSCU9999999'] },
+        'user1',
+      ),
+    ).rejects.toThrow(/Not on booking BK-2026-000300: MSCU9999999/);
+    expect(requests.create).not.toHaveBeenCalled();
+  });
+
+  it('refuses the same container twice', async () => {
+    const { service } = build();
+
+    await expect(
+      service.create(
+        { bookingId: 'b1', containerNumbers: ['TEMU1111111', 'TEMU1111111'] },
+        'user1',
+      ),
+    ).rejects.toThrow(/selected twice/i);
+  });
+
+  it('refuses a container already sitting on a live request', async () => {
+    const { service } = build({
+      queries: [['unnest(r.container_numbers)', [{ containerNumber: 'TEMU1111111' }]]],
+    });
+
+    await expect(
+      service.create({ bookingId: 'b1', containerNumbers: ['TEMU1111111'] }, 'user1'),
+    ).rejects.toThrow(/Already on an empty return request/);
+  });
+
+  it('refuses a booking that already ships with return', async () => {
+    const { service } = build({ booking: { equipmentReturn: 'WITH_RETURN' } });
+
+    await expect(
+      service.create({ bookingId: 'b1', containerNumbers: ['TEMU1111111'] }, 'user1'),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+});
+
+describe('EmptyReturnRequestsService — pricing', () => {
+  it('prices a container at the route WITH_RETURN rate, converted to birr', async () => {
+    const { service, booking: b } = build();
+    const quote = await service.quote(b as never);
+
+    // 100 USD × 120 ETB/USD
+    expect(quote).toMatchObject({ unitAmount: 12000, currency: 'ETB', sourceRateUsd: 100 });
+    expect(quote.unavailableReason).toBeNull();
+  });
+
+  it('falls back to the route rate that names no container type', async () => {
+    const { service, booking: b } = build({
+      rates: [
+        {
+          trigger: 'WITH_RETURN',
+          currency: 'USD',
+          tradeDirection: 'IMPORT',
+          originYardId: 'y-dj',
+          destinationYardId: 'y-mojo',
+          containerTypeId: null,
+          rateValue: '80',
+        },
+      ],
+    });
+
+    expect((await service.quote(b as never)).unitAmount).toBe(9600);
+  });
+
+  it('reports no price when no rate covers the route', async () => {
+    const { service, booking: b } = build({
+      rates: [
+        {
+          trigger: 'WITH_RETURN',
+          currency: 'USD',
+          tradeDirection: 'EXPORT',
+          originYardId: 'other',
+          destinationYardId: 'other',
+          containerTypeId: null,
+          rateValue: '80',
+        },
+      ],
+    });
+    const quote = await service.quote(b as never);
+
+    expect(quote.unitAmount).toBeNull();
+    expect(quote.unavailableReason).toMatch(/no empty-return rate/i);
+  });
+});
+
+describe('EmptyReturnRequestsService — approval', () => {
+  it('bills container count × the route rate and stores the invoice', async () => {
+    const { service, billing, requests } = build();
+    await service.approve('r1', 'staff1', {});
+
+    expect(billing.generateInvoice).toHaveBeenCalledWith(
+      expect.objectContaining({
+        source: 'empty_return_request',
+        sourceId: 'r1',
+        currency: 'ETB',
+        totalAmount: 36000, // 3 × 12,000
+      }),
+    );
+    expect(requests.update).toHaveBeenCalledWith(
+      'r1',
+      expect.objectContaining({
+        status: 'APPROVED',
+        quotedUnitAmount: 12000,
+        quotedTotalAmount: 36000,
+        invoiceId: 'inv1',
+      }),
+    );
+  });
+
+  it("bills the reviewer's override instead of the route rate", async () => {
+    const { service, billing } = build();
+    await service.approve('r1', 'staff1', { unitAmount: 5000 });
+
+    expect(billing.generateInvoice).toHaveBeenCalledWith(
+      expect.objectContaining({ totalAmount: 15000 }),
+    );
+  });
+
+  it('refuses to approve without a price when no rate covers the route', async () => {
+    const { service } = build({ rates: [] });
+    await expect(service.approve('r1', 'staff1', {})).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('only approves a submitted request', async () => {
+    const { service } = build({ request: { status: 'APPROVED' } });
+    await expect(service.approve('r1', 'staff1', {})).rejects.toThrow(/Only a submitted request/);
+  });
+});
+
+describe('EmptyReturnRequestsService — scheduling', () => {
+  const details = {
+    returnDate: '2026-09-20',
+    truckPlateNumber: '3-a12345',
+    truckDriverName: 'Abebe K.',
+  };
+
+  it('takes the date and truck once the invoice is paid', async () => {
+    const { service, requests } = build({ request: { status: 'PAID' } });
+    await service.schedule('r1', 'user1', details);
+
+    expect(requests.update).toHaveBeenCalledWith(
+      'r1',
+      expect.objectContaining({
+        status: 'SCHEDULED',
+        requestedReturnDate: '2026-09-20',
+        truckPlateNumber: '3-A12345',
+      }),
+    );
+  });
+
+  it('tells an unpaid customer to pay first', async () => {
+    const { service } = build({ request: { status: 'APPROVED' } });
+    await expect(service.schedule('r1', 'user1', details)).rejects.toThrow(
+      /Pay the empty return invoice/,
+    );
+  });
+});
+
+describe('EmptyReturnRequestsService — payment and completion', () => {
+  it('moves an approved request to PAID when its invoice settles', async () => {
+    const { service, requests } = build({ request: { status: 'APPROVED' } });
+    await service.onInvoicePaid({ sourceId: 'r1' });
+
+    expect(requests.update).toHaveBeenCalledWith('r1', expect.objectContaining({ status: 'PAID' }));
+  });
+
+  it('ignores a settlement for a request that is not awaiting payment', async () => {
+    const { service, requests } = build({ request: { status: 'SCHEDULED' } });
+    await service.onInvoicePaid({ sourceId: 'r1' });
+
+    expect(requests.update).not.toHaveBeenCalled();
+  });
+
+  it('completes a scheduled request once every container is recorded back', async () => {
+    const { service, requests } = build({ request: { status: 'SCHEDULED' } });
+    await service.settleScheduledForBooking('b1');
+
+    expect(requests.update).toHaveBeenCalledWith(
+      'r1',
+      expect.objectContaining({ status: 'COMPLETED' }),
+    );
+  });
+
+  it('leaves it scheduled while any container is still outstanding', async () => {
+    const { service, requests } = build({
+      request: { status: 'SCHEDULED' },
+      queries: [['COUNT(*) AS outstanding', [{ outstanding: '2' }]]],
+    });
+    await service.settleScheduledForBooking('b1');
+
+    expect(requests.update).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.service.ts b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.service.ts
new file mode 100644
index 000000000..aae59de39
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/empty-return-requests/empty-return-requests.service.ts
@@ -0,0 +1,617 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { DataSource } from 'typeorm';
+
+import { ExchangeService } from '@edr/api-common';
+import { Freight, NotificationAudience, NotificationPriority, NotificationType } from '@edr/types';
+
+import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
+import { BillingService } from '../billing/billing.service';
+import { BookingsRepository } from '../bookings/bookings.repository';
+import { BookingsService } from '../bookings/bookings.service';
+import { Booking } from '../bookings/entities/booking.entity';
+import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
+import { RatesService } from '../rule-engine/services/rates.service';
+import {
+  ApproveEmptyReturnRequestDto,
+  CreateEmptyReturnRequestDto,
+  RejectEmptyReturnRequestDto,
+  ScheduleEmptyReturnRequestDto,
+} from './dto/empty-return-request.dto';
+import {
+  EmptyReturnRequest,
+  type EmptyReturnRequestStatus,
+} from './entities/empty-return-request.entity';
+import { EmptyReturnRequestsRepository } from './empty-return-requests.repository';
+
+/** The invoice `source` this module owns — also the `${source}.invoice.paid` event prefix. */
+const INVOICE_SOURCE = 'empty_return_request';
+
+/**
+ * Booking statuses that may still ask for an empty return. The empty only goes
+ * back after the cargo is delivered, so everything from departure onward
+ * qualifies — cutting it off at ARRIVED would take the option away exactly
+ * when the customer needs it.
+ */
+const REQUESTABLE_BOOKING_STATUSES = ['IN_TRANSIT', 'ARRIVED', 'COMPLETED'];
+
+/** Requests that still hold their container numbers — a rejected one releases them. */
+const OPEN_STATUSES: EmptyReturnRequestStatus[] = [
+  'SUBMITTED',
+  'APPROVED',
+  'PAID',
+  'SCHEDULED',
+  'COMPLETED',
+];
+
+export interface EmptyReturnQuote {
+  /** Per-container price in `currency`; null when no rate covers this route. */
+  unitAmount: number | null;
+  currency: string;
+  /** The USD route rate the quote came from, before conversion. */
+  sourceRateUsd: number | null;
+  /** Why there is no price, for the UI to show instead of a number. */
+  unavailableReason: string | null;
+}
+
+export interface EmptyReturnEligibility {
+  eligible: boolean;
+  /** Why the customer cannot request one, when `eligible` is false. */
+  reason: string | null;
+  /** Containers on the booking that are not already spoken for. */
+  availableContainerNumbers: string[];
+  maxContainers: number;
+  quote: EmptyReturnQuote;
+}
+
+@Injectable()
+export class EmptyReturnRequestsService {
+  constructor(
+    private readonly requests: EmptyReturnRequestsRepository,
+    private readonly bookingsRepository: BookingsRepository,
+    private readonly bookingsService: BookingsService,
+    private readonly billing: BillingService,
+    private readonly notifications: NotificationInboxService,
+    private readonly ratesService: RatesService,
+    private readonly exchange: ExchangeService,
+    private readonly dataSource: DataSource,
+  ) {}
+
+  // ── reads ────────────────────────────────────────────────────────────────
+
+  async findAll(filter: {
+    status?: EmptyReturnRequestStatus;
+    bookingId?: string;
+  }): Promise<
+    Array<EmptyReturnRequest & { bookingReference: string | null; companyName: string | null }>
+  > {
+    return this.dataSource.query(
+      `SELECT r.*,
+              b.reference AS "bookingReference",
+              c.name      AS "companyName"
+         FROM freight.empty_return_requests r
+         LEFT JOIN freight.bookings b ON b.id = r.booking_id AND b.deleted_at IS NULL
+         LEFT JOIN freight.companies c ON c.id = r.company_id
+        WHERE r.deleted_at IS NULL
+          AND ($1::text IS NULL OR r.status = $1)
+          AND ($2::uuid IS NULL OR r.booking_id = $2)
+        ORDER BY r.submitted_at DESC`,
+      [filter.status ?? null, filter.bookingId ?? null],
+    );
+  }
+
+  /** One request. A portal caller must own the booking; staff pass `null`. */
+  async findById(id: string, userId: string | null = null): Promise<EmptyReturnRequest> {
+    const request = await this.requests.findById(id);
+    if (!request) throw new NotFoundException(`Empty return request ${id} not found`);
+    if (userId) {
+      const booking = await this.bookingsService.findById(request.bookingId);
+      await this.bookingsService.assertCustomerCanAccessBooking(userId, booking);
+    }
+    return request;
+  }
+
+  /** A booking's own requests — the portal card's history. */
+  findForBooking(bookingId: string): Promise<EmptyReturnRequest[]> {
+    return this.requests.findAll({
+      where: { bookingId },
+      order: { submittedAt: 'DESC' },
+    });
+  }
+
+  /**
+   * Can this booking ask for an empty return, how many containers are left to
+   * ask for, and what one would cost. Drives the portal card: the customer
+   * sees the price before committing, and staff see the same number prefilled
+   * at approval.
+   */
+  async eligibility(bookingId: string, userId: string | null): Promise<EmptyReturnEligibility> {
+    const booking = await this.bookingsService.findById(bookingId);
+    if (userId) await this.bookingsService.assertCustomerCanAccessBooking(userId, booking);
+
+    const quote = await this.quote(booking);
+    const spoken = await this.spokenForContainers(bookingId);
+    const all = await this.bookingContainerNumbers(bookingId);
+    const available = all.filter((number) => !spoken.has(number));
+
+    const reason = this.ineligibilityReason(booking, all.length, available.length);
+    return {
+      eligible: reason === null,
+      reason,
+      availableContainerNumbers: available,
+      maxContainers: available.length,
+      quote,
+    };
+  }
+
+  private ineligibilityReason(
+    booking: Booking,
+    bookingContainerCount: number,
+    availableCount: number,
+  ): string | null {
+    if (booking.freightType !== 'CONTAINER') {
+      return 'Empty container return applies to container freight only.';
+    }
+    if (booking.equipmentReturn === 'WITH_RETURN' || booking.equipmentReturn === 'RETURN') {
+      return 'This booking already ships with empty container return included.';
+    }
+    if (!REQUESTABLE_BOOKING_STATUSES.includes(booking.status)) {
+      return `An empty return can be requested once the booking is in transit (current status: ${booking.status}).`;
+    }
+    // The customer picks from this booking's own containers, so a booking that
+    // never captured its container numbers has nothing to pick.
+    if (bookingContainerCount === 0) {
+      return 'No container numbers are recorded on this booking — contact EDR to arrange the return.';
+    }
+    if (availableCount === 0) {
+      return 'Every container on this booking is already on an empty return request.';
+    }
+    return null;
+  }
+
+  // ── pricing ──────────────────────────────────────────────────────────────
+
+  /**
+   * Per-container price for returning an empty on this booking, taken from the
+   * same live WITH_RETURN rate the rule engine bills when the service is
+   * bought up front (route + trade direction + container type, priced in USD).
+   * Billed in ETB, converted at the current rate, because this is collected
+   * locally rather than on the freight invoice.
+   *
+   * ponytail: prices off the booking's FIRST container line. A booking mixing
+   * 20ft and 40ft therefore quotes one size's rate for every box — split the
+   * quote per container if mixed-size bookings start returning empties.
+   */
+  async quote(booking: Booking): Promise<EmptyReturnQuote> {
+    const currency = 'ETB';
+    if (booking.freightType !== 'CONTAINER') {
+      return {
+        unitAmount: null,
+        currency,
+        sourceRateUsd: null,
+        unavailableReason: 'Not container freight.',
+      };
+    }
+
+    const [line]: Array<{ containerTypeId: string | null }> = await this.dataSource.query(
+      `SELECT container_type_id AS "containerTypeId"
+         FROM freight.booking_container
+        WHERE booking_id = $1 AND deleted_at IS NULL
+        ORDER BY created_at ASC
+        LIMIT 1`,
+      [booking.id],
+    );
+
+    const rates = await this.ratesService.findLiveRatesDetailed();
+    const onLeg = rates.filter(
+      (rate) =>
+        rate.trigger === 'WITH_RETURN' &&
+        rate.currency === 'USD' &&
+        rate.tradeDirection === booking.tradeDirection &&
+        rate.originYardId === booking.originYardId &&
+        rate.destinationYardId === booking.destinationYardId,
+    );
+    const rate =
+      onLeg.find((r) => r.containerTypeId === (line?.containerTypeId ?? null)) ??
+      onLeg.find((r) => !r.containerTypeId);
+
+    if (!rate) {
+      return {
+        unitAmount: null,
+        currency,
+        sourceRateUsd: null,
+        unavailableReason:
+          'No empty-return rate covers this route and container type — enter the amount manually.',
+      };
+    }
+
+    const usdToEtb = await this.exchange.getRate('USD', 'ETB');
+    const rateUsd = Number(rate.rateValue);
+    return {
+      unitAmount: Math.round(rateUsd * usdToEtb * 100) / 100,
+      currency,
+      sourceRateUsd: rateUsd,
+      unavailableReason: null,
+    };
+  }
+
+  // ── customer actions ─────────────────────────────────────────────────────
+
+  async create(
+    dto: CreateEmptyReturnRequestDto,
+    userId: string | null,
+  ): Promise<EmptyReturnRequest> {
+    const booking = await this.bookingsService.findById(dto.bookingId);
+    if (userId) await this.bookingsService.assertCustomerCanAccessBooking(userId, booking);
+
+    const numbers = dto.containerNumbers.map((n) => n.trim().toUpperCase()).filter(Boolean);
+    if (numbers.length === 0) {
+      throw new BadRequestException('Select at least one container.');
+    }
+    if (new Set(numbers).size !== numbers.length) {
+      throw new BadRequestException('The same container is selected twice.');
+    }
+
+    // Only this booking's own containers can be returned against it. The
+    // portal offers a pick list, so anything else is a stale page or a
+    // hand-made request.
+    const onBooking = new Set(await this.bookingContainerNumbers(booking.id));
+    const foreign = numbers.filter((number) => !onBooking.has(number));
+    if (foreign.length > 0) {
+      throw new BadRequestException(
+        `Not on booking ${booking.reference ?? booking.id}: ${foreign.join(', ')}`,
+      );
+    }
+
+    const reason = this.ineligibilityReason(booking, onBooking.size, numbers.length);
+    if (reason) throw new BadRequestException(reason);
+
+    await this.assertContainersFree(numbers);
+
+    const saved = await this.requests.create({
+      bookingId: booking.id,
+      companyId: booking.companyId ?? null,
+      status: 'SUBMITTED',
+      containerNumbers: numbers,
+      containerCount: numbers.length,
+      submittedByUserId: userId,
+      submittedAt: new Date(),
+    } as Partial<EmptyReturnRequest>);
+
+    void this.notifications.notify({
+      recipients: { permissionKeys: [FREIGHT_PERMS.emptyReturnRequests.review] },
+      audience: NotificationAudience.BACKOFFICE,
+      type: NotificationType.BOOKING_STATUS,
+      title: 'Empty container return requested',
+      body: `${booking.reference ?? booking.id}: a customer asked to return ${numbers.length} empty container${
+        numbers.length === 1 ? '' : 's'
+      }.`,
+      link: '/dashboard/empty-return-requests',
+      data: { bookingId: booking.id, requestId: saved.id },
+      priority: NotificationPriority.HIGH,
+    });
+
+    return saved;
+  }
+
+  /** Date + truck, once the invoice is settled. This is what the warehouse then expects. */
+  async schedule(
+    id: string,
+    userId: string | null,
+    dto: ScheduleEmptyReturnRequestDto,
+  ): Promise<EmptyReturnRequest> {
+    const request = await this.findById(id, userId);
+    if (request.status !== 'PAID' && request.status !== 'SCHEDULED') {
+      throw new BadRequestException(
+        request.status === 'APPROVED'
+          ? 'Pay the empty return invoice before booking a date.'
+          : `This request cannot be scheduled (current status: ${request.status}).`,
+      );
+    }
+
+    await this.requests.update(id, {
+      status: 'SCHEDULED',
+      requestedReturnDate: dto.returnDate,
+      truckPlateNumber: dto.truckPlateNumber.trim().toUpperCase(),
+      truckDriverName: dto.truckDriverName.trim(),
+      truckType: dto.truckType?.trim() ?? null,
+      scheduledAt: new Date(),
+    } as Partial<EmptyReturnRequest>);
+
+    void this.notifications.notify({
+      recipients: { permissionKeys: [FREIGHT_PERMS.emptyReturnRequests.review] },
+      audience: NotificationAudience.BACKOFFICE,
+      type: NotificationType.BOOKING_STATUS,
+      title: 'Empty return scheduled',
+      body: `${request.containerCount} empty container${request.containerCount === 1 ? '' : 's'} arriving ${
+        dto.returnDate
+      } on truck ${dto.truckPlateNumber}.`,
+      link: '/dashboard/container-returns',
+      data: { bookingId: request.bookingId, requestId: id },
+    });
+
+    return this.findById(id);
+  }
+
+  // ── staff actions ────────────────────────────────────────────────────────
+
+  /**
+   * Approve and bill. The reviewer's `unitAmount` wins; otherwise the route
+   * rate stands. The invoice is issued here, so the customer can pay straight
+   * away — payment lands back on `onInvoicePaid`.
+   */
+  async approve(
+    id: string,
+    staffId: string | null,
+    dto: ApproveEmptyReturnRequestDto,
+  ): Promise<EmptyReturnRequest> {
+    const request = await this.findById(id);
+    if (request.status !== 'SUBMITTED') {
+      throw new BadRequestException(
+        `Only a submitted request can be approved (current status: ${request.status}).`,
+      );
+    }
+
+    const booking = await this.bookingsService.findById(request.bookingId);
+    // `chk_invoices_single_payer` requires exactly one payer, and this invoice
+    // is always billed to the customer — so a booking with no company cannot
+    // be invoiced at all. Say so here rather than at the constraint.
+    if (!booking.companyId) {
+      throw new BadRequestException(
+        `Booking ${booking.reference ?? booking.id} has no company to bill — the empty return cannot be invoiced.`,
+      );
+    }
+
+    const quote = await this.quote(booking);
+    const unitAmount = dto.unitAmount ?? quote.unitAmount;
+    if (!unitAmount || unitAmount <= 0) {
+      throw new BadRequestException(
+        quote.unavailableReason ?? 'No price for this return — enter the per-container amount.',
+      );
+    }
+
+    const currency = dto.currency ?? quote.currency;
+    const totalAmount = Math.round(unitAmount * request.containerCount * 100) / 100;
+
+    const invoice = await this.billing.generateInvoice({
+      source: INVOICE_SOURCE as Freight.InvoiceSource,
+      sourceId: request.id,
+      type: 'EMPTY_RETURN',
+      companyId: booking.companyId,
+      companyProfileId: booking.companyProfileId || '',
+      currency,
+      lines: [
+        {
+          chargeType: 'CONTAINER_WITH_RETURN',
+          description: `Empty container return — ${request.containerCount} container${
+            request.containerCount === 1 ? '' : 's'
+          } on booking ${booking.reference ?? booking.id}`,
+          amount: totalAmount,
+        },
+      ],
+      totalAmount,
+    });
+
+    await this.requests.update(id, {
+      status: 'APPROVED',
+      quotedUnitAmount: unitAmount,
+      quotedTotalAmount: totalAmount,
+      currency,
+      invoiceId: invoice.id,
+      reviewedByStaffId: staffId,
+      reviewedAt: new Date(),
+    } as Partial<EmptyReturnRequest>);
+
+    if (booking.companyId) {
+      void this.notifications.notify({
+        recipients: { companyId: booking.companyId },
+        audience: NotificationAudience.PORTAL,
+        type: NotificationType.INVOICE_ISSUED,
+        title: 'Empty container return approved — payment due',
+        body: `Your empty return request for booking ${booking.reference ?? booking.id} was approved: ${totalAmount.toLocaleString()} ${currency} for ${request.containerCount} container${
+          request.containerCount === 1 ? '' : 's'
+        }. Pay the invoice, then choose your return date and truck.`,
+        link: `/bookings/${booking.id}`,
+        data: { bookingId: booking.id, requestId: id, invoiceId: invoice.id },
+        priority: NotificationPriority.HIGH,
+      });
+    }
+
+    return this.findById(id);
+  }
+
+  async reject(
+    id: string,
+    staffId: string | null,
+    dto: RejectEmptyReturnRequestDto,
+  ): Promise<EmptyReturnRequest> {
+    const request = await this.findById(id);
+    if (request.status !== 'SUBMITTED') {
+      throw new BadRequestException(
+        `Only a submitted request can be rejected (current status: ${request.status}).`,
+      );
+    }
+
+    await this.requests.update(id, {
+      status: 'REJECTED',
+      reviewedByStaffId: staffId,
+      reviewedAt: new Date(),
+      rejectionReason: dto.reason,
+    } as Partial<EmptyReturnRequest>);
+
+    const booking = await this.bookingsRepository.findById(request.bookingId);
+    if (booking?.companyId) {
+      void this.notifications.notify({
+        recipients: { companyId: booking.companyId },
+        audience: NotificationAudience.PORTAL,
+        type: NotificationType.BOOKING_STATUS,
+        title: 'Empty container return rejected',
+        body: `Your empty return request for booking ${booking.reference ?? request.bookingId} was rejected: ${dto.reason}`,
+        link: `/bookings/${request.bookingId}`,
+        data: { bookingId: request.bookingId, requestId: id },
+        priority: NotificationPriority.HIGH,
+      });
+    }
+
+    return this.findById(id);
+  }
+
+  // ── warehouse handoff ────────────────────────────────────────────────────
+
+  /**
+   * Scheduled requests the warehouse is waiting on — the planned side of the
+   * Container Returns screen. Containers already recorded as returned are
+   * carried per request so staff confirm only what is still outstanding.
+   */
+  async plannedReturns(): Promise<
+    Array<{
+      requestId: string;
+      bookingId: string;
+      bookingReference: string | null;
+      companyName: string | null;
+      companyId: string | null;
+      requestedReturnDate: string | null;
+      truckPlateNumber: string | null;
+      truckDriverName: string | null;
+      truckType: string | null;
+      containers: Array<{ containerNumber: string; returnId: string | null }>;
+    }>
+  > {
+    return this.dataSource.query(
+      `SELECT r.id                     AS "requestId",
+              r.booking_id             AS "bookingId",
+              b.reference              AS "bookingReference",
+              c.name                   AS "companyName",
+              r.company_id             AS "companyId",
+              r.requested_return_date  AS "requestedReturnDate",
+              r.truck_plate_number     AS "truckPlateNumber",
+              r.truck_driver_name      AS "truckDriverName",
+              r.truck_type             AS "truckType",
+              (
+                SELECT json_agg(json_build_object(
+                         'containerNumber', n,
+                         'returnId', (
+                           SELECT er.id FROM freight.empty_container_returns er
+                            WHERE er.deleted_at IS NULL
+                              AND er.booking_id = r.booking_id
+                              AND upper(er.container_number) = upper(n)
+                            ORDER BY er.created_at DESC LIMIT 1
+                         )
+                       ) ORDER BY ord)
+                  FROM unnest(r.container_numbers) WITH ORDINALITY AS t(n, ord)
+              ) AS containers
+         FROM freight.empty_return_requests r
+         LEFT JOIN freight.bookings b ON b.id = r.booking_id AND b.deleted_at IS NULL
+         LEFT JOIN freight.companies c ON c.id = r.company_id
+        WHERE r.deleted_at IS NULL
+          AND r.status = 'SCHEDULED'
+        ORDER BY r.requested_return_date ASC NULLS LAST, r.scheduled_at ASC`,
+    );
+  }
+
+  /**
+   * Close a scheduled request once every container it covers has been recorded
+   * as returned. Called after the warehouse records the returns; a request
+   * with anything still outstanding stays SCHEDULED.
+   */
+  async settleScheduledForBooking(bookingId: string): Promise<void> {
+    const open = await this.requests.findAll({
+      where: { bookingId, status: 'SCHEDULED' },
+    });
+
+    for (const request of open) {
+      const [{ outstanding }]: Array<{ outstanding: string }> = await this.dataSource.query(
+        `SELECT COUNT(*) AS outstanding
+           FROM unnest($2::text[]) AS n
+          WHERE NOT EXISTS (
+            SELECT 1 FROM freight.empty_container_returns er
+             WHERE er.deleted_at IS NULL
+               AND er.booking_id = $1
+               AND upper(er.container_number) = upper(n)
+          )`,
+        [bookingId, request.containerNumbers],
+      );
+      if (Number(outstanding) > 0) continue;
+
+      await this.requests.update(request.id, {
+        status: 'COMPLETED',
+        completedAt: new Date(),
+      } as Partial<EmptyReturnRequest>);
+    }
+  }
+
+  // ── payment ──────────────────────────────────────────────────────────────
+
+  /** Gateway and manual settlements both land here (`${source}.invoice.paid`). */
+  @OnEvent(`${INVOICE_SOURCE}.invoice.paid`)
+  async onInvoicePaid(payload: { sourceId: string }): Promise<void> {
+    const request = await this.requests.findById(payload.sourceId);
+    if (!request || request.status !== 'APPROVED') return;
+
+    await this.requests.update(request.id, {
+      status: 'PAID',
+      paidAt: new Date(),
+    } as Partial<EmptyReturnRequest>);
+
+    const booking = await this.bookingsRepository.findById(request.bookingId);
+    if (!booking?.companyId) return;
+    void this.notifications.notify({
+      recipients: { companyId: booking.companyId },
+      audience: NotificationAudience.PORTAL,
+      type: NotificationType.PAYMENT_RECEIVED,
+      title: 'Empty return paid — choose your return date',
+      body: `Payment received for the empty return on booking ${booking.reference ?? request.bookingId}. Tell us the date and the truck bringing the containers back.`,
+      link: `/bookings/${request.bookingId}`,
+      data: { bookingId: request.bookingId, requestId: request.id },
+      priority: NotificationPriority.HIGH,
+    });
+  }
+
+  // ── helpers ──────────────────────────────────────────────────────────────
+
+  /** Container numbers captured on the booking, upper-cased. */
+  private async bookingContainerNumbers(bookingId: string): Promise<string[]> {
+    const rows: Array<{ containerNumber: string }> = await this.dataSource.query(
+      `SELECT DISTINCT upper(bcu.container_number) AS "containerNumber"
+         FROM freight.booking_container_units bcu
+         JOIN freight.booking_container bc
+           ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
+        WHERE bc.booking_id = $1
+          AND bcu.deleted_at IS NULL
+          AND bcu.container_number IS NOT NULL
+        ORDER BY 1`,
+      [bookingId],
+    );
+    return rows.map((row) => row.containerNumber);
+  }
+
+  /** Numbers already claimed by a live request on this booking. */
+  private async spokenForContainers(bookingId: string): Promise<Set<string>> {
+    const rows: Array<{ containerNumber: string }> = await this.dataSource.query(
+      `SELECT DISTINCT upper(n) AS "containerNumber"
+         FROM freight.empty_return_requests r, unnest(r.container_numbers) AS n
+        WHERE r.deleted_at IS NULL
+          AND r.booking_id = $1
+          AND r.status = ANY($2)`,
+      [bookingId, OPEN_STATUSES],
+    );
+    return new Set(rows.map((row) => row.containerNumber));
+  }
+
+  /** A container may only sit on one live request at a time, on any booking. */
+  private async assertContainersFree(numbers: string[]): Promise<void> {
+    const rows: Array<{ containerNumber: string }> = await this.dataSource.query(
+      `SELECT DISTINCT upper(n) AS "containerNumber"
+         FROM freight.empty_return_requests r, unnest(r.container_numbers) AS n
+        WHERE r.deleted_at IS NULL
+          AND r.status = ANY($1)
+          AND upper(n) = ANY($2)`,
+      [OPEN_STATUSES, numbers],
+    );
+    if (rows.length > 0) {
+      throw new BadRequestException(
+        `Already on an empty return request: ${rows.map((r) => r.containerNumber).join(', ')}`,
+      );
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/empty-return-requests/entities/empty-return-request.entity.ts b/apps/edr-freight-api/src/modules/empty-return-requests/entities/empty-return-request.entity.ts
new file mode 100644
index 000000000..6bb8257be
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/empty-return-requests/entities/empty-return-request.entity.ts
@@ -0,0 +1,127 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+
+import { Booking } from '../../bookings/entities/booking.entity';
+
+export const EMPTY_RETURN_REQUEST_STATUSES = [
+  /** Customer named the containers; waiting on operations. */
+  'SUBMITTED',
+  /** Operations approved and priced it; the invoice is out, waiting on payment. */
+  'APPROVED',
+  'REJECTED',
+  /** Invoice settled; waiting on the customer to book a date and a truck. */
+  'PAID',
+  /** Date and truck given — the warehouse now expects these empties. */
+  'SCHEDULED',
+  /** The empties arrived and were recorded as returns. */
+  'COMPLETED',
+  'CANCELLED',
+] as const;
+
+export type EmptyReturnRequestStatus = (typeof EMPTY_RETURN_REQUEST_STATUSES)[number];
+
+/**
+ * A customer's request to return empties on a booking that did NOT buy the
+ * return service up front (`equipment_return` is not WITH_RETURN). Container
+ * freight only — a bulk booking has no equipment to give back.
+ *
+ * The request carries the commercial half of the flow: which containers, what
+ * operations priced it at, the invoice, and the date/truck the customer
+ * booked. The physical return is still recorded in `empty_container_returns`
+ * when the truck arrives, which is what closes this row out as COMPLETED.
+ */
+@Entity({ schema: 'freight', name: 'empty_return_requests' })
+@Index(['bookingId'])
+@Index(['status'])
+export class EmptyReturnRequest extends BaseEntity {
+  @Column({ name: 'booking_id', type: 'uuid' })
+  bookingId!: string;
+
+  @ManyToOne(() => Booking, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'booking_id' })
+  booking?: Booking;
+
+  /** Denormalised at submit so the queue and the invoice agree on the payer. */
+  @Column({ name: 'company_id', type: 'uuid', nullable: true })
+  companyId?: string | null;
+
+  @Column({ name: 'status', type: 'varchar', length: 30, default: 'SUBMITTED' })
+  status!: EmptyReturnRequestStatus;
+
+  /** The container numbers the customer is sending back, as typed. */
+  @Column({ name: 'container_numbers', type: 'text', array: true, default: () => "'{}'" })
+  containerNumbers!: string[];
+
+  @Column({ name: 'container_count', type: 'smallint', default: 0 })
+  containerCount!: number;
+
+  /** Per-container price at approval — the route's WITH_RETURN rate, or the reviewer's override. */
+  @Column({
+    name: 'quoted_unit_amount',
+    type: 'numeric',
+    precision: 14,
+    scale: 2,
+    nullable: true,
+    transformer: {
+      to: (v?: number | null) => v,
+      from: (v?: string | null) => (v == null ? null : Number(v)),
+    },
+  })
+  quotedUnitAmount?: number | null;
+
+  @Column({
+    name: 'quoted_total_amount',
+    type: 'numeric',
+    precision: 14,
+    scale: 2,
+    nullable: true,
+    transformer: {
+      to: (v?: number | null) => v,
+      from: (v?: string | null) => (v == null ? null : Number(v)),
+    },
+  })
+  quotedTotalAmount?: number | null;
+
+  @Column({ name: 'currency', type: 'varchar', length: 8, nullable: true })
+  currency?: string | null;
+
+  @Column({ name: 'invoice_id', type: 'uuid', nullable: true })
+  invoiceId?: string | null;
+
+  @Column({ name: 'paid_at', type: 'timestamptz', nullable: true })
+  paidAt?: Date | null;
+
+  /** Customer's chosen day for handing the empties over. */
+  @Column({ name: 'requested_return_date', type: 'date', nullable: true })
+  requestedReturnDate?: string | null;
+
+  @Column({ name: 'truck_plate_number', type: 'varchar', length: 32, nullable: true })
+  truckPlateNumber?: string | null;
+
+  @Column({ name: 'truck_driver_name', type: 'varchar', length: 120, nullable: true })
+  truckDriverName?: string | null;
+
+  @Column({ name: 'truck_type', type: 'varchar', length: 60, nullable: true })
+  truckType?: string | null;
+
+  @Column({ name: 'scheduled_at', type: 'timestamptz', nullable: true })
+  scheduledAt?: Date | null;
+
+  @Column({ name: 'submitted_by_user_id', type: 'uuid', nullable: true })
+  submittedByUserId?: string | null;
+
+  @Column({ name: 'submitted_at', type: 'timestamptz', default: () => 'now()' })
+  submittedAt!: Date;
+
+  @Column({ name: 'reviewed_by_staff_id', type: 'uuid', nullable: true })
+  reviewedByStaffId?: string | null;
+
+  @Column({ name: 'reviewed_at', type: 'timestamptz', nullable: true })
+  reviewedAt?: Date | null;
+
+  @Column({ name: 'rejection_reason', type: 'text', nullable: true })
+  rejectionReason?: string | null;
+
+  @Column({ name: 'completed_at', type: 'timestamptz', nullable: true })
+  completedAt?: Date | null;
+}
diff --git a/apps/edr-freight-api/src/modules/exports/datasets/customers.dataset.ts b/apps/edr-freight-api/src/modules/exports/datasets/customers.dataset.ts
index a840f54a0..d36bbecd6 100644
--- a/apps/edr-freight-api/src/modules/exports/datasets/customers.dataset.ts
+++ b/apps/edr-freight-api/src/modules/exports/datasets/customers.dataset.ts
@@ -122,6 +122,16 @@ export const customersDataset: ExportDataset = {
       { value: 'ethiopian', label: 'Ethiopian' },
       { value: 'foreign', label: 'Foreign' },
     ] },
+    // The operational role, NOT `type` above — the list's Role pill. One
+    // `customer` company routinely holds several profiles, so this asks "who
+    // does X?" rather than "what kind of company is this?".
+    { key: 'profileType', label: 'Role', type: 'select', options: [
+      { value: 'importer', label: 'Importer' },
+      { value: 'exporter', label: 'Exporter' },
+      { value: 'freight_forwarder', label: 'Freight forwarder' },
+      { value: 'dj_freight_forwarder', label: 'DJ freight forwarder' },
+      { value: 'transporter', label: 'Transporter' },
+    ] },
     // The list's Status filter folds the review queues in, and sends these two
     // alongside `status`. They are predicates, not columns — see
     // `company-scope.sql.ts`, shared with the list so both agree exactly.
@@ -147,6 +157,18 @@ export const customersDataset: ExportDataset = {
     if (params.kind) qb.andWhere('c.kind = :kind', { kind: params.kind });
     if (params.status) qb.andWhere('c.status = :status', { status: params.status });
     if (params.nationality) qb.andWhere('c.nationality = :nationality', { nationality: params.nationality });
+    if (params.profileType) {
+      // EXISTS, matching the list repository exactly — a join here would
+      // multiply a company holding two profiles into two rows and put the file
+      // out of step with the count endpoint.
+      qb.andWhere(
+        `EXISTS (SELECT 1 FROM freight.company_profiles cp_type
+                 WHERE cp_type.company_id = c.id
+                   AND cp_type.deleted_at IS NULL
+                   AND cp_type.type = :profileType)`,
+        { profileType: params.profileType },
+      );
+    }
     if (params.onboardingCompleted) {
       const draft = companyDraftSql('c');
       qb.andWhere(params.onboardingCompleted === 'true' ? `NOT ${draft}` : draft);
diff --git a/apps/edr-freight-api/src/modules/exports/export-request.util.spec.ts b/apps/edr-freight-api/src/modules/exports/export-request.util.spec.ts
index 1b473b12a..58724298c 100644
--- a/apps/edr-freight-api/src/modules/exports/export-request.util.spec.ts
+++ b/apps/edr-freight-api/src/modules/exports/export-request.util.spec.ts
@@ -2,6 +2,7 @@ import {
   EXPORT_MIME,
   formatRowCap,
   pickByKey,
+  pickDatasetFields,
   resolveExportFormat,
   resolveRowLimit,
 } from './export-request.util';
@@ -85,3 +86,48 @@ describe('pickByKey', () => {
     expect(pickByKey(columns, 'ghost,also-ghost')).toEqual(columns);
   });
 });
+
+describe('pickDatasetFields', () => {
+  const fields = [
+    { key: 'name', label: 'Company', default: true },
+    { key: 'tin', label: 'TIN', default: true },
+    { key: 'website', label: 'Website' },
+    { key: 'kebele', label: 'Kebele' },
+  ];
+  const defaults = [fields[0], fields[1]];
+
+  it.each([undefined, '', '   ', ','])('%p means the default fields', (raw) => {
+    expect(pickDatasetFields(fields, raw)).toEqual(defaults);
+  });
+
+  it('a subset is honoured, in the dataset\'s own order', () => {
+    expect(pickDatasetFields(fields, 'kebele,name')).toEqual([fields[0], fields[3]]);
+  });
+
+  it('asking for EVERY field exports every field', () => {
+    // The dialog's "All columns" chip sends exactly this. Falling back to the
+    // defaults here was the bug: 37 ticked customer columns exported as 9.
+    expect(pickDatasetFields(fields, 'name,tin,website,kebele')).toEqual(fields);
+  });
+
+  it('a non-default field alone is not widened back to the defaults', () => {
+    expect(pickDatasetFields(fields, 'website')).toEqual([fields[2]]);
+  });
+
+  it('unknown keys are dropped, the recognised ones still stand', () => {
+    expect(pickDatasetFields(fields, 'ghost,website')).toEqual([fields[2]]);
+  });
+
+  it('all-unknown keys fall back to the defaults, not to everything', () => {
+    expect(pickDatasetFields(fields, 'ghost,also-ghost')).toEqual(defaults);
+  });
+
+  it('surrounding whitespace in a hand-built fields list is tolerated', () => {
+    expect(pickDatasetFields(fields, ' name , website ')).toEqual([fields[0], fields[2]]);
+  });
+
+  it('a dataset with no default flags falls back to every field', () => {
+    const flat = [{ key: 'a', label: 'A' }, { key: 'b', label: 'B' }];
+    expect(pickDatasetFields(flat, undefined)).toEqual(flat);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/exports/export-request.util.ts b/apps/edr-freight-api/src/modules/exports/export-request.util.ts
index 39f1f2e8c..5b57c82f0 100644
--- a/apps/edr-freight-api/src/modules/exports/export-request.util.ts
+++ b/apps/edr-freight-api/src/modules/exports/export-request.util.ts
@@ -56,3 +56,31 @@ export function pickByKey<T extends { key: string }>(all: T[], raw: string | und
   const filtered = requested?.length ? all.filter((c) => requested.includes(c.key)) : all;
   return filtered.length ? filtered : all;
 }
+
+/**
+ * A dataset's requested field subset, whitelisted against what the caller may
+ * have. Unlike `pickByKey`, "nothing recognised" falls back to the DEFAULT
+ * fields rather than to every field — a bookings export declares ~70 columns
+ * and dumping all of them on an unparameterised call is nobody's intent.
+ *
+ * Selecting every field is a legitimate request — the dialog's "All columns"
+ * chip sends exactly that — so the fallback keys off whether any requested key
+ * MATCHED, never off how many fields came back. Comparing the picked count to
+ * `all.length` (as this did originally) made "All columns" silently export the
+ * default columns instead.
+ */
+export function pickDatasetFields<T extends { key: string; default?: boolean }>(
+  all: T[],
+  raw: string | undefined,
+): T[] {
+  const requested = new Set(
+    raw
+      ?.split(',')
+      .map((k) => k.trim())
+      .filter(Boolean) ?? [],
+  );
+  const picked = requested.size ? all.filter((f) => requested.has(f.key)) : [];
+  if (picked.length) return picked;
+  const defaults = all.filter((f) => f.default);
+  return defaults.length ? defaults : all;
+}
diff --git a/apps/edr-freight-api/src/modules/exports/exports.controller.ts b/apps/edr-freight-api/src/modules/exports/exports.controller.ts
index 46c6ebad2..808e375bc 100644
--- a/apps/edr-freight-api/src/modules/exports/exports.controller.ts
+++ b/apps/edr-freight-api/src/modules/exports/exports.controller.ts
@@ -13,7 +13,7 @@ import { resolveDatasetFields, resolveFilterOptions } from './export-filter.util
 import {
   EXPORT_MIME,
   formatRowCap,
-  pickByKey,
+  pickDatasetFields,
   resolveExportFormat,
   resolveRowLimit,
 } from './export-request.util';
@@ -105,7 +105,7 @@ export class ExportsController {
     const dataset = this.resolve(key, user);
     const directions = await this.userTradeAccessService.resolveAllowedDirections(user);
     const format = resolveExportFormat(query.format);
-    const fields = ExportsController.pickFields(
+    const fields = pickDatasetFields(
       await resolveDatasetFields(dataset, this.dataSource),
       query.fields,
     );
@@ -135,22 +135,6 @@ export class ExportsController {
     res.send(buffer);
   }
 
-  /**
-   * Requested fields, whitelisted against the dataset. No `fields=` means the
-   * DEFAULT set, not everything — a booking export has ~70 fields and dumping
-   * all of them on an unparameterised call is nobody's intent.
-   */
-  private static pickFields(all: ExportField[], raw: string | undefined): ExportField[] {
-    if (raw?.trim()) {
-      const picked = pickByKey(all, raw);
-      // pickByKey falls back to everything when nothing matched; for a dataset
-      // the safer read of "all keys unknown" is still the default set.
-      if (picked.length !== all.length) return picked;
-    }
-    const defaults = all.filter((f) => f.default);
-    return defaults.length ? defaults : all;
-  }
-
   private resolve(key: string, user: TCurrentUser): ExportDataset {
     const dataset = getDataset(key);
     if (!dataset) throw new NotFoundException(`Unknown export dataset: ${key}`);
diff --git a/apps/edr-freight-api/src/modules/health/health.controller.spec.ts b/apps/edr-freight-api/src/modules/health/health.controller.spec.ts
new file mode 100644
index 000000000..26c873567
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/health/health.controller.spec.ts
@@ -0,0 +1,100 @@
+import 'reflect-metadata';
+
+import type { Response } from 'express';
+import type { DataSource } from 'typeorm';
+
+import type { MatrixClient } from '../chat/matrix.client';
+import type { EmailClientService } from '../notifications/email-client.service';
+import type { SmsClientService } from '../notifications/sms-client.service';
+import { HealthController } from './health.controller';
+
+type ReadinessBody = {
+  status: string;
+  checks: {
+    chat: { status: string; enabled: boolean; actingAs?: string; error?: string };
+  };
+};
+
+/** Captures what the controller wrote, in place of an express Response. */
+function recorder() {
+  const sent: { code?: number; body?: ReadinessBody } = {};
+  const res = {
+    status(code: number) {
+      sent.code = code;
+      return this;
+    },
+    json(body: ReadinessBody) {
+      sent.body = body;
+      return this;
+    },
+  };
+  return { sent, res: res as unknown as Response };
+}
+
+function controllerWith(matrix: Partial<MatrixClient>) {
+  const dataSource = { query: jest.fn(async () => [{ '?column?': 1 }]) };
+  return new HealthController(
+    dataSource as unknown as DataSource,
+    { brokerConnected: true } as unknown as SmsClientService,
+    { brokerConnected: true } as unknown as EmailClientService,
+    matrix as MatrixClient,
+  );
+}
+
+describe('HealthController readiness — chat check', () => {
+  it('reports degraded, not 503, when MATRIX_ADMIN_TOKEN is not a server admin', async () => {
+    // The dev outage. Chat is broken, but chat is not worth pulling the pod
+    // out of the load balancer for — bookings and billing still work.
+    const controller = controllerWith({
+      enabled: true,
+      adminCheck: jest.fn(async () => ({
+        ok: false,
+        actingAs: '@super-admin.f15347:matrixdev.edrsc.com',
+        error: 'Matrix GET /_synapse/admin/v2/users?limit=1 -> 403: not a server admin',
+      })),
+    });
+
+    const { sent, res } = recorder();
+    await controller.readiness(res);
+
+    expect(sent.code).toBe(200);
+    expect(sent.body?.status).toBe('degraded');
+    expect(sent.body?.checks.chat.status).toBe('error');
+    // The account name is the actionable half — it says *which* token is wired up.
+    expect(sent.body?.checks.chat.actingAs).toBe(
+      '@super-admin.f15347:matrixdev.edrsc.com',
+    );
+  });
+
+  it('reports ok when the token really is a server admin', async () => {
+    const controller = controllerWith({
+      enabled: true,
+      adminCheck: jest.fn(async () => ({
+        ok: true,
+        actingAs: '@edrbot:matrixdev.edrsc.com',
+      })),
+    });
+
+    const { sent, res } = recorder();
+    await controller.readiness(res);
+
+    expect(sent.body?.status).toBe('ok');
+    expect(sent.body?.checks.chat).toMatchObject({
+      status: 'ok',
+      enabled: true,
+      actingAs: '@edrbot:matrixdev.edrsc.com',
+    });
+  });
+
+  it('does not call Synapse, or degrade, when chat is switched off', async () => {
+    const adminCheck = jest.fn();
+    const controller = controllerWith({ enabled: false, adminCheck });
+
+    const { sent, res } = recorder();
+    await controller.readiness(res);
+
+    expect(adminCheck).not.toHaveBeenCalled();
+    expect(sent.body?.status).toBe('ok');
+    expect(sent.body?.checks.chat).toEqual({ status: 'unknown', enabled: false });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/health/health.controller.ts b/apps/edr-freight-api/src/modules/health/health.controller.ts
index 6b559f2e3..94b8eb698 100644
--- a/apps/edr-freight-api/src/modules/health/health.controller.ts
+++ b/apps/edr-freight-api/src/modules/health/health.controller.ts
@@ -7,6 +7,7 @@ import { Public } from "@edr/api-common";
 import { Response } from "express";
 import { DataSource } from "typeorm";
 
+import { MatrixClient } from "../chat/matrix.client";
 import { EmailClientService } from "../notifications/email-client.service";
 import { SmsClientService } from "../notifications/sms-client.service";
 
@@ -32,6 +33,7 @@ export class HealthController {
     private readonly dataSource: DataSource,
     private readonly smsClient: SmsClientService,
     private readonly emailClient: EmailClientService,
+    private readonly matrix: MatrixClient,
   ) {}
 
   @Get()
@@ -45,7 +47,7 @@ export class HealthController {
   @Public()
   @ApiOperation({
     summary:
-      "Readiness probe — database plus SMS/email broker connectivity. Broker failures report as degraded unless READINESS_REQUIRES_BROKER=true.",
+      "Readiness probe — database, SMS/email broker connectivity, and the Matrix admin token. Broker failures report as degraded unless READINESS_REQUIRES_BROKER=true; chat failures always report as degraded.",
   })
   async readiness(@Res() res: Response) {
     const startedAt = Date.now();
@@ -76,23 +78,55 @@ export class HealthController {
       enabled: process.env.RABBITMQ_ENABLED !== "false",
     };
 
+    const chat = await this.chatCheck();
+
     const brokerDown =
       broker.sms.status === "error" || broker.email.status === "error";
     const failed =
       database.status === "error" ||
       (READINESS_REQUIRES_BROKER && brokerDown);
 
-    const status = failed ? "error" : brokerDown ? "degraded" : "ok";
+    const status = failed
+      ? "error"
+      : brokerDown || chat.status === "error"
+        ? "degraded"
+        : "ok";
 
     return res
       .status(failed ? HttpStatus.SERVICE_UNAVAILABLE : HttpStatus.OK)
       .json({
         status,
         timestamp: new Date().toISOString(),
-        checks: { database, broker },
+        checks: { database, broker, chat },
       });
   }
 
+  /**
+   * Chat provisioning runs entirely on MATRIX_ADMIN_TOKEN, and a token that is
+   * valid but not *server admin* fails only the `/_synapse/admin` half: rooms
+   * are never created, joins never happen, and the sole symptom is an empty
+   * Element for every employee. Nothing else in the probe would catch that.
+   *
+   * Degraded, never a 503 — chat is not worth pulling the pod out of the load
+   * balancer for, by the same reasoning as the broker check above. `unknown`
+   * when MATRIX_ENABLED is off: a feature that is switched off is not a fault.
+   */
+  private async chatCheck(): Promise<{
+    status: CheckStatus;
+    enabled: boolean;
+    actingAs?: string;
+    error?: string;
+  }> {
+    if (!this.matrix.enabled) return { status: "unknown", enabled: false };
+    const check = await this.matrix.adminCheck();
+    return {
+      status: check.ok ? "ok" : "error",
+      enabled: true,
+      actingAs: check.actingAs,
+      error: check.error,
+    };
+  }
+
   @Get("info")
   @Public()
   @ApiOperation({ summary: "App info — version, environment, uptime" })
diff --git a/apps/edr-freight-api/src/modules/health/health.module.ts b/apps/edr-freight-api/src/modules/health/health.module.ts
index 572e5eb86..1aa74f56f 100644
--- a/apps/edr-freight-api/src/modules/health/health.module.ts
+++ b/apps/edr-freight-api/src/modules/health/health.module.ts
@@ -2,13 +2,15 @@
 
 import { Module } from "@nestjs/common";
 
+import { ChatModule } from "../chat/chat.module";
 import { HealthController } from "./health.controller";
 import { NotificationsModule } from "../notifications/notifications.module";
 
 @Module({
   // NotificationsModule exports the SMS/email clients; the readiness probe reads
   // their broker connection state rather than opening a second connection.
-  imports: [NotificationsModule],
+  // ChatModule exports MatrixClient for the MATRIX_ADMIN_TOKEN check.
+  imports: [NotificationsModule, ChatModule],
   controllers: [HealthController],
 })
 export class HealthModule {}
diff --git a/apps/edr-freight-api/src/modules/import-operations/empty-return-bookings.util.spec.ts b/apps/edr-freight-api/src/modules/import-operations/empty-return-bookings.util.spec.ts
new file mode 100644
index 000000000..848732f47
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/import-operations/empty-return-bookings.util.spec.ts
@@ -0,0 +1,98 @@
+import {
+  assembleEmptyReturnBookings,
+  type EmptyReturnBookingUnitRow,
+} from './empty-return-bookings.util';
+
+const booking = {
+  bookingId: 'b1',
+  bookingReference: 'BK-2026-000263',
+  bookingStatus: 'IN_TRANSIT',
+  equipmentReturn: 'WITH_RETURN',
+  customerId: 'c1',
+  companyName: 'Afri Software Solutions',
+};
+
+const unit = (
+  overrides: Partial<EmptyReturnBookingUnitRow> & { unitId: string; containerNumber: string },
+): EmptyReturnBookingUnitRow => ({
+  ...booking,
+  containerSize: '40ft',
+  containerType: '40FT',
+  returnId: null,
+  returnStatus: null,
+  ...overrides,
+});
+
+describe('assembleEmptyReturnBookings', () => {
+  it('groups a booking’s flagged containers onto one row, all pending', () => {
+    const rows = assembleEmptyReturnBookings([
+      unit({ unitId: 'u1', containerNumber: 'MSFH8596324' }),
+      unit({ unitId: 'u2', containerNumber: 'SDJU8596324' }),
+    ]);
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0].bookingReference).toBe('BK-2026-000263');
+    expect(rows[0].companyName).toBe('Afri Software Solutions');
+    expect(rows[0].containers.map((c) => c.containerNumber)).toEqual([
+      'MSFH8596324',
+      'SDJU8596324',
+    ]);
+    expect(rows[0]).toMatchObject({ expectedCount: 2, recordedCount: 0, pendingCount: 2 });
+  });
+
+  it('keeps an already-recorded container visible but out of the pending count', () => {
+    const rows = assembleEmptyReturnBookings([
+      unit({
+        unitId: 'u1',
+        containerNumber: 'MSFH8596324',
+        returnId: 'r1',
+        returnStatus: 'ASSIGNED_STORAGE',
+      }),
+      unit({ unitId: 'u2', containerNumber: 'SDJU8596324' }),
+    ]);
+
+    expect(rows[0]).toMatchObject({ expectedCount: 2, recordedCount: 1, pendingCount: 1 });
+    expect(rows[0].containers[0].returnStatus).toBe('ASSIGNED_STORAGE');
+  });
+
+  it('drops a booking once every container is recorded', () => {
+    const rows = assembleEmptyReturnBookings([
+      unit({
+        unitId: 'u1',
+        containerNumber: 'MSFH8596324',
+        returnId: 'r1',
+        returnStatus: 'RETURNED',
+      }),
+      unit({
+        unitId: 'u2',
+        containerNumber: 'SDJU8596324',
+        returnId: 'r2',
+        returnStatus: 'COMPLETED',
+      }),
+    ]);
+
+    expect(rows).toEqual([]);
+  });
+
+  it('keeps each booking on its own row, in query order', () => {
+    const other = {
+      ...booking,
+      bookingId: 'b2',
+      bookingReference: 'BK-2026-000286',
+      companyName: 'DE BE KE',
+    };
+    const rows = assembleEmptyReturnBookings([
+      unit({ unitId: 'u1', containerNumber: 'MSFH8596324' }),
+      { ...unit({ unitId: 'u2', containerNumber: 'ASDS1234567' }), ...other },
+      unit({ unitId: 'u3', containerNumber: 'SDJU8596324' }),
+    ]);
+
+    expect(rows.map((r) => r.bookingReference)).toEqual(['BK-2026-000263', 'BK-2026-000286']);
+    expect(rows[0].containers).toHaveLength(2);
+    expect(rows[1].containers).toHaveLength(1);
+  });
+
+  it('returns nothing when no booking owes an empty', () => {
+    expect(assembleEmptyReturnBookings([])).toEqual([]);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/import-operations/empty-return-bookings.util.ts b/apps/edr-freight-api/src/modules/import-operations/empty-return-bookings.util.ts
new file mode 100644
index 000000000..e2f56df9d
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/import-operations/empty-return-bookings.util.ts
@@ -0,0 +1,107 @@
+import type { EmptyContainerReturnStatus } from './entities/empty-container-return.entity';
+
+/**
+ * `WITH_RETURN` is the current value; `RETURN` is what older bookings were
+ * written with. Both mean the same thing — the booking owes empties back.
+ */
+export const WITH_RETURN_EQUIPMENT_VALUES = ['WITH_RETURN', 'RETURN'];
+
+/** Bookings in these statuses never ship, so they never owe an empty back. */
+export const EMPTY_RETURN_CLOSED_BOOKING_STATUSES = ['DRAFT', 'CANCELLED', 'REJECTED', 'EXPIRED'];
+
+/**
+ * One flagged return container of a booking, as the query hands it over: the
+ * booking columns repeat on every row, and `returnId` is set when this exact
+ * container already has an empty return recorded against the booking.
+ */
+export interface EmptyReturnBookingUnitRow {
+  bookingId: string;
+  bookingReference: string;
+  bookingStatus: string;
+  equipmentReturn: string;
+  customerId: string | null;
+  companyName: string | null;
+  unitId: string;
+  containerNumber: string;
+  containerSize: string | null;
+  containerType: string | null;
+  returnId: string | null;
+  returnStatus: EmptyContainerReturnStatus | null;
+}
+
+/** One container a booking owes back empty. */
+export interface EmptyReturnBookingContainer {
+  /** Stable row key — the booking container unit id. */
+  key: string;
+  unitId: string;
+  containerNumber: string;
+  containerSize: string | null;
+  containerType: string | null;
+  /** Set once the empty return for this container has been recorded. */
+  returnId: string | null;
+  returnStatus: EmptyContainerReturnStatus | null;
+}
+
+/** A booking that ships with empty-container return and still owes empties. */
+export interface EmptyReturnBookingRow {
+  bookingId: string;
+  bookingReference: string;
+  bookingStatus: string;
+  equipmentReturn: string;
+  customerId: string | null;
+  companyName: string | null;
+  containers: EmptyReturnBookingContainer[];
+  expectedCount: number;
+  recordedCount: number;
+  pendingCount: number;
+}
+
+/**
+ * Groups a booking's flagged return containers onto one row per booking.
+ *
+ * A container whose empty return is already recorded keeps its row — the
+ * screen shows what has been done — but stops counting as pending, and a
+ * booking with nothing left pending drops off the list entirely.
+ *
+ * Row order follows the query (newest booking first, containers in booking
+ * order), so the caller decides the ordering, not this function.
+ */
+export function assembleEmptyReturnBookings(
+  units: EmptyReturnBookingUnitRow[],
+): EmptyReturnBookingRow[] {
+  const rows = new Map<string, EmptyReturnBookingRow>();
+
+  for (const unit of units) {
+    const row = rows.get(unit.bookingId) ?? {
+      bookingId: unit.bookingId,
+      bookingReference: unit.bookingReference,
+      bookingStatus: unit.bookingStatus,
+      equipmentReturn: unit.equipmentReturn,
+      customerId: unit.customerId,
+      companyName: unit.companyName,
+      containers: [],
+      expectedCount: 0,
+      recordedCount: 0,
+      pendingCount: 0,
+    };
+    row.containers.push({
+      key: unit.unitId,
+      unitId: unit.unitId,
+      containerNumber: unit.containerNumber,
+      containerSize: unit.containerSize,
+      containerType: unit.containerType,
+      returnId: unit.returnId,
+      returnStatus: unit.returnStatus,
+    });
+    rows.set(unit.bookingId, row);
+  }
+
+  return [...rows.values()]
+    .map((row) => ({
+      ...row,
+      expectedCount: row.containers.length,
+      recordedCount: row.containers.filter((container) => container.returnId).length,
+      pendingCount: row.containers.filter((container) => !container.returnId).length,
+    }))
+    .filter((row) => row.pendingCount > 0);
+}
diff --git a/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts b/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
index 1116e9440..53875d64d 100644
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
@@ -119,6 +119,15 @@ export class ImportOperationsController {
     return this.service.listEmptyReturns();
   }
 
+  @Get('empty-return-bookings')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
+  @ApiOperation({
+    summary: 'Bookings shipping with empty-container return that still owe empties, with their containers',
+  })
+  listEmptyReturnBookings() {
+    return this.service.listEmptyReturnBookings();
+  }
+
   @Post('empty-container-returns')
   @BookingStaff(FREIGHT_PERMS.bookings.operations)
   @ApiOperation({ summary: 'Batch 16: create an empty container return record' })
diff --git a/apps/edr-freight-api/src/modules/import-operations/import-operations.module.ts b/apps/edr-freight-api/src/modules/import-operations/import-operations.module.ts
index 8cdc83853..d6cb00fd2 100644
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.module.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.module.ts
@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { BookingsModule } from '../bookings/bookings.module';
+import { EmptyReturnRequestsModule } from '../empty-return-requests/empty-return-requests.module';
 import { NotificationInboxModule } from '../notification-inbox/notification-inbox.module';
 import { NotificationsModule } from '../notifications/notifications.module';
 import { WarehousesModule } from '../warehouses/warehouses.module';
@@ -26,6 +27,9 @@ import { ImportOperationsService } from './import-operations.service';
     BookingsModule,
     NotificationInboxModule,
     NotificationsModule,
+    // Recording a return is what closes out the customer's scheduled empty
+    // return request, once every container on it is back.
+    EmptyReturnRequestsModule,
   ],
   controllers: [ImportOperationsController],
   providers: [ImportOperationsService],
diff --git a/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts b/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
index 9a84a0551..6333af97e 100644
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
@@ -8,6 +8,7 @@ import { logoImageCss, logoMarkup } from '../billing/documents/logo-markup.util'
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import { NotificationsService } from '../notifications/notifications.service';
 import { sendCompanyChannels } from '../notifications/notify-company.util';
+import { EmptyReturnRequestsService } from '../empty-return-requests/empty-return-requests.service';
 import { WarehouseReleaseDocumentService } from '../warehouses/warehouse-release-document.service';
 import {
   BulkCreateEmptyContainerReturnsDto,
@@ -25,6 +26,13 @@ import {
   type DjiboutiIncidentType,
 } from './entities/djibouti-incident.entity';
 import { assertWagonLoad } from './empty-container-wagon.util';
+import {
+  assembleEmptyReturnBookings,
+  EMPTY_RETURN_CLOSED_BOOKING_STATUSES,
+  WITH_RETURN_EQUIPMENT_VALUES,
+  type EmptyReturnBookingRow,
+  type EmptyReturnBookingUnitRow,
+} from './empty-return-bookings.util';
 import {
   EmptyContainerReturn,
   type EmptyContainerReturnListItem,
@@ -57,6 +65,7 @@ export class ImportOperationsService {
     private readonly logoSettings: LogoSettingsService,
     private readonly inbox: NotificationInboxService,
     private readonly notifications: NotificationsService,
+    private readonly emptyReturnRequests: EmptyReturnRequestsService,
   ) {}
 
   listIncidents(bookingId?: string) {
@@ -207,6 +216,51 @@ export class ImportOperationsService {
     return this.emptyReturns.find({ where: { bookingId }, order: { createdAt: 'DESC' } as never });
   }
 
+  /**
+   * Bookings that ship WITH empty-container return and still owe empties, each
+   * with the containers that are to be returned — the ones the booking flagged
+   * `is_return`, carrying the empty return already recorded against each, if
+   * any.
+   */
+  async listEmptyReturnBookings(): Promise<EmptyReturnBookingRow[]> {
+    const units: EmptyReturnBookingUnitRow[] = await this.emptyReturns.manager.query(
+      `SELECT b.id                       AS "bookingId",
+              b.reference                AS "bookingReference",
+              b.status                   AS "bookingStatus",
+              b.equipment_return         AS "equipmentReturn",
+              b.company_id               AS "customerId",
+              c.name                     AS "companyName",
+              u.id                       AS "unitId",
+              u.container_number         AS "containerNumber",
+              COALESCE(bc.container_size, ct.code) AS "containerSize",
+              ct.label                   AS "containerType",
+              r.id                       AS "returnId",
+              r.status                   AS "returnStatus"
+         FROM freight.booking_container_units u
+         JOIN freight.booking_container bc ON bc.id = u.booking_container_id AND bc.deleted_at IS NULL
+         JOIN freight.bookings b ON b.id = bc.booking_id AND b.deleted_at IS NULL
+         LEFT JOIN freight.companies c ON c.id = b.company_id
+         LEFT JOIN freight.container_types ct ON ct.id = bc.container_type_id
+         LEFT JOIN LATERAL (
+           SELECT er.id, er.status
+             FROM freight.empty_container_returns er
+            WHERE er.deleted_at IS NULL
+              AND er.booking_id = b.id
+              AND upper(er.container_number) = upper(u.container_number)
+            ORDER BY er.created_at DESC
+            LIMIT 1
+         ) r ON TRUE
+        WHERE u.deleted_at IS NULL
+          AND u.is_return = true
+          AND b.equipment_return = ANY($1)
+          AND b.status <> ALL($2)
+        ORDER BY b.created_at DESC, u.sort_order ASC`,
+      [WITH_RETURN_EQUIPMENT_VALUES, EMPTY_RETURN_CLOSED_BOOKING_STATUSES],
+    );
+
+    return assembleEmptyReturnBookings(units);
+  }
+
   async createEmptyReturn(dto: CreateEmptyContainerReturnDto) {
     const returnDate = dto.returnDate ? new Date(dto.returnDate) : new Date();
     const saved = await this.emptyReturns.save(
@@ -236,6 +290,8 @@ export class ImportOperationsService {
     // Standalone returns (no booking) have no company to notify.
     if (saved.bookingId) {
       await this.notifyEquipmentInterchangeReady(saved);
+      // Closes the customer's scheduled request once its last container is in.
+      await this.emptyReturnRequests.settleScheduledForBooking(saved.bookingId);
     }
     return saved;
   }
diff --git a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
index 37612d318..8d56bd0d7 100644
--- a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
@@ -378,6 +378,13 @@ export class LastMileRequestsService {
       contractGeneratedAt: new Date(),
     } as Partial<LastMileRequest>);
 
+    // Only now, with the request APPROVED, is an advance actually owed on the
+    // leg. The warehouse auto-accept (IMPORT inspection PASSED) may have already
+    // opened that leg at READY_TO_TRANSIT, so pull it back to PAYMENT_PENDING —
+    // otherwise this booking would be dispatchable before the customer has
+    // signed the contract or paid a birr. No-op for a leg this call just created.
+    await this.lastMileService.holdForAdvance(lastMile.id);
+
     if (booking.companyId) {
       void this.notifications.notify({
         recipients: { companyId: booking.companyId },
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.advance-gate.spec.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.advance-gate.spec.ts
new file mode 100644
index 000000000..8e0b8ba55
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.advance-gate.spec.ts
@@ -0,0 +1,214 @@
+import { BadRequestException } from '@nestjs/common';
+import type { DataSource } from 'typeorm';
+
+import { ADVANCE_UNPAID_MESSAGE, LastMileService } from './last-mile.service';
+import type { LastMileStatus } from './entities/last-mile.entity';
+import type { UpdateLastMileDto } from './dto/update-last-mile.dto';
+
+/**
+ * The advance gate: a delivery becomes dispatchable (READY_TO_TRANSIT) or moves
+ * (IN_TRANSIT) only once the customer has paid the advance the Truck & Machinery
+ * chief approved.
+ *
+ * It used to leak both ways. The warehouse auto-accept (IMPORT inspection
+ * PASSED) opens the leg at READY_TO_TRANSIT and runs independently of the
+ * review, so whichever side acted second found the other already done: accept
+ * first and the leg was dispatchable before an advance was ever asked for;
+ * approve first and create() handed the existing dispatchable leg straight back
+ * untouched.
+ */
+function makeService(
+  opts: {
+    /** APPROVED requests on the booking carrying a positive advance. */
+    advancesDue?: number;
+    /** PAID LAST_MILE_ADVANCE invoices on the leg. */
+    advancesPaid?: number;
+    status?: LastMileStatus;
+  } = {},
+) {
+  const leg = {
+    id: 'lm-1',
+    bookingId: 'b-1',
+    status: opts.status ?? 'READY_TO_TRANSIT',
+    vehicleId: 'v-1',
+    booking: { reference: 'BK-001' },
+  };
+
+  const query = jest.fn((sql: string) => {
+    if (sql.includes('customer_truck_assignments')) return Promise.resolve([]);
+    // The batched list enrichment, not the gate's own lookup.
+    if (sql.includes('FROM freight.last_mile lm')) return Promise.resolve([]);
+    if (sql.includes('freight.last_mile_requests')) {
+      return Promise.resolve([{ count: opts.advancesDue ?? 0 }]);
+    }
+    // Discriminated on the charge type, not the table: attachMileFinancials
+    // also queries freight.invoices (for the booking-invoice advance line).
+    if (sql.includes('LAST_MILE_ADVANCE')) {
+      return Promise.resolve([{ count: opts.advancesPaid ?? 0 }]);
+    }
+    if (sql.includes('FROM freight.bookings')) {
+      return Promise.resolve([
+        { tradeDirection: 'IMPORT', firstMile: null, lastMile: 'Bole, Addis Ababa' },
+      ]);
+    }
+    return Promise.resolve([]);
+  });
+
+  const lastMileRepository = {
+    findAll: jest.fn().mockResolvedValue([]),
+    findById: jest.fn().mockResolvedValue(leg),
+    create: jest.fn((row: unknown) => Promise.resolve({ id: 'lm-1', ...(row as object) })),
+    update: jest.fn((_id: string, patch: object) => Promise.resolve({ ...leg, ...patch })),
+  };
+
+  const service = new LastMileService(
+    lastMileRepository as never,
+    {} as never, // bookingsRepository
+    {
+      findById: jest.fn().mockResolvedValue({
+        id: 'v-1',
+        plateNumber: 'AA-123',
+        assignedDriverId: 'd-1',
+        assignedDriverName: 'Driver',
+      }),
+      setAvailability: jest.fn(),
+      releaseIfUnused: jest.fn(),
+    } as never, // vehiclesService
+    {} as never, // driversService
+    {} as never, // smsClient
+    {
+      query,
+      // DELIVERED frees the trucks this leg was holding.
+      manager: {
+        find: jest.fn().mockResolvedValue([]),
+        count: jest.fn().mockResolvedValue(0),
+      },
+    } as unknown as DataSource,
+    { record: jest.fn() } as never, // history
+    { findBySourceIds: jest.fn().mockResolvedValue([]) } as never, // billing
+    { findLiveRatesDetailed: jest.fn().mockResolvedValue([]) } as never, // ratesService
+    {} as never, // filesService
+  );
+
+  return { service, lastMileRepository, leg };
+}
+
+const createdStatus = (repo: { create: jest.Mock }) =>
+  (repo.create.mock.calls[0]?.[0] as { status?: string } | undefined)?.status;
+
+describe('LastMileService - advance gate on creation', () => {
+  it('opens an auto-accepted leg at PAYMENT_PENDING when an advance is owed', async () => {
+    const { service, lastMileRepository } = makeService({ advancesDue: 1 });
+
+    // The warehouse path asks for no status at all - it used to get
+    // READY_TO_TRANSIT and hand the customer a dispatchable unpaid delivery.
+    await service.create({ bookingId: 'b-1', advancedPayment: 0 } as never);
+
+    expect(createdStatus(lastMileRepository)).toBe('PAYMENT_PENDING');
+  });
+
+  it('still opens at READY_TO_TRANSIT when no approved request owes an advance', async () => {
+    const { service, lastMileRepository } = makeService({ advancesDue: 0 });
+
+    await service.create({ bookingId: 'b-1', advancedPayment: 0 } as never);
+
+    expect(createdStatus(lastMileRepository)).toBe('READY_TO_TRANSIT');
+  });
+});
+
+describe('LastMileService - advance gate on transitions', () => {
+  it('refuses IN_TRANSIT while the advance is unpaid', async () => {
+    const { service } = makeService({ advancesDue: 1, advancesPaid: 0 });
+
+    await expect(
+      service.update('lm-1', { status: 'IN_TRANSIT' } as UpdateLastMileDto),
+    ).rejects.toThrow(ADVANCE_UNPAID_MESSAGE);
+  });
+
+  it('refuses a leg being made dispatchable while the advance is unpaid', async () => {
+    const { service } = makeService({
+      advancesDue: 1,
+      advancesPaid: 0,
+      status: 'PAYMENT_PENDING',
+    });
+
+    await expect(
+      service.update('lm-1', { status: 'READY_TO_TRANSIT' } as UpdateLastMileDto),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('allows IN_TRANSIT once the advance invoice is paid', async () => {
+    const { service } = makeService({ advancesDue: 1, advancesPaid: 1 });
+
+    const updated = await service.update('lm-1', {
+      status: 'IN_TRANSIT',
+    } as UpdateLastMileDto);
+
+    expect(updated.status).toBe('IN_TRANSIT');
+  });
+
+  it('requires one paid advance per approved departure', async () => {
+    // Containers arriving across two departures get a request - and an advance
+    // - each. One paid advance does not release the second.
+    const { service } = makeService({ advancesDue: 2, advancesPaid: 1 });
+
+    await expect(
+      service.update('lm-1', { status: 'IN_TRANSIT' } as UpdateLastMileDto),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('lets the paid listener through before the invoice row is visible', async () => {
+    // Billing emits inline, pre-commit, when the transition joins a caller's
+    // transaction - so the invoice still reads unpaid here. The event is the
+    // proof of payment; re-reading the row would refuse the transition the
+    // payment just earned.
+    const { service } = makeService({
+      advancesDue: 1,
+      advancesPaid: 0,
+      status: 'PAYMENT_PENDING',
+    });
+
+    const updated = await service.update(
+      'lm-1',
+      { status: 'READY_TO_TRANSIT' } as UpdateLastMileDto,
+      { advanceSettled: true },
+    );
+
+    expect(updated.status).toBe('READY_TO_TRANSIT');
+  });
+
+  it('leaves states that are not transit alone', async () => {
+    const { service } = makeService({ advancesDue: 1, advancesPaid: 0 });
+
+    await expect(
+      service.update('lm-1', { status: 'DELIVERED' } as UpdateLastMileDto),
+    ).resolves.toBeDefined();
+  });
+});
+
+describe('LastMileService.holdForAdvance', () => {
+  it('pulls an already-dispatchable leg back when approval imposes an advance', async () => {
+    const { service, lastMileRepository } = makeService({
+      advancesDue: 1,
+      status: 'READY_TO_TRANSIT',
+    });
+
+    await service.holdForAdvance('lm-1');
+
+    expect(lastMileRepository.update).toHaveBeenCalledWith(
+      'lm-1',
+      expect.objectContaining({ status: 'PAYMENT_PENDING' }),
+    );
+  });
+
+  it('never rewrites a leg that is already on the road', async () => {
+    const { service, lastMileRepository } = makeService({
+      advancesDue: 1,
+      status: 'IN_TRANSIT',
+    });
+
+    await service.holdForAdvance('lm-1');
+
+    expect(lastMileRepository.update).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
index 8ed5ae8aa..4f8acd03a 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
@@ -59,6 +59,13 @@ const SORTABLE_FIELDS: (keyof LastMile)[] = [
   'createdAt',
 ];
 
+/** The states that mean the delivery is dispatchable or already on the road. */
+const TRANSIT_STATUSES: LastMileStatus[] = ['READY_TO_TRANSIT', 'IN_TRANSIT'];
+
+export const ADVANCE_UNPAID_MESSAGE =
+  'The last-mile advance has not been paid yet — this delivery cannot become ' +
+  'dispatchable or move until the advance invoice is settled.';
+
 @Injectable()
 export class LastMileService {
   private readonly logger = new Logger(LastMileService.name);
@@ -93,9 +100,47 @@ export class LastMileService {
     for (const r of records) {
       (r as LastMile & { invoice?: unknown }).invoice = byId.get(r.id) ?? null;
     }
+    await this.attachAdvanceState(records);
     await attachMileFinancials(this.dataSource, records, 'LAST_MILE');
   }
 
+  /**
+   * Flag the legs whose advance is still owed, so the UI can disable the actions
+   * the API would refuse instead of firing them into a 400. Same rule as
+   * {@link advanceOutstanding}, batched over the whole page.
+   */
+  private async attachAdvanceState(records: LastMile[]): Promise<void> {
+    const ids = records.map((r) => r.id).filter(Boolean);
+    if (!ids.length) return;
+    const rows: Array<{ lastMileId: string; due: number; paid: number }> =
+      await this.dataSource.query(
+        `SELECT lm.id AS "lastMileId",
+                (SELECT COUNT(*)
+                   FROM freight.last_mile_requests lmr
+                  WHERE lmr.booking_id = lm.booking_id
+                    AND lmr.deleted_at IS NULL
+                    AND lmr.status = 'APPROVED'
+                    AND COALESCE(lmr.approved_advance_amount, 0) > 0)::int AS "due",
+                (SELECT COUNT(*)
+                   FROM freight.invoices i
+                  WHERE i.source = 'last_mile'
+                    AND i.source_id = lm.id::text
+                    AND i.type = 'LAST_MILE_ADVANCE'
+                    AND i.status = 'PAID'
+                    AND i.deleted_at IS NULL)::int AS "paid"
+           FROM freight.last_mile lm
+          WHERE lm.id = ANY($1::uuid[]) AND lm.deleted_at IS NULL`,
+        [ids],
+      );
+    const outstanding = new Map(
+      rows.map((r) => [r.lastMileId, Number(r.due) > Number(r.paid)]),
+    );
+    for (const r of records) {
+      (r as LastMile & { advanceOutstanding?: boolean }).advanceOutstanding =
+        outstanding.get(r.id) ?? false;
+    }
+  }
+
   /** Resolve a vehicle's driver + human labels, for stamping mile events onto
    *  the driver's timeline and naming the vehicle. Best-effort — never throws. */
   private async vehicleInfo(
@@ -185,6 +230,67 @@ export class LastMileService {
     }
   }
 
+  /**
+   * Whether this booking still owes an advance on its delivery.
+   *
+   * An advance is owed for every APPROVED last-mile request carrying a positive
+   * approved amount — a booking whose containers arrive across several
+   * departures gets a request, and therefore an advance, per departure. Each is
+   * settled by a PAID `LAST_MILE_ADVANCE` invoice raised on the leg when the
+   * customer signs that request's contract, so the leg is clear only once it has
+   * as many paid advance invoices as the booking has approved requests.
+   *
+   * A booking with no approved request owes nothing and is unaffected: legs that
+   * never went through the confirmation flow keep behaving exactly as before.
+   * `lastMileId` is null while the leg is still being created — no invoice can
+   * point at a row that does not exist yet, so nothing can have been settled.
+   */
+  private async advanceOutstanding(
+    bookingId: string,
+    lastMileId: string | null,
+  ): Promise<boolean> {
+    const [due] = await this.dataSource.query(
+      `SELECT COUNT(*)::int AS "count"
+         FROM freight.last_mile_requests lmr
+        WHERE lmr.booking_id = $1
+          AND lmr.deleted_at IS NULL
+          AND lmr.status = 'APPROVED'
+          AND COALESCE(lmr.approved_advance_amount, 0) > 0`,
+      [bookingId],
+    );
+    const owed = Number(due?.count ?? 0);
+    if (!owed) return false;
+    if (!lastMileId) return true;
+
+    const [paid] = await this.dataSource.query(
+      `SELECT COUNT(*)::int AS "count"
+         FROM freight.invoices i
+        WHERE i.source = 'last_mile'
+          AND i.source_id = $1
+          AND i.type = 'LAST_MILE_ADVANCE'
+          AND i.status = 'PAID'
+          AND i.deleted_at IS NULL`,
+      [lastMileId],
+    );
+    return Number(paid?.count ?? 0) < owed;
+  }
+
+  /**
+   * Hold a leg at PAYMENT_PENDING because an advance has just been imposed on it.
+   *
+   * The warehouse auto-accept (IMPORT inspection PASSED) opens the leg
+   * independently of the chief's review, and opens it at READY_TO_TRANSIT. When
+   * that happens first, approval has to pull the leg back — otherwise the advance
+   * gate never holds on that ordering and the delivery is dispatchable unpaid.
+   * A leg already IN_TRANSIT or DELIVERED is left alone: that is a record of what
+   * happened, not a plan that can still be changed.
+   */
+  async holdForAdvance(id: string): Promise<void> {
+    const record = await this.findById(id);
+    if (record.status !== 'READY_TO_TRANSIT') return;
+    await this.update(id, { status: 'PAYMENT_PENDING' } as UpdateLastMileDto);
+  }
+
   async acceptBooking(bookingReference: string): Promise<LastMile | null> {
     const booking = await this.bookingsRepository.findByReference(bookingReference);
 
@@ -425,9 +531,16 @@ export class LastMileService {
 
     await this.assertEdrHaulsThisBooking(dto.bookingId);
 
+    // A leg that owes an advance is not dispatchable, whatever the caller asked
+    // for. The warehouse auto-accept path asks for no status at all and used to
+    // land straight in READY_TO_TRANSIT, which let an unpaid delivery go.
+    const status: LastMileStatus = (await this.advanceOutstanding(dto.bookingId, null))
+      ? 'PAYMENT_PENDING'
+      : (dto.status ?? 'READY_TO_TRANSIT');
+
     const record = await this.lastMileRepository.create({
       bookingId: dto.bookingId,
-      status: dto.status ?? 'READY_TO_TRANSIT',
+      status,
       advancedPayment: dto.advancedPayment ?? 0,
       remainingPayment: dto.remainingPayment ?? 0,
       estimatedKm: dto.estimatedKm ?? (await estimateMileKm(this.dataSource, dto.bookingId, 'LAST')),
@@ -461,11 +574,16 @@ export class LastMileService {
   async onBookingInvoicePaid(payload: InvoiceEventPayload): Promise<void> {
     try {
       if (payload.type === 'LAST_MILE_ADVANCE') {
-        // Advance paid → the leg becomes dispatchable, not delivered.
-        await this.update(payload.sourceId, {
-          status: 'READY_TO_TRANSIT',
-          advancedPayment: payload.totalAmount,
-        } as unknown as UpdateLastMileDto);
+        // Advance paid → the leg becomes dispatchable, not delivered. This event
+        // IS the settlement, so it carries its own way past the advance gate.
+        await this.update(
+          payload.sourceId,
+          {
+            status: 'READY_TO_TRANSIT',
+            advancedPayment: payload.totalAmount,
+          } as unknown as UpdateLastMileDto,
+          { advanceSettled: true },
+        );
         this.logger.log(
           `Last-mile ${payload.sourceId} READY_TO_TRANSIT on advance invoice ${payload.invoiceId} payment`,
         );
@@ -484,9 +602,32 @@ export class LastMileService {
     }
   }
 
-  async update(id: string, dto: UpdateLastMileDto): Promise<LastMile> {
+  /**
+   * `opts.advanceSettled` is the paid listener's own bypass, and nothing else
+   * should pass it: the invoice event is itself the proof of payment, and it can
+   * reach us inline before the invoice row commits (billing emits before commit
+   * when the transition is enlisted in a caller-supplied manager), so re-reading
+   * the invoice here would still see it unpaid and refuse the very transition the
+   * payment just earned.
+   */
+  async update(
+    id: string,
+    dto: UpdateLastMileDto,
+    opts: { advanceSettled?: boolean } = {},
+  ): Promise<LastMile> {
     const existing = await this.findById(id);
 
+    // Nothing becomes dispatchable, and nothing moves, until the advance is paid.
+    if (
+      !opts.advanceSettled &&
+      dto.status !== undefined &&
+      dto.status !== existing.status &&
+      TRANSIT_STATUSES.includes(dto.status) &&
+      (await this.advanceOutstanding(existing.bookingId, id))
+    ) {
+      throw new BadRequestException(ADVANCE_UNPAID_MESSAGE);
+    }
+
     // A leg can only go IN_TRANSIT once a vehicle is assigned (allowing a vehicle
     // assigned in this same request).
     if (dto.status === 'IN_TRANSIT' && existing.status !== 'IN_TRANSIT') {
diff --git a/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts b/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts
index 467b172ba..1dd8ad9ca 100644
--- a/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts
+++ b/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts
@@ -83,3 +83,184 @@ export async function notifyCarriageAcceptanceReady(
     logger.warn(`Carriage acceptance ready notify failed for ${bookingId}: ${(err as Error).message}`);
   }
 }
+
+/** One container line on the load manifest notice. */
+interface LoadManifestLists {
+  reference: string;
+  companyId: string | null;
+  trainNumber: string | null;
+  originStation: string | null;
+  destinationStation: string | null;
+  departureAt: Date | null;
+  loaded: string[];
+  leftBehind: string[];
+}
+
+/** At most `max` numbers, then "+N more" — an SMS must not carry 44 of them. */
+function summarizeNumbers(numbers: string[], max = 5): string {
+  if (numbers.length === 0) return 'none';
+  const shown = numbers.slice(0, max).join(', ');
+  const rest = numbers.length - max;
+  return rest > 0 ? `${shown} +${rest} more` : shown;
+}
+
+/**
+ * Read what actually went on the train and what did not. Left behind = every
+ * container the customer declared minus the ones sitting on a LOADED/DEPARTED
+ * wagon, so a booking loaded in parts reports honestly on both halves.
+ */
+export async function loadManifestLists(
+  dataSource: DataSource,
+  bookingId: string,
+  trainScheduleId: string,
+): Promise<LoadManifestLists | null> {
+  const [booking]: Array<{ reference: string; companyId: string | null }> =
+    await dataSource.query(
+      `SELECT reference, company_id AS "companyId"
+         FROM freight.bookings
+        WHERE id = $1 AND deleted_at IS NULL`,
+      [bookingId],
+    );
+  if (!booking) return null;
+
+  const [train]: Array<{
+    trainNumber: string | null;
+    originStation: string | null;
+    destinationStation: string | null;
+    departureAt: Date | null;
+  }> = await dataSource.query(
+    `SELECT s.train_number              AS "trainNumber",
+            so.label                    AS "originStation",
+            sd.label                    AS "destinationStation",
+            s.scheduled_departure_date  AS "departureAt"
+       FROM freight.train_schedules s
+       LEFT JOIN freight.yards so ON so.id = s.origin_station_id
+       LEFT JOIN freight.yards sd ON sd.id = s.destination_station_id
+      WHERE s.id = $1 AND s.deleted_at IS NULL`,
+    [trainScheduleId],
+  );
+
+  const loadedRows: Array<{ containerNumber: string | null }> = await dataSource.query(
+    `SELECT DISTINCT ci.container_number AS "containerNumber"
+       FROM freight.wagon_allocation_container_items ci
+       JOIN freight.wagon_booking_allocations a
+         ON a.id = ci.wagon_booking_allocation_id AND a.deleted_at IS NULL
+      WHERE a.booking_id = $1
+        AND ci.deleted_at IS NULL
+        AND a.status IN ('LOADED', 'DEPARTED')
+      ORDER BY 1`,
+    [bookingId],
+  );
+  const declaredRows: Array<{ containerNumber: string | null }> = await dataSource.query(
+    `SELECT DISTINCT u.container_number AS "containerNumber"
+       FROM freight.booking_container_units u
+       JOIN freight.booking_container l
+         ON l.id = u.booking_container_id AND l.deleted_at IS NULL
+      WHERE l.booking_id = $1 AND u.deleted_at IS NULL
+      ORDER BY 1`,
+    [bookingId],
+  );
+
+  const loaded = loadedRows.map((r) => r.containerNumber).filter(Boolean) as string[];
+  const loadedSet = new Set(loaded);
+  const leftBehind = (declaredRows.map((r) => r.containerNumber).filter(Boolean) as string[]).filter(
+    (n) => !loadedSet.has(n),
+  );
+
+  return {
+    reference: booking.reference,
+    companyId: booking.companyId,
+    trainNumber: train?.trainNumber ?? null,
+    originStation: train?.originStation ?? null,
+    destinationStation: train?.destinationStation ?? null,
+    departureAt: train?.departureAt ?? null,
+    loaded,
+    leftBehind,
+  };
+}
+
+/**
+ * Tell the customer what boarded the train and what did not, over in-app + SMS
+ * + email, and raise a warehouse-desk notice for anything left behind so
+ * somebody owns finding it space. A booking is routinely loaded in parts, and
+ * before this the customer learnt about it only by reading the sheet.
+ *
+ * Best-effort throughout: loading must never roll back because a provider is
+ * down.
+ */
+export async function notifyLoadManifest(
+  dataSource: DataSource,
+  notifications: NotificationsService,
+  inbox: NotificationInboxService,
+  bookingId: string,
+  trainScheduleId: string,
+  warehouseNotificationPermission: string,
+  logger: Logger,
+): Promise<void> {
+  try {
+    const m = await loadManifestLists(dataSource, bookingId, trainScheduleId);
+    if (!m) return;
+
+    const route =
+      m.originStation && m.destinationStation
+        ? ` ${m.originStation} → ${m.destinationStation}`
+        : '';
+    const departs = m.departureAt
+      ? `, departs ${new Date(m.departureAt).toLocaleString('en-GB')}`
+      : '';
+    const train = m.trainNumber ? `train ${m.trainNumber}` : 'the train';
+
+    const headline =
+      `Booking ${m.reference}: ${m.loaded.length} container(s) loaded on ${train}` +
+      `${route}${departs}.`;
+    const loadedLine = m.loaded.length > 0 ? ` Loaded: ${summarizeNumbers(m.loaded)}.` : '';
+    const leftLine =
+      m.leftBehind.length > 0
+        ? ` Not loaded (${m.leftBehind.length}): ${summarizeNumbers(m.leftBehind)}.` +
+          ' These stay with EDR — once a warehouse is assigned you will receive the GRN.'
+        : '';
+    const body = headline + loadedLine + leftLine;
+
+    if (m.companyId) {
+      await inbox.notify({
+        recipients: { companyId: m.companyId },
+        audience: NotificationAudience.PORTAL,
+        type: NotificationType.BOOKING_STATUS,
+        title: m.leftBehind.length > 0 ? 'Cargo partly loaded' : 'Cargo loaded',
+        // The in-app copy carries every number; SMS and email get the summary.
+        body:
+          headline +
+          (m.loaded.length > 0 ? `\nLoaded: ${m.loaded.join(', ')}` : '') +
+          (m.leftBehind.length > 0
+            ? `\nNot loaded: ${m.leftBehind.join(', ')}\nThese stay with EDR — once a warehouse is assigned you will receive the GRN.`
+            : ''),
+        link: `/bookings/${bookingId}`,
+        data: {
+          bookingId,
+          reference: m.reference,
+          trainNumber: m.trainNumber,
+          loaded: m.loaded,
+          leftBehind: m.leftBehind,
+        },
+      });
+      await sendCompanyChannels(dataSource, notifications, m.companyId, body);
+    }
+
+    // Nothing left behind is nothing for the warehouse desk to place.
+    if (m.leftBehind.length > 0) {
+      await inbox.notify({
+        recipients: { permissionKeys: [warehouseNotificationPermission] },
+        audience: NotificationAudience.BACKOFFICE,
+        type: NotificationType.REQUEST_SUBMITTED,
+        title: `${m.leftBehind.length} container(s) left behind — ${m.reference}`,
+        body:
+          `${train} departed without ${m.leftBehind.length} container(s) of booking ${m.reference}: ` +
+          `${m.leftBehind.join(', ')}. Assign warehouse space and raise the GRN.`,
+        link: `/dashboard/booking-requests/${bookingId}`,
+        data: { bookingId, reference: m.reference, leftBehind: m.leftBehind },
+      });
+    }
+  } catch (err) {
+    logger.warn(`Load manifest notify failed for ${bookingId}: ${(err as Error).message}`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts b/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts
index 00f8d107a..086baef66 100644
--- a/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts
@@ -35,9 +35,24 @@ describe("isDomesticPhone", () => {
     (phone) => expect(isDomesticPhone(phone)).toBe(true),
   );
 
-  it.each(["+14155550123", "+447911123456", "0712345678", "+2519866", "12345"])(
-    "rejects non-domestic or malformed %s",
-    (phone) => expect(isDomesticPhone(phone)).toBe(false),
+  // Djibouti is the line's other end: the gateway reaches its 77x mobiles.
+  it.each(["+25377123456", "25377123456", "77123456"])(
+    "accepts Djibouti mobile form %s",
+    (phone) => expect(isDomesticPhone(phone)).toBe(true),
+  );
+
+  it.each([
+    "+14155550123",
+    "+447911123456",
+    "0712345678",
+    "+2519866",
+    "12345",
+    // Djibouti fixed line (2x) — valid number, not a mobile the gateway serves.
+    "+25321350000",
+    // Right length, wrong Djibouti prefix.
+    "+25366123456",
+  ])("rejects unreachable or malformed %s", (phone) =>
+    expect(isDomesticPhone(phone)).toBe(false),
   );
 });
 
diff --git a/apps/edr-freight-api/src/modules/otp/otp.service.ts b/apps/edr-freight-api/src/modules/otp/otp.service.ts
index b27520c25..6b5a0e0d9 100644
--- a/apps/edr-freight-api/src/modules/otp/otp.service.ts
+++ b/apps/edr-freight-api/src/modules/otp/otp.service.ts
@@ -42,20 +42,42 @@ function normalizePhone(rawPhone: string): string {
   if (digits.startsWith("+")) return digits;
   const bare = digits.replace(/^0+/, "");
   if (/^251\d{9}$/.test(digits)) return `+${digits}`;
+  if (/^253\d{8}$/.test(digits)) return `+${digits}`;
   if (/^9\d{8}$|^7\d{8}$/.test(bare)) return `+251${bare}`;
+  // Djibouti mobiles are 8 digits starting 77 and have no trunk prefix, so a
+  // bare "77…" is unambiguous — it cannot be an Ethiopian local number, which
+  // is always 9 digits after the trunk zero.
+  if (/^77\d{6}$/.test(bare)) return `+253${bare}`;
   // Unknown shape (foreign number, already-clean intl without +) — prefix + if
   // it looks like a full international number, else leave as typed.
   return digits.length >= 11 ? `+${digits}` : raw;
 }
 
 /**
- * Whether a phone is an Ethiopian mobile the SMS gateway can actually reach —
- * the carrier integration is domestic-only, so a send to anything else is
- * queued and silently lost. Callers use this to fall back to email instead of
- * pretending an SMS is on its way.
+ * Mobile ranges the SMS gateway is contracted to reach, as E.164 patterns.
+ *
+ * The gateway itself is opaque from here — `SmsClientService` publishes to
+ * RabbitMQ and the carrier sits several hops downstream — so this list is a
+ * policy statement, not a capability probe: a number outside it is treated as
+ * unreachable and callers fall back to email rather than promising an SMS that
+ * would be queued and silently dropped.
+ *
+ * - Ethiopia: `+2519…` mobiles only. `+2517…` is deliberately absent; it parses
+ *   as a valid ET number but is not a range this gateway delivers to.
+ * - Djibouti: `+25377…`, the country's only mobile range (2x is fixed-line).
+ */
+const REACHABLE_MOBILE_PATTERNS = [/^\+2519\d{8}$/, /^\+25377\d{6}$/];
+
+/**
+ * Whether a phone sits in a mobile range the SMS gateway can actually reach.
+ *
+ * Named "domestic" for the Ethiopian-only era this predates; it now covers both
+ * countries the railway runs through. Callers use it to fall back to email
+ * instead of pretending an SMS is on its way.
  */
 export function isDomesticPhone(rawPhone: string): boolean {
-  return /^\+2519\d{8}$/.test(normalizePhone(rawPhone));
+  const normalized = normalizePhone(rawPhone);
+  return REACHABLE_MOBILE_PATTERNS.some((p) => p.test(normalized));
 }
 
 /**
@@ -99,7 +121,7 @@ export class OtpService {
     private readonly otpRepository: OtpRepository,
     private readonly notifications: NotificationsService,
     private readonly emailClient: EmailClientService,
-  ) { }
+  ) {}
 
   // ---------------------------------------------------------------------------
   // Generate OTP
@@ -197,8 +219,10 @@ export class OtpService {
 
       for (const outcome of outcomes) {
         this.logger.log(
-          `otp.dispatch channel=${outcome.channel} target=${label} queued=${outcome.queued
-          } latencyMs=${Date.now() - startedAt}${outcome.error ? ` error=${outcome.error}` : ""
+          `otp.dispatch channel=${outcome.channel} target=${label} queued=${
+            outcome.queued
+          } latencyMs=${Date.now() - startedAt}${
+            outcome.error ? ` error=${outcome.error}` : ""
           }`,
         );
       }
@@ -222,7 +246,8 @@ export class OtpService {
         // user who never receives a code — indistinguishable from carrier loss,
         // and the misleading success response makes it look like our side worked.
         this.logger.error(
-          `otp.dispatch.dropped channels=${channels.join("+")} target=${label} rabbitmqEnabled=${process.env.RABBITMQ_ENABLED ?? "unset"
+          `otp.dispatch.dropped channels=${channels.join("+")} target=${label} rabbitmqEnabled=${
+            process.env.RABBITMQ_ENABLED ?? "unset"
           } — no transport reported hand-off; no code will arrive for this send`,
         );
       }
@@ -247,7 +272,8 @@ export class OtpService {
       // Log the real cause (DB/SMS/email failure) with its stack so a deployed
       // "Failed to send OTP" 400 is diagnosable from the API logs, not opaque.
       this.logger.error(
-        `otp.dispatch.failed channels=${channels.join("+")} target=${label} latencyMs=${Date.now() - startedAt
+        `otp.dispatch.failed channels=${channels.join("+")} target=${label} latencyMs=${
+          Date.now() - startedAt
         }: ${error instanceof Error ? error.message : String(error)}`,
         error instanceof Error ? error.stack : undefined,
       );
@@ -330,8 +356,9 @@ export class OtpService {
   ) {
     const line = `otp.verify channels=${channelsOf(target).join(
       "+",
-    )} target=${this.targetLabel(target)} mode=${mode} result=${result}${detail ? ` ${detail}` : ""
-      }`;
+    )} target=${this.targetLabel(target)} mode=${mode} result=${result}${
+      detail ? ` ${detail}` : ""
+    }`;
     if (result === "ok") this.logger.log(line);
     else this.logger.warn(line);
 
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
index 3fbecc036..f035f8a64 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
@@ -508,12 +508,12 @@ export class RuleEngineService {
 
     if (input.tradeDirection === 'IMPORT') {
       appliedModifiers.push(
-        ...this.derivedImportOverweight(
+        ...(await this.derivedImportOverweight(
           input,
           containerWeightResults,
           lineMaxVgmTons,
           liveRates,
-        ),
+        )),
       );
     }
 
@@ -540,23 +540,37 @@ export class RuleEngineService {
   }
 
   /**
-   * Import overweight — derived, never configured. Each overweight container
-   * line bills its excess tons at (its own base import freight on the booking's
-   * route) ÷ (2 × its weight limit): 20ft at 1000 USD with a 20 t limit →
-   * 25 USD per excess ton. Export keeps the configured OVERWEIGHT rate.
-   * Note: derives from the LIVE route rate even for frozen-rate contract
-   * bookings — the frozen snapshot has no route-scoped container price to
-   * divide.
+   * Import overweight — derived, never configured. Excess tons are billed on a
+   * PER-WAGON basis: (the wagon's base import freight on the booking's route)
+   * ÷ (2 × the container's weight limit).
+   *
+   * The rate is normalised to a wagon before dividing, because a 20ft rate
+   * quoted PER_CONTAINER prices only HALF a wagon — two 20ft ride one wagon —
+   * while a 40ft container IS the whole wagon. So a PER_CONTAINER 20ft rate is
+   * doubled first; 40ft (and any rate already quoted PER_WAGON) is taken as is:
+   *   - 20ft PER_CONTAINER 845 USD, 20 t limit → (845 × 2) / (2 × 20) = 42.25
+   *   - 40ft PER_CONTAINER 1676 USD, 40 t limit → 1676 / (2 × 40) = 20.95
+   * Halving over 2 × the limit keeps the original meaning: filling one wagon's
+   * worth of excess costs one extra wagon of freight.
+   *
+   * Export keeps the configured OVERWEIGHT rate. Note: derives from the LIVE
+   * route rate even for frozen-rate contract bookings — the frozen snapshot has
+   * no route-scoped container price to divide.
    */
-  private derivedImportOverweight(
+  private async derivedImportOverweight(
     input: BookingEvaluationInput,
     weightResults: ContainerWeightResult[],
     lineMaxVgmTons: Array<number | null>,
     liveRates: Rate[],
-  ): AppliedCargoModifier[] {
+  ): Promise<AppliedCargoModifier[]> {
     const modifiers: AppliedCargoModifier[] = [];
     if (!input.originYardId || !input.destinationYardId) return modifiers;
 
+    // How many of each container type ride one wagon: a 40ft fills a wagon,
+    // two 20ft share one. Keyed by container type so a PER_CONTAINER rate can
+    // be scaled up to the wagon the overweight formula prices against.
+    const sizeByTypeId = await this.containersPerWagonByTypeId(weightResults);
+
     for (let i = 0; i < weightResults.length; i++) {
       const wr = weightResults[i];
       const excess = Number(wr?.overweightExcessTons ?? 0);
@@ -578,7 +592,16 @@ export class RuleEngineService {
       // No base rate → the base-freight line hard-blocks this booking anyway.
       if (!base) continue;
 
-      const perTon = Number(base.rateValue) / (2 * maxVgm);
+      // Normalise the rate to ONE WAGON before dividing. A PER_CONTAINER 20ft
+      // rate covers half a wagon, so it is scaled by the 2 containers that ride
+      // one; 40ft scales by 1. A rate already quoted PER_WAGON is the wagon
+      // price already — never scale it again.
+      const perWagonRate =
+        base.rateUnit === 'PER_CONTAINER'
+          ? Number(base.rateValue) * (sizeByTypeId.get(wr.containerTypeId) ?? 1)
+          : Number(base.rateValue);
+
+      const perTon = perWagonRate / (2 * maxVgm);
       const amount = excess * perTon;
       if (!(amount > 0)) continue;
 
@@ -595,6 +618,42 @@ export class RuleEngineService {
     return modifiers;
   }
 
+  /**
+   * Containers of each type that ride ONE wagon, derived from the type's
+   * size_ft against a 40ft wagon slot: 20ft → 2, 40ft → 1. Only the types the
+   * caller actually needs are looked up. Unknown or non-positive sizes fall
+   * back to 1, which leaves a PER_CONTAINER rate unscaled — the pre-existing
+   * behaviour, so a missing size can never inflate a bill.
+   */
+  private async containersPerWagonByTypeId(
+    weightResults: ContainerWeightResult[],
+  ): Promise<Map<string, number>> {
+    const perWagon = new Map<string, number>();
+    const ids = [...new Set(weightResults.map((w) => w.containerTypeId).filter(Boolean))];
+    if (ids.length === 0) return perWagon;
+
+    let rows: Array<{ id: string; size_ft: string | number | null }> = [];
+    try {
+      rows = await this.dataSource.query(
+        'SELECT id, size_ft FROM freight.container_types WHERE id = ANY($1)',
+        [ids],
+      );
+    } catch {
+      // Size lookup unavailable — fall back to an unscaled (×1) rate, the
+      // behaviour before per-wagon normalisation. Never fail pricing over it.
+      return perWagon;
+    }
+    const WAGON_SLOT_FT = 40;
+    for (const row of rows) {
+      const sizeFt = Number(row.size_ft ?? 0);
+      perWagon.set(
+        row.id,
+        sizeFt > 0 ? Math.max(1, Math.floor(WAGON_SLOT_FT / sizeFt)) : 1,
+      );
+    }
+    return perWagon;
+  }
+
   /**
    * Empty-container return — sold per direction + route + container type, like
    * base freight. Each container line that opted in (returnQuantity, or every
diff --git a/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts b/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts
index 7c41ee43a..23b3f164e 100644
--- a/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts
+++ b/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts
@@ -270,7 +270,7 @@ export class SchedulingRescheduleService {
     // M12: only announce a new departure when the date actually moved —
     // `newDeparture` is null when the date was unchanged, so retained customers
     // are not falsely told the train was rescheduled.
-    await this.notifyRescheduleOutcome(dto, newDeparture);
+    await this.notifyRescheduleOutcome(scheduleId, dto, newDeparture);
     if (newDeparture) void this.trainSchedulingService.emitWindowState(scheduleId);
 
     return { plan, schedule: assignResult };
@@ -283,6 +283,7 @@ export class SchedulingRescheduleService {
    * company so the notifier has a phone/email to reach.
    */
   private async notifyRescheduleOutcome(
+    scheduleId: string,
     dto: ExecuteRescheduleDto,
     newDeparture: Date | null,
   ): Promise<void> {
@@ -294,9 +295,9 @@ export class SchedulingRescheduleService {
         const booking = await this.loadBookingForNotify(bookingId);
         if (!booking) continue;
         if (isMaintenance) {
-          this.notifier.maintenanceMoved(booking, newDeparture);
+          this.notifier.maintenanceMoved(booking, newDeparture, scheduleId, dto.reason);
         } else {
-          this.notifier.rescheduled(booking, newDeparture);
+          this.notifier.rescheduled(booking, newDeparture, scheduleId, dto.reason);
         }
       }
     }
@@ -307,7 +308,8 @@ export class SchedulingRescheduleService {
       for (const bookingId of dto.displacedBookingIds) {
         const booking = await this.loadBookingForNotify(bookingId);
         if (!booking) continue;
-        this.notifier.removedFromTrain(booking);
+        // Displaced bookings no longer point at the schedule — pass it explicitly.
+        this.notifier.removedFromTrain(booking, scheduleId);
       }
     }
   }
diff --git a/apps/edr-freight-api/src/modules/train-schedules/train-run-label.util.spec.ts b/apps/edr-freight-api/src/modules/train-schedules/train-run-label.util.spec.ts
new file mode 100644
index 000000000..dfafcee43
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-schedules/train-run-label.util.spec.ts
@@ -0,0 +1,32 @@
+import { trainRunLabel } from './train-run-label.util';
+
+describe('trainRunLabel', () => {
+  it('names the departure by the schedule train number and voyage number', () => {
+    expect(trainRunLabel({ trainNumber: '8001', voyageNumber: 'V-117' })).toBe(
+      'train 8001 (voyage V-117)',
+    );
+  });
+
+  it('drops the voyage bracket when the schedule has no voyage number', () => {
+    expect(trainRunLabel({ trainNumber: '8001', voyageNumber: null })).toBe('train 8001');
+    expect(trainRunLabel({ trainNumber: '8001', voyageNumber: '  ' })).toBe('train 8001');
+  });
+
+  it('still quotes the voyage when the pool train number is not assigned yet', () => {
+    expect(trainRunLabel({ trainNumber: null, voyageNumber: 'V-117' })).toBe(
+      'train (voyage V-117)',
+    );
+  });
+
+  it('returns null when neither number is known so callers can fall back', () => {
+    expect(trainRunLabel({ trainNumber: null, voyageNumber: null })).toBeNull();
+    expect(trainRunLabel(null)).toBeNull();
+    expect(trainRunLabel(undefined)).toBeNull();
+  });
+
+  it('capitalizes for sentence starts on request', () => {
+    expect(
+      trainRunLabel({ trainNumber: '8001', voyageNumber: 'V-117' }, { capitalize: true }),
+    ).toBe('Train 8001 (voyage V-117)');
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/train-schedules/train-run-label.util.ts b/apps/edr-freight-api/src/modules/train-schedules/train-run-label.util.ts
new file mode 100644
index 000000000..3c13506ac
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-schedules/train-run-label.util.ts
@@ -0,0 +1,30 @@
+import { TrainSchedule } from './entities/train-schedule.entity';
+
+export type TrainRunSource = Pick<TrainSchedule, 'trainNumber' | 'voyageNumber'>;
+
+/**
+ * How a departure is named in every customer-facing SMS / email:
+ *
+ *   "train 8001 (voyage V-2026-117)"
+ *
+ * Both identifiers are the SCHEDULE's own columns — `train_schedules.train_number`
+ * and `train_schedules.voyage_number`. The built train (`freight.trains`) carries
+ * a `train_name` that the build form labels "voyage number"; that is a different
+ * identifier and must never be quoted to customers. Always pass the schedule.
+ *
+ * Returns null when the schedule has neither number (older rows, or an unbuilt
+ * departure whose pool number is assigned at dispatch) so callers can fall back
+ * to a generic phrase instead of printing "train (voyage)".
+ */
+export function trainRunLabel(
+  schedule: TrainRunSource | null | undefined,
+  opts: { capitalize?: boolean } = {},
+): string | null {
+  if (!schedule) return null;
+  const train = schedule.trainNumber?.trim() || null;
+  const voyage = schedule.voyageNumber?.trim() || null;
+  if (!train && !voyage) return null;
+  const head = train ? `train ${train}` : 'train';
+  const label = voyage ? `${head} (voyage ${voyage})` : head;
+  return opts.capitalize ? label.charAt(0).toUpperCase() + label.slice(1) : label;
+}
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
index bf9c0aa5f..c933a5e34 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
@@ -607,7 +607,6 @@ export class BookingBatchService implements OnModuleInit {
     const isBatchPaid =
       booking.status === "SELECTED_FOR_BATCH" ||
       booking.status === "AWAITING_PAYMENT" ||
-      booking.status === "PAID" ||
       booking.paymentStatus === "PAID";
     if (!isBatchPaid) return;
 
@@ -786,7 +785,7 @@ export class BookingBatchService implements OnModuleInit {
       `SELECT id FROM freight.bookings
         WHERE deleted_at IS NULL
           AND train_schedule_id IS NULL
-          AND (payment_status = 'PAID' OR status = 'PAID')
+          AND payment_status = 'PAID'
           AND scheduled_date IS NOT NULL
           AND DATE(scheduled_date AT TIME ZONE 'Africa/Addis_Ababa') = $1`,
       [day],
@@ -3476,7 +3475,7 @@ export class BookingBatchService implements OnModuleInit {
       schedule?.scheduledDepartureDate &&
       eatDay(schedule.scheduledDepartureDate) !== previousDay
     ) {
-      this.notifier.allocatedOtherDay(fresh, schedule.scheduledDepartureDate);
+      this.notifier.allocatedOtherDay(fresh, schedule.scheduledDepartureDate, schedule);
     }
   }
 
@@ -3819,7 +3818,6 @@ export class BookingBatchService implements OnModuleInit {
       fresh.trainScheduleId === scheduleId &&
       (fresh.status === "SELECTED_FOR_BATCH" ||
         fresh.status === "AWAITING_PAYMENT" ||
-        fresh.status === "PAID" ||
         fresh.paymentStatus === "PAID")
     ) {
       this.logger.debug(
@@ -3967,6 +3965,11 @@ export class BookingBatchService implements OnModuleInit {
         schedulingStatus: "SCHEDULED",
         scheduledAt: new Date(),
         wagonsRequired,
+        // Pinned for cancellation pricing: unassign clears wagonsRequired, this
+        // stays. Written once — a later re-allocation keeps the first stamp.
+        ...(Number(booking.cancellationWagons ?? 0) > 0
+          ? {}
+          : { cancellationWagons: wagonsRequired }),
         paymentDeadline: null,
         selectedForBatchAt: null,
       } as never);
@@ -4530,7 +4533,7 @@ export class BookingBatchService implements OnModuleInit {
           manager,
         );
       });
-      this.notifier.displaced(victim);
+      this.notifier.displaced(victim, scheduleId);
       budget.add(this.needFor(victim, wagonDims), victimLeg);
       // Displacing frees wagons the same way an expiry does — don't leave the
       // schedule stuck at FULL.
@@ -5484,7 +5487,6 @@ export class BookingBatchService implements OnModuleInit {
     ).filter(
       (b) =>
         b.paymentStatus === "PAID" ||
-        b.status === "PAID" ||
         !payWindowLapsed(b.paymentDeadline, deadlineCutoff),
     );
     // Export FCFS: a customer's pending operation request HOLDS its wagons from
@@ -5596,7 +5598,6 @@ export class BookingBatchService implements OnModuleInit {
     return reserved.some(
       (b) =>
         b.paymentStatus !== "PAID" &&
-        b.status !== "PAID" &&
         b.paymentDeadline != null &&
         !payWindowLapsed(b.paymentDeadline, now),
     );
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts
index ea936465e..91136ab97 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts
@@ -13,6 +13,7 @@ describe('BookingJourneyService.autoPlaceOnFreedWagons', () => {
     { emit: jest.fn() } as never, // events
     {} as never, // notifications
     {} as never, // inbox
+    { record: jest.fn() } as never, // wagonHistory
   );
 
   const schedule = { id: 'sched-1', trainSetId: 'ts-1' };
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts
index 07de05853..cc060bf4e 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts
@@ -31,7 +31,10 @@ import { TrainCheckpointEvent } from './entities/train-checkpoint-event.entity';
 import { assertExportReceivedWithGrn, DIRECT_TO_TRAIN } from '../../common/export-received-gate';
 import { NotificationsService } from '../notifications/notifications.service';
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
-import { notifyCarriageAcceptanceReady } from '../notifications/notify-company.util';
+import { notifyCarriageAcceptanceReady,notifyLoadManifest } from '../notifications/notify-company.util';
+import { WagonEventInput, WagonHistoryService } from '../wagon-history/wagon-history.service';
+import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
+
 
 /**
  * Per-booking journey along a train's corridor — for EVERY trade direction.
@@ -61,12 +64,18 @@ export class BookingJourneyService {
     private readonly events: EventEmitter2,
     private readonly notifications: NotificationsService,
     private readonly inbox: NotificationInboxService,
+    private readonly wagonHistory: WagonHistoryService,
     @Optional() private readonly milestoneService?: ClearanceMilestoneService,
   ) {}
 
-  /** Statuses from which a booking may be loaded (gov bookings don't prepay). */
+  /**
+   * Whether a booking may be loaded. Paid is decided by the booking's
+   * PAYMENT status only — never by `status === 'PAID'`, which lags or is
+   * skipped on several flows (batch pay, manual mark-paid, gov expedite).
+   * Government bookings don't prepay: APPROVED is enough for them.
+   */
   private canLoad(booking: Booking): boolean {
-    if (booking.status === 'PAID') return true;
+    if (booking.paymentStatus === 'PAID') return true;
     return booking.isGovernment && booking.status === 'APPROVED';
   }
 
@@ -117,6 +126,7 @@ export class BookingJourneyService {
         loadedAt: now,
         loadedByUserId: userId ?? null,
       });
+      await this.wagonHistory.record(manager, this.cargoEvent(target, schedule, booking, 'LOADED', now, userId ?? null));
       if (!booking.loadingStartedAt) {
         await manager
           .getRepository(Booking)
@@ -188,7 +198,8 @@ export class BookingJourneyService {
     }
     if (!this.canLoad(booking)) {
       throw new BadRequestException(
-        `Booking must be paid before loading (currently ${booking.status})`,
+        `Booking must be paid before loading (payment status ${booking.paymentStatus ?? 'PENDING'}, ` +
+          `booking status ${booking.status})`,
       );
     }
     await this.assertTrainAtYard(schedule, booking.originYardId, 'origin');
@@ -235,7 +246,12 @@ export class BookingJourneyService {
       if (booking.tradeDirection === 'DOMESTIC') {
         await this.autoPlaceOnFreedWagons(manager, schedule, booking);
       }
-      await this.setAllocationStatuses(manager, scheduleId, bookingId, 'LOADED');
+      await this.setAllocationStatuses(manager, scheduleId, bookingId, 'LOADED', {
+        userId: userId ?? null,
+        at: now,
+        schedule,
+        booking,
+      });
       // Keep the schedule↔booking link's tracking flag in sync — the dispatch
       // readiness warnings and workspace badges read loading_status, not loadedAt.
       await manager
@@ -267,6 +283,20 @@ export class BookingJourneyService {
       });
     });
 
+    // What actually boarded, and what did not. A booking is routinely loaded in
+    // parts; the customer is told both halves, and the warehouse desk is told
+    // about the leftovers so somebody owns placing them. After the transaction:
+    // the lists are read back from the allocation statuses it just wrote.
+    void notifyLoadManifest(
+      this.dataSource,
+      this.notifications,
+      this.inbox,
+      bookingId,
+      scheduleId,
+      FREIGHT_PERMS.warehouseInventory.getNotification,
+      this.logger,
+    );
+
     // Customer tracking: cargo is on the train — loading milestones plus the
     // direction's "departed" handoff. Doc-trigger path no-ops non-customs
     // bookings (intercity) and already-completed codes.
@@ -328,6 +358,7 @@ export class BookingJourneyService {
       unloadedAt: now,
       unloadedByUserId: userId ?? null,
     });
+    await this.wagonHistory.record(null, this.cargoEvent(target, schedule, booking, 'DEPARTED', now, userId ?? null));
 
     const remaining = allocations.filter(
       (a) => a.id !== target.id && a.status !== 'DEPARTED',
@@ -385,7 +416,12 @@ export class BookingJourneyService {
         arrivedAt: now,
         arrivedByUserId: userId ?? null,
       } as never);
-      await this.setAllocationStatuses(manager, scheduleId, bookingId, 'DEPARTED');
+      await this.setAllocationStatuses(manager, scheduleId, bookingId, 'DEPARTED', {
+        userId: userId ?? null,
+        at: now,
+        schedule,
+        booking,
+      });
       await this.settleWagonsOnUnload(manager, schedule, booking, now, userId ?? null);
       // The facility took the cargo off the train — raise its GRN. Where the
       // facility also stores cargo (Indode), the event links the storage record
@@ -464,6 +500,7 @@ export class BookingJourneyService {
       id: b.id,
       reference: b.reference,
       status: b.status,
+      paymentStatus: b.paymentStatus ?? null,
       tradeDirection: b.tradeDirection,
       isGovernment: b.isGovernment,
       customer: b.company?.name ?? 'Unknown customer',
@@ -901,12 +938,61 @@ export class BookingJourneyService {
     scheduleId: string,
     bookingId: string,
     status: 'LOADED' | 'DEPARTED',
+    ctx?: { userId: string | null; at: Date; schedule: TrainSchedule; booking: Booking },
   ): Promise<void> {
     const allocations = await this.allocationsForBooking(manager, scheduleId, bookingId);
     if (!allocations.length) return;
     await manager
       .getRepository(WagonBookingAllocation)
       .update({ id: In(allocations.map((a) => a.id)) }, { status });
+    if (!ctx) return;
+    // Per-wagon cargo history. Allocations already at (or past) the target
+    // status were logged by the per-wagon load/unload endpoint — skip them so
+    // the whole-booking completion never double-writes a wagon's row.
+    const pending = allocations.filter((a) =>
+      status === 'LOADED'
+        ? a.status !== 'LOADED' && a.status !== 'DEPARTED'
+        : a.status !== 'DEPARTED',
+    );
+    await this.wagonHistory.record(
+      manager,
+      pending
+        .map((a) => this.cargoEvent(a, ctx.schedule, ctx.booking, status, ctx.at, ctx.userId))
+        .filter((e): e is WagonEventInput => e !== null),
+    );
+  }
+
+  /** CARGO_LOADED / CARGO_UNLOADED row for one allocation's physical wagon; null when the slot has no wagon pinned. */
+  private cargoEvent(
+    alloc: WagonBookingAllocation & { trainSetWagon?: TrainSetWagon },
+    schedule: TrainSchedule,
+    booking: Booking,
+    status: 'LOADED' | 'DEPARTED',
+    at: Date,
+    userId: string | null,
+  ): WagonEventInput | null {
+    const slot = alloc.trainSetWagon;
+    if (!slot?.physicalWagonId) return null;
+    const loaded = status === 'LOADED';
+    return {
+      wagonId: slot.physicalWagonId,
+      wagonNumber: slot.physicalWagon?.wagonNumber ?? null,
+      type: loaded ? Freight.WagonEventType.CargoLoaded : Freight.WagonEventType.CargoUnloaded,
+      occurredAt: at,
+      actorUserId: userId,
+      toYardId: loaded
+        ? (slot.boardYardId ?? schedule.originStationId ?? null)
+        : (booking.destinationYardId ?? slot.alightYardId ?? schedule.destinationStationId ?? null),
+      trainScheduleId: schedule.id,
+      trainId: schedule.trainSet?.trainId ?? null,
+      bookingId: booking.id,
+      toValue: booking.reference ?? null,
+      metadata: {
+        allocationId: alloc.id,
+        loadType: alloc.loadType ?? null,
+        weightTons: Number(alloc.allocatedWeightTons ?? 0),
+      },
+    };
   }
 
   private async allocationsForBooking(
@@ -994,6 +1080,20 @@ export class BookingJourneyService {
             ? Freight.WagonStatus.Assigned
             : Freight.WagonStatus.Available,
         });
+        await this.wagonHistory.record(manager, {
+          wagonId: wagon.id,
+          wagonNumber: wagon.wagonNumber,
+          type: Freight.WagonEventType.ReleasedAtUnload,
+          occurredAt: now,
+          actorUserId: userId,
+          fromYardId: boardYardId ?? null,
+          toYardId: booking.destinationYardId ?? null,
+          trainScheduleId: schedule.id,
+          trainId: wagon.trainId ?? null,
+          bookingId: booking.id,
+          toValue: wagon.trainId ? Freight.WagonStatus.Assigned : Freight.WagonStatus.Available,
+          metadata: { slotId: slot.id },
+        });
       }
     }
   }
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.spec.ts
new file mode 100644
index 000000000..524eeddc7
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.spec.ts
@@ -0,0 +1,76 @@
+import { BookingNotifierService } from './booking-notifier.service';
+
+/**
+ * Message wording for the schedule-related customer notices: every one must
+ * quote the SCHEDULE's train + voyage numbers, and reschedules must carry the
+ * staff-entered reason instead of a hard-coded "for maintenance".
+ */
+describe('BookingNotifierService messages', () => {
+  const schedule = { trainNumber: '8001', voyageNumber: 'V-117' };
+  const booking = { id: 'b1', reference: 'BK-2026-000928', companyId: 'c1' } as never;
+  const departure = new Date('2026-09-01T05:00:00.000Z');
+
+  let sent: string[];
+  let inbox: string[];
+  let service: BookingNotifierService;
+
+  beforeEach(() => {
+    sent = [];
+    inbox = [];
+    const notifications = {
+      directSend: jest.fn(async (_m: string, _to: string, msg: string) => {
+        sent.push(msg);
+      }),
+    };
+    const inboxSvc = {
+      notify: jest.fn(async (input: { body: string }) => {
+        inbox.push(input.body);
+      }),
+    };
+    const trainSchedules = {
+      findByIdWithStations: jest.fn(async () => ({ ...schedule, reference: 'S-2026-00012' })),
+    };
+    // Company contact lookup goes through raw SQL; return one phone + email.
+    const dataSource = {
+      query: jest.fn(async () => [{ phone: '+251900000000', email: 'ops@example.com' }]),
+    };
+    service = new BookingNotifierService(
+      notifications as never,
+      inboxSvc as never,
+      trainSchedules as never,
+      dataSource as never,
+    );
+  });
+
+  const flush = () => new Promise((r) => setImmediate(r));
+
+  it('maintenance reschedule quotes train, voyage and the staff reason', async () => {
+    service.maintenanceMoved(booking, departure, schedule, 'Locomotive maintenance.');
+    await flush();
+    expect(inbox[0]).toBe(
+      'Train 8001 (voyage V-117) for booking BK-2026-000928 was rescheduled — reason: Locomotive maintenance. ' +
+        'New departure date: 01/09/2026.',
+    );
+  });
+
+  it('maintenance reschedule falls back to "for maintenance" without a reason', async () => {
+    service.maintenanceMoved(booking, departure, schedule, '   ');
+    await flush();
+    expect(inbox[0]).toContain('was rescheduled for maintenance. New departure date');
+  });
+
+  it('plain reschedule carries the reason and the run label', async () => {
+    service.rescheduled(booking, departure, schedule, 'Crew change');
+    await flush();
+    expect(inbox[0]).toBe(
+      'Booking BK-2026-000928 on train 8001 (voyage V-117) has been rescheduled — reason: Crew change. ' +
+        'New departure date: 01/09/2026.',
+    );
+  });
+
+  it('resolves the run label from a schedule id when only the id is known', async () => {
+    service.scheduleCancelled(booking, 'sched-1');
+    await flush();
+    expect(inbox[0]).toMatch(/^Train 8001 \(voyage V-117\) for booking BK-2026-000928 has been cancelled/);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts
index 1c2d99401..fd42fdd7b 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts
@@ -14,8 +14,21 @@ import { NotificationInboxService } from '../notification-inbox/notification-inb
 import { resolveCompanyNotifyContact } from '../notifications/resolve-company-phone.util';
 import { resolveShippingLineNotifyTarget } from '../notifications/resolve-shipping-line-contact.util';
 import { TrainSchedulesRepository } from '../train-schedules/train-schedules.repository';
+import { trainRunLabel, type TrainRunSource } from '../train-schedules/train-run-label.util';
 import { BATCH_TIMEZONE } from './booking-batch.constants';
 
+const capitalize = (text: string): string => text.charAt(0).toUpperCase() + text.slice(1);
+
+/**
+ * " — reason: Locomotive maintenance" for the staff-entered reschedule reason,
+ * or '' when none was given. Trailing punctuation is trimmed so the sentence's
+ * own full stop follows cleanly.
+ */
+const reasonClause = (reason?: string | null): string => {
+  const text = reason?.trim().replace(/[.\s]+$/, '');
+  return text ? ` — reason: ${text}` : '';
+};
+
 @Injectable()
 export class BookingNotifierService {
   private readonly logger = new Logger(BookingNotifierService.name);
@@ -30,8 +43,9 @@ export class BookingNotifierService {
 
   /**
    * Human-readable description of a train schedule for customer messages:
-   * reference (or train number) + route + departure date. Never leaks a UUID —
-   * falls back to a generic phrase when the schedule can't be loaded.
+   * train number + voyage number (both the SCHEDULE's own — see trainRunLabel),
+   * then reference, route and departure date. Never leaks a UUID — falls back
+   * to a generic phrase when the schedule can't be loaded.
    */
   private async scheduleLabel(scheduleId?: string | null): Promise<string> {
     const fallback = 'your selected train';
@@ -39,15 +53,32 @@ export class BookingNotifierService {
     try {
       const s = await this.trainSchedules.findByIdWithStations(scheduleId);
       if (!s) return fallback;
-      const ref = s.reference ?? s.trainNumber ?? null;
-      const route =
+      // Customers know the departure by its train number (8001) and voyage
+      // number, not the schedule reference — lead with those and keep S-… as
+      // the secondary id.
+      const run = trainRunLabel(s);
+      const parts = [
+        s.reference,
         s.originStation?.label && s.destinationStation?.label
-          ? ` (${s.originStation.label} → ${s.destinationStation.label})`
-          : '';
+          ? `${s.originStation.label} → ${s.destinationStation.label}`
+          : null,
+      ].filter(Boolean);
+      const detail = parts.length ? ` (${parts.join(', ')})` : '';
       const departure = s.scheduledDepartureDate
-        ? `, departing ${new Date(s.scheduledDepartureDate).toLocaleDateString('en-GB', { timeZone: BATCH_TIMEZONE })}`
+        ? `, departing ${new Date(s.scheduledDepartureDate).toLocaleString('en-GB', {
+            timeZone: BATCH_TIMEZONE,
+            day: '2-digit',
+            month: '2-digit',
+            year: 'numeric',
+            hour: '2-digit',
+            minute: '2-digit',
+            hour12: false,
+          })} EAT`
         : '';
-      return ref ? `train ${ref}${route}${departure}` : `${fallback}${route}${departure}`;
+      if (run) return `${run}${detail}${departure}`;
+      return s.reference
+        ? `train ${s.reference}${departure}`
+        : `${fallback}${detail}${departure}`;
     } catch (err) {
       this.logger.warn(
         `scheduleLabel(${scheduleId}) failed: ${(err as Error).message}`,
@@ -56,6 +87,51 @@ export class BookingNotifierService {
     }
   }
 
+  /**
+   * "train 8001 (voyage V-117)" for the departure a message is about, or null
+   * when nothing is known. Accepts the schedule row itself (preferred — callers
+   * that have just cancelled or detached the booking still hold it) or its id,
+   * falling back to the booking's own train_schedule_id. Never throws: a label
+   * lookup must not stop a notification going out.
+   */
+  private async trainRun(
+    b: Booking,
+    schedule?: TrainRunSource | string | null,
+  ): Promise<string | null> {
+    if (schedule && typeof schedule !== 'string') return trainRunLabel(schedule);
+    const scheduleId = schedule ?? b.trainScheduleId ?? null;
+    if (!scheduleId) return null;
+    try {
+      const s = await this.trainSchedules.findByIdWithStations(scheduleId);
+      return trainRunLabel(s);
+    } catch (err) {
+      this.logger.warn(`trainRun(${scheduleId}) failed: ${(err as Error).message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Resolve the run label, then build and send the SMS/email + in-app item.
+   * Fire-and-forget like every notifier method; `build` receives the label
+   * (null when unknown) and returns the message text.
+   */
+  private withRun(
+    b: Booking,
+    schedule: TrainRunSource | string | null | undefined,
+    logLabel: string,
+    title: string,
+    build: (run: string | null) => string,
+    opts: { contact?: boolean; inApp?: Partial<NotifyInput> } = {},
+  ): void {
+    void (async () => {
+      const msg = build(await this.trainRun(b, schedule));
+      if (opts.contact !== false) await this.notifyContact(b, msg, logLabel);
+      this.inApp(b, title, msg, opts.inApp);
+    })().catch((err) =>
+      this.logger.warn(`${logLabel} notification failed for ${this.ref(b)}: ${(err as Error).message}`),
+    );
+  }
+
   private ref(b: Booking): string {
     return `${b.reference}${b.isGovernment ? ' (gov)' : ''}`;
   }
@@ -147,21 +223,30 @@ export class BookingNotifierService {
   }
 
   /** Train carrying the booking departed — dispatched origin → destination. */
-  dispatched(b: Booking, origin: string | null, destination: string | null): void {
-    const msg =
+  dispatched(
+    b: Booking,
+    origin: string | null,
+    destination: string | null,
+    schedule?: TrainRunSource | string | null,
+  ): void {
+    this.withRun(b, schedule, 'DISPATCHED', 'Shipment dispatched', (run) =>
       `Your booking ${b.reference ?? b.id} has been dispatched` +
-      `${origin || destination ? ` from ${origin ?? '?'} to ${destination ?? '?'}` : ''}.`;
-    void this.notifyContact(b, msg, 'DISPATCHED');
-    this.inApp(b, 'Shipment dispatched', msg);
+      `${origin || destination ? ` from ${origin ?? '?'} to ${destination ?? '?'}` : ''}` +
+      `${run ? ` on ${run}` : ''}.`,
+    );
   }
 
   /** Train carrying the booking arrived at destination. */
-  arrived(b: Booking, origin: string | null, destination: string | null): void {
-    const msg =
-      `Your booking ${b.reference ?? b.id} has arrived` +
-      `${destination ? ` at ${destination}` : ''}${origin ? ` (from ${origin})` : ''}.`;
-    void this.notifyContact(b, msg, 'ARRIVED');
-    this.inApp(b, 'Shipment arrived', msg);
+  arrived(
+    b: Booking,
+    origin: string | null,
+    destination: string | null,
+    schedule?: TrainRunSource | string | null,
+  ): void {
+    this.withRun(b, schedule, 'ARRIVED', 'Shipment arrived', (run) =>
+      `Your booking ${b.reference ?? b.id}${run ? ` on ${run}` : ''} has arrived` +
+      `${destination ? ` at ${destination}` : ''}${origin ? ` (from ${origin})` : ''}.`,
+    );
   }
 
   async payNow(b: Booking, deadline: Date): Promise<void> {
@@ -303,21 +388,28 @@ export class BookingNotifierService {
     );
   }
 
-  displaced(b: Booking): void {
-    const msg = `Booking ${b.reference ?? b.id} was displaced by a government booking. Move to another schedule or cancel.`;
-    void this.notifyContact(b, msg, 'DISPLACED');
-    this.inApp(b, 'Booking displaced', msg);
+  displaced(b: Booking, schedule?: TrainRunSource | string | null): void {
+    this.withRun(b, schedule, 'DISPLACED', 'Booking displaced', (run) =>
+      `Booking ${b.reference ?? b.id} was displaced${run ? ` from ${run}` : ''} by a government booking. ` +
+      `Move to another schedule or cancel.`,
+    );
   }
 
   /**
    * Staff rescheduled the train carrying this booking to a new departure date.
    * The booking stays on the train — only the date moved.
    */
-  rescheduled(b: Booking, newDeparture: Date): void {
+  rescheduled(
+    b: Booking,
+    newDeparture: Date,
+    schedule?: TrainRunSource | string | null,
+    reason?: string | null,
+  ): void {
     const when = newDeparture.toLocaleDateString('en-GB', { timeZone: BATCH_TIMEZONE });
-    const msg = `Booking ${b.reference ?? b.id} has been rescheduled. New departure date: ${when}.`;
-    void this.notifyContact(b, msg, 'RESCHEDULED');
-    this.inApp(b, 'Booking rescheduled', msg);
+    this.withRun(b, schedule, 'RESCHEDULED', 'Booking rescheduled', (run) =>
+      `Booking ${b.reference ?? b.id}${run ? ` on ${run}` : ''} has been rescheduled` +
+      `${reasonClause(reason)}. New departure date: ${when}.`,
+    );
   }
 
   /**
@@ -325,49 +417,75 @@ export class BookingNotifierService {
    * the customer's original choice. In-app only — staff drove the change and
    * the allocation itself already notifies through the secured path.
    */
-  allocatedOtherDay(b: Booking, newDeparture: Date): void {
+  allocatedOtherDay(
+    b: Booking,
+    newDeparture: Date,
+    schedule?: TrainRunSource | string | null,
+  ): void {
     const when = newDeparture.toLocaleDateString('en-GB', { timeZone: BATCH_TIMEZONE });
-    const msg =
-      `Booking ${b.reference ?? b.id} has been allocated to a train on a different date. ` +
-      `New departure date: ${when}.`;
-    this.inApp(b, 'Booking allocated to another date', msg);
+    this.withRun(
+      b,
+      schedule,
+      'ALLOCATED OTHER DAY',
+      'Booking allocated to another date',
+      (run) =>
+        `Booking ${b.reference ?? b.id} has been allocated to ${run ?? 'a train'} on a different date. ` +
+        `New departure date: ${when}.`,
+      { contact: false },
+    );
   }
 
   /**
    * Booking was removed from its train during a staff reschedule (not a government
    * pre-empt). It returns to eligible — the customer must rebook or reschedule.
    */
-  removedFromTrain(b: Booking): void {
-    const msg =
-      `Booking ${b.reference ?? b.id} has been removed from its train during rescheduling. ` +
-      `Please rebook or select a new schedule from the portal.`;
-    void this.notifyContact(b, msg, 'REMOVED FROM TRAIN');
-    this.inApp(b, 'Removed from train', msg);
+  removedFromTrain(b: Booking, schedule?: TrainRunSource | string | null): void {
+    this.withRun(b, schedule, 'REMOVED FROM TRAIN', 'Removed from train', (run) =>
+      `Booking ${b.reference ?? b.id} has been removed from ${run ?? 'its train'} during rescheduling. ` +
+      `Please rebook or select a new schedule from the portal.`,
+    );
   }
 
   /**
    * The train carrying this booking was cancelled. The booking is detached and
    * returns to the eligible pool — the customer must rebook or pick a new schedule.
    */
-  scheduleCancelled(b: Booking): void {
-    const msg =
-      `The train for booking ${b.reference ?? b.id} has been cancelled. ` +
-      `Your booking is not lost — please rebook or select a new schedule from the portal.`;
-    void this.notifyContact(b, msg, 'TRAIN CANCELLED');
+  scheduleCancelled(b: Booking, schedule?: TrainRunSource | string | null): void {
     // HIGH: a cancelled train invalidates the customer's plans — must reach SMS/email.
-    this.inApp(b, 'Train cancelled', msg, { priority: NotificationPriority.HIGH });
+    this.withRun(
+      b,
+      schedule,
+      'TRAIN CANCELLED',
+      'Train cancelled',
+      (run) =>
+        `${run ? capitalize(run) : 'The train'} for booking ${b.reference ?? b.id} has been cancelled. ` +
+        `Your booking is not lost — please rebook or select a new schedule from the portal.`,
+      { inApp: { priority: NotificationPriority.HIGH } },
+    );
   }
 
   /**
-   * The train carrying this booking was moved for maintenance to a new departure
-   * date. The booking stays on the train — only the date moved.
+   * The train carrying this booking was moved (maintenance reschedule) to a new
+   * departure date. The booking stays on the train — only the date moved. The
+   * staff-entered reason is what the customer reads; "for maintenance" is only
+   * the fallback when none was typed.
    */
-  maintenanceMoved(b: Booking, newDeparture: Date): void {
+  maintenanceMoved(
+    b: Booking,
+    newDeparture: Date,
+    schedule?: TrainRunSource | string | null,
+    reason?: string | null,
+  ): void {
     const when = newDeparture.toLocaleDateString('en-GB', { timeZone: BATCH_TIMEZONE });
-    const msg =
-      `The train for booking ${b.reference ?? b.id} was rescheduled for maintenance. ` +
-      `New departure date: ${when}.`;
-    void this.notifyContact(b, msg, 'MAINTENANCE RESCHEDULE');
-    this.inApp(b, 'Train maintenance reschedule', msg);
+    const why = reason?.trim() ? reasonClause(reason) : ' for maintenance';
+    this.withRun(
+      b,
+      schedule,
+      'MAINTENANCE RESCHEDULE',
+      'Train rescheduled',
+      (run) =>
+        `${run ? capitalize(run) : 'The train'} for booking ${b.reference ?? b.id} was rescheduled${why}. ` +
+        `New departure date: ${when}.`,
+    );
   }
 }
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-window.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-window.service.ts
index 47d0a0d21..49a730e68 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-window.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-window.service.ts
@@ -11,6 +11,7 @@ import {
 import { Booking } from '../bookings/entities/booking.entity';
 import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
 import { TrainSchedulesRepository } from '../train-schedules/train-schedules.repository';
+import { trainRunLabel } from '../train-schedules/train-run-label.util';
 import { NotificationsService } from '../notifications/notifications.service';
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import {
@@ -671,8 +672,11 @@ export class BookingWindowService implements OnModuleInit {
       const depart = schedule.scheduledDepartureDate.toLocaleDateString('en-GB', {
         timeZone: BATCH_TIMEZONE,
       });
+      // Name the departure by the schedule's train + voyage numbers (never the
+      // built train's name) so customers can match it to yard/customs paperwork.
+      const run = trainRunLabel(schedule);
       const msg =
-        `Booking is now open for the train departing ${depart}. ` +
+        `Booking is now open for ${run ?? 'the train'} departing ${depart}. ` +
         `Book your shipment from the portal home page before ${closes} EAT.`;
 
       const seenPhone = new Set<string>();
@@ -797,8 +801,9 @@ export class BookingWindowService implements OnModuleInit {
       const depart = schedule.scheduledDepartureDate.toLocaleDateString('en-GB', {
         timeZone: BATCH_TIMEZONE,
       });
+      const run = trainRunLabel(schedule, { capitalize: true });
       const msgFor = (corridors: string[]) =>
-        `A train is scheduled on your intercity corridor ${corridors.join(', ')}, ` +
+        `${run ?? 'A train'} is scheduled on your intercity corridor ${corridors.join(', ')}, ` +
         `departing ${depart}. EDR will confirm once your cargo is placed on a train.`;
 
       // One inbox item per booking (its `data` is the once-per-booking marker
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/checkpoint-leave-behind.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/checkpoint-leave-behind.spec.ts
new file mode 100644
index 000000000..c9ee445ca
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/checkpoint-leave-behind.spec.ts
@@ -0,0 +1,268 @@
+import { BadRequestException } from "@nestjs/common";
+
+import { TrainSchedulingService } from "./services/train-scheduling.service";
+
+/**
+ * Mid-corridor leave-behind. Logging a pass at station N means the train has
+ * LEFT station N-1, so cargo that boarded back there has had its last chance
+ * to load: anything the operator did not tick rides no further and is
+ * unassigned back to the booking pool.
+ *
+ * Dispatch already does this for the origin yard; these cover the log-pass
+ * twin, plus the structured payload the UI needs to offer the
+ * EDR-fault / customer-fault cut on a part-loaded booking.
+ */
+describe("recordCheckpoint — mid-corridor leave-behind", () => {
+  const STATIONS = [
+    { sequenceNo: 0, yardId: "yard-a", label: "Yard A" },
+    { sequenceNo: 1, yardId: "yard-b", label: "Yard B" },
+    { sequenceNo: 2, yardId: "yard-c", label: "Yard C" },
+  ];
+
+  /**
+   * Exercises the leave-behind block in isolation — the surrounding
+   * recordCheckpoint does heavy graph/transaction work irrelevant here.
+   */
+  const runLeaveBehind = async (
+    dto: { sequenceNo: number; loadedBookingIds?: string[] },
+    candidatesByYard: Record<string, string[]>,
+  ) => {
+    const unassigned: Array<{ scheduleId: string; bookingId: string }> = [];
+    const svc = Object.create(TrainSchedulingService.prototype) as {
+      unloadedBoarderIdsAtYard(
+        scheduleId: string,
+        yardId: string,
+      ): Promise<string[]>;
+      unassignBooking(
+        scheduleId: string,
+        bookingId: string,
+        userId?: string,
+      ): Promise<void>;
+    };
+    svc.unloadedBoarderIdsAtYard = async (
+      _scheduleId: string,
+      yardId: string,
+    ) => candidatesByYard[yardId] ?? [];
+    svc.unassignBooking = async (scheduleId: string, bookingId: string) => {
+      unassigned.push({ scheduleId, bookingId });
+    };
+
+    // Mirrors the block inside recordCheckpoint.
+    if (dto.loadedBookingIds && dto.sequenceNo > 0) {
+      const departedYardId = STATIONS.find(
+        (s) => s.sequenceNo === dto.sequenceNo - 1,
+      )?.yardId;
+      if (departedYardId) {
+        const keep = new Set(dto.loadedBookingIds);
+        const candidates = await svc.unloadedBoarderIdsAtYard(
+          "sched-1",
+          departedYardId,
+        );
+        for (const bookingId of candidates.filter((id) => !keep.has(id))) {
+          await svc.unassignBooking("sched-1", bookingId, undefined);
+        }
+      }
+    }
+    return unassigned.map((u) => u.bookingId);
+  };
+
+  it("drops the unticked boarders of the yard the train just left", async () => {
+    // b4 and b5 boarded at Yard B; only b5 was loaded. Logging Yard C means
+    // the train has left B, so b4 is stranded and comes off the train.
+    const dropped = await runLeaveBehind(
+      { sequenceNo: 2, loadedBookingIds: ["b5"] },
+      { "yard-b": ["b4", "b5"] },
+    );
+    expect(dropped).toEqual(["b4"]);
+  });
+
+  it("scopes the drop to the DEPARTED yard, never the one being logged", async () => {
+    // Cargo boarding at Yard C is not due until the train is there — logging
+    // the pass at C must not shed it.
+    const dropped = await runLeaveBehind(
+      { sequenceNo: 2, loadedBookingIds: [] },
+      { "yard-b": [], "yard-c": ["b6", "b7"] },
+    );
+    expect(dropped).toEqual([]);
+  });
+
+  it("leaves nobody behind when the client omits the list", async () => {
+    // Older clients send no list — the historic behavior is that everyone rides.
+    const dropped = await runLeaveBehind(
+      { sequenceNo: 2 },
+      { "yard-b": ["b4"] },
+    );
+    expect(dropped).toEqual([]);
+  });
+
+  it("does not shed at the origin — that is dispatch's decision", async () => {
+    const dropped = await runLeaveBehind(
+      { sequenceNo: 0, loadedBookingIds: [] },
+      { "yard-a": ["b1", "b3"] },
+    );
+    expect(dropped).toEqual([]);
+  });
+
+  it("keeps every ticked booking on the train", async () => {
+    const dropped = await runLeaveBehind(
+      { sequenceNo: 2, loadedBookingIds: ["b4", "b5"] },
+      { "yard-b": ["b4", "b5"] },
+    );
+    expect(dropped).toEqual([]);
+  });
+});
+
+describe("assertNoPartiallyLoadedBookings — structured payload", () => {
+  const makeService = (
+    rows: Array<{
+      bookingId: string;
+      reference: string;
+      loaded: string;
+      total: string;
+      unloadedAllocationIds: string[];
+    }>,
+  ) => {
+    const svc = Object.create(TrainSchedulingService.prototype) as {
+      dataSource: {
+        query: (sql: string, params: unknown[]) => Promise<unknown>;
+      };
+      assertNoPartiallyLoadedBookings(
+        schedule: unknown,
+        boardingYardId: string,
+        context: { action: string; yardLabel?: string },
+      ): Promise<void>;
+    };
+    svc.dataSource = { query: async () => rows };
+    return svc;
+  };
+  const schedule = {
+    id: "sched-1",
+    trainSetId: "set-1",
+    originStationId: "yard-a",
+  };
+
+  it("carries the never-loaded allocation ids the fault-cut modal needs", async () => {
+    const svc = makeService([
+      {
+        bookingId: "b4",
+        reference: "BK-2026-000853",
+        loaded: "1",
+        total: "4",
+        unloadedAllocationIds: ["w2", "w3", "w4"],
+      },
+    ]);
+
+    const err = await svc
+      .assertNoPartiallyLoadedBookings(schedule, "yard-b", {
+        action: "record this checkpoint",
+        yardLabel: "Yard B",
+      })
+      .catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(BadRequestException);
+    const body = (err as BadRequestException).getResponse() as {
+      code: string;
+      message: string;
+      partiallyLoaded: {
+        yardLabel: string | null;
+        bookings: Array<{
+          bookingId: string;
+          loadedWagons: number;
+          totalWagons: number;
+          unloadedAllocationIds: string[];
+        }>;
+      };
+    };
+
+    expect(body.code).toBe("PARTIALLY_LOADED_BOOKINGS");
+    expect(body.partiallyLoaded.yardLabel).toBe("Yard B");
+    expect(body.partiallyLoaded.bookings).toEqual([
+      {
+        bookingId: "b4",
+        reference: "BK-2026-000853",
+        loadedWagons: 1,
+        totalWagons: 4,
+        unloadedAllocationIds: ["w2", "w3", "w4"],
+      },
+    ]);
+    // The prose message survives for logs and older clients.
+    expect(body.message).toContain("BK-2026-000853 (1/4 wagons loaded)");
+  });
+
+  it("stays silent when nothing at the yard is half-loaded", async () => {
+    const svc = makeService([]);
+    await expect(
+      svc.assertNoPartiallyLoadedBookings(schedule, "yard-b", {
+        action: "dispatch",
+      }),
+    ).resolves.toBeUndefined();
+  });
+});
+
+/**
+ * Dispatch's origin auto-load. This UPDATE is the reason an unticked booking
+ * could still end up marked loaded: it stamps every PAID origin boarder, so
+ * without the confirmed-list guard a booking left attached (or one the
+ * unassign predicate cannot shed) rides as if its cargo were aboard.
+ */
+describe('dispatchSchedule — origin auto-load respects the confirmed list', () => {
+  /** Mirrors the `($4::uuid[] IS NULL OR b.id = ANY($4::uuid[]))` guard. */
+  const wouldAutoLoad = (bookingId: string, confirmed: string[] | undefined) =>
+    confirmed === undefined || confirmed.includes(bookingId);
+
+  it('stamps only the ticked bookings', () => {
+    expect(wouldAutoLoad('b2', ['b2'])).toBe(true);
+    expect(wouldAutoLoad('b1', ['b2'])).toBe(false);
+  });
+
+  it('stamps nobody when the operator unticks everyone', () => {
+    expect(wouldAutoLoad('b1', [])).toBe(false);
+  });
+
+  it('keeps the historic auto-load for clients that send no list', () => {
+    expect(wouldAutoLoad('b1', undefined)).toBe(true);
+    expect(wouldAutoLoad('b2', undefined)).toBe(true);
+  });
+});
+
+/**
+ * Empty wagons must travel with their train.
+ *
+ * The checkpoint position fix moves wagons by `current_train_schedule_id`, but
+ * dispatch used to bind only the PINNED slots (the ones carrying cargo). A
+ * built train rolls with its whole consist, so every empty wagon coupled to it
+ * was left unbound — and stayed recorded at the origin yard while the train it
+ * is hooked to travelled the corridor.
+ */
+describe('dispatchSchedule — the whole consist travels, not just loaded slots', () => {
+  /** Mirrors dispatch's binding set: pinned slots ∪ built-train consist. */
+  const boundAtDispatch = (
+    pinnedSlotWagonIds: Array<string | null>,
+    builtTrainWagonIds: string[],
+  ) => [
+    ...new Set([
+      ...pinnedSlotWagonIds.filter((id): id is string => Boolean(id)),
+      ...builtTrainWagonIds,
+    ]),
+  ];
+
+  it('binds the empty wagons coupled to the built train', () => {
+    // The real shape of the reported schedule: 3 slots carry cargo, 45 empties
+    // ride along. All 48 must move when a checkpoint is logged.
+    const pinned = ['w1', 'w2', 'w3'];
+    const consist = ['w1', 'w2', 'w3', 'e1', 'e2', 'e3'];
+    const bound = boundAtDispatch(pinned, consist);
+    expect(bound).toEqual(['w1', 'w2', 'w3', 'e1', 'e2', 'e3']);
+    expect(bound).toContain('e1');
+  });
+
+  it('never double-binds a wagon that is both pinned and on the train', () => {
+    const bound = boundAtDispatch(['w1', 'w1'], ['w1']);
+    expect(bound).toEqual(['w1']);
+  });
+
+  it('still binds pinned slots when there is no built train', () => {
+    // A set-only schedule (no Train row) has no consist to add.
+    expect(boundAtDispatch(['w1', null, 'w2'], [])).toEqual(['w1', 'w2']);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/dto/create-container-train-schedule.dto.ts b/apps/edr-freight-api/src/modules/train-scheduling/dto/create-container-train-schedule.dto.ts
index 18904c032..44d0615af 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/dto/create-container-train-schedule.dto.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/dto/create-container-train-schedule.dto.ts
@@ -6,10 +6,13 @@ import {
   IsBoolean,
   IsDateString,
   IsInt,
+  IsNotEmpty,
   IsNumber,
   IsOptional,
+  IsString,
   IsUUID,
   Max,
+  MaxLength,
   Min,
   ValidateNested,
 } from 'class-validator';
@@ -119,6 +122,19 @@ export class CreateContainerTrainScheduleDto {
   @IsDateString()
   scheduleDate!: string;
 
+  @ApiProperty({
+    example: 'V-2026-0620',
+    maxLength: 20,
+    description:
+      'Voyage (sailing) number for this departure — the run identifier yards and ' +
+      'customs quote. Required at creation; the UI pre-fills it with the built ' +
+      "train's direction-matched run number, but staff may override it.",
+  })
+  @IsString()
+  @IsNotEmpty({ message: 'A voyage number is required' })
+  @MaxLength(20)
+  voyageNumber!: string;
+
   @ApiPropertyOptional({
     format: 'uuid',
     description:
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts b/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts
index 06c363bc4..d96a1db4a 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts
@@ -1,5 +1,5 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { TrainCheckpointKind } from '@edr/types';
+import { ApiProperty } from "@nestjs/swagger";
+import { TrainCheckpointKind } from "@edr/types";
 import {
   IsArray,
   IsEnum,
@@ -10,10 +10,12 @@ import {
   IsUUID,
   MaxLength,
   Min,
-} from 'class-validator';
+} from "class-validator";
 
 export class RecordCheckpointDto {
-  @ApiProperty({ description: 'Station position along the route (0 = origin).' })
+  @ApiProperty({
+    description: "Station position along the route (0 = origin).",
+  })
   @IsInt()
   @Min(0)
   sequenceNo!: number;
@@ -31,7 +33,7 @@ export class RecordCheckpointDto {
   @ApiProperty({
     required: false,
     description:
-      'ISO timestamp; defaults to now. Past allowed, future rejected, must be in corridor order.',
+      "ISO timestamp; defaults to now. Past allowed, future rejected, must be in corridor order.",
   })
   @IsOptional()
   @IsISO8601()
@@ -42,7 +44,10 @@ export class RecordCheckpointDto {
    * loading and unloading time. All optional: a stop logged without them still
    * records its staying time.
    */
-  @ApiProperty({ required: false, description: 'ISO timestamp; unloading start.' })
+  @ApiProperty({
+    required: false,
+    description: "ISO timestamp; unloading start.",
+  })
   @IsOptional()
   @IsISO8601()
   unloadingStartedAt?: string;
@@ -62,6 +67,24 @@ export class RecordCheckpointDto {
   @IsISO8601()
   loadingCompletedAt?: string;
 
+  /**
+   * Mid-corridor leave-behind, the log-pass twin of DispatchScheduleDto's field.
+   * Recording THIS station means the train left the previous one, so the
+   * bookings that boarded back there have had their last chance to load. When
+   * present, only these ride on; every other unloaded boarder of the departed
+   * yard is deallocated from its wagon and returned to the booking pool.
+   * Absent (older clients) = nobody is left behind, the historic behavior.
+   */
+  @ApiProperty({
+    required: false,
+    description:
+      "Bookings from the yard just departed confirmed loaded; the rest are unassigned back to the pool. Omit to leave nobody behind.",
+  })
+  @IsOptional()
+  @IsArray()
+  @IsUUID("4", { each: true })
+  loadedBookingIds?: string[];
+
   @ApiProperty({ required: false })
   @IsOptional()
   @IsString()
@@ -73,7 +96,8 @@ export class RecordCheckpointDto {
 export class UpdateCheckpointDto {
   @ApiProperty({
     required: false,
-    description: 'ISO timestamp. Past allowed, future rejected, must be in corridor order.',
+    description:
+      "ISO timestamp. Past allowed, future rejected, must be in corridor order.",
   })
   @IsOptional()
   @IsISO8601()
@@ -110,7 +134,8 @@ export class UpdateCheckpointDto {
 export class DispatchScheduleDto {
   @ApiProperty({
     required: false,
-    description: 'Actual departure time; defaults to now. Past allowed, future rejected.',
+    description:
+      "Actual departure time; defaults to now. Past allowed, future rejected.",
   })
   @IsOptional()
   @IsISO8601()
@@ -125,10 +150,10 @@ export class DispatchScheduleDto {
   @ApiProperty({
     required: false,
     description:
-      'Origin-yard bookings confirmed loaded; the rest are unassigned back to the pool. Omit to auto-load all.',
+      "Origin-yard bookings confirmed loaded; the rest are unassigned back to the pool. Omit to auto-load all.",
   })
   @IsOptional()
   @IsArray()
-  @IsUUID('4', { each: true })
+  @IsUUID("4", { each: true })
   loadedBookingIds?: string[];
 }
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/intercity.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/intercity.service.ts
index 9dc75335f..121dd5ed6 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/intercity.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/intercity.service.ts
@@ -439,6 +439,7 @@ export class IntercityService {
       id: booking.id,
       reference: booking.reference,
       status: booking.status,
+      paymentStatus: booking.paymentStatus ?? null,
       freightType: booking.freightType,
       isGovernment: booking.isGovernment,
       customer: booking.company?.name ?? 'Unknown customer',
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
index d6e778216..f61593442 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
@@ -508,6 +508,7 @@ describe('TrainSchedulingService', () => {
     const result = await service.createContainerTrainSchedule({
       routeId: 'route-1',
       scheduleDate: futureDeparture,
+      voyageNumber: 'V-TEST-1',
       locomotiveIds: ['loc-1', 'loc-2'],
     });
 
@@ -610,6 +611,7 @@ describe('TrainSchedulingService', () => {
       service.createContainerTrainSchedule({
         routeId: 'route-1',
         scheduleDate: '2026-06-20T08:00:00.000Z',
+        voyageNumber: 'V-TEST-2',
         locomotiveIds: ['loc-1', 'loc-2'],
       }),
     ).rejects.toBeInstanceOf(ConflictException);
@@ -1062,6 +1064,7 @@ describe('TrainSchedulingService', () => {
     const makeWagon = (sequenceNo: number, wagonNumber: string, allocations: unknown[]) => ({
       sequenceNo,
       wagonNumber,
+      physicalWagonId: `wagon-id-${wagonNumber}`,
       physicalWagon: { wagonNumber },
       wagonType: { code: 'NW5', name: 'Flat Wagon', tareWeightTons: 22 },
       lengthMeters: 14,
@@ -1134,7 +1137,7 @@ describe('TrainSchedulingService', () => {
       expect(html).toContain('2 (1 empty)');
     });
 
-    it('marks a leg slot on the import document as TO BE LOADED and keeps it out of the loaded tallies', () => {
+    it('drops a leg slot entirely from the import document — not part of the departing consist', () => {
       const loadList = {
         generatedAt: '2026-07-17T08:00:00.000Z',
         trainScheduleId: 'schedule-1',
@@ -1176,15 +1179,67 @@ describe('TrainSchedulingService', () => {
         buildImportLoadListHtml: (l: unknown) => string;
       }).buildImportLoadListHtml(loadList);
 
-      expect(html).toContain('TO BE LOADED AT DIRE DAWA PORT');
-      // Departure station of the leg slot is its board yard, not the origin.
-      expect(html).toContain('<td>Dire Dawa Port</td>');
-      // Only the origin-loaded container counts; the leg slot's tallies separately.
+      // The leg slot (W-ICY, boards later at Dire Dawa) gets no row at all —
+      // it isn't on the departing consist. Only W-IMP appears.
+      expect(html).not.toContain('W-ICY');
+      expect(html).not.toContain('ICY-001');
+      expect(html).toContain('W-IMP');
+      expect(html).toContain('<span>Wagons</span><strong>1</strong>');
       expect(html).toContain('<span>Total containers</span><strong>1</strong>');
-      expect(html).toContain('<span>To load en route</span><strong>1 containers</strong>');
     });
 
-    it('marks a leg slot on the export document as TO LOAD AT its board yard and keeps it out of the tallies', () => {
+    it('drops a slot with no physical wagon pinned from the import document too', () => {
+      const loadList = {
+        generatedAt: '2026-07-17T08:00:00.000Z',
+        trainScheduleId: 'schedule-1',
+        trainNumber: '7002',
+        route: 'DCT/SGTD → GMP',
+        origin: 'DCT/SGTD',
+        destination: 'GMP',
+        totalBookings: 2,
+        wagons: [
+          {
+            sequenceNo: 1,
+            // No physical wagon pinned (fleet shortfall, or a REAL cut nulled
+            // it out) — nothing physical to marshal, even though the slot
+            // still carries a LOADED allocation.
+            wagonNumber: null,
+            boardYard: null,
+            alightYard: null,
+            allocations: [
+              {
+                ...loadedAllocation,
+                containerItems: [{ containerNumber: 'GHOST-001' }],
+              },
+            ],
+          },
+          {
+            sequenceNo: 2,
+            wagonNumber: 'W-IMP',
+            boardYard: null,
+            alightYard: null,
+            allocations: [
+              {
+                ...loadedAllocation,
+                containerItems: [{ containerNumber: 'CONT-001', containerType: { sizeFt: 20 } }],
+              },
+            ],
+          },
+        ],
+        operation: { status: {} },
+      };
+
+      const html = (service as never as {
+        buildImportLoadListHtml: (l: unknown) => string;
+      }).buildImportLoadListHtml(loadList);
+
+      expect(html).not.toContain('GHOST-001');
+      expect(html).toContain('W-IMP');
+      expect(html).toContain('<span>Wagons</span><strong>1</strong>');
+      expect(html).toContain('<span>Total containers</span><strong>1</strong>');
+    });
+
+    it('drops a leg slot entirely from the export document — not part of the departing consist', () => {
       const sizedAllocation = {
         ...loadedAllocation,
         containerItems: [{ containerNumber: 'CONT-001', containerType: { sizeFt: 20 } }],
@@ -1204,9 +1259,33 @@ describe('TrainSchedulingService', () => {
         pendingBoardYardLabelBySlot: new Map([['slot-leg', 'Dire Dawa Port']]),
       });
 
-      expect(html).toContain('TO LOAD AT DIRE DAWA PORT');
+      // The leg slot (W-LEG, boards later at Dire Dawa) gets no row at all.
+      expect(html).not.toContain('W-LEG');
+      expect(html).toContain('<span>Wagons</span><strong>1</strong>');
+      expect(html).toContain('<span>Total containers</span><strong>1</strong>');
+    });
+
+    it('drops a whole-route slot with no physical wagon pinned from the export document too', () => {
+      const sizedAllocation = {
+        ...loadedAllocation,
+        containerItems: [{ containerNumber: 'CONT-001', containerType: { sizeFt: 20 } }],
+      };
+      const ghost = { ...makeWagon(2, 'W-GHOST', [sizedAllocation]), id: 'slot-ghost', physicalWagonId: null };
+      const schedule = {
+        id: 'schedule-1',
+        trainNumber: '8302',
+        direction: 'EXPORT',
+        trainSet: { wagons: [{ ...makeWagon(1, 'W-001', [sizedAllocation]), id: 'slot-1' }, ghost] },
+        scheduleBookings: [],
+      };
+
+      const html = (service as never as {
+        buildExportLoadListHtml: (s: unknown, o?: unknown) => string;
+      }).buildExportLoadListHtml(schedule, {});
+
+      expect(html).not.toContain('W-GHOST');
+      expect(html).toContain('<span>Wagons</span><strong>1</strong>');
       expect(html).toContain('<span>Total containers</span><strong>1</strong>');
-      expect(html).toContain('<span>To load en route</span><strong>1 containers</strong>');
     });
 
     it('prints the consist-changes table for this stop, and omits it when there are none', () => {
@@ -1240,6 +1319,44 @@ describe('TrainSchedulingService', () => {
       expect(withoutChanges).not.toContain('Consist Changed At This Stop');
     });
 
+    it('shows per-row Departure/Arrival Station — schedule endpoints for a whole-route wagon, its own board/alight yard for a leg slot', () => {
+      const wholeRoute = { ...makeWagon(1, 'W-001', [loadedAllocation]), id: 'slot-1' };
+      const legSlot = {
+        ...makeWagon(2, 'W-LEG', [loadedAllocation]),
+        id: 'slot-leg',
+        boardYardId: 'yard-dire',
+        alightYardId: 'yard-adama',
+      };
+      const schedule = {
+        id: 'schedule-1',
+        trainNumber: '8302',
+        direction: 'EXPORT',
+        originStation: { label: 'DCT/SGTD' },
+        destinationStation: { label: 'GMP (Gelan Multipurpose Port)' },
+        trainSet: { wagons: [wholeRoute, legSlot] },
+        scheduleBookings: [],
+      };
+      const build = (service as never as {
+        buildExportLoadListHtml: (s: unknown, o?: unknown) => string;
+      }).buildExportLoadListHtml.bind(service);
+
+      const html = build(schedule, {
+        yardLabelById: new Map([
+          ['yard-dire', 'Dire Dawa Port'],
+          ['yard-adama', 'Adama'],
+        ]),
+      });
+
+      expect(html).toContain('<th>Departure Station</th>');
+      expect(html).toContain('<th>Arrival Station</th>');
+      // Whole-route wagon: schedule's own endpoints.
+      expect(html).toContain('<td>DCT/SGTD</td>');
+      expect(html).toContain('<td>GMP (Gelan Multipurpose Port)</td>');
+      // Leg slot: its own board/alight yard, not the schedule's endpoints.
+      expect(html).toContain('<td>Dire Dawa Port</td>');
+      expect(html).toContain('<td>Adama</td>');
+    });
+
     it('lists loaded empty containers by number and states they are empty', () => {
       const schedule = {
         id: 'schedule-1',
@@ -1404,6 +1521,46 @@ describe('TrainSchedulingService', () => {
       expect(numbers).toEqual(['W-LEG2']);
     });
 
+    it('drops a whole-route slot with no physical wagon pinned, even though its allocation is LOADED', () => {
+      // A booking can hold a LOADED allocation before a real wagon backs it
+      // (fleet shortfall left the slot unpinned), or a REAL cut nulls
+      // physicalWagonId without ever touching the slot's own status. Either
+      // way there is no physical wagon standing there to marshal.
+      const pinned = makeWagon(1, 'W-001', [allocWith({ status: 'LOADED' })]);
+      const ghost = { ...makeWagon(2, 'W-002', [allocWith({ status: 'LOADED' })]), physicalWagonId: null };
+      const schedule = { trainSet: { wagons: [pinned, ghost] }, scheduleBookings: [] };
+
+      const { wagons } = onBoardView(schedule);
+      const numbers = (wagons as Array<{ physicalWagon: { wagonNumber: string } }>).map(
+        (w) => w.physicalWagon.wagonNumber,
+      );
+      expect(numbers).toEqual(['W-001']);
+    });
+
+    it('drops a leg slot LOADED by generation time but not yet coupled as of this stop', () => {
+      // Both W-DIRE (coupled+loaded at Dire Dawa) and W-ADAMA (coupled+loaded
+      // at Adama, a LATER stop) read identically to intercityOnBoardView by
+      // the time this runs — both LOADED right now. Only the adjustment log
+      // knows W-ADAMA hadn't coupled yet as of Dire Dawa's own timestamp.
+      const wholeRoute = makeWagon(1, 'W-001', [allocWith({ status: 'LOADED' })]);
+      const legDireDawa = { ...makeWagon(2, 'W-DIRE', [allocWith({ status: 'LOADED' })]), boardYardId: 'yard-dire' };
+      const legAdama = { ...makeWagon(3, 'W-ADAMA', [allocWith({ status: 'LOADED' })]), boardYardId: 'yard-adama' };
+      const schedule = { trainSet: { wagons: [wholeRoute, legDireDawa, legAdama] }, scheduleBookings: [] };
+
+      const { wagons } = onBoardView(schedule);
+      const boardedByDireDawa = new Set(['W-DIRE']); // logged ADD only up to Dire Dawa's stop
+      const wagonsAsOfStop = (service as never as {
+        wagonsAsOfStop: (w: unknown, s: Set<string>) => Array<{ physicalWagon: { wagonNumber: string } }>;
+      }).wagonsAsOfStop.bind(service);
+
+      const asOfDireDawa = wagonsAsOfStop(wagons, boardedByDireDawa);
+      expect(asOfDireDawa.map((w) => w.physicalWagon.wagonNumber)).toEqual(['W-001', 'W-DIRE']);
+
+      const boardedByAdama = new Set(['W-DIRE', 'W-ADAMA']); // both stops have now happened
+      const asOfAdama = wagonsAsOfStop(wagons, boardedByAdama);
+      expect(asOfAdama.map((w) => w.physicalWagon.wagonNumber)).toEqual(['W-001', 'W-DIRE', 'W-ADAMA']);
+    });
+
     it('lists an IN_TRANSIT booking with no wagon allocation in the unassigned section', () => {
       const rider = {
         id: 'booking-9',
@@ -1796,6 +1953,8 @@ describe('TrainSchedulingService', () => {
         save: jest.fn().mockResolvedValue(undefined),
         create: jest.fn((x: unknown) => x),
       })),
+      // Wagon-history lookup of the released allocations' physical wagons.
+      query: jest.fn().mockResolvedValue([]),
     };
 
     beforeEach(() => {
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index dbf0c7f7c..4f416cdcf 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -6,6 +6,7 @@
   TrainCheckpointKind,
   TrainScheduleStatus as TrainScheduleStatusEnum,
   WagonAllocationSnapshot,
+  WagonEventType,
   WagonMovementKind,
   WagonStatus,
 } from '@edr/types';
@@ -28,6 +29,7 @@ import {
   ILike,
   In,
   IsNull,
+  LessThanOrEqual,
   Not,
   QueryFailedError,
   Raw,
@@ -71,6 +73,7 @@ import { Yard } from '../../rule-engine/entities/yard.entity';
 import { WagonType } from '../../wagon-types/entities/wagon-type.entity';
 import { WagonTypesRepository } from '../../wagon-types/wagon-types.repository';
 import { Wagon } from '../../wagons/entities/wagon.entity';
+import { WagonEventInput, WagonHistoryService } from '../../wagon-history/wagon-history.service';
 import { AdjustScheduleConsistDto } from '../dto/adjust-schedule-consist.dto';
 import { AssignBookingsDto } from '../dto/assign-bookings.dto';
 import { CreateContainerTrainScheduleDto } from '../dto/create-container-train-schedule.dto';
@@ -421,8 +424,28 @@ export class TrainSchedulingService {
     @Optional()
     @Inject(forwardRef(() => BookingBatchService))
     private readonly bookingBatchService?: BookingBatchService,
+    // Per-wagon history ledger (global module). @Optional keeps the positional
+    // spec constructors working; production always has it.
+    @Optional() private readonly wagonHistory?: WagonHistoryService,
   ) {}
 
+  /** Physical wagons behind a set of booking allocations (via their slots), for cargo history rows. */
+  private async wagonsOfAllocations(
+    manager: EntityManager,
+    allocationIds: string[],
+  ): Promise<Array<{ allocationId: string; wagonId: string; wagonNumber: string; yardId: string | null; trainId: string | null }>> {
+    if (!allocationIds.length) return [];
+    return manager.query(
+      `SELECT a.id AS "allocationId", w.id AS "wagonId", w.wagon_number AS "wagonNumber",
+              w.current_yard_id AS "yardId", w.train_id AS "trainId"
+         FROM freight.wagon_booking_allocations a
+         JOIN freight.train_set_wagons tsw ON tsw.id = a.train_set_wagon_id
+         JOIN freight.wagons w ON w.id = tsw.physical_wagon_id
+        WHERE a.id = ANY($1::uuid[])`,
+      [allocationIds],
+    );
+  }
+
   /**
    * Notify each booking's customer that their shipment was dispatched / arrived,
    * with a deep-link to the booking. Fire-and-forget — never blocks the action.
@@ -442,8 +465,11 @@ export class TrainSchedulingService {
         relations: { company: true },
       });
       for (const b of bookings) {
-        if (event === 'dispatched') this.bookingNotifier.dispatched(b, origin, destination);
-        else this.bookingNotifier.arrived(b, origin, destination);
+        if (event === 'dispatched') {
+          this.bookingNotifier.dispatched(b, origin, destination, schedule);
+        } else {
+          this.bookingNotifier.arrived(b, origin, destination, schedule);
+        }
       }
     } catch (err) {
       this.logger.warn(`Failed to notify schedule bookings (${event}): ${(err as Error).message}`);
@@ -1169,7 +1195,7 @@ export class TrainSchedulingService {
         });
         for (const booking of allocatedBookings) {
           if (['CANCELLED', 'EXPIRED', 'REJECTED'].includes(booking.status)) continue;
-          this.bookingNotifier.rescheduled(booking, departure);
+          this.bookingNotifier.rescheduled(booking, departure, schedule);
           notifiedCount += 1;
         }
       }
@@ -1374,7 +1400,7 @@ export class TrainSchedulingService {
         .getRepository(Booking)
         .update(aboard.map((b) => b.id), { scheduledDate: departure } as never);
       for (const booking of aboard) {
-        this.bookingNotifier.maintenanceMoved(booking, departure);
+        this.bookingNotifier.maintenanceMoved(booking, departure, schedule, dto.reason);
       }
     }
 
@@ -1871,6 +1897,10 @@ export class TrainSchedulingService {
           status: TrainScheduleStatusEnum.Scheduled,
           direction,
           trainNumber: pairTrainNumber ?? undefined,
+          // Staff-entered at creation; the UI defaults it to the built train's
+          // own voyage number (Train.trainName). Fall back to the pair train
+          // number here only for non-UI callers that send none.
+          voyageNumber: dto.voyageNumber?.trim() || pairTrainNumber || null,
           maxWagons,
           plannedWagonYards,
           reverseWagonOrder: dto.reverseWagonOrder ?? false,
@@ -2320,12 +2350,18 @@ export class TrainSchedulingService {
       // batch fill, which unlinks it and frees its wagons on the next window cycle.
       const scheduledAt = new Date();
       for (const booking of bookings) {
+        const wagonsRequired = sumWagonsRequired(booking, wagonPlan);
         await this.bookingsRepository.updateSchedulingFields(
           booking.id,
           {
             schedulingStatus: SchedulingStatus.Scheduled,
             scheduledAt,
-            wagonsRequired: sumWagonsRequired(booking, wagonPlan),
+            wagonsRequired,
+            // Pinned for cancellation pricing: unassign clears wagonsRequired,
+            // this stays. Written once — re-allocation keeps the first stamp.
+            ...(Number(booking.cancellationWagons ?? 0) > 0
+              ? {}
+              : { cancellationWagons: wagonsRequired }),
           },
           manager,
         );
@@ -2408,6 +2444,21 @@ export class TrainSchedulingService {
           manager,
         );
         await this.wagonAllocationBulkLoadsRepository.deleteByAllocationIds(allocationIds, manager);
+        const carried = await this.wagonsOfAllocations(manager, allocationIds);
+        await this.wagonHistory?.record(
+          manager,
+          carried.map((c) => ({
+            wagonId: c.wagonId,
+            wagonNumber: c.wagonNumber,
+            type: WagonEventType.BookingUnassigned,
+            actorUserId: userId ?? null,
+            fromYardId: c.yardId,
+            trainId: c.trainId,
+            trainScheduleId: scheduleId,
+            bookingId,
+            metadata: { allocationId: c.allocationId },
+          })),
+        );
         await manager.getRepository(WagonBookingAllocation).delete(allocationIds);
       }
 
@@ -2474,6 +2525,18 @@ export class TrainSchedulingService {
                 trainSetWagonId: null,
                 status: wagon.trainId ? WagonStatus.Assigned : WagonStatus.Available,
               });
+              await this.wagonHistory?.record(manager, {
+                wagonId: wagon.id,
+                wagonNumber: wagon.wagonNumber,
+                type: WagonEventType.ReleasedFromSchedule,
+                actorUserId: userId ?? null,
+                fromYardId: wagon.currentYardId ?? null,
+                trainId: wagon.trainId ?? null,
+                trainScheduleId: scheduleId,
+                bookingId,
+                toValue: wagon.trainId ? WagonStatus.Assigned : WagonStatus.Available,
+                reason: 'Booking unassigned from the dispatched train',
+              });
             }
           }
           await manager.getRepository(TrainSetWagon).delete(slot.id);
@@ -2524,7 +2587,8 @@ export class TrainSchedulingService {
       .getRepository(Booking)
       .findOne({ where: { id: bookingId }, relations: { company: true } });
     if (removedBooking && opts.notifyCustomer !== false) {
-      this.bookingNotifier.removedFromTrain(removedBooking);
+      // The booking's train_schedule_id is already cleared — name the run explicitly.
+      this.bookingNotifier.removedFromTrain(removedBooking, schedule);
     }
     this.logger.log(
       `Booking ${bookingReference} removed from schedule ${scheduleId} by user ${userId ?? 'unknown'} — customer notified to reschedule or cancel.`,
@@ -2816,10 +2880,34 @@ export class TrainSchedulingService {
 
         // The pin lives ONLY on the schedule's slot — the Wagon entity keeps
         // its status untouched so other schedules can still use the wagon.
+        const previousPinId = slotById.get(assignment.trainSetWagonId)?.physicalWagonId ?? null;
         await manager.getRepository(TrainSetWagon).update(assignment.trainSetWagonId, {
           physicalWagonId: assignment.physicalWagonId,
           status: 'RESERVED',
         });
+        if (previousPinId !== assignment.physicalWagonId) {
+          const pinEvents: WagonEventInput[] = [
+            {
+              wagonId: assignment.physicalWagonId,
+              type: WagonEventType.PinnedToSchedule,
+              trainScheduleId: scheduleId,
+              trainId: builtTrainId ?? null,
+              fromYardId: schedule.originStationId ?? null,
+              metadata: { slotId: assignment.trainSetWagonId, auto: false },
+            },
+          ];
+          if (previousPinId) {
+            pinEvents.push({
+              wagonId: previousPinId,
+              type: WagonEventType.UnpinnedFromSchedule,
+              trainScheduleId: scheduleId,
+              trainId: builtTrainId ?? null,
+              reason: 'Replaced on the slot',
+              metadata: { slotId: assignment.trainSetWagonId },
+            });
+          }
+          await this.wagonHistory?.record(manager, pinEvents);
+        }
         for (const [physicalId, slotId] of slotIdByPhysicalId) {
           if (slotId === assignment.trainSetWagonId) {
             slotIdByPhysicalId.delete(physicalId);
@@ -2985,9 +3073,27 @@ export class TrainSchedulingService {
       }
       // The train is out — every pinned wagon is ASSIGNED to this schedule and
       // stays pinned so no other schedule can pick it while it's rolling.
-      const dispatchedPhysicalIds = (schedule.trainSet?.wagons ?? [])
+      const pinnedDispatchIds = (schedule.trainSet?.wagons ?? [])
         .map((slot) => slot.physicalWagonId)
         .filter((id): id is string => Boolean(id));
+      // A built train rolls with its WHOLE consist, not just the slots that
+      // carry cargo: an empty wagon coupled to the train is physically leaving
+      // the yard too. Binding only the pinned slots left those empties behind
+      // on `current_train_schedule_id`, so the checkpoint position fix (which
+      // filters on exactly that column) never moved them and they stayed
+      // recorded at the origin yard while the train they are hooked to
+      // travelled the corridor.
+      const consistPhysicalIds = schedule.trainSet?.trainId
+        ? (
+            await manager.getRepository(Wagon).find({
+              where: { trainId: schedule.trainSet.trainId },
+              select: { id: true },
+            })
+          ).map((w) => w.id)
+        : [];
+      const dispatchedPhysicalIds = [
+        ...new Set([...pinnedDispatchIds, ...consistPhysicalIds]),
+      ];
       if (dispatchedPhysicalIds.length) {
         await manager
           .getRepository(Wagon)
@@ -2995,6 +3101,25 @@ export class TrainSchedulingService {
             { id: In(dispatchedPhysicalIds) },
             { status: WagonStatus.Assigned, currentTrainScheduleId: scheduleId },
           );
+        const dispatchedWagons = await manager.getRepository(Wagon).find({
+          where: { id: In(dispatchedPhysicalIds) },
+          select: { id: true, wagonNumber: true, currentYardId: true, trainId: true },
+        });
+        await this.wagonHistory?.record(
+          manager,
+          dispatchedWagons.map((w) => ({
+            wagonId: w.id,
+            wagonNumber: w.wagonNumber,
+            type: WagonEventType.Dispatched,
+            occurredAt: now,
+            actorUserId: userId ?? null,
+            fromYardId: w.currentYardId ?? null,
+            trainId: w.trainId ?? schedule.trainSet?.trainId ?? null,
+            trainScheduleId: scheduleId,
+            toValue: WagonStatus.Assigned,
+            metadata: { destinationYardId: schedule.destinationStationId ?? null },
+          })),
+        );
       }
       // Planned couples boarding at the ORIGIN join the built train now — the
       // departure is the moment they are physically hooked on. Mid-route
@@ -3032,6 +3157,32 @@ export class TrainSchedulingService {
             status: WagonStatus.Assigned,
             currentTrainScheduleId: scheduleId,
           });
+          await this.wagonHistory?.record(manager, [
+            {
+              wagonId: wagon.id,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.CoupledToTrain,
+              occurredAt: now,
+              actorUserId: userId ?? null,
+              fromYardId: coupleYardId,
+              trainId: dispatchTrainId,
+              trainScheduleId: scheduleId,
+              toValue: maxSeq,
+              reason: 'Planned couple at the origin yard',
+              metadata: { status: { from: wagon.status, to: WagonStatus.Assigned } },
+            },
+            {
+              wagonId: wagon.id,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.Dispatched,
+              occurredAt: now,
+              actorUserId: userId ?? null,
+              fromYardId: coupleYardId,
+              trainId: dispatchTrainId,
+              trainScheduleId: scheduleId,
+              toValue: WagonStatus.Assigned,
+            },
+          ]);
           await manager.getRepository(ScheduleWagonAdjustmentLog).save(
             manager.getRepository(ScheduleWagonAdjustmentLog).create({
               trainScheduleId: scheduleId,
@@ -3057,6 +3208,15 @@ export class TrainSchedulingService {
       // that the operator didn't load individually are auto-loaded now — the
       // train is leaving with them. Mid-corridor boarders stay PAID until the
       // operator loads them at their own yard.
+      //
+      // When the client sends the confirmed list, loading is a MANUAL decision:
+      // only the ticked bookings are stamped loaded. Anything unticked was
+      // already unassigned above, but a booking can also sit here unticked and
+      // still attached (government, or one this predicate cannot shed) — those
+      // must not be auto-loaded, or an empty wagon rides as if it carried cargo.
+      // Absent (older clients) = auto-load every origin boarder, the historic
+      // behavior.
+      const confirmedLoadedIds = dto.loadedBookingIds;
       await manager.query(
         `UPDATE freight.bookings b
             SET status = 'IN_TRANSIT',
@@ -3068,8 +3228,14 @@ export class TrainSchedulingService {
             AND b.deleted_at IS NULL
             AND b.origin_yard_id = $2
             AND b.loaded_at IS NULL
-            AND (b.status = 'PAID' OR (b.is_government = true AND b.status = 'APPROVED'))`,
-        [scheduleId, schedule.originStationId, now],
+            AND (b.payment_status = 'PAID' OR (b.is_government = true AND b.status = 'APPROVED'))
+            AND ($4::uuid[] IS NULL OR b.id = ANY($4::uuid[]))`,
+        [
+          scheduleId,
+          schedule.originStationId,
+          now,
+          confirmedLoadedIds ? confirmedLoadedIds : null,
+        ],
       );
       // Close the booking window; any still-pending (unallocated) reservations don't ride this train.
       await manager
@@ -3167,11 +3333,19 @@ export class TrainSchedulingService {
     context: { action: string; yardLabel?: string },
   ): Promise<void> {
     if (!schedule.trainSetId) return;
-    const rows: Array<{ reference: string; loaded: string; total: string }> =
-      await this.dataSource.query(
-        `SELECT b.reference,
+    const rows: Array<{
+      bookingId: string;
+      reference: string;
+      loaded: string;
+      total: string;
+      unloadedAllocationIds: string[];
+    }> = await this.dataSource.query(
+      `SELECT b.id AS "bookingId",
+                b.reference,
                 COUNT(*) FILTER (WHERE a.status IN ('LOADED', 'DEPARTED')) AS loaded,
-                COUNT(*) AS total
+                COUNT(*) AS total,
+                ARRAY_AGG(a.id) FILTER (WHERE a.status NOT IN ('LOADED', 'DEPARTED'))
+                  AS "unloadedAllocationIds"
            FROM freight.wagon_booking_allocations a
            JOIN freight.train_set_wagons tsw ON tsw.id = a.train_set_wagon_id
            JOIN freight.bookings b ON b.id = a.booking_id
@@ -3183,18 +3357,38 @@ export class TrainSchedulingService {
           GROUP BY b.id, b.reference
          HAVING COUNT(*) FILTER (WHERE a.status IN ('LOADED', 'DEPARTED')) > 0
             AND COUNT(*) FILTER (WHERE a.status NOT IN ('LOADED', 'DEPARTED')) > 0`,
-        [schedule.trainSetId, boardingYardId],
-      );
+      [schedule.trainSetId, boardingYardId],
+    );
     if (rows.length) {
       const detail = rows
         .map((r) => `${r.reference} (${r.loaded}/${r.total} wagons loaded)`)
         .join(', ');
       const where = context.yardLabel ? ` at ${context.yardLabel}` : '';
-      throw new BadRequestException(
-        `Cannot ${context.action}: booking(s) partially loaded${where} — load every wagon ` +
+      // The message stays human-readable for logs and older clients, but the
+      // payload carries the machine-readable cut so the UI can offer the
+      // EDR-fault / customer-fault decision instead of parsing prose.
+      throw new BadRequestException({
+        statusCode: 400,
+        error: 'Bad Request',
+        code: 'PARTIALLY_LOADED_BOOKINGS',
+        message:
+          `Cannot ${context.action}: booking(s) partially loaded${where} — load every wagon ` +
           `or cancel the remainder (customer fault: cancellation fee; EDR fault: no fee, ` +
           `rebookable) first: ${detail}`,
-      );
+        partiallyLoaded: {
+          scheduleId: schedule.id,
+          boardingYardId,
+          yardLabel: context.yardLabel ?? null,
+          action: context.action,
+          bookings: rows.map((r) => ({
+            bookingId: r.bookingId,
+            reference: r.reference,
+            loadedWagons: Number(r.loaded),
+            totalWagons: Number(r.total),
+            unloadedAllocationIds: r.unloadedAllocationIds ?? [],
+          })),
+        },
+      });
     }
   }
 
@@ -3221,6 +3415,20 @@ export class TrainSchedulingService {
     }
   }
 
+  /**
+   * The log-pass twin of {@link unloadedOriginBoarderIds}: bookings that boarded
+   * at `yardId` and are still unloaded once the train has left it. Same
+   * predicate — partially-loaded bookings (loading_started_at set) are excluded
+   * because assertNoPartiallyLoadedBookings resolves those first, and government
+   * bookings can never be shed.
+   */
+  private async unloadedBoarderIdsAtYard(
+    scheduleId: string,
+    yardId: string,
+  ): Promise<string[]> {
+    return this.unloadedOriginBoarderIds(scheduleId, yardId);
+  }
+
   private async unloadedOriginBoarderIds(
     scheduleId: string,
     originYardId: string,
@@ -3237,7 +3445,7 @@ export class TrainSchedulingService {
           AND b.loading_started_at IS NULL
           AND COALESCE(tsb.loading_status, 'UNLOADED') <> 'LOADED'
           AND b.is_government = false
-          AND (b.status = 'PAID'
+          AND (b.payment_status = 'PAID'
             OR (b.shipping_line_company_id IS NOT NULL AND b.status = 'FULLY_EXECUTED'))`,
       [scheduleId, originYardId],
     );
@@ -3351,7 +3559,7 @@ export class TrainSchedulingService {
     // milestone still counts as paid — the clearance views self-heal the row on
     // read, and the gate pass must not lag behind that.
     for (const booking of bookings) {
-      if (booking.paymentStatus === 'PAID' || booking.status === 'PAID') {
+      if (booking.paymentStatus === 'PAID') {
         paidBookingIds.add(booking.id);
       }
     }
@@ -3550,17 +3758,19 @@ export class TrainSchedulingService {
 
     // Leg slots couple mid-corridor — this origin document must say where their
     // cargo boards instead of listing it as loaded here (see the import list).
-    const slotYardLabels = await this.yardLabelsById(
-      (schedule.trainSet?.wagons ?? []).map((wagon) => wagon.boardYardId),
+    // Also doubles as the per-row Departure/Arrival Station lookup below.
+    const yardLabelById = await this.yardLabelsById(
+      (schedule.trainSet?.wagons ?? []).flatMap((wagon) => [wagon.boardYardId, wagon.alightYardId]),
     );
     const pendingBoardYardLabelBySlot = new Map(
       (schedule.trainSet?.wagons ?? [])
         .filter((wagon) => wagon.boardYardId)
-        .map((wagon) => [wagon.id, slotYardLabels.get(wagon.boardYardId!) ?? 'en route']),
+        .map((wagon) => [wagon.id, yardLabelById.get(wagon.boardYardId!) ?? 'en route']),
     );
 
     const html = this.buildExportLoadListHtml(schedule, {
       pendingBoardYardLabelBySlot,
+      yardLabelById,
       emptyContainers: await this.loadedEmptyContainers(scheduleId),
       logoImageUrl: await this.logoSettings.getLogoImageUrl(),
     });
@@ -3593,6 +3803,13 @@ export class TrainSchedulingService {
     const wagons = (schedule.trainSet?.wagons ?? [])
       .filter((wagon) => {
         if (wagon.status === 'DEPARTED') return false;
+        // No physical wagon pinned to the slot — a booking can hold an
+        // allocation before a real wagon backs it (e.g. a fleet shortfall
+        // left it unpinned). There is nothing physical here to marshal, and
+        // a REAL cut also lands here: it nulls physicalWagonId without ever
+        // touching this slot's own status, so a cut wagon would otherwise
+        // linger as a phantom row with its cargo still listed.
+        if (!wagon.physicalWagonId) return false;
         const hasLoaded = (wagon.allocations ?? []).some((a) => a.status === 'LOADED');
         return wagon.boardYardId == null || hasLoaded;
       })
@@ -3617,6 +3834,24 @@ export class TrainSchedulingService {
     return { wagons, unassignedBookings };
   }
 
+  /**
+   * Corrects intercityOnBoardView's CURRENT-state wagon list against a
+   * specific stop's document. intercityOnBoardView's "boardYardId == null ||
+   * hasLoaded" test reads whatever is true RIGHT NOW — it can't distinguish
+   * "this leg slot coupled at THIS stop" from "it coupled at a LATER stop
+   * that has, by generation time, also already happened" (both look LOADED).
+   * Reprinting an earlier stop's document after a later one has run would
+   * otherwise leak the later stop's wagons in. `boardedWagonNumbers` is the
+   * set of physical wagon numbers with a logged ADD at or before this stop
+   * (see marshallingDocumentAt) — the ground truth a real-time heuristic
+   * can't provide once multiple stops have already happened.
+   */
+  private wagonsAsOfStop(wagons: TrainSetWagon[], boardedWagonNumbers: Set<string>): TrainSetWagon[] {
+    return wagons.filter(
+      (wagon) => wagon.boardYardId == null || boardedWagonNumbers.has(wagon.physicalWagon?.wagonNumber ?? ''),
+    );
+  }
+
   /**
    * Every corridor stop where the consist actually changed for this schedule
    * (coupled, uncoupled, or switched — any flavor), in the order the train
@@ -3711,11 +3946,37 @@ export class TrainSchedulingService {
       );
     }
 
-    const { wagons, unassignedBookings } = this.intercityOnBoardView(schedule);
+    const { wagons: currentWagons, unassignedBookings } = this.intercityOnBoardView(schedule);
+    // intercityOnBoardView's "boardYardId == null || hasLoaded" test reads
+    // CURRENT state — it can't tell "coupled here" from "coupled at a LATER
+    // stop that has since also happened" (both look LOADED by generation
+    // time once the trip has moved past this stop). Reprinting Marshalling 2
+    // after Marshalling 3's stop already ran would otherwise show Marshalling
+    // 3's coupled wagons too. Correct it against the log: a leg-slot wagon
+    // belongs on THIS stop's document only if it actually has a logged ADD
+    // at or before THIS stop's own timestamp.
+    const boardedByThisStop = new Set(
+      (
+        await this.dataSource.getRepository(ScheduleWagonAdjustmentLog).find({
+          where: {
+            trainScheduleId: scheduleId,
+            action: 'ADD',
+            occurredAt: LessThanOrEqual(new Date(stop.firstOccurredAt)),
+          },
+        })
+      ).map((row) => row.wagonNumber),
+    );
+    const wagons = this.wagonsAsOfStop(currentWagons, boardedByThisStop);
     const logRows = await this.dataSource.getRepository(ScheduleWagonAdjustmentLog).find({
       where: { trainScheduleId: scheduleId, yardId: stop.yardId },
       order: { occurredAt: 'ASC' },
     });
+    // Per-row Departure/Arrival Station: a whole-route wagon reads the
+    // schedule's own origin/destination, a leg-slot wagon reads where IT
+    // boards/alights instead.
+    const yardLabelById = await this.yardLabelsById(
+      (schedule.trainSet?.wagons ?? []).flatMap((wagon) => [wagon.boardYardId, wagon.alightYardId]),
+    );
     const html = this.buildExportLoadListHtml(schedule, {
       title: `Intercity Marshalling Document / Load List (Marshalling ${stopIndex})`,
       positionLabel: `At ${stop.yardLabel}`,
@@ -3724,6 +3985,7 @@ export class TrainSchedulingService {
       emptyContainers: await this.loadedEmptyContainers(scheduleId),
       logoImageUrl: await this.logoSettings.getLogoImageUrl(),
       consistChangesAtStop: this.consistChangesAt(schedule, logRows),
+      yardLabelById,
     });
     // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
     const buffer = await this.pdfDocuments.renderTabularDocument(html, `Marshalling ${stopIndex}`);
@@ -3763,6 +4025,9 @@ export class TrainSchedulingService {
       ? `After ${last.yard?.label ?? last.yard?.code ?? 'checkpoint'}`
       : `At ${schedule.originStation?.label ?? schedule.originStation?.code ?? 'origin'} — no checkpoint recorded`;
     const { wagons, unassignedBookings } = this.intercityOnBoardView(schedule);
+    const yardLabelById = await this.yardLabelsById(
+      (schedule.trainSet?.wagons ?? []).flatMap((wagon) => [wagon.boardYardId, wagon.alightYardId]),
+    );
     const html = this.buildExportLoadListHtml(schedule, {
       title: 'Intercity Marshalling Document / Load List (Marshalling 2)',
       positionLabel,
@@ -3770,6 +4035,7 @@ export class TrainSchedulingService {
       unassignedBookings,
       emptyContainers: await this.loadedEmptyContainers(scheduleId),
       logoImageUrl: await this.logoSettings.getLogoImageUrl(),
+      yardLabelById,
     });
     // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
     const buffer = await this.pdfDocuments.renderTabularDocument(html, 'Intercity marshalling / load list');
@@ -3839,6 +4105,10 @@ export class TrainSchedulingService {
       // Slots that couple to the train downstream (slot id → board yard label).
       // Their cargo renders as TO LOAD AT and stays out of the loaded tallies.
       pendingBoardYardLabelBySlot?: Map<string, string>;
+      // yardId → label, for the per-row Departure/Arrival Station columns
+      // (falls back to the schedule's own origin/destination when a wagon's
+      // boardYardId/alightYardId is null — i.e. it rides the whole corridor).
+      yardLabelById?: Map<string, string>;
       // Numbered marshalling docs only (see marshallingDocumentAt /
       // consistChangesAt) — couples/uncouples/switches logged at THIS stop.
       // Origin import/export docs never pass this, so they render no such box.
@@ -3860,10 +4130,20 @@ export class TrainSchedulingService {
     const time = (value: unknown) => (value ? new Date(value as string | Date).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }) : '-');
     const bookingById = new Map((schedule.scheduleBookings ?? []).map((link) => [link.bookingId, link.booking]));
     // The document is checked against the physical train, so it has to run in
-    // consist order — the relation comes back unordered.
-    const wagons = [...(opts?.wagons ?? schedule.trainSet?.wagons ?? [])].sort(
-      (a, b) => Number(a.sequenceNo ?? 0) - Number(b.sequenceNo ?? 0),
-    );
+    // consist order — the relation comes back unordered. Slots planned to
+    // couple at a LATER stop (pendingBoardYardLabelBySlot, origin docs only —
+    // intercity calls never pass it, their wagons list is already on-board
+    // only) are dropped here, not just tallied around: they are not part of
+    // the departing consist, so they get no row and no count on this document.
+    // Their own coupling shows up on THAT stop's own marshalling document.
+    const wagons = [...(opts?.wagons ?? schedule.trainSet?.wagons ?? [])]
+      .filter((wagon) => !opts?.pendingBoardYardLabelBySlot?.get(wagon.id))
+      // No physical wagon pinned to the slot (fleet shortfall left a booking's
+      // allocation unpinned, or a REAL cut nulled it out): nothing physical
+      // to marshal, so no row. Harmless no-op for the numbered docs, whose
+      // wagons list already went through intercityOnBoardView's own check.
+      .filter((wagon) => Boolean(wagon.physicalWagonId))
+      .sort((a, b) => Number(a.sequenceNo ?? 0) - Number(b.sequenceNo ?? 0));
     // Empties sit on wagons that carry no booking allocation, keyed by the wagon
     // slot recorded when they were loaded.
     const emptiesByWagon = new Map<number, EmptyContainerReturn[]>();
@@ -3874,15 +4154,28 @@ export class TrainSchedulingService {
         empty,
       ]);
     }
+    const originLabel = schedule.originStation?.label ?? schedule.originStation?.code;
+    const destinationLabel = schedule.destinationStation?.label ?? schedule.destinationStation?.code;
     const rows = wagons
       .flatMap((wagon) => {
+        // Departure/Arrival Station per row: a leg-slot wagon boards/alights
+        // somewhere other than the schedule's own endpoints; a whole-route
+        // wagon just reads origin/destination.
+        const departureLabel = wagon.boardYardId
+          ? (opts?.yardLabelById?.get(wagon.boardYardId) ?? 'en route')
+          : originLabel;
+        const arrivalLabel = wagon.alightYardId
+          ? (opts?.yardLabelById?.get(wagon.alightYardId) ?? 'en route')
+          : destinationLabel;
         // Wagon identity is the same on every row the wagon produces, loaded or not.
         const wagonCells = `<td>${esc(wagon.sequenceNo)}</td>
             <td>${esc(wagon.physicalWagon?.wagonNumber)}</td>
             <td>${esc(wagon.wagonType?.code ?? wagon.wagonType?.name)}</td>
             <td class="num">${esc(Number(wagon.lengthMeters || 0).toFixed(3))}</td>
             <td class="num">${esc(Number(wagon.wagonType?.tareWeightTons ?? 0).toFixed(2))}</td>
-            <td class="num">${esc(Number(wagon.capacityTons || 0).toFixed(3))}</td>`;
+            <td class="num">${esc(Number(wagon.capacityTons || 0).toFixed(3))}</td>
+            <td>${esc(departureLabel)}</td>
+            <td>${esc(arrivalLabel)}</td>`;
         const allocations = wagon.allocations ?? [];
         // An empty wagon still runs in the consist, so it still gets a line. Staff
         // check this document against the physical train — a wagon with no row
@@ -3906,11 +4199,10 @@ export class TrainSchedulingService {
           return [
             `<tr class="empty">
             ${wagonCells}
-            <td colspan="4">EMPTY — no cargo allocated</td>
+            <td colspan="5">EMPTY — no cargo allocated</td>
           </tr>`,
           ];
         }
-        const pendingAt = opts?.pendingBoardYardLabelBySlot?.get(wagon.id);
         return allocations.map((allocation) => {
           const booking = allocation.booking ?? bookingById.get(allocation.bookingId);
           const cargoType = (booking as unknown as { cargoType?: { name?: string; code?: string } } | undefined)?.cargoType;
@@ -3922,7 +4214,7 @@ export class TrainSchedulingService {
           const chassisNumbers = containerItems.map((item) => item.chassisNumber).filter(Boolean).join(', ');
           return `<tr>
             ${wagonCells}
-            <td>${pendingAt ? `TO LOAD AT ${esc(pendingAt).toUpperCase()} — ` : ''}${esc(cargoType?.name ?? cargoType?.code ?? allocation.loadType)}</td>
+            <td>${esc(cargoType?.name ?? cargoType?.code ?? allocation.loadType)}</td>
             <td>${esc(companyName)}</td>
             <td>${esc(containerNumbers || firstContainer?.containerNumber)}</td>
             <td>${esc(chassisNumbers)}</td>
@@ -3935,7 +4227,7 @@ export class TrainSchedulingService {
     // they are still physically on the train, so they get rows of their own.
     const unassigned = opts?.unassignedBookings ?? [];
     const unassignedRows = unassigned.length
-      ? `<tr class="empty"><td colspan="11">ON BOARD — WAGON NOT RECORDED</td></tr>` +
+      ? `<tr class="empty"><td colspan="13">ON BOARD — WAGON NOT RECORDED</td></tr>` +
         unassigned
           .map((booking) => {
             const containerNumbers = (booking.bookingContainers ?? [])
@@ -3944,7 +4236,7 @@ export class TrainSchedulingService {
               .join(', ');
             const leg = `${booking.originYard?.label ?? booking.originYard?.code ?? '-'} → ${booking.destinationYard?.label ?? booking.destinationYard?.code ?? '-'}`;
             return `<tr>
-            <td colspan="6">${esc(booking.reference)} — ${esc(leg)}</td>
+            <td colspan="8">${esc(booking.reference)} — ${esc(leg)}</td>
             <td>${esc(booking.cargoType?.cargoTypeName ?? booking.cargoType?.code)}</td>
             <td>${esc(booking.company?.name)}</td>
             <td>${esc(containerNumbers)}</td>
@@ -3959,27 +4251,20 @@ export class TrainSchedulingService {
         (wagon.allocations ?? []).length === 0 &&
         !emptiesByWagon.get(Number(wagon.sequenceNo))?.length,
     ).length;
-    const loadsHere = (wagon: TrainSetWagon) => !opts?.pendingBoardYardLabelBySlot?.get(wagon.id);
     const totalWeight = wagons.reduce(
       (sum, wagon) =>
-        sum +
-        (loadsHere(wagon)
-          ? (wagon.allocations ?? []).reduce((wagonSum, allocation) => wagonSum + Number(allocation.allocatedWeightTons || 0), 0)
-          : 0),
+        sum + (wagon.allocations ?? []).reduce((wagonSum, allocation) => wagonSum + Number(allocation.allocatedWeightTons || 0), 0),
       0,
     );
 
     // Container count summary (40ft, 20ft) — empties returning to Djibouti are
-    // physically on the train, so they count, and are called out on their own tile.
-    // Cargo boarding downstream is not on this train yet — it tallies separately.
-    let count40ft = 0, count20ft = 0, pendingContainers = 0;
+    // physically on the train, so they count, and are called out on their own
+    // tile. Cargo boarding downstream never enters this loop — `wagons` above
+    // already excludes those slots.
+    let count40ft = 0, count20ft = 0;
     wagons.forEach((wagon) => {
       (wagon.allocations ?? []).forEach((allocation) => {
         (allocation.containerItems ?? []).forEach((item) => {
-          if (!loadsHere(wagon)) {
-            pendingContainers++;
-            return;
-          }
           const size = this.resolveContainerItemSize(item);
           if (size === 40) count40ft++;
           else if (size === 20) count20ft++;
@@ -4047,7 +4332,6 @@ export class TrainSchedulingService {
     <div class="tile"><span>Containers 40ft</span><strong>${esc(count40ft)}</strong></div>
     <div class="tile"><span>Containers 20ft</span><strong>${esc(count20ft)}</strong></div>
     <div class="tile"><span>Total containers</span><strong>${esc(count40ft + count20ft)}</strong></div>
-    ${pendingContainers ? `<div class="tile"><span>To load en route</span><strong>${esc(pendingContainers)} containers</strong></div>` : ''}
     ${emptyContainers.length ? `<div class="tile"><span>Empty containers</span><strong>${esc(emptyContainers.length)}</strong></div>` : ''}
     <div class="tile"><span>Prepared person</span><strong>${esc(schedule.preparedByUserId)}</strong></div>
     <div class="tile"><span>Check person</span><strong>${esc(schedule.checkedByUserId)}</strong></div>
@@ -4093,6 +4377,8 @@ export class TrainSchedulingService {
         <th class="num">Equated Length</th>
         <th class="num">Tare Weight</th>
         <th class="num">Load Capacity</th>
+        <th>Departure Station</th>
+        <th>Arrival Station</th>
         <th>Cargo Type</th>
         <th>Company</th>
         <th>Container No</th>
@@ -4101,7 +4387,7 @@ export class TrainSchedulingService {
       </tr>
     </thead>
     <tbody>
-      ${rows || '<tr><td colspan="10">No wagons on this train set.</td></tr>'}
+      ${rows || '<tr><td colspan="13">No wagons on this train set.</td></tr>'}
       ${unassignedRows}
     </tbody>
   </table>
@@ -4247,30 +4533,26 @@ export class TrainSchedulingService {
         .replace(/'/g, '&#39;');
     const date = (value: unknown) => (value ? new Date(value as string | Date).toLocaleString('en-GB') : '-');
     const status = loadList.operation.status;
-    // A leg slot (boardYard set) couples mid-corridor — its cargo is NOT on the
-    // physical train this Djibouti-side document is checked against, so it must
-    // stay out of the loaded tallies or the gate count stops matching.
-    const loadsHere = (wagon: (typeof loadList.wagons)[number]) => !wagon.boardYard;
-    const totalAllocations = loadList.wagons.reduce((sum, wagon) => sum + wagon.allocations.length, 0);
-    const totalWeight = loadList.wagons.reduce(
-      (sum, wagon) =>
-        sum +
-        (loadsHere(wagon)
-          ? wagon.allocations.reduce((wagonSum, allocation) => wagonSum + Number(allocation.allocatedWeightTons || 0), 0)
-          : 0),
+    // A leg slot (boardYard set) couples mid-corridor — it is not part of the
+    // consist this Djibouti-side document is checked against yet, so it gets
+    // no row and no count here at all. Its own coupling shows up on THAT
+    // stop's own marshalling document once it actually happens. Same for a
+    // slot with no physical wagon pinned at all — a booking can hold an
+    // allocation before a real wagon backs it (fleet shortfall), or a REAL
+    // cut nulled it out; either way there is nothing physical to marshal.
+    const wagons = loadList.wagons.filter((wagon) => !wagon.boardYard && wagon.wagonNumber != null);
+    const totalAllocations = wagons.reduce((sum, wagon) => sum + wagon.allocations.length, 0);
+    const totalWeight = wagons.reduce(
+      (sum, wagon) => sum + wagon.allocations.reduce((wagonSum, allocation) => wagonSum + Number(allocation.allocatedWeightTons || 0), 0),
       0,
     );
-    const emptyWagons = loadList.wagons.filter((wagon) => wagon.allocations.length === 0).length;
+    const emptyWagons = wagons.filter((wagon) => wagon.allocations.length === 0).length;
 
-    // Container count summary (40ft, 20ft) — loaded at origin vs. en route
-    let count40ft = 0, count20ft = 0, pendingContainers = 0;
-    loadList.wagons.forEach((wagon) => {
+    // Container count summary (40ft, 20ft)
+    let count40ft = 0, count20ft = 0;
+    wagons.forEach((wagon) => {
       wagon.allocations.forEach((allocation) => {
         (allocation.containerItems ?? []).forEach((item) => {
-          if (!loadsHere(wagon)) {
-            pendingContainers++;
-            return;
-          }
           const size = this.resolveContainerItemSize(item);
           if (size === 40) count40ft++;
           else if (size === 20) count20ft++;
@@ -4278,7 +4560,7 @@ export class TrainSchedulingService {
       });
     });
 
-    const allocationRows = loadList.wagons
+    const allocationRows = wagons
       .flatMap((wagon) => {
         const wagonCells = `<td>${esc(wagon.sequenceNo)}</td>
             <td>${esc(wagon.wagonNumber)}</td>
@@ -4311,7 +4593,7 @@ export class TrainSchedulingService {
             <td>${esc(allocation.loadType)}</td>
             <td>${esc(allocation.containerNumbers.length ? allocation.containerNumbers.join(', ') : '-')}</td>
             <td>${esc(sealNumbers || '-')}</td>
-            <td>${wagon.boardYard ? `TO BE LOADED AT ${esc(wagon.boardYard).toUpperCase()}` : ''}</td>
+            <td></td>
             <td class="num">${esc(Number(allocation.allocatedWeightTons || 0).toFixed(3))}</td>
           </tr>`;
           },
@@ -4378,13 +4660,12 @@ export class TrainSchedulingService {
       <div class="tile"><span>Origin</span><strong>${esc(loadList.origin)}</strong></div>
       <div class="tile"><span>Destination</span><strong>${esc(loadList.destination)}</strong></div>
       <div class="tile"><span>Total bookings</span><strong>${esc(loadList.totalBookings)}</strong></div>
-      <div class="tile"><span>Wagons</span><strong>${esc(loadList.wagons.length)}${emptyWagons ? ` (${emptyWagons} empty)` : ''}</strong></div>
+      <div class="tile"><span>Wagons</span><strong>${esc(wagons.length)}${emptyWagons ? ` (${emptyWagons} empty)` : ''}</strong></div>
       <div class="tile"><span>Allocations</span><strong>${esc(totalAllocations)}</strong></div>
       <div class="tile"><span>Total weight</span><strong>${esc(totalWeight.toFixed(3))} T</strong></div>
       <div class="tile"><span>Containers 40ft</span><strong>${esc(count40ft)}</strong></div>
       <div class="tile"><span>Containers 20ft</span><strong>${esc(count20ft)}</strong></div>
       <div class="tile"><span>Total containers</span><strong>${esc(count40ft + count20ft)}</strong></div>
-      ${pendingContainers ? `<div class="tile"><span>To load en route</span><strong>${esc(pendingContainers)} containers</strong></div>` : ''}
       <div class="tile"><span>Gatepass granted</span><strong>${esc(date(loadList.operation.gatepassGrantedAt))}</strong></div>
     </div>
 
@@ -4918,6 +5199,24 @@ export class TrainSchedulingService {
     // skipped checkpoint log cannot smuggle an unresolved yard past the gate.
     await this.assertPassedYardsFullyLoaded(schedule, stations, dto.sequenceNo);
 
+    // Mid-corridor leave-behind. Recording THIS station means the train has
+    // left the previous one, so cargo that boarded back there has had its last
+    // chance to load: anything the operator did not tick is deallocated and
+    // returned to the pool, exactly as dispatch does for the origin yard.
+    // Origin (seq 0) is dispatch's job, so only seq >= 1 has a departed yard.
+    if (dto.loadedBookingIds && dto.sequenceNo > 0) {
+      const departedYardId = stations.find(
+        (s) => s.sequenceNo === dto.sequenceNo - 1,
+      )?.yardId;
+      if (departedYardId) {
+        const keep = new Set(dto.loadedBookingIds);
+        const candidates = await this.unloadedBoarderIdsAtYard(scheduleId, departedYardId);
+        for (const bookingId of candidates.filter((id) => !keep.has(id))) {
+          await this.unassignBooking(scheduleId, bookingId, undefined);
+        }
+      }
+    }
+
     // Upsert by (scheduleId, sequenceNo) so re-logging a station updates rather than duplicates.
     const [existing] = await this.trainCheckpointEventsRepository.findAll({
       where: { trainScheduleId: scheduleId, sequenceNo: dto.sequenceNo },
@@ -5004,6 +5303,7 @@ export class TrainSchedulingService {
         );
         const adjustmentRows: ScheduleWagonAdjustmentLog[] = [];
         const movementRows: WagonMovement[] = [];
+        const historyRows: WagonEventInput[] = [];
         let realCutHappened = false;
         for (const [wagonId, cutYardId] of cutNow) {
           const wagon = cutWagonById.get(wagonId);
@@ -5011,6 +5311,31 @@ export class TrainSchedulingService {
           if (!wagon || wagon.currentTrainScheduleId !== scheduleId) continue;
           if (realCutIds.has(wagonId) && builtTrainId) {
             // REAL cut: the built train permanently loses the wagon here.
+            historyRows.push(
+              {
+                wagonId,
+                wagonNumber: wagon.wagonNumber,
+                type: WagonEventType.CutAtYard,
+                occurredAt,
+                fromYardId: scheduleYardOf(schedule.plannedWagonYards, wagon) ?? schedule.originStationId ?? null,
+                toYardId: cutYardId,
+                trainId: builtTrainId,
+                trainScheduleId: scheduleId,
+                toValue: WagonStatus.Available,
+                metadata: { permanent: true },
+              },
+              {
+                wagonId,
+                wagonNumber: wagon.wagonNumber,
+                type: WagonEventType.UncoupledFromTrain,
+                occurredAt,
+                fromYardId: cutYardId,
+                trainId: builtTrainId,
+                trainScheduleId: scheduleId,
+                fromValue: wagon.sequenceNumber,
+                reason: 'Cut from the train at this yard (permanent)',
+              },
+            );
             await manager.getRepository(Wagon).update(wagonId, {
               currentYardId: cutYardId,
               currentTrainScheduleId: null,
@@ -5043,6 +5368,18 @@ export class TrainSchedulingService {
             realCutHappened = true;
           } else {
             // Soft cut: sits out the rest of this trip, stays in the build.
+            historyRows.push({
+              wagonId,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.CutAtYard,
+              occurredAt,
+              fromYardId: scheduleYardOf(schedule.plannedWagonYards, wagon) ?? schedule.originStationId ?? null,
+              toYardId: cutYardId,
+              trainId: wagon.trainId ?? null,
+              trainScheduleId: scheduleId,
+              toValue: wagon.trainId ? WagonStatus.Assigned : WagonStatus.Available,
+              metadata: { permanent: false },
+            });
             await manager.getRepository(Wagon).update(wagonId, {
               currentYardId: cutYardId,
               currentTrainScheduleId: null,
@@ -5067,6 +5404,7 @@ export class TrainSchedulingService {
         if (movementRows.length) {
           await manager.getRepository(WagonMovement).save(movementRows);
         }
+        await this.wagonHistory?.record(manager, historyRows);
         // Keep the coupling order gapless after permanent removals.
         if (realCutHappened && builtTrainId) {
           const remaining = await manager.getRepository(Wagon).find({
@@ -5120,6 +5458,18 @@ export class TrainSchedulingService {
               status: WagonStatus.Assigned,
               currentTrainScheduleId: scheduleId,
             });
+            await this.wagonHistory?.record(manager, {
+              wagonId,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.CoupledToTrain,
+              occurredAt,
+              fromYardId: coupleYardId,
+              trainId: builtTrainId,
+              trainScheduleId: scheduleId,
+              toValue: maxSeq,
+              reason: 'Planned couple at a mid-route stop',
+              metadata: { status: { from: wagon.status, to: WagonStatus.Assigned } },
+            });
             coupleLogRows.push(
               manager.getRepository(ScheduleWagonAdjustmentLog).create({
                 trainScheduleId: scheduleId,
@@ -5137,6 +5487,20 @@ export class TrainSchedulingService {
             await manager.getRepository(ScheduleWagonAdjustmentLog).save(coupleLogRows);
           }
         }
+        // Which wagons the position fix below will actually move — read first
+        // so each gets its own PASSED_CHECKPOINT history row (from → to yard).
+        const riding = await manager
+          .getRepository(Wagon)
+          .createQueryBuilder('w')
+          .select(['w.id', 'w.wagonNumber', 'w.currentYardId', 'w.trainId'])
+          .where('w.current_train_schedule_id = :scheduleId', { scheduleId })
+          .andWhere('(w.current_yard_id IS NULL OR w.current_yard_id IN (:...passedYardIds))', {
+            passedYardIds,
+          })
+          .andWhere('w.current_yard_id IS DISTINCT FROM :stationYardId', {
+            stationYardId: station.yardId,
+          })
+          .getMany();
 
         // Leg slots (booking legs boarding/alighting mid-corridor — see
         // stampSlotLegs) reaching their board/alight yard here: logged same as
@@ -5219,6 +5583,20 @@ export class TrainSchedulingService {
             passedYardIds,
           })
           .execute();
+        await this.wagonHistory?.record(
+          manager,
+          riding.map((w) => ({
+            wagonId: w.id,
+            wagonNumber: w.wagonNumber,
+            type: WagonEventType.PassedCheckpoint,
+            occurredAt,
+            fromYardId: w.currentYardId ?? null,
+            toYardId: station.yardId,
+            trainId: w.trainId ?? schedule.trainSet?.trainId ?? null,
+            trainScheduleId: scheduleId,
+            metadata: { sequenceNo: dto.sequenceNo, kind: dto.kind ?? null },
+          })),
+        );
         if (schedule.trainSet?.trainId) {
           await manager
             .getRepository(Train)
@@ -5445,6 +5823,7 @@ export class TrainSchedulingService {
       );
       const arrivalLogRows: ScheduleWagonAdjustmentLog[] = [];
       const arrivalMovementRows: WagonMovement[] = [];
+      const arrivalHistoryRows: WagonEventInput[] = [];
       for (const slot of schedule.trainSet?.wagons ?? []) {
         if (!slot.physicalWagonId) continue;
         const wagon = settleWagonById.get(slot.physicalWagonId);
@@ -5468,6 +5847,32 @@ export class TrainSchedulingService {
           // Arrival fallback for a journey logged without mid-route
           // checkpoints: the REAL cut still permanently removes the wagon
           // from the built train at its cut yard.
+          arrivalHistoryRows.push(
+            {
+              wagonId: wagon.id,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.CutAtYard,
+              occurredAt: now,
+              fromYardId: slot.boardYardId ?? schedule.originStationId ?? null,
+              toYardId: settleYardId,
+              trainId: ownerTrainId,
+              trainScheduleId: scheduleId,
+              bookingId: (slot.allocations ?? [])[0]?.bookingId ?? null,
+              toValue: WagonStatus.Available,
+              metadata: { permanent: true, atArrival: true },
+            },
+            {
+              wagonId: wagon.id,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.UncoupledFromTrain,
+              occurredAt: now,
+              fromYardId: settleYardId,
+              trainId: ownerTrainId,
+              trainScheduleId: scheduleId,
+              fromValue: wagon.sequenceNumber,
+              reason: 'Cut from the train at its planned yard (permanent)',
+            },
+          );
           await manager.getRepository(Wagon).update(wagon.id, {
             currentTrainScheduleId: null,
             trainSetWagonId: null,
@@ -5497,6 +5902,19 @@ export class TrainSchedulingService {
             }),
           );
         } else {
+          arrivalHistoryRows.push({
+            wagonId: wagon.id,
+            wagonNumber: wagon.wagonNumber,
+            type: WagonEventType.SettledOnArrival,
+            occurredAt: now,
+            fromYardId: slot.boardYardId ?? schedule.originStationId ?? null,
+            toYardId: settleYardId,
+            trainId: wagon.trainId ?? null,
+            trainScheduleId: scheduleId,
+            bookingId: (slot.allocations ?? [])[0]?.bookingId ?? null,
+            toValue: wagon.trainId ? WagonStatus.Assigned : WagonStatus.Available,
+            metadata: { slotId: slot.id, loaded: (slot.allocations ?? []).length > 0 },
+          });
           await manager.getRepository(Wagon).update(wagon.id, {
             currentTrainScheduleId: null,
             trainSetWagonId: null,
@@ -5548,6 +5966,18 @@ export class TrainSchedulingService {
         if (!wagon) continue;
         if (wagon.currentTrainScheduleId === scheduleId) {
           // Joined during the trip, slot-less: settle at the destination.
+          arrivalHistoryRows.push({
+            wagonId: wagon.id,
+            wagonNumber: wagon.wagonNumber,
+            type: WagonEventType.SettledOnArrival,
+            occurredAt: now,
+            fromYardId: coupleYardId,
+            toYardId: schedule.destinationStationId ?? null,
+            trainId: wagon.trainId ?? null,
+            trainScheduleId: scheduleId,
+            toValue: wagon.trainId ? WagonStatus.Assigned : WagonStatus.Available,
+            metadata: { loaded: false, coupledMidRoute: true },
+          });
           await manager.getRepository(Wagon).update(wagon.id, {
             currentTrainScheduleId: null,
             trainSetWagonId: null,
@@ -5585,6 +6015,32 @@ export class TrainSchedulingService {
             status: WagonStatus.Assigned,
             currentYardId: schedule.destinationStationId,
           });
+          arrivalHistoryRows.push(
+            {
+              wagonId: wagon.id,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.CoupledToTrain,
+              occurredAt: now,
+              fromYardId: coupleYardId,
+              trainId: arrivalTrainId,
+              trainScheduleId: scheduleId,
+              toValue: arrivalMaxSeq,
+              reason: 'Planned couple joined on arrival',
+              metadata: { status: { from: wagon.status, to: WagonStatus.Assigned } },
+            },
+            {
+              wagonId: wagon.id,
+              wagonNumber: wagon.wagonNumber,
+              type: WagonEventType.SettledOnArrival,
+              occurredAt: now,
+              fromYardId: coupleYardId,
+              toYardId: schedule.destinationStationId ?? null,
+              trainId: arrivalTrainId,
+              trainScheduleId: scheduleId,
+              toValue: WagonStatus.Assigned,
+              metadata: { loaded: false, coupledMidRoute: true },
+            },
+          );
           arrivalLogRows.push(
             manager.getRepository(ScheduleWagonAdjustmentLog).create({
               trainScheduleId: scheduleId,
@@ -5609,9 +6065,43 @@ export class TrainSchedulingService {
           );
         }
       }
+      // Consist-only empties: coupled to the built train and bound at dispatch
+      // so the checkpoint position fix moves them, but they own no slot, so the
+      // per-slot settle above never sees them. Release them here or they stay
+      // locked to a finished schedule and no later train can pick them up.
+      // They carry no cargo, so they simply settle where the train ended up.
+      const looseEmpties = await manager.getRepository(Wagon).find({
+        where: { currentTrainScheduleId: scheduleId },
+        select: { id: true, wagonNumber: true, currentYardId: true, trainId: true },
+      });
+      arrivalHistoryRows.push(
+        ...looseEmpties.map((w) => ({
+          wagonId: w.id,
+          wagonNumber: w.wagonNumber,
+          type: WagonEventType.SettledOnArrival,
+          occurredAt: now,
+          fromYardId: w.currentYardId ?? null,
+          toYardId: schedule.destinationStationId ?? null,
+          trainId: w.trainId ?? null,
+          trainScheduleId: scheduleId,
+          metadata: { loaded: false, consistOnly: true },
+        })),
+      );
+      await manager
+        .getRepository(Wagon)
+        .createQueryBuilder()
+        .update(Wagon)
+        .set({
+          currentTrainScheduleId: null,
+          trainSetWagonId: null,
+          currentYardId: schedule.destinationStationId,
+        })
+        .where('current_train_schedule_id = :scheduleId', { scheduleId })
+        .execute();
       if (arrivalLogRows.length) {
         await manager.getRepository(ScheduleWagonAdjustmentLog).save(arrivalLogRows);
       }
+      await this.wagonHistory?.record(manager, arrivalHistoryRows);
       if (arrivalMovementRows.length) {
         await manager.getRepository(WagonMovement).save(arrivalMovementRows);
       }
@@ -5808,6 +6298,19 @@ export class TrainSchedulingService {
       }
       for (const wagon of schedule.trainSet?.wagons ?? []) {
         if (wagon.physicalWagonId) {
+          await this.wagonHistory?.record(manager, {
+            wagonId: wagon.physicalWagonId,
+            wagonNumber: wagon.physicalWagon?.wagonNumber ?? null,
+            type: WagonEventType.ReturnedOnCancel,
+            actorUserId: userId ?? null,
+            fromYardId: wagon.physicalWagon?.currentYardId ?? null,
+            toYardId: schedule.originStationId ?? null,
+            trainId: wagon.physicalWagon?.trainId ?? null,
+            trainScheduleId: id,
+            toValue: wagon.physicalWagon?.trainId ? WagonStatus.Assigned : WagonStatus.Available,
+            reason: dto?.reason?.trim() || 'Schedule cancelled',
+            metadata: { slotId: wagon.id },
+          });
           await manager.getRepository(Wagon).update(wagon.physicalWagonId, {
             currentTrainScheduleId: null,
             trainSetWagonId: null,
@@ -5844,7 +6347,8 @@ export class TrainSchedulingService {
       const booking = await this.bookingsRepository
         .findByIdWithFiles(sb.bookingId)
         .catch(() => null);
-      if (booking) this.bookingNotifier.scheduleCancelled(booking);
+      // Detached above, so pass the cancelled schedule for its train/voyage numbers.
+      if (booking) this.bookingNotifier.scheduleCancelled(booking, schedule);
     }
 
     // Window retired (DONE) — remove the card from portal/GL lists right away.
@@ -6784,6 +7288,15 @@ export class TrainSchedulingService {
         physicalWagonId: physical.id,
         status: 'RESERVED',
       });
+      await this.wagonHistory?.record(manager, {
+        wagonId: physical.id,
+        wagonNumber: physical.wagonNumber,
+        type: WagonEventType.PinnedToSchedule,
+        trainScheduleId: scheduleId,
+        trainId: builtTrainId ?? null,
+        fromYardId: physical.currentYardId ?? null,
+        metadata: { slotId: slot.trainSetWagonId, auto: true },
+      });
       const pinnedSpans = occupiedSpans.get(physical.id) ?? [];
       pinnedSpans.push(span);
       occupiedSpans.set(physical.id, pinnedSpans);
@@ -8860,6 +9373,21 @@ export class TrainSchedulingService {
       for (const wagon of removed) {
         await manager.getRepository(Wagon).update(wagon.id, detachPatch);
       }
+      const consistReason = (dto as { reason?: string | null }).reason?.trim() || null;
+      await this.wagonHistory?.record(
+        manager,
+        removed.map((wagon) => ({
+          wagonId: wagon.id,
+          wagonNumber: wagon.wagonNumber,
+          type: WagonEventType.UncoupledFromTrain,
+          actorUserId: userId ?? null,
+          trainId: train.id,
+          trainScheduleId: scheduleId,
+          fromYardId: currentYardId ?? null,
+          fromValue: wagon.sequenceNumber,
+          reason: consistReason ?? 'Trimmed from the consist on the schedule',
+        })),
+      );
       if (removed.length && ownSetIds.length) {
         // This train's own pins (all its runs) on trimmed wagons are stale —
         // clear them so the freed wagon isn't still claimed by slots it left.
@@ -8897,6 +9425,32 @@ export class TrainSchedulingService {
         // Mirror on the in-memory row — the compaction below sorts by it.
         to.sequenceNumber = from.sequenceNumber;
         await manager.getRepository(Wagon).update(from.id, detachPatch);
+        await this.wagonHistory?.record(manager, [
+          {
+            wagonId: to.id,
+            wagonNumber: to.wagonNumber,
+            type: WagonEventType.CoupledToTrain,
+            actorUserId: userId ?? null,
+            trainId: train.id,
+            trainScheduleId: scheduleId,
+            fromYardId: to.currentYardId ?? null,
+            toValue: from.sequenceNumber,
+            reason: consistReason ?? `Switched in for ${from.wagonNumber}`,
+            metadata: { replaced: from.wagonNumber, replacedWagonId: from.id },
+          },
+          {
+            wagonId: from.id,
+            wagonNumber: from.wagonNumber,
+            type: WagonEventType.UncoupledFromTrain,
+            actorUserId: userId ?? null,
+            trainId: train.id,
+            trainScheduleId: scheduleId,
+            fromYardId: currentYardId ?? null,
+            fromValue: from.sequenceNumber,
+            reason: consistReason ?? `Switched out for ${to.wagonNumber}`,
+            metadata: { replacedBy: to.wagonNumber, replacedByWagonId: to.id },
+          },
+        ]);
       }
 
       const remaining = consist.filter(
@@ -8912,6 +9466,7 @@ export class TrainSchedulingService {
         }
       }
       let sequence = compacted.length;
+      const addedEvents: WagonEventInput[] = [];
       for (const wagon of added) {
         sequence += 1;
         await manager.getRepository(Wagon).update(wagon.id, {
@@ -8919,7 +9474,20 @@ export class TrainSchedulingService {
           sequenceNumber: sequence,
           status: WagonStatus.Assigned,
         });
+        addedEvents.push({
+          wagonId: wagon.id,
+          wagonNumber: wagon.wagonNumber,
+          type: WagonEventType.CoupledToTrain,
+          actorUserId: userId ?? null,
+          trainId: train.id,
+          trainScheduleId: scheduleId,
+          fromYardId: wagon.currentYardId ?? null,
+          toValue: sequence,
+          reason: consistReason ?? 'Added to the consist on the schedule',
+          metadata: { status: { from: wagon.status, to: WagonStatus.Assigned } },
+        });
       }
+      await this.wagonHistory?.record(manager, addedEvents);
 
       // The schedule is full when every consist wagon is allocated.
       await manager
@@ -10448,6 +11016,8 @@ export class TrainSchedulingService {
           // without the wagons' tare. The legs tab shows this per booking.
           cargoWeightTons: sb.booking ? bookingCargoTons(sb.booking) : 0,
           status: sb.booking?.status ?? null,
+          // Loadability is decided by the payment status, not `status`.
+          paymentStatus: sb.booking?.paymentStatus ?? null,
           schedulingStatus: sb.booking?.schedulingStatus ?? null,
           freightType: sb.booking?.freightType ?? null,
           // Which leg of the corridor this booking rides — the workspace can't
@@ -11443,6 +12013,30 @@ export class TrainSchedulingService {
           await allocs.update(alloc.id, { trainSetWagonId: created.id });
         }
         await slotRepo.update(source.id, emptyLoadFields);
+        await this.wagonHistory?.record(manager, [
+          ...(source.physicalWagonId
+            ? [
+                {
+                  wagonId: source.physicalWagonId,
+                  wagonNumber: source.physicalWagon?.wagonNumber ?? null,
+                  type: WagonEventType.LoadMovedOut,
+                  trainScheduleId: scheduleId,
+                  bookingId: sourceAllocs[0]?.bookingId ?? null,
+                  toValue: consistWagon.wagonNumber,
+                  metadata: { toWagonId: consistWagon.id, allocations: sourceAllocs.length },
+                },
+              ]
+            : []),
+          {
+            wagonId: consistWagon.id,
+            wagonNumber: consistWagon.wagonNumber,
+            type: WagonEventType.LoadMovedIn,
+            trainScheduleId: scheduleId,
+            bookingId: sourceAllocs[0]?.bookingId ?? null,
+            fromValue: source.physicalWagon?.wagonNumber ?? null,
+            metadata: { fromWagonId: source.physicalWagonId ?? null, allocations: sourceAllocs.length },
+          },
+        ]);
         return;
       }
 
@@ -11457,6 +12051,54 @@ export class TrainSchedulingService {
       }
       await slotRepo.update(target.id, sourceLoadFields);
       await slotRepo.update(source.id, targetLoadFields);
+      const moveEvents: WagonEventInput[] = [];
+      if (source.physicalWagonId) {
+        moveEvents.push({
+          wagonId: source.physicalWagonId,
+          wagonNumber: source.physicalWagon?.wagonNumber ?? null,
+          type: WagonEventType.LoadMovedOut,
+          trainScheduleId: scheduleId,
+          bookingId: sourceAllocs[0]?.bookingId ?? null,
+          toValue: target.physicalWagon?.wagonNumber ?? null,
+          metadata: { toWagonId: target.physicalWagonId ?? null, allocations: sourceAllocs.length, swap: targetAllocs.length > 0 },
+        });
+      }
+      if (target.physicalWagonId) {
+        moveEvents.push({
+          wagonId: target.physicalWagonId,
+          wagonNumber: target.physicalWagon?.wagonNumber ?? null,
+          type: WagonEventType.LoadMovedIn,
+          trainScheduleId: scheduleId,
+          bookingId: sourceAllocs[0]?.bookingId ?? null,
+          fromValue: source.physicalWagon?.wagonNumber ?? null,
+          metadata: { fromWagonId: source.physicalWagonId ?? null, allocations: sourceAllocs.length, swap: targetAllocs.length > 0 },
+        });
+      }
+      if (targetAllocs.length) {
+        if (target.physicalWagonId) {
+          moveEvents.push({
+            wagonId: target.physicalWagonId,
+            wagonNumber: target.physicalWagon?.wagonNumber ?? null,
+            type: WagonEventType.LoadMovedOut,
+            trainScheduleId: scheduleId,
+            bookingId: targetAllocs[0]?.bookingId ?? null,
+            toValue: source.physicalWagon?.wagonNumber ?? null,
+            metadata: { toWagonId: source.physicalWagonId ?? null, allocations: targetAllocs.length, swap: true },
+          });
+        }
+        if (source.physicalWagonId) {
+          moveEvents.push({
+            wagonId: source.physicalWagonId,
+            wagonNumber: source.physicalWagon?.wagonNumber ?? null,
+            type: WagonEventType.LoadMovedIn,
+            trainScheduleId: scheduleId,
+            bookingId: targetAllocs[0]?.bookingId ?? null,
+            fromValue: target.physicalWagon?.wagonNumber ?? null,
+            metadata: { fromWagonId: target.physicalWagonId ?? null, allocations: targetAllocs.length, swap: true },
+          });
+        }
+      }
+      await this.wagonHistory?.record(manager, moveEvents);
     });
 
     return this.getTrainScheduleById(scheduleId);
@@ -11761,7 +12403,11 @@ export class TrainSchedulingService {
     return assignability.shortage;
   }
 
-  /** Paid (or government) bookings that may be loaded onto wagons — excludes expired / awaiting payment. */
+  /**
+   * Paid (or government) bookings that may be loaded onto wagons — excludes
+   * expired / awaiting payment. "Paid" is read from the PAYMENT status only;
+   * the booking status is not a reliable payment signal.
+   */
   private isReadyToLoadBooking(booking: {
     status: string;
     paymentStatus?: string | null;
@@ -11771,7 +12417,7 @@ export class TrainSchedulingService {
     if (booking.status === 'SELECTED_FOR_BATCH' || booking.status === 'AWAITING_PAYMENT') {
       return false;
     }
-    if (booking.status === 'PAID' || booking.paymentStatus === 'PAID') return true;
+    if (booking.paymentStatus === 'PAID') return true;
     if (booking.isGovernment) return true;
     return false;
   }
@@ -12151,6 +12797,12 @@ export class TrainSchedulingService {
       // 2. The physical wagons follow the train — the target's stay put, and
       //    EVERY wagon on the source train (coupled or loose) moves across so
       //    nothing strands on the deactivated train.
+      const mergedFromSource = sourceTrainId
+        ? await manager.getRepository(Wagon).find({
+            where: { trainId: sourceTrainId },
+            select: { id: true, wagonNumber: true, currentYardId: true },
+          })
+        : [];
       if (incomingWagons.length) {
         await manager.getRepository(Wagon).update(
           { id: In(incomingWagons.map((w) => w.id)) },
@@ -12162,6 +12814,20 @@ export class TrainSchedulingService {
           .getRepository(Wagon)
           .update({ trainId: sourceTrainId }, { trainId: targetTrain.id });
       }
+      await this.wagonHistory?.record(
+        manager,
+        mergedFromSource.map((w) => ({
+          wagonId: w.id,
+          wagonNumber: w.wagonNumber,
+          type: WagonEventType.TrainMerged,
+          fromYardId: w.currentYardId ?? null,
+          trainId: targetTrain.id,
+          trainScheduleId: schedule.id,
+          fromValue: sourceTrainId,
+          toValue: targetTrain.code,
+          reason: `Train merged into ${targetTrain.code}`,
+        })),
+      );
 
       // 3. Carry the target's train-set wagon rows into THIS consist, appended
       //    after the existing wagons. Sequence is provisional — staff reorder
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
index 7b28a8582..8160127b0 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
@@ -1,4 +1,4 @@
-import { Freight, WagonMovementKind, WagonStatus } from '@edr/types';
+import { Freight, WagonEventType, WagonMovementKind, WagonStatus } from '@edr/types';
 import {
   BadRequestException,
   ConflictException,
@@ -19,11 +19,13 @@ import { combinedLocomotiveLimits } from '../train-scheduling/train-capacity.uti
 import { ScheduleWagonAdjustmentLog } from '../train-schedules/entities/schedule-wagon-adjustment-log.entity';
 import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
 import { TrainSet } from '../train-sets/entities/train-set.entity';
+import { TrainSetLocomotive } from '../train-sets/entities/train-set-locomotive.entity';
 import { TrainSetWagon } from '../train-sets/entities/train-set-wagon.entity';
 import { WagonType } from '../wagon-types/entities/wagon-type.entity';
 import { WagonMovement } from '../wagons/entities/wagon-movement.entity';
 import { WagonStatusLog } from '../wagons/entities/wagon-status-log.entity';
 import { Wagon } from '../wagons/entities/wagon.entity';
+import { WagonEventInput, WagonHistoryService } from '../wagon-history/wagon-history.service';
 import { AssignTrainWagonsDto } from './dto/assign-train-wagons.dto';
 import { BuildTrainDto } from './dto/build-train.dto';
 import { ListBuiltTrainsQueryDto } from './dto/list-built-trains-query.dto';
@@ -75,6 +77,7 @@ export class TrainBuilderService {
   constructor(
     private readonly dataSource: DataSource,
     private readonly bookingBatchService: BookingBatchService,
+    private readonly wagonHistory: WagonHistoryService,
   ) {}
 
   async buildTrain(dto: BuildTrainDto) {
@@ -133,7 +136,7 @@ export class TrainBuilderService {
       await this.replaceLocomotiveLinks(manager, train.id, locomotiveIds);
 
       if (dto.wagonIds?.length) {
-        await this.attachWagons(manager, train, dto.wagonIds, 0);
+        await this.attachWagons(manager, train, dto.wagonIds, 0, null);
       }
       return train.id;
     });
@@ -504,7 +507,7 @@ export class TrainBuilderService {
     if (locomotiveIds.length < 1) {
       throw new BadRequestException('A train must be pulled by at least one locomotive');
     }
-    await this.dataSource.transaction(async (manager) => {
+    const pending = await this.dataSource.transaction(async (manager) => {
       const train = await this.getEditableTrain(manager, id);
       const yard = await manager
         .getRepository(Yard)
@@ -523,10 +526,76 @@ export class TrainBuilderService {
       await manager
         .getRepository(Train)
         .update(train.id, { capacityTons: round(limits?.maxPullWeightTons ?? 0) });
+      // Capacity math reads the SET's locomotives, not the train's — push the
+      // new pull weight onto the live runs too, or they keep the old ceiling.
+      return this.syncLiveSchedulesAfterLocomotiveChange(manager, train.id, locomotiveIds);
     });
+    // Re-derive FULL/reopen once committed — a bigger pull weight can free room
+    // on a schedule that had closed as FULL.
+    await this.reconcileWindowsAfterConsistChange(pending);
     return this.getComposition(id);
   }
 
+  /**
+   * Mirror a built train's locomotive change onto every LIVE (DRAFT/SCHEDULED)
+   * schedule formed from it. The three capacity axes are derived from
+   * `train_set_locomotives` (see trainSetLocomotiveLimits), which is snapshotted
+   * when the set is built and never re-synced — so adding a second locomotive
+   * raised `trains.capacity_tons` but left every existing schedule pulling on
+   * the old single-loco ceiling, still refusing bookings for want of weight.
+   *
+   * Only DRAFT/SCHEDULED runs follow the live train; DISPATCHED/ARRIVED render
+   * from their frozen snapshot and must not be disturbed (same rule as
+   * syncLiveScheduleAfterConsistChange).
+   */
+  private async syncLiveSchedulesAfterLocomotiveChange(
+    manager: EntityManager,
+    trainId: string,
+    locomotiveIds: string[],
+  ): Promise<PendingWindowCheck[]> {
+    const trainSets = await manager.getRepository(TrainSet).find({ where: { trainId } });
+    if (!trainSets.length) return [];
+
+    const schedules = await manager.getRepository(TrainSchedule).find({
+      where: {
+        trainSetId: In(trainSets.map((s) => s.id)),
+        status: In(['DRAFT', 'SCHEDULED']),
+      },
+    });
+    if (!schedules.length) return [];
+
+    // Only the sets still backing a live run — a set behind an ARRIVED schedule
+    // keeps the locomotives it actually ran with.
+    const liveSetIds = [...new Set(schedules.map((s) => s.trainSetId))];
+    const [primaryId] = locomotiveIds;
+    for (const trainSetId of liveSetIds) {
+      await manager.getRepository(TrainSetLocomotive).delete({ trainSetId });
+      await manager.getRepository(TrainSetLocomotive).save(
+        locomotiveIds.map((locomotiveId, index) =>
+          manager
+            .getRepository(TrainSetLocomotive)
+            .create({ trainSetId, locomotiveId, sequenceNo: index }),
+        ),
+      );
+      // `locomotiveId` is the primary-locomotive fallback for single-loco reads.
+      await manager.getRepository(TrainSet).update(trainSetId, { locomotiveId: primaryId });
+    }
+
+    return schedules.map((s) => ({
+      scheduleId: s.id,
+      wasFull: s.bookingWindowStatus === 'FULL',
+    }));
+  }
+
+  /** {@link reconcileWindowAfterConsistChange} over several schedules. */
+  private async reconcileWindowsAfterConsistChange(
+    pending: PendingWindowCheck[],
+  ): Promise<void> {
+    for (const check of pending) {
+      await this.reconcileWindowAfterConsistChange(check);
+    }
+  }
+
   /**
    * Edit a built train's display identity: name and fixed import/export run
    * numbers. Mirrors the build-time number rules — the pair may not collide
@@ -617,8 +686,19 @@ export class TrainBuilderService {
           wagon.currentYardId === previousYardId,
       );
       const now = new Date();
+      const events: WagonEventInput[] = [];
       for (const wagon of wagons) {
         if (wagon.currentYardId === yard.id) continue;
+        events.push({
+          wagonId: wagon.id,
+          wagonNumber: wagon.wagonNumber,
+          type: WagonEventType.MovedWithTrain,
+          occurredAt: now,
+          fromYardId: wagon.currentYardId ?? null,
+          toYardId: yard.id,
+          trainId: train.id,
+          reason: `Train ${train.code} relocated`,
+        });
         await manager.getRepository(Wagon).update(wagon.id, { currentYardId: yard.id });
         // Ledger row keeps the wagon's yard history auditable (mirrors the
         // manual-relocation path in the wagons service).
@@ -632,6 +712,7 @@ export class TrainBuilderService {
           }),
         );
       }
+      await this.wagonHistory.record(manager, events);
     });
     return this.getComposition(id);
   }
@@ -668,6 +749,16 @@ export class TrainBuilderService {
           occurredAt: new Date(),
         }),
       );
+      await this.wagonHistory.record(manager, {
+        wagonId: wagon.id,
+        wagonNumber: wagon.wagonNumber,
+        type: WagonEventType.MovedManually,
+        actorUserId: userId ?? null,
+        fromYardId: wagon.currentYardId ?? null,
+        toYardId: yard.id,
+        trainId: train.id,
+        reason: 'Coupled wagon moved from the train builder',
+      });
     });
     return this.getComposition(id);
   }
@@ -720,6 +811,19 @@ export class TrainBuilderService {
       await manager
         .getRepository(Wagon)
         .update(moving.map((w) => w.id), { currentYardId: yard.id });
+      await this.wagonHistory.record(
+        manager,
+        moving.map((w) => ({
+          wagonId: w.id,
+          wagonNumber: w.wagonNumber,
+          type: WagonEventType.MovedManually,
+          actorUserId: userId ?? null,
+          fromYardId: w.currentYardId ?? null,
+          toYardId: yard.id,
+          trainId: train.id,
+          reason: 'Coupled wagons moved from the train builder',
+        })),
+      );
       await manager.getRepository(WagonMovement).save(
         moving.map((w) =>
           manager.getRepository(WagonMovement).create({
@@ -743,7 +847,7 @@ export class TrainBuilderService {
       const currentCount = await manager
         .getRepository(Wagon)
         .count({ where: { trainId: train.id } });
-      const attached = await this.attachWagons(manager, train, dto.wagonIds, currentCount);
+      const attached = await this.attachWagons(manager, train, dto.wagonIds, currentCount, userId ?? null);
       return this.syncLiveScheduleAfterConsistChange(
         manager,
         train.id,
@@ -882,6 +986,18 @@ export class TrainBuilderService {
           }),
         );
       }
+      await this.wagonHistory.record(manager, {
+        wagonId: wagon.id,
+        wagonNumber: wagon.wagonNumber,
+        type: WagonEventType.StatusChanged,
+        actorUserId: userId ?? null,
+        trainId: train.id,
+        fromYardId: wagon.currentYardId ?? train.currentYardId ?? null,
+        fromValue: previousStatus,
+        toValue: WagonStatus.Maintenance,
+        reason: note?.trim() || null,
+        metadata: { trainCode: train.code },
+      });
       // Audit row: which train it came off and when. The wagon does not change
       // yard here, so from/to are the same — the ledger is the wagon's history
       // surface, and a maintenance detach has to be in it.
@@ -1099,6 +1215,22 @@ export class TrainBuilderService {
       for (let i = 0; i < dto.wagonIds.length; i++) {
         await manager.getRepository(Wagon).update(dto.wagonIds[i], { sequenceNumber: i + 1 });
       }
+      const previousSeq = new Map(wagons.map((w) => [w.id, w]));
+      await this.wagonHistory.record(
+        manager,
+        dto.wagonIds
+          .map((wid, i) => ({ wagon: previousSeq.get(wid), to: i + 1 }))
+          .filter((x) => x.wagon && x.wagon.sequenceNumber !== x.to)
+          .map(({ wagon, to }) => ({
+            wagonId: wagon!.id,
+            wagonNumber: wagon!.wagonNumber,
+            type: WagonEventType.SequenceChanged,
+            trainId: train.id,
+            fromValue: wagon!.sequenceNumber,
+            toValue: to,
+            reason: 'Consist reordered',
+          })),
+      );
 
       // Propagate the new order to every live (DRAFT/SCHEDULED) schedule of
       // this train: slots pinned to a reordered wagon adopt the wagon's new
@@ -1220,6 +1352,10 @@ export class TrainBuilderService {
           'Train has active schedules; cancel them before disbanding the train',
         );
       }
+      const consist = await manager.getRepository(Wagon).find({
+        where: { trainId: train.id },
+        select: { id: true, wagonNumber: true, currentYardId: true, sequenceNumber: true, status: true },
+      });
       await manager
         .getRepository(Wagon)
         .update(
@@ -1232,6 +1368,19 @@ export class TrainBuilderService {
             exportTrainNumber: null,
           },
         );
+      await this.wagonHistory.record(
+        manager,
+        consist.map((w) => ({
+          wagonId: w.id,
+          wagonNumber: w.wagonNumber,
+          type: WagonEventType.TrainDisbanded,
+          trainId: train.id,
+          fromYardId: w.currentYardId ?? null,
+          fromValue: w.sequenceNumber,
+          reason: `Train ${train.code} disbanded`,
+          metadata: { status: { from: w.status, to: WagonStatus.Available } },
+        })),
+      );
       await manager.getRepository(TrainLocomotive).delete({ trainId: train.id });
       await manager.getRepository(Train).remove(train);
     });
@@ -1365,6 +1514,25 @@ export class TrainBuilderService {
       ),
     );
 
+    // COUPLED rows are written by attachWagons (build + assign); the detach
+    // side is logged here, where the reason and the live schedule are known.
+    await this.wagonHistory.record(
+      manager,
+      changes
+        .filter((c) => c.action === 'REMOVE')
+        .map((c) => ({
+          wagonId: c.wagonId,
+          wagonNumber: c.wagonNumber,
+          type: WagonEventType.UncoupledFromTrain,
+          occurredAt: now,
+          actorUserId: userId,
+          trainId,
+          trainScheduleId: schedule?.id ?? null,
+          fromYardId: yardId,
+          reason: reason?.trim() || null,
+        })),
+    );
+
     if (!schedule) return null;
 
     await manager.getRepository(TrainSchedule).update(schedule.id, { maxWagons: wagonCount });
@@ -1476,6 +1644,7 @@ export class TrainBuilderService {
     train: Train,
     wagonIds: string[],
     startCount: number,
+    userId: string | null = null,
   ): Promise<Wagon[]> {
     const uniqueIds = [...new Set(wagonIds)];
     const wagonRepo = manager.getRepository(Wagon);
@@ -1505,6 +1674,7 @@ export class TrainBuilderService {
     await this.assertConsistLengthWithinLimit(manager, train, toAttach);
 
     let sequence = startCount;
+    const events: WagonEventInput[] = [];
     for (const wagon of toAttach) {
       sequence += 1;
       await wagonRepo.update(wagon.id, {
@@ -1516,7 +1686,23 @@ export class TrainBuilderService {
         importTrainNumber: train.importTrainNumber,
         exportTrainNumber: train.exportTrainNumber,
       });
+      events.push({
+        wagonId: wagon.id,
+        wagonNumber: wagon.wagonNumber,
+        type: WagonEventType.CoupledToTrain,
+        actorUserId: userId,
+        trainId: train.id,
+        fromYardId: wagon.currentYardId ?? null,
+        toValue: sequence,
+        metadata: {
+          trainCode: train.code,
+          status: { from: wagon.status, to: WagonStatus.Assigned },
+          importTrainNumber: train.importTrainNumber ?? null,
+          exportTrainNumber: train.exportTrainNumber ?? null,
+        },
+      });
     }
+    await this.wagonHistory.record(manager, events);
     return toAttach;
   }
 
diff --git a/apps/edr-freight-api/src/modules/transit-agents/dto/create-transit-agent.dto.ts b/apps/edr-freight-api/src/modules/transit-agents/dto/create-transit-agent.dto.ts
index be3810c0b..d035c53f8 100644
--- a/apps/edr-freight-api/src/modules/transit-agents/dto/create-transit-agent.dto.ts
+++ b/apps/edr-freight-api/src/modules/transit-agents/dto/create-transit-agent.dto.ts
@@ -1,25 +1,34 @@
-import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { Transform } from 'class-transformer';
-import { IsBoolean, IsDateString, IsOptional, IsString, MaxLength } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { Transform } from "class-transformer";
+import {
+  IsBoolean,
+  IsDateString,
+  IsEmail,
+  IsOptional,
+  IsString,
+  MaxLength,
+} from "class-validator";
+
+import { IsValidPhone } from "../../../common/validators/is-phone-number.validator";
 
 const toBoolean = ({ value }: { value: unknown }) => {
-  if (typeof value === 'boolean') return value;
-  if (value === 'true') return true;
-  if (value === 'false') return false;
+  if (typeof value === "boolean") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
   return value;
 };
 
 export class CreateTransitAgentDto {
-  @ApiProperty({ maxLength: 150, example: 'Ahmed Bourhan' })
+  @ApiProperty({ maxLength: 150, example: "Ahmed Bourhan" })
   @IsString()
   @MaxLength(150)
   name!: string;
 
-  @ApiProperty({ example: '2026-01-01' })
+  @ApiProperty({ example: "2026-01-01" })
   @IsDateString()
   validFrom!: string;
 
-  @ApiProperty({ example: '2026-12-31' })
+  @ApiProperty({ example: "2026-12-31" })
   @IsDateString()
   validTo!: string;
 
@@ -28,4 +37,33 @@ export class CreateTransitAgentDto {
   @Transform(toBoolean)
   @IsBoolean()
   isActive?: boolean;
+
+  /**
+   * Becomes the IAM account's email and is where the activation link is sent.
+   * Optional: an agent may be created as a GL-assignable roster entry only, and
+   * invited later. Supplying it creates the portal account right away.
+   */
+  @ApiPropertyOptional({ example: "a.bourhan@transit.dj" })
+  @IsOptional()
+  @IsEmail()
+  @MaxLength(150)
+  email?: string;
+
+  @ApiPropertyOptional({
+    example: "+25377834567",
+    description:
+      "E.164. Djiboutian (+253 77…) and Ethiopian (+251 9…) mobiles also receive the activation link by SMS.",
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(30)
+  @IsValidPhone()
+  phoneNumber?: string;
+
+  /** Login name. Defaults to the email, which is what the agent tries first. */
+  @ApiPropertyOptional({ example: "a-bourhan" })
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  username?: string;
 }
diff --git a/apps/edr-freight-api/src/modules/transit-agents/dto/invite-transit-agent.dto.ts b/apps/edr-freight-api/src/modules/transit-agents/dto/invite-transit-agent.dto.ts
new file mode 100644
index 000000000..7b317c58c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-agents/dto/invite-transit-agent.dto.ts
@@ -0,0 +1,36 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { IsEmail, IsOptional, IsString, MaxLength } from "class-validator";
+
+import { IsValidPhone } from "../../../common/validators/is-phone-number.validator";
+
+/**
+ * Give an EXISTING roster-only transit agent a portal login.
+ *
+ * Email is required here even though it is optional on the agent itself: this
+ * endpoint's whole job is to send the activation link, and email is the only
+ * channel guaranteed to reach a Djibouti-registered officer. Omitting a field
+ * keeps whatever the agent already has.
+ */
+export class InviteTransitAgentDto {
+  @ApiProperty({ example: "a.bourhan@transit.dj" })
+  @IsEmail()
+  @MaxLength(150)
+  email!: string;
+
+  @ApiPropertyOptional({
+    example: "+25377834567",
+    description:
+      "E.164. Djiboutian (+253 77…) and Ethiopian (+251 9…) mobiles also receive the activation link by SMS.",
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(30)
+  @IsValidPhone()
+  phoneNumber?: string;
+
+  @ApiPropertyOptional({ example: "a-bourhan" })
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  username?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/transit-agents/dto/update-transit-agent.dto.ts b/apps/edr-freight-api/src/modules/transit-agents/dto/update-transit-agent.dto.ts
index 7e18a93da..08f28473c 100644
--- a/apps/edr-freight-api/src/modules/transit-agents/dto/update-transit-agent.dto.ts
+++ b/apps/edr-freight-api/src/modules/transit-agents/dto/update-transit-agent.dto.ts
@@ -1,5 +1,5 @@
-import { PartialType } from '@nestjs/mapped-types';
+import { PartialType } from "@nestjs/mapped-types";
 
-import { CreateTransitAgentDto } from './create-transit-agent.dto';
+import { CreateTransitAgentDto } from "./create-transit-agent.dto";
 
 export class UpdateTransitAgentDto extends PartialType(CreateTransitAgentDto) {}
diff --git a/apps/edr-freight-api/src/modules/transit-agents/entities/transit-agent.entity.ts b/apps/edr-freight-api/src/modules/transit-agents/entities/transit-agent.entity.ts
index 6d0ef9158..433b6587f 100644
--- a/apps/edr-freight-api/src/modules/transit-agents/entities/transit-agent.entity.ts
+++ b/apps/edr-freight-api/src/modules/transit-agents/entities/transit-agent.entity.ts
@@ -1,5 +1,5 @@
-import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index } from 'typeorm';
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, Index } from "typeorm";
 
 /**
  * Djibouti transit officer GL Djibouti may assign against a shipment's
@@ -7,18 +7,43 @@ import { Column, Entity, Index } from 'typeorm';
  * validity window arrive without a code change; `isActive` is the manual
  * suspend/reactivate switch, independent of the validity window.
  */
-@Entity({ schema: 'freight', name: 'transit_agents' })
-@Index(['isActive'])
+@Entity({ schema: "freight", name: "transit_agents" })
+@Index(["isActive"])
 export class TransitAgent extends BaseEntity {
-  @Column({ name: 'name', type: 'varchar', length: 150 })
+  @Column({ name: "name", type: "varchar", length: 150 })
   name!: string;
 
-  @Column({ name: 'valid_from', type: 'date' })
+  @Column({ name: "valid_from", type: "date" })
   validFrom!: string;
 
-  @Column({ name: 'valid_to', type: 'date' })
+  @Column({ name: "valid_to", type: "date" })
   validTo!: string;
 
-  @Column({ name: 'is_active', type: 'boolean', default: true })
+  @Column({ name: "is_active", type: "boolean", default: true })
   isActive!: boolean;
+
+  /**
+   * The IAM account (`iam.users`, userType `individual`) that signs in to the
+   * portal as this agent. No FK: `iam` is a separate schema owned by the IAM
+   * service, and the rest of the codebase reaches it by query rather than by
+   * relation.
+   *
+   * NULL for every agent that exists only as a GL-assignable roster entry —
+   * which is all of them before this feature, and stays legal afterwards. An
+   * agent gains an account when staff invite it, so `userId !== null` IS the
+   * "has a portal login" predicate; nothing else needs to track it.
+   */
+  @Column({ name: "user_id", type: "uuid", nullable: true })
+  userId?: string | null;
+
+  /**
+   * Mirrors the IAM account's email; the activation link is sent here. Nullable
+   * because a roster-only agent has never needed one — but an invite cannot be
+   * sent without it, so {@link TransitAgentsService.invite} requires it.
+   */
+  @Column({ name: "email", type: "varchar", length: 150, nullable: true })
+  email?: string | null;
+
+  @Column({ name: "phone_number", type: "varchar", length: 30, nullable: true })
+  phoneNumber?: string | null;
 }
diff --git a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.controller.ts b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.controller.ts
index 4f4b90c7b..d254f7982 100644
--- a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.controller.ts
+++ b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.controller.ts
@@ -10,36 +10,38 @@ import {
   Patch,
   Post,
   Query,
-} from '@nestjs/common';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+} from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import {
   RuleEngineCreate,
   RuleEngineDelete,
   RuleEngineUpdate,
   RuleEngineView,
-} from '../../common/rule-engine-guards';
+} from "../../common/rule-engine-guards";
 
-import { CreateTransitAgentDto } from './dto/create-transit-agent.dto';
-import { UpdateTransitAgentDto } from './dto/update-transit-agent.dto';
-import { TransitAgentsService } from './transit-agents.service';
+import { BackofficeResetPasswordDto } from "../auth/dto/forgot-password.dto";
+import { CreateTransitAgentDto } from "./dto/create-transit-agent.dto";
+import { InviteTransitAgentDto } from "./dto/invite-transit-agent.dto";
+import { UpdateTransitAgentDto } from "./dto/update-transit-agent.dto";
+import { TransitAgentsService } from "./transit-agents.service";
 
-@ApiTags('transit-agents')
-@Controller('transit-agents')
+@ApiTags("transit-agents")
+@Controller("transit-agents")
 @ApiBearerAuth()
 export class TransitAgentsController {
   constructor(private readonly transitAgentsService: TransitAgentsService) {}
 
   @Get()
-  @RuleEngineView('transit-agents')
-  @ApiOperation({ summary: 'List transit agents' })
+  @RuleEngineView("transit-agents")
+  @ApiOperation({ summary: "List transit agents" })
   findAll(@Query() query: Record<string, string | undefined>) {
     return this.transitAgentsService.findAll({
       isActive:
-        query.isActive === 'all'
+        query.isActive === "all"
           ? undefined
           : query.isActive !== undefined
-            ? query.isActive === 'true'
+            ? query.isActive === "true"
             : undefined,
       page: query.page ? parseInt(query.page, 10) : undefined,
       pageSize: query.pageSize ? parseInt(query.pageSize, 10) : undefined,
@@ -49,39 +51,77 @@ export class TransitAgentsController {
   }
 
   /** Active + currently valid officers — the transit-assignee assignment dropdown. */
-  @Get('assignable')
-  @RuleEngineView('transit-agents')
-  @ApiOperation({ summary: 'List transit agents assignable right now (active and in-window)' })
+  @Get("assignable")
+  @RuleEngineView("transit-agents")
+  @ApiOperation({
+    summary: "List transit agents assignable right now (active and in-window)",
+  })
   findAssignable() {
     return this.transitAgentsService.findAssignable();
   }
 
-  @Get(':id')
-  @RuleEngineView('transit-agents')
-  @ApiOperation({ summary: 'Get a transit agent by ID' })
-  findOne(@Param('id', ParseUUIDPipe) id: string) {
+  @Get(":id")
+  @RuleEngineView("transit-agents")
+  @ApiOperation({ summary: "Get a transit agent by ID" })
+  findOne(@Param("id", ParseUUIDPipe) id: string) {
     return this.transitAgentsService.findById(id);
   }
 
   @Post()
-  @RuleEngineCreate('transit-agents')
-  @ApiOperation({ summary: 'Create a transit agent' })
+  @RuleEngineCreate("transit-agents")
+  @ApiOperation({
+    summary:
+      "Create a transit agent; with an email, also creates its portal account and sends the activation link",
+  })
   create(@Body() dto: CreateTransitAgentDto) {
-    return this.transitAgentsService.create(dto);
+    return this.transitAgentsService.createWithInvite(dto);
   }
 
-  @Patch(':id')
-  @RuleEngineUpdate('transit-agents')
-  @ApiOperation({ summary: 'Update a transit agent' })
-  update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateTransitAgentDto) {
+  /**
+   * The path for the roster entries already in production: they were created
+   * before transit agents had logins, so they get their account here rather
+   * than at create time.
+   */
+  @Post(":id/invite")
+  @RuleEngineUpdate("transit-agents")
+  @ApiOperation({
+    summary:
+      "Create a portal account for an existing transit agent and send the activation link",
+  })
+  invite(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: InviteTransitAgentDto,
+  ) {
+    return this.transitAgentsService.invite(id, dto);
+  }
+
+  @Post(":id/resend-activation")
+  @RuleEngineUpdate("transit-agents")
+  @ApiOperation({
+    summary: "Resend a transit agent's activation / password-reset link",
+  })
+  resendActivation(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: BackofficeResetPasswordDto,
+  ) {
+    return this.transitAgentsService.resendActivation(id, dto.channel);
+  }
+
+  @Patch(":id")
+  @RuleEngineUpdate("transit-agents")
+  @ApiOperation({ summary: "Update a transit agent" })
+  update(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: UpdateTransitAgentDto,
+  ) {
     return this.transitAgentsService.update(id, dto);
   }
 
-  @Delete(':id')
-  @RuleEngineDelete('transit-agents')
+  @Delete(":id")
+  @RuleEngineDelete("transit-agents")
   @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({ summary: 'Soft-delete a transit agent' })
-  remove(@Param('id', ParseUUIDPipe) id: string) {
+  @ApiOperation({ summary: "Soft-delete a transit agent" })
+  remove(@Param("id", ParseUUIDPipe) id: string) {
     return this.transitAgentsService.remove(id);
   }
 }
diff --git a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.module.ts b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.module.ts
index 47e655e94..425971170 100644
--- a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.module.ts
+++ b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.module.ts
@@ -1,13 +1,24 @@
-import { Module } from '@nestjs/common';
-import { TypeOrmModule } from '@nestjs/typeorm';
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
 
-import { TransitAgent } from './entities/transit-agent.entity';
-import { TransitAgentsController } from './transit-agents.controller';
-import { TransitAgentsRepository } from './transit-agents.repository';
-import { TransitAgentsService } from './transit-agents.service';
+import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
+
+import { FreightAuthModule } from "../auth/freight-auth.module";
+import { OtpModule } from "../otp/otp.module";
+import { TransitAgent } from "./entities/transit-agent.entity";
+import { TransitAgentsController } from "./transit-agents.controller";
+import { TransitAgentsRepository } from "./transit-agents.repository";
+import { TransitAgentsService } from "./transit-agents.service";
 
 @Module({
-  imports: [TypeOrmModule.forFeature([TransitAgent])],
+  imports: [
+    // `User` is registered here so this module can create the IAM account that
+    // backs an invited transit agent, in the same transaction as the agent row.
+    TypeOrmModule.forFeature([TransitAgent, User]),
+    // CustomerResetService — activation links reuse the staff-triggered reset path.
+    FreightAuthModule,
+    OtpModule,
+  ],
   controllers: [TransitAgentsController],
   providers: [TransitAgentsRepository, TransitAgentsService],
   exports: [TransitAgentsRepository, TransitAgentsService],
diff --git a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.repository.ts b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.repository.ts
index 4418ad938..5ae4191eb 100644
--- a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.repository.ts
+++ b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.repository.ts
@@ -1,9 +1,14 @@
-import { BaseRepository } from '@edr/api-common';
-import { Injectable } from '@nestjs/common';
-import { InjectRepository } from '@nestjs/typeorm';
-import { LessThanOrEqual, MoreThanOrEqual, Repository } from 'typeorm';
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import {
+  EntityManager,
+  LessThanOrEqual,
+  MoreThanOrEqual,
+  Repository,
+} from "typeorm";
 
-import { TransitAgent } from './entities/transit-agent.entity';
+import { TransitAgent } from "./entities/transit-agent.entity";
 
 @Injectable()
 export class TransitAgentsRepository extends BaseRepository<TransitAgent> {
@@ -22,7 +27,48 @@ export class TransitAgentsRepository extends BaseRepository<TransitAgent> {
         validFrom: LessThanOrEqual(today),
         validTo: MoreThanOrEqual(today),
       },
-      order: { name: 'ASC' },
+      order: { name: "ASC" },
     });
   }
+
+  /** The transit agent signed in as `userId`, or null for any other account. */
+  findByUserId(userId: string): Promise<TransitAgent | null> {
+    return this.repository.findOne({ where: { userId } });
+  }
+
+  /**
+   * Case-insensitive, matching the `lower(email)` unique index. `exceptId` lets
+   * an update re-save its own address without colliding with itself.
+   */
+  async existsByEmail(email: string, exceptId?: string): Promise<boolean> {
+    const qb = this.repository
+      .createQueryBuilder("ta")
+      .where("lower(ta.email) = lower(:email)", { email });
+    if (exceptId) qb.andWhere("ta.id != :exceptId", { exceptId });
+    return (await qb.getCount()) > 0;
+  }
+
+  /**
+   * Insert inside a caller-supplied transaction, so the agent row and the IAM
+   * user it points at commit together — a row referencing a user that was
+   * rolled back (or vice versa) is an account nobody can sign in to.
+   */
+  createInTransaction(
+    manager: EntityManager,
+    data: Partial<TransitAgent>,
+  ): Promise<TransitAgent> {
+    const repo = manager.getRepository(TransitAgent);
+    return repo.save(repo.create(data));
+  }
+
+  /** Attach an IAM account to an existing agent, inside the caller's transaction. */
+  async linkAccountInTransaction(
+    manager: EntityManager,
+    id: string,
+    data: Pick<TransitAgent, "userId" | "email" | "phoneNumber">,
+  ): Promise<TransitAgent> {
+    const repo = manager.getRepository(TransitAgent);
+    await repo.update(id, data);
+    return repo.findOneOrFail({ where: { id } });
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.service.spec.ts b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.service.spec.ts
new file mode 100644
index 000000000..3aa5e6e02
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.service.spec.ts
@@ -0,0 +1,346 @@
+import { BadRequestException, ConflictException } from "@nestjs/common";
+import {
+  EUserStatus,
+  EUserType,
+} from "@tria-plc/api-common/utils/enums/user.enum";
+
+import { ResetChannel } from "../auth/dto/forgot-password.dto";
+import { TransitAgentsService } from "./transit-agents.service";
+
+/**
+ * The account half of a transit agent. The roster half (validity window,
+ * assignability) predates this and is untouched — what these lock is that
+ * adding a login did not make an account MANDATORY, since production is full of
+ * roster-only agents that must keep working.
+ */
+describe("TransitAgentsService accounts", () => {
+  const savedUser = { id: "user-1" };
+
+  let repo: {
+    existsByEmail: jest.Mock;
+    createInTransaction: jest.Mock;
+    linkAccountInTransaction: jest.Mock;
+    findById: jest.Mock;
+    findByUserId: jest.Mock;
+    create: jest.Mock;
+    update: jest.Mock;
+  };
+  let userRepository: { findOne: jest.Mock; update: jest.Mock };
+  let customerResetService: {
+    sendResetLinkToUser: jest.Mock;
+    sendResetLinkToUserOnChannels: jest.Mock;
+  };
+  let dataSource: { transaction: jest.Mock };
+  let userRepoInTx: { create: jest.Mock; save: jest.Mock };
+  let service: TransitAgentsService;
+
+  const base = {
+    name: "Ahmed Bourhan",
+    validFrom: "2026-01-01",
+    validTo: "2026-12-31",
+  };
+
+  beforeEach(() => {
+    userRepoInTx = {
+      create: jest.fn((v) => v),
+      save: jest.fn().mockResolvedValue(savedUser),
+    };
+
+    repo = {
+      existsByEmail: jest.fn().mockResolvedValue(false),
+      createInTransaction: jest.fn(async (_m, data) => ({
+        id: "ta-1",
+        ...data,
+      })),
+      linkAccountInTransaction: jest.fn(async (_m, id, data) => ({
+        id,
+        ...base,
+        isActive: true,
+        ...data,
+      })),
+      findById: jest.fn(),
+      findByUserId: jest.fn(),
+      create: jest.fn(async (data) => ({ id: "ta-1", ...data })),
+      // `BaseRepository.update` re-reads the row via `findById`, so the result
+      // carries columns the caller never passed — `userId` above all, which is
+      // what decides whether IAM gets synced.
+      update: jest.fn(async (id, data) => ({
+        ...(await repo.findById(id)),
+        id,
+        ...data,
+      })),
+    };
+    userRepository = {
+      findOne: jest.fn().mockResolvedValue(null),
+      update: jest.fn(),
+    };
+    customerResetService = {
+      sendResetLinkToUser: jest
+        .fn()
+        .mockResolvedValue({
+          maskedTarget: "a**@transit.dj",
+          channel: ResetChannel.Email,
+        }),
+      sendResetLinkToUserOnChannels: jest
+        .fn()
+        .mockResolvedValue([
+          { maskedTarget: "a**@transit.dj", channel: ResetChannel.Email },
+        ]),
+    };
+    dataSource = {
+      transaction: jest.fn(async (cb) =>
+        cb({ getRepository: () => userRepoInTx } as never),
+      ),
+    };
+
+    service = new TransitAgentsService(
+      repo as never,
+      userRepository as never,
+      customerResetService as never,
+      dataSource as never,
+    );
+  });
+
+  describe("create", () => {
+    it("creates a roster-only agent with no account when no email is given", async () => {
+      const { agent, activationSentTo } = await service.createWithInvite(base);
+
+      expect(dataSource.transaction).not.toHaveBeenCalled();
+      expect(
+        customerResetService.sendResetLinkToUserOnChannels,
+      ).not.toHaveBeenCalled();
+      expect(agent.hasAccount).toBe(false);
+      expect(activationSentTo).toBeNull();
+    });
+
+    it("creates the IAM account with no password set when an email is given", async () => {
+      await service.createWithInvite({
+        ...base,
+        email: "A.Bourhan@Transit.DJ",
+      });
+
+      expect(userRepoInTx.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          email: "a.bourhan@transit.dj",
+          username: "a.bourhan@transit.dj",
+          userType: EUserType.INDIVIDUAL,
+          hasSetPassword: false,
+          status: EUserStatus.ACCEPTED,
+        }),
+      );
+    });
+
+    it("sends the activation link only after the transaction commits", async () => {
+      const order: string[] = [];
+      dataSource.transaction.mockImplementation(
+        async (cb: (m: unknown) => unknown) => {
+          const result = await cb({ getRepository: () => userRepoInTx });
+          order.push("commit");
+          return result;
+        },
+      );
+      customerResetService.sendResetLinkToUserOnChannels.mockImplementation(
+        async () => {
+          order.push("send");
+          return [
+            { maskedTarget: "a**@transit.dj", channel: ResetChannel.Email },
+          ];
+        },
+      );
+
+      await service.createWithInvite({ ...base, email: "a@transit.dj" });
+
+      expect(order).toEqual(["commit", "send"]);
+    });
+  });
+
+  describe("invite", () => {
+    it("attaches an account to an existing roster-only agent and sends the link", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: null,
+      });
+
+      const { agent, activationSentTo } = await service.invite("ta-1", {
+        email: "a@transit.dj",
+      });
+
+      expect(repo.linkAccountInTransaction).toHaveBeenCalledWith(
+        expect.anything(),
+        "ta-1",
+        expect.objectContaining({ userId: "user-1", email: "a@transit.dj" }),
+      );
+      expect(agent.hasAccount).toBe(true);
+      expect(activationSentTo).toBe("a**@transit.dj");
+    });
+
+    it("refuses to mint a second account for an agent that already has one", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: "user-9",
+      });
+
+      await expect(
+        service.invite("ta-1", { email: "a@transit.dj" }),
+      ).rejects.toThrow(ConflictException);
+      expect(dataSource.transaction).not.toHaveBeenCalled();
+    });
+
+    it("refuses credentials that already belong to another account", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: null,
+      });
+      userRepository.findOne.mockResolvedValue({ id: "someone-else" });
+
+      await expect(
+        service.invite("ta-1", { email: "a@transit.dj" }),
+      ).rejects.toThrow(ConflictException);
+    });
+
+    it("texts the link as well when the number is domestic", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: null,
+      });
+
+      await service.invite("ta-1", {
+        email: "a@transit.dj",
+        phoneNumber: "+251911223344",
+      });
+
+      expect(
+        customerResetService.sendResetLinkToUserOnChannels,
+      ).toHaveBeenCalledWith(
+        "user-1",
+        [ResetChannel.Email, ResetChannel.Phone],
+        expect.objectContaining({ allowWithoutCredential: true }),
+      );
+    });
+
+    it("emails only when the number is foreign — the SMS gateway is domestic-only", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: null,
+      });
+
+      await service.invite("ta-1", {
+        email: "a@transit.dj",
+        phoneNumber: "+33612345678",
+      });
+
+      expect(
+        customerResetService.sendResetLinkToUserOnChannels,
+      ).toHaveBeenCalledWith("user-1", [ResetChannel.Email], expect.anything());
+    });
+  });
+
+  describe("update", () => {
+    it("mirrors an edited email onto the linked IAM account", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: "user-1",
+      });
+
+      await service.update("ta-1", { email: "New@Transit.DJ" });
+
+      expect(repo.update).toHaveBeenCalledWith(
+        "ta-1",
+        expect.objectContaining({ email: "new@transit.dj" }),
+      );
+      expect(userRepository.update).toHaveBeenCalledWith(
+        "user-1",
+        expect.objectContaining({ email: "new@transit.dj" }),
+      );
+    });
+
+    it("never writes username — it names an IAM account, not a column on this table", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: null,
+      });
+
+      await service.update("ta-1", { username: "nope" } as never);
+
+      expect(repo.update).toHaveBeenCalledWith(
+        "ta-1",
+        expect.not.objectContaining({ username: expect.anything() }),
+      );
+    });
+
+    it("leaves IAM alone for a roster-only agent", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: null,
+      });
+
+      await service.update("ta-1", { email: "a@transit.dj" });
+
+      expect(userRepository.update).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("resendActivation", () => {
+    it("refuses for an agent that has no account yet", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: null,
+      });
+
+      await expect(
+        service.resendActivation("ta-1", ResetChannel.Email),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it("refuses an SMS resend to a foreign number", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: "user-1",
+        phoneNumber: "+33612345678",
+      });
+
+      await expect(
+        service.resendActivation("ta-1", ResetChannel.Phone),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it("reuses the existing account rather than minting a new one", async () => {
+      repo.findById.mockResolvedValue({
+        id: "ta-1",
+        ...base,
+        isActive: true,
+        userId: "user-1",
+        email: "a@transit.dj",
+      });
+
+      await service.resendActivation("ta-1", ResetChannel.Email);
+
+      expect(customerResetService.sendResetLinkToUser).toHaveBeenCalledWith(
+        "user-1",
+        ResetChannel.Email,
+        expect.objectContaining({ allowWithoutCredential: true }),
+      );
+      expect(dataSource.transaction).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.service.ts b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.service.ts
index ec9c24e9d..b54f1fddb 100644
--- a/apps/edr-freight-api/src/modules/transit-agents/transit-agents.service.ts
+++ b/apps/edr-freight-api/src/modules/transit-agents/transit-agents.service.ts
@@ -1,17 +1,49 @@
-import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
-import { FindOptionsOrder } from 'typeorm';
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import {
+  EUserStatus,
+  EUserType,
+} from "@tria-plc/api-common/utils/enums/user.enum";
+// Subpath import (not the package root) so ts-jest can resolve it when this
+// file lands in a spec's compile graph — same reason as backoffice.service.ts.
+import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
+import {
+  DataSource,
+  EntityManager,
+  FindOptionsOrder,
+  Repository,
+} from "typeorm";
 
-import { CreateTransitAgentDto } from './dto/create-transit-agent.dto';
-import { UpdateTransitAgentDto } from './dto/update-transit-agent.dto';
-import { TransitAgent } from './entities/transit-agent.entity';
-import { TransitAgentsRepository } from './transit-agents.repository';
+import { CustomerResetService } from "../auth/customer-reset.service";
+import { ResetChannel } from "../auth/dto/forgot-password.dto";
+import { isDomesticPhone } from "../otp/otp.service";
+import { CreateTransitAgentDto } from "./dto/create-transit-agent.dto";
+import { InviteTransitAgentDto } from "./dto/invite-transit-agent.dto";
+import { UpdateTransitAgentDto } from "./dto/update-transit-agent.dto";
+import { TransitAgent } from "./entities/transit-agent.entity";
+import { TransitAgentsRepository } from "./transit-agents.repository";
 
-export type TransitAgentValidityStatus = 'VALID' | 'NOT_STARTED' | 'EXPIRED';
+export type TransitAgentValidityStatus = "VALID" | "NOT_STARTED" | "EXPIRED";
 
 export type TransitAgentView = TransitAgent & {
   validityStatus: TransitAgentValidityStatus;
+  /** True once an IAM account backs this agent — i.e. it can sign in. */
+  hasAccount: boolean;
 };
 
+export interface InvitedTransitAgent {
+  agent: TransitAgentView;
+  /** Masked destination of the activation link, or null if none was sent. */
+  activationSentTo: string | null;
+  activationChannel: ResetChannel | null;
+}
+
 type TransitAgentListFilter = {
   isActive?: boolean;
   page?: number;
@@ -25,20 +57,34 @@ function todayISODate(): string {
   return new Date().toISOString().slice(0, 10);
 }
 
-function validityStatus(agent: Pick<TransitAgent, 'validFrom' | 'validTo'>): TransitAgentValidityStatus {
+function validityStatus(
+  agent: Pick<TransitAgent, "validFrom" | "validTo">,
+): TransitAgentValidityStatus {
   const today = todayISODate();
-  if (today < agent.validFrom) return 'NOT_STARTED';
-  if (today > agent.validTo) return 'EXPIRED';
-  return 'VALID';
+  if (today < agent.validFrom) return "NOT_STARTED";
+  if (today > agent.validTo) return "EXPIRED";
+  return "VALID";
 }
 
 function withValidityStatus(agent: TransitAgent): TransitAgentView {
-  return { ...agent, validityStatus: validityStatus(agent) };
+  return {
+    ...agent,
+    validityStatus: validityStatus(agent),
+    hasAccount: Boolean(agent.userId),
+  };
 }
 
 @Injectable()
 export class TransitAgentsService {
-  constructor(private readonly transitAgentsRepository: TransitAgentsRepository) {}
+  private readonly logger = new Logger(TransitAgentsService.name);
+
+  constructor(
+    private readonly transitAgentsRepository: TransitAgentsRepository,
+    @InjectRepository(User)
+    private readonly userRepository: Repository<User>,
+    private readonly customerResetService: CustomerResetService,
+    private readonly dataSource: DataSource,
+  ) {}
 
   async findAll(filter: TransitAgentListFilter = {}): Promise<{
     data: TransitAgentView[];
@@ -46,10 +92,13 @@ export class TransitAgentsService {
   }> {
     const page = filter.page ?? 1;
     const pageSize = filter.pageSize ?? 500;
-    const sortBy = ['name', 'validFrom', 'validTo', 'isActive'].includes(filter.sortBy ?? '')
+    const sortBy = ["name", "validFrom", "validTo", "isActive"].includes(
+      filter.sortBy ?? "",
+    )
       ? (filter.sortBy as keyof TransitAgent)
-      : 'name';
-    const sortOrder = filter.sortOrder?.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+      : "name";
+    const sortOrder =
+      filter.sortOrder?.toUpperCase() === "DESC" ? "DESC" : "ASC";
 
     const [data, total] = await this.transitAgentsRepository.findAndCount({
       where: filter.isActive === undefined ? {} : { isActive: filter.isActive },
@@ -86,12 +135,14 @@ export class TransitAgentsService {
   async getAssignable(id: string): Promise<TransitAgent> {
     const agent = await this.transitAgentsRepository.findById(id);
     if (!agent) {
-      throw new BadRequestException('Selected transit officer was not found.');
+      throw new BadRequestException("Selected transit officer was not found.");
     }
     if (!agent.isActive) {
-      throw new BadRequestException(`${agent.name} is suspended — pick another transit officer.`);
+      throw new BadRequestException(
+        `${agent.name} is suspended — pick another transit officer.`,
+      );
     }
-    if (validityStatus(agent) !== 'VALID') {
+    if (validityStatus(agent) !== "VALID") {
       throw new BadRequestException(
         `${agent.name}'s validity window has expired — pick another transit officer or extend their dates.`,
       );
@@ -99,38 +150,364 @@ export class TransitAgentsService {
     return agent;
   }
 
-  async create(dto: CreateTransitAgentDto): Promise<TransitAgentView> {
-    if (dto.validTo < dto.validFrom) {
-      throw new BadRequestException('Valid-to date must be on or after valid-from date.');
+  /**
+   * Create an IAM account for a transit agent, inside the caller's transaction.
+   *
+   * Follows `ShippingLineCompaniesService.register` — same entities, same shape
+   * — including its one deliberate difference from employee creation: no
+   * `UserCredential` row is written and `hasSetPassword` stays false, so the
+   * agent must come through the activation link. Staff never handle a password.
+   */
+  private async createIamAccount(
+    manager: EntityManager,
+    args: {
+      name: string;
+      email: string;
+      username: string;
+      phoneNumber?: string;
+    },
+  ): Promise<string> {
+    const userRepo = manager.getRepository(User);
+    const user = await userRepo.save(
+      userRepo.create({
+        email: args.email,
+        username: args.username,
+        phoneNumber: args.phoneNumber,
+        name: { en: args.name },
+        userType: EUserType.INDIVIDUAL,
+        isActive: true,
+        // No credential row: the account has no password until the activation
+        // link is used. `hasSetPassword` must stay false or the portal treats
+        // the account as ready to sign in with a password that does not exist.
+        hasSetPassword: false,
+        status: EUserStatus.ACCEPTED,
+      }),
+    );
+    return user.id as string;
+  }
+
+  /**
+   * Normalize and validate the account fields shared by create and invite, and
+   * refuse credentials that already belong to somebody.
+   */
+  private async prepareAccountFields(
+    dto: { email: string; phoneNumber?: string; username?: string },
+    exceptAgentId?: string,
+  ) {
+    const email = dto.email.trim().toLowerCase();
+    const username = (dto.username?.trim() || email).toLowerCase();
+    const phoneNumber = dto.phoneNumber?.trim() || undefined;
+
+    if (
+      await this.transitAgentsRepository.existsByEmail(email, exceptAgentId)
+    ) {
+      throw new ConflictException(
+        `A transit agent with email ${email} already exists`,
+      );
     }
-    const agent = await this.transitAgentsRepository.create({
+
+    // An existing IAM account means these credentials already belong to a
+    // customer, a shipping line or an employee. Reusing it would let one login
+    // resolve to two different account kinds, so this is refused rather than
+    // merged.
+    const existingUser = await this.userRepository.findOne({
+      where: [{ email }, { username }],
+      select: { id: true },
+    });
+    if (existingUser) {
+      throw new ConflictException("email_or_username_already_in_use");
+    }
+
+    return { email, username, phoneNumber };
+  }
+
+  /**
+   * Create a transit agent.
+   *
+   * With no `email` this is the pre-existing behaviour: a GL-assignable roster
+   * entry with no login, which is what production is full of. With an `email`
+   * the IAM account and the agent row are created in one transaction and the
+   * activation link goes out.
+   */
+  async create(dto: CreateTransitAgentDto): Promise<TransitAgentView> {
+    return (await this.createWithInvite(dto)).agent;
+  }
+
+  /** {@link create}, also reporting where the activation link went. */
+  async createWithInvite(
+    dto: CreateTransitAgentDto,
+  ): Promise<InvitedTransitAgent> {
+    if (dto.validTo < dto.validFrom) {
+      throw new BadRequestException(
+        "Valid-to date must be on or after valid-from date.",
+      );
+    }
+
+    const base = {
       name: dto.name.trim(),
       validFrom: dto.validFrom,
       validTo: dto.validTo,
       isActive: dto.isActive ?? true,
+    };
+
+    if (!dto.email) {
+      // Roster-only agent — no account, nothing to send.
+      const agent = await this.transitAgentsRepository.create(base);
+      return {
+        agent: withValidityStatus(agent),
+        activationSentTo: null,
+        activationChannel: null,
+      };
+    }
+
+    const { email, username, phoneNumber } = await this.prepareAccountFields({
+      email: dto.email,
+      phoneNumber: dto.phoneNumber,
+      username: dto.username,
     });
-    return withValidityStatus(agent);
+
+    const agent = await this.dataSource.transaction(async (manager) => {
+      const userId = await this.createIamAccount(manager, {
+        name: base.name,
+        email,
+        username,
+        phoneNumber,
+      });
+      return this.transitAgentsRepository.createInTransaction(manager, {
+        ...base,
+        userId,
+        email,
+        phoneNumber: phoneNumber ?? null,
+      });
+    });
+
+    // Outside the transaction on purpose: a delivery failure must not roll back
+    // a registered agent. The link is resendable, and the account is already
+    // valid without it.
+    const activation = await this.sendActivationLink(agent);
+    return {
+      agent: withValidityStatus(agent),
+      activationSentTo: activation?.maskedTarget ?? null,
+      activationChannel: activation?.channel ?? null,
+    };
   }
 
-  async update(id: string, dto: UpdateTransitAgentDto): Promise<TransitAgentView> {
+  /**
+   * Give an EXISTING agent a portal login — the path for the roster entries
+   * already in production. Creates the IAM account, attaches it, and sends the
+   * activation link.
+   */
+  async invite(
+    id: string,
+    dto: InviteTransitAgentDto,
+  ): Promise<InvitedTransitAgent> {
+    const current = await this.transitAgentsRepository.findById(id);
+    if (!current) {
+      throw new NotFoundException(`Transit agent ${id} not found`);
+    }
+    if (current.userId) {
+      // Already has an account — resending is `resendActivation`, which reuses
+      // the existing user instead of minting a second one for the same person.
+      throw new ConflictException(
+        "This transit agent already has a portal account — resend the activation link instead.",
+      );
+    }
+
+    const { email, username, phoneNumber } = await this.prepareAccountFields(
+      dto,
+      id,
+    );
+
+    const agent = await this.dataSource.transaction(async (manager) => {
+      const userId = await this.createIamAccount(manager, {
+        name: current.name,
+        email,
+        username,
+        phoneNumber,
+      });
+      return this.transitAgentsRepository.linkAccountInTransaction(
+        manager,
+        id,
+        {
+          userId,
+          email,
+          phoneNumber: phoneNumber ?? null,
+        },
+      );
+    });
+
+    const activation = await this.sendActivationLink(agent);
+    return {
+      agent: withValidityStatus(agent),
+      activationSentTo: activation?.maskedTarget ?? null,
+      activationChannel: activation?.channel ?? null,
+    };
+  }
+
+  /**
+   * Send the activation link.
+   *
+   * Email always goes out — it is the only channel guaranteed to reach a
+   * foreign-registered officer. SMS is sent in addition when the number is
+   * domestic, since the gateway silently drops anything else. Both carry the
+   * SAME single-use ticket: minting retires earlier tickets, so two mints would
+   * kill the email link the moment the SMS went out.
+   *
+   * Reports the email send, as that is the one that is always attempted.
+   */
+  async sendActivationLink(agent: TransitAgent) {
+    if (!agent.userId) return null;
+
+    const scope = `transit agent ${agent.id}`;
+    const channels = [ResetChannel.Email];
+    if (agent.phoneNumber && isDomesticPhone(agent.phoneNumber)) {
+      channels.push(ResetChannel.Phone);
+    }
+
+    const sent = await this.customerResetService.sendResetLinkToUserOnChannels(
+      agent.userId,
+      channels,
+      { scope, allowWithoutCredential: true },
+    );
+    const emailed = sent.find((s) => s.channel === ResetChannel.Email) ?? null;
+
+    if (!emailed) {
+      this.logger.error(
+        `Activation email not sent for transit agent ${agent.id} — no reachable address`,
+      );
+    }
+    if (
+      channels.includes(ResetChannel.Phone) &&
+      !sent.some((s) => s.channel === ResetChannel.Phone)
+    ) {
+      this.logger.warn(`Activation SMS not sent for transit agent ${agent.id}`);
+    }
+
+    return emailed;
+  }
+
+  async resendActivation(id: string, channel: ResetChannel) {
+    const agent = await this.transitAgentsRepository.findById(id);
+    if (!agent) {
+      throw new NotFoundException("Transit agent not found");
+    }
+    if (!agent.userId) {
+      throw new BadRequestException(
+        "This transit agent has no portal account yet — invite them first.",
+      );
+    }
+
+    if (
+      channel === ResetChannel.Phone &&
+      (!agent.phoneNumber || !isDomesticPhone(agent.phoneNumber))
+    ) {
+      throw new BadRequestException(
+        "This transit agent has no domestic phone number — the SMS gateway cannot reach it",
+      );
+    }
+
+    const sent = await this.customerResetService.sendResetLinkToUser(
+      agent.userId,
+      channel,
+      {
+        scope: `transit agent ${agent.id}`,
+        allowWithoutCredential: true,
+      },
+    );
+
+    if (!sent) {
+      throw new NotFoundException(
+        `No active account with ${
+          channel === ResetChannel.Email ? "an email address" : "a phone number"
+        } for this transit agent`,
+      );
+    }
+
+    return sent;
+  }
+
+  /** The transit agent signed in as `userId`, or null for any other account. */
+  findByUserId(userId: string): Promise<TransitAgent | null> {
+    return this.transitAgentsRepository.findByUserId(userId);
+  }
+
+  async update(
+    id: string,
+    dto: UpdateTransitAgentDto,
+  ): Promise<TransitAgentView> {
     const current = await this.findById(id);
     const nextValidFrom = dto.validFrom ?? current.validFrom;
     const nextValidTo = dto.validTo ?? current.validTo;
     if (nextValidTo < nextValidFrom) {
-      throw new BadRequestException('Valid-to date must be on or after valid-from date.');
+      throw new BadRequestException(
+        "Valid-to date must be on or after valid-from date.",
+      );
+    }
+
+    // `username` only ever names an IAM account, and it is chosen once at
+    // account creation. Accepting it here (PartialType inherits it from the
+    // create DTO) would write a column that does not exist on this table.
+    const { username: _ignoredUsername, email, phoneNumber, ...rest } = dto;
+
+    const contact: Partial<TransitAgent> = {};
+    if (email !== undefined) {
+      const normalized = email.trim().toLowerCase();
+      if (await this.transitAgentsRepository.existsByEmail(normalized, id)) {
+        throw new ConflictException(
+          `A transit agent with email ${normalized} already exists`,
+        );
+      }
+      contact.email = normalized;
+    }
+    if (phoneNumber !== undefined) {
+      contact.phoneNumber = phoneNumber.trim() || null;
     }
 
     const updated = await this.transitAgentsRepository.update(id, {
-      ...dto,
+      ...rest,
+      ...contact,
       ...(dto.name ? { name: dto.name.trim() } : {}),
     });
 
     if (!updated) {
       throw new NotFoundException(`Transit agent ${id} not found`);
     }
+
+    // Keep the IAM account in step. Without this, an agent whose address was
+    // corrected here would still receive its activation link at the old one —
+    // the reset service reads the address off `iam.users`, not off this row.
+    if (
+      updated.userId &&
+      (contact.email !== undefined || contact.phoneNumber !== undefined)
+    ) {
+      await this.syncIamContact(updated);
+    }
+
     return withValidityStatus(updated);
   }
 
+  /**
+   * Mirror an edited email/phone onto the linked IAM account.
+   *
+   * Best-effort: a failure here must not fail the agent edit that already
+   * committed, but it does mean the two are out of step, so it is logged loudly
+   * rather than swallowed. Re-running the edit retries it.
+   */
+  private async syncIamContact(agent: TransitAgent): Promise<void> {
+    if (!agent.userId) return;
+    try {
+      await this.userRepository.update(agent.userId, {
+        ...(agent.email ? { email: agent.email } : {}),
+        phoneNumber: agent.phoneNumber ?? undefined,
+      });
+    } catch (error) {
+      this.logger.error(
+        `Transit agent ${agent.id} contact updated but IAM user ${agent.userId} was not — ` +
+          `activation links will still go to the old address: ${String(error)}`,
+      );
+    }
+  }
+
   async remove(id: string): Promise<void> {
     await this.findById(id);
     await this.transitAgentsRepository.softDelete(id);
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/dto/create-transit-assignment.dto.ts b/apps/edr-freight-api/src/modules/transit-assignments/dto/create-transit-assignment.dto.ts
new file mode 100644
index 000000000..a21f75dd9
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/dto/create-transit-assignment.dto.ts
@@ -0,0 +1,36 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import {
+  IsEnum,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+} from "class-validator";
+
+import { TransitAssignmentStatus } from "../entities/transit-assignment.entity";
+
+export class CreateTransitAssignmentDto {
+  @ApiProperty({ format: "uuid" })
+  @IsUUID()
+  bookingId!: string;
+
+  @ApiProperty({ format: "uuid" })
+  @IsUUID()
+  transitAgentId!: string;
+
+  @ApiPropertyOptional({
+    enum: TransitAssignmentStatus,
+    default: TransitAssignmentStatus.NotStarted,
+    description:
+      "Assignments normally start NOT_STARTED; pass one only to record work already under way.",
+  })
+  @IsOptional()
+  @IsEnum(TransitAssignmentStatus)
+  status?: TransitAssignmentStatus;
+
+  @ApiPropertyOptional({ maxLength: 2000 })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  note?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/dto/my-assignments-query.dto.ts b/apps/edr-freight-api/src/modules/transit-assignments/dto/my-assignments-query.dto.ts
new file mode 100644
index 000000000..4c7089780
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/dto/my-assignments-query.dto.ts
@@ -0,0 +1,43 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import { IsEnum, IsInt, IsOptional, IsString, Max, Min } from "class-validator";
+
+import { TransitAssignmentStatus } from "../entities/transit-assignment.entity";
+
+/** Filters for the transit agent's own booking list. */
+export class MyAssignmentsQueryDto {
+  /** Free text over the booking reference and the customer's company name. */
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  @ApiPropertyOptional({ enum: TransitAssignmentStatus })
+  @IsOptional()
+  @IsEnum(TransitAssignmentStatus)
+  status?: TransitAssignmentStatus;
+
+  @ApiPropertyOptional({
+    example: "DISPATCHED",
+    description: "The booking's scheduling state.",
+  })
+  @IsOptional()
+  @IsString()
+  schedulingStatus?: string;
+
+  @ApiPropertyOptional({ default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @ApiPropertyOptional({ default: 20 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  // Bounded so a hand-edited query string cannot ask for the whole table.
+  @Max(100)
+  pageSize?: number;
+}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/dto/submit-transit-assignment.dto.ts b/apps/edr-freight-api/src/modules/transit-assignments/dto/submit-transit-assignment.dto.ts
new file mode 100644
index 000000000..f6e91cd31
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/dto/submit-transit-assignment.dto.ts
@@ -0,0 +1,23 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { Transform } from "class-transformer";
+import { IsBoolean, IsOptional, IsString, MaxLength } from "class-validator";
+
+/** The portal's Save / Finish action on the agent's own assignment. */
+export class SubmitTransitAssignmentDto {
+  @ApiProperty({
+    description:
+      "true finishes the assignment, which also locks its documents. false saves progress and leaves it open.",
+  })
+  // Arrives as a string when posted as multipart alongside files.
+  @Transform(({ value }) =>
+    value === "true" ? true : value === "false" ? false : value,
+  )
+  @IsBoolean()
+  finish!: boolean;
+
+  @ApiPropertyOptional({ maxLength: 2000 })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  note?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/dto/transit-assignment-query.dto.ts b/apps/edr-freight-api/src/modules/transit-assignments/dto/transit-assignment-query.dto.ts
new file mode 100644
index 000000000..166306f2a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/dto/transit-assignment-query.dto.ts
@@ -0,0 +1,36 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import { IsEnum, IsInt, IsOptional, IsUUID, Min } from "class-validator";
+
+import { TransitAssignmentStatus } from "../entities/transit-assignment.entity";
+
+export class TransitAssignmentQueryDto {
+  @ApiPropertyOptional({ format: "uuid" })
+  @IsOptional()
+  @IsUUID()
+  bookingId?: string;
+
+  @ApiPropertyOptional({ format: "uuid" })
+  @IsOptional()
+  @IsUUID()
+  transitAgentId?: string;
+
+  @ApiPropertyOptional({ enum: TransitAssignmentStatus })
+  @IsOptional()
+  @IsEnum(TransitAssignmentStatus)
+  status?: TransitAssignmentStatus;
+
+  @ApiPropertyOptional({ default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @ApiPropertyOptional({ default: 20 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  pageSize?: number;
+}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/dto/update-transit-assignment.dto.ts b/apps/edr-freight-api/src/modules/transit-assignments/dto/update-transit-assignment.dto.ts
new file mode 100644
index 000000000..2dda6b34e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/dto/update-transit-assignment.dto.ts
@@ -0,0 +1,22 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsEnum, IsOptional, IsString, MaxLength } from "class-validator";
+
+import { TransitAssignmentStatus } from "../entities/transit-assignment.entity";
+
+/**
+ * `bookingId` and `transitAgentId` are absent on purpose: repointing an
+ * assignment at a different booking or agent would silently reattribute the
+ * work and the documents already filed under it. Delete and re-create instead.
+ */
+export class UpdateTransitAssignmentDto {
+  @ApiPropertyOptional({ enum: TransitAssignmentStatus })
+  @IsOptional()
+  @IsEnum(TransitAssignmentStatus)
+  status?: TransitAssignmentStatus;
+
+  @ApiPropertyOptional({ maxLength: 2000 })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  note?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/entities/transit-assignment.entity.ts b/apps/edr-freight-api/src/modules/transit-assignments/entities/transit-assignment.entity.ts
new file mode 100644
index 000000000..dd7f07ac7
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/entities/transit-assignment.entity.ts
@@ -0,0 +1,79 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm";
+
+import { Booking } from "../../bookings/entities/booking.entity";
+import { TransitAgent } from "../../transit-agents/entities/transit-agent.entity";
+
+/** Where the agent's work on this booking currently stands. */
+export enum TransitAssignmentStatus {
+  NotStarted = "NOT_STARTED",
+  InProgress = "IN_PROGRESS",
+  Finished = "FINISHED",
+}
+
+/**
+ * One transit agent's work on one booking. An agent handles many bookings, so
+ * this is the join between the two, carrying the work's own state: when it
+ * started, when it finished, and the documents produced along the way.
+ *
+ * Deliberately separate from the transit-assignee handshake on the booking
+ * (`/bookings/:id/clearance/transit-assignee/...`), which is a pre-declaration
+ * agreement between GL Ethiopia and GL Djibouti about WHO will handle customs.
+ * Nothing here reads or writes that flow.
+ *
+ * There is no stored duration. "Time after the train arrives" is
+ * `finishedAt − booking.arrivedAt`; both halves already exist, and storing the
+ * difference would be a third source of truth that goes stale the moment either
+ * timestamp is corrected. It is computed on read — see
+ * `TransitAssignmentsService.toView`.
+ *
+ * Documents live in `freight.files` under
+ * {@link TRANSIT_ASSIGNMENT_FILE_RESOURCE}, which already carries the MinIO
+ * object, the upload time, the uploader and the supersede history.
+ */
+@Entity({ schema: "freight", name: "transit_assignments" })
+@Index(["bookingId"])
+@Index(["transitAgentId", "status"])
+export class TransitAssignment extends BaseEntity {
+  @Column({ name: "booking_id", type: "uuid" })
+  bookingId!: string;
+
+  @ManyToOne(() => Booking)
+  @JoinColumn({ name: "booking_id" })
+  booking?: Booking;
+
+  @Column({ name: "transit_agent_id", type: "uuid" })
+  transitAgentId!: string;
+
+  @ManyToOne(() => TransitAgent)
+  @JoinColumn({ name: "transit_agent_id" })
+  transitAgent?: TransitAgent;
+
+  @Column({
+    name: "status",
+    type: "varchar",
+    length: 32,
+    default: TransitAssignmentStatus.NotStarted,
+  })
+  status!: TransitAssignmentStatus;
+
+  /** Stamped on the first move to IN_PROGRESS; never overwritten afterwards. */
+  @Column({ name: "started_at", type: "timestamptz", nullable: true })
+  startedAt?: Date | null;
+
+  /** Stamped on the move to FINISHED. Cleared if the work is reopened. */
+  @Column({ name: "finished_at", type: "timestamptz", nullable: true })
+  finishedAt?: Date | null;
+
+  @Column({ name: "assigned_by_user_id", type: "uuid", nullable: true })
+  assignedByUserId?: string | null;
+
+  @Column({ name: "assigned_at", type: "timestamptz", default: () => "now()" })
+  assignedAt!: Date;
+
+  @Column({ name: "note", type: "text", nullable: true })
+  note?: string | null;
+}
+
+/** `files.resource` value for documents attached to a transit assignment. */
+export const TRANSIT_ASSIGNMENT_FILE_RESOURCE = "transit_assignments";
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.controller.ts b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.controller.ts
new file mode 100644
index 000000000..76dd0eb9c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.controller.ts
@@ -0,0 +1,255 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Param,
+  ParseUUIDPipe,
+  Patch,
+  Post,
+  Query,
+  UploadedFiles,
+  UseInterceptors,
+} from "@nestjs/common";
+import { AnyFilesInterceptor } from "@nestjs/platform-express";
+import {
+  ApiBearerAuth,
+  ApiConsumes,
+  ApiOperation,
+  ApiTags,
+} from "@nestjs/swagger";
+
+import { CurrentUser } from "@edr/api-common";
+import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
+
+import { BookingStaff, PortalCustomer } from "../../common/booking-guards";
+import { documentUploadMulterOptions } from "../../common/document-upload.options";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { CreateTransitAssignmentDto } from "./dto/create-transit-assignment.dto";
+import { MyAssignmentsQueryDto } from "./dto/my-assignments-query.dto";
+import { SubmitTransitAssignmentDto } from "./dto/submit-transit-assignment.dto";
+import { TransitAssignmentQueryDto } from "./dto/transit-assignment-query.dto";
+import { UpdateTransitAssignmentDto } from "./dto/update-transit-assignment.dto";
+import { TransitAssignmentsService } from "./transit-assignments.service";
+
+/**
+ * Transit assignments — one transit agent's work on one booking.
+ *
+ * Distinct from the transit-assignee handshake under
+ * `/bookings/:id/clearance/transit-assignee/...`, which decides WHO will handle
+ * a shipment's customs. This is the work record that follows: status, timings
+ * and documents.
+ */
+@ApiTags("transit-assignments")
+@Controller("transit-assignments")
+@ApiBearerAuth()
+export class TransitAssignmentsController {
+  constructor(
+    private readonly transitAssignmentsService: TransitAssignmentsService,
+  ) {}
+
+  // ── Portal — the signed-in transit agent's own work ───────────────────────
+  // Declared first so the literal `my` segment is matched before `:id`.
+  // Every route resolves the agent from the session; none accepts an agent id.
+
+  @Get("my/stats")
+  @PortalCustomer()
+  @ApiOperation({
+    summary: "Dashboard figures for the signed-in transit agent's own work",
+  })
+  myStats(@CurrentUser() user: TCurrentUser) {
+    return this.transitAssignmentsService.myStats(user.id);
+  }
+
+  @Get("my")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "The signed-in transit agent's assigned bookings (paginated, filterable)",
+  })
+  findMine(
+    @CurrentUser() user: TCurrentUser,
+    @Query() query: MyAssignmentsQueryDto,
+  ) {
+    return this.transitAssignmentsService.findMine(user.id, query);
+  }
+
+  @Get("my/:id")
+  @PortalCustomer()
+  @ApiOperation({ summary: "One of my assignments, with its documents" })
+  findMineById(
+    @CurrentUser() user: TCurrentUser,
+    @Param("id", ParseUUIDPipe) id: string,
+  ) {
+    return this.transitAssignmentsService.findMineById(user.id, id);
+  }
+
+  @Post("my/:id/files")
+  @PortalCustomer()
+  @ApiConsumes("multipart/form-data")
+  @UseInterceptors(AnyFilesInterceptor(documentUploadMulterOptions))
+  @ApiOperation({
+    summary:
+      "Upload documents to my assignment. Allowed only while the booking is DISPATCHED and the assignment is not finished.",
+  })
+  uploadMyFiles(
+    @CurrentUser() user: TCurrentUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFiles() files: Express.Multer.File[],
+    // One `titles` part per file, in the same order. A single-file upload posts
+    // one part, which multipart parsing hands back as a bare string rather than
+    // an array — normalised here so the service always sees a positional list.
+    @Body("titles") titles?: string | string[],
+  ) {
+    return this.transitAssignmentsService.uploadMyFiles(
+      user.id,
+      id,
+      files,
+      { userId: user.id, name: user.name?.en ?? undefined },
+      titles === undefined ? undefined : ([] as string[]).concat(titles),
+    );
+  }
+
+  @Delete("my/:id/files/:fileId")
+  @PortalCustomer()
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: "Remove a document from my assignment" })
+  removeMyFile(
+    @CurrentUser() user: TCurrentUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("fileId", ParseUUIDPipe) fileId: string,
+  ) {
+    return this.transitAssignmentsService.removeMyFile(user.id, id, fileId);
+  }
+
+  @Post("my/:id/submit")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Save progress, or finish the assignment (which locks its documents)",
+  })
+  submitMine(
+    @CurrentUser() user: TCurrentUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: SubmitTransitAssignmentDto,
+  ) {
+    return this.transitAssignmentsService.submitMine(user.id, id, dto);
+  }
+
+  // ── Backoffice ────────────────────────────────────────────────────────────
+
+  @Get()
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.view)
+  @ApiOperation({
+    summary:
+      "List transit assignments (paginated, filterable by booking / agent / status)",
+  })
+  findAll(@Query() query: TransitAssignmentQueryDto) {
+    return this.transitAssignmentsService.findAll(query);
+  }
+
+  /**
+   * Declared before `:id` — Nest matches routes in order, so a literal segment
+   * registered after a parameter would be swallowed by it.
+   */
+  @Get("by-agent/:transitAgentId")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.view)
+  @ApiOperation({ summary: "Every assignment handed to one transit agent" })
+  findByTransitAgent(
+    @Param("transitAgentId", ParseUUIDPipe) transitAgentId: string,
+  ) {
+    return this.transitAssignmentsService.findByTransitAgent(transitAgentId);
+  }
+
+  @Get("by-booking/:bookingId")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.view)
+  @ApiOperation({ summary: "Every transit agent assigned to one booking" })
+  findByBooking(@Param("bookingId", ParseUUIDPipe) bookingId: string) {
+    return this.transitAssignmentsService.findByBooking(bookingId);
+  }
+
+  @Get(":id")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.view)
+  @ApiOperation({
+    summary:
+      "One assignment, with its attached documents and computed duration",
+  })
+  findOne(@Param("id", ParseUUIDPipe) id: string) {
+    return this.transitAssignmentsService.findById(id);
+  }
+
+  @Post()
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.create)
+  @ApiOperation({ summary: "Assign a transit agent to a booking" })
+  create(
+    @Body() dto: CreateTransitAssignmentDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.transitAssignmentsService.create(dto, user?.id);
+  }
+
+  @Patch(":id")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.update)
+  @ApiOperation({
+    summary:
+      "Update status or note — status changes stamp the start/finish clocks",
+  })
+  update(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: UpdateTransitAssignmentDto,
+  ) {
+    return this.transitAssignmentsService.update(id, dto);
+  }
+
+  @Delete(":id")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.delete)
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: "Soft-delete an assignment" })
+  remove(@Param("id", ParseUUIDPipe) id: string) {
+    return this.transitAssignmentsService.remove(id);
+  }
+
+  // ── Documents ─────────────────────────────────────────────────────────────
+
+  @Get(":id/files")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.view)
+  @ApiOperation({ summary: "An assignment's uploaded documents" })
+  listFiles(@Param("id", ParseUUIDPipe) id: string) {
+    return this.transitAssignmentsService.listFiles(id);
+  }
+
+  @Post(":id/files")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.update)
+  @ApiConsumes("multipart/form-data")
+  @UseInterceptors(AnyFilesInterceptor(documentUploadMulterOptions))
+  @ApiOperation({
+    summary:
+      "Upload one or more documents; re-uploading adds a version, it does not overwrite",
+  })
+  uploadFiles(
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFiles() files: Express.Multer.File[],
+    @CurrentUser() user: TCurrentUser,
+    @Body("titles") titles?: string | string[],
+  ) {
+    return this.transitAssignmentsService.uploadFiles(
+      id,
+      files,
+      { userId: user?.id, name: user?.name?.en ?? undefined },
+      titles === undefined ? undefined : ([] as string[]).concat(titles),
+    );
+  }
+
+  @Delete(":id/files/:fileId")
+  @BookingStaff(FREIGHT_PERMS.transitAssignments.update)
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: "Remove one document from an assignment" })
+  removeFile(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("fileId", ParseUUIDPipe) fileId: string,
+  ) {
+    return this.transitAssignmentsService.removeFile(id, fileId);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.module.ts b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.module.ts
new file mode 100644
index 000000000..44862e2ff
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.module.ts
@@ -0,0 +1,35 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+
+import { Booking } from "../bookings/entities/booking.entity";
+import { ClearanceMilestone } from "../contracts/entities/clearance-milestone.entity";
+import { FilesModule } from "../files/files.module";
+import { TrainSchedule } from "../train-schedules/entities/train-schedule.entity";
+import { TransitAgentsModule } from "../transit-agents/transit-agents.module";
+import { TransitAssignment } from "./entities/transit-assignment.entity";
+import { TransitAssignmentsController } from "./transit-assignments.controller";
+import { TransitAssignmentsRepository } from "./transit-assignments.repository";
+import { TransitAssignmentsService } from "./transit-assignments.service";
+
+@Module({
+  imports: [
+    // `Booking` is registered as an ENTITY rather than importing BookingsModule:
+    // this module only confirms a booking id exists, and that module would drag
+    // its whole graph (billing, contracts, scheduling, first/last mile) along.
+    // Milestones and train schedules are read for the agent's dashboard
+    // timings (declaration stamps, departure/arrival fallbacks) — entities
+    // only, for the same reason as Booking.
+    TypeOrmModule.forFeature([
+      TransitAssignment,
+      Booking,
+      ClearanceMilestone,
+      TrainSchedule,
+    ]),
+    FilesModule,
+    TransitAgentsModule,
+  ],
+  controllers: [TransitAssignmentsController],
+  providers: [TransitAssignmentsService, TransitAssignmentsRepository],
+  exports: [TransitAssignmentsService, TransitAssignmentsRepository],
+})
+export class TransitAssignmentsModule {}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.repository.ts b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.repository.ts
new file mode 100644
index 000000000..9030d58f7
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.repository.ts
@@ -0,0 +1,139 @@
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+
+import {
+  TransitAssignment,
+  TransitAssignmentStatus,
+} from "./entities/transit-assignment.entity";
+
+export interface TransitAssignmentFilter {
+  bookingId?: string;
+  transitAgentId?: string;
+  status?: TransitAssignmentStatus;
+  /** The booking's scheduling state (DISPATCHED / SCHEDULED / …). */
+  schedulingStatus?: string;
+  /** Free text over the booking reference and the customer's company name. */
+  search?: string;
+}
+
+@Injectable()
+export class TransitAssignmentsRepository extends BaseRepository<TransitAssignment> {
+  constructor(
+    @InjectRepository(TransitAssignment)
+    private readonly assignmentsRepo: Repository<TransitAssignment>,
+  ) {
+    super(assignmentsRepo);
+  }
+
+  /**
+   * The booking is joined rather than lazily loaded because every read needs
+   * its `arrivedAt` — that is the other half of the computed
+   * "time after the train arrives", so a list without it would be N+1 queries
+   * or a column of nulls. The customer's company rides along for the same
+   * reason: the agent's list is read by reference AND by whose cargo it is.
+   */
+  private baseQuery() {
+    return this.assignmentsRepo
+      .createQueryBuilder("ta")
+      .leftJoinAndSelect("ta.booking", "booking")
+      .leftJoinAndSelect("booking.company", "company")
+      .leftJoinAndSelect("ta.transitAgent", "agent")
+      .where("ta.deletedAt IS NULL");
+  }
+
+  /** Shared filter application, so a list and its count can never diverge. */
+  private applyFilters(
+    qb: ReturnType<TransitAssignmentsRepository["baseQuery"]>,
+    filter: TransitAssignmentFilter,
+  ) {
+    if (filter.bookingId) {
+      qb.andWhere("ta.bookingId = :bookingId", { bookingId: filter.bookingId });
+    }
+    if (filter.transitAgentId) {
+      qb.andWhere("ta.transitAgentId = :transitAgentId", {
+        transitAgentId: filter.transitAgentId,
+      });
+    }
+    if (filter.status) {
+      qb.andWhere("ta.status = :status", { status: filter.status });
+    }
+    if (filter.schedulingStatus) {
+      qb.andWhere("booking.schedulingStatus = :schedulingStatus", {
+        schedulingStatus: filter.schedulingStatus,
+      });
+    }
+    if (filter.search?.trim()) {
+      qb.andWhere(
+        "(booking.reference ILIKE :search OR company.name ILIKE :search)",
+        { search: `%${filter.search.trim()}%` },
+      );
+    }
+    return qb;
+  }
+
+  async findPaginated(
+    filter: TransitAssignmentFilter,
+    skip: number,
+    take: number,
+  ): Promise<[TransitAssignment[], number]> {
+    return this.applyFilters(this.baseQuery(), filter)
+      .orderBy("ta.assignedAt", "DESC")
+      .skip(skip)
+      .take(take)
+      .getManyAndCount();
+  }
+
+  /**
+   * One agent's own list, filtered and paginated. Differs from
+   * {@link findPaginated} only in that the agent is pinned by the caller from
+   * the session, so it can never be widened by a query parameter.
+   */
+  async findByTransitAgentPaginated(
+    transitAgentId: string,
+    filter: Omit<TransitAssignmentFilter, "transitAgentId">,
+    skip: number,
+    take: number,
+  ): Promise<[TransitAssignment[], number]> {
+    return this.applyFilters(this.baseQuery(), { ...filter, transitAgentId })
+      .orderBy("ta.assignedAt", "DESC")
+      .skip(skip)
+      .take(take)
+      .getManyAndCount();
+  }
+
+  findOneWithRelations(id: string): Promise<TransitAssignment | null> {
+    return this.baseQuery().andWhere("ta.id = :id", { id }).getOne();
+  }
+
+  /** Every live assignment for one agent — the agent's own workload list. */
+  findByTransitAgent(transitAgentId: string): Promise<TransitAssignment[]> {
+    return this.baseQuery()
+      .andWhere("ta.transitAgentId = :transitAgentId", { transitAgentId })
+      .orderBy("ta.assignedAt", "DESC")
+      .getMany();
+  }
+
+  /** Every live assignment on one booking. */
+  findByBooking(bookingId: string): Promise<TransitAssignment[]> {
+    return this.baseQuery()
+      .andWhere("ta.bookingId = :bookingId", { bookingId })
+      .orderBy("ta.assignedAt", "DESC")
+      .getMany();
+  }
+
+  /** Guards the unique (booking, agent) pair before an insert 23505s. */
+  async existsForPair(
+    bookingId: string,
+    transitAgentId: string,
+  ): Promise<boolean> {
+    const count = await this.assignmentsRepo
+      .createQueryBuilder("ta")
+      .where("ta.bookingId = :bookingId", { bookingId })
+      .andWhere("ta.transitAgentId = :transitAgentId", { transitAgentId })
+      .andWhere("ta.deletedAt IS NULL")
+      .getCount();
+    return count > 0;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.service.spec.ts b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.service.spec.ts
new file mode 100644
index 000000000..68e856eff
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.service.spec.ts
@@ -0,0 +1,427 @@
+import {
+  ConflictException,
+  ForbiddenException,
+  NotFoundException,
+} from "@nestjs/common";
+
+import {
+  TransitAssignment,
+  TransitAssignmentStatus,
+} from "./entities/transit-assignment.entity";
+import { TransitAssignmentsService } from "./transit-assignments.service";
+
+/**
+ * The two things this module gets wrong quietly: the status transitions that
+ * stamp the clocks, and the duration computed from them. Both are invisible
+ * until a report reads a null or a negative number months later.
+ */
+describe("TransitAssignmentsService", () => {
+  const ARRIVED = new Date("2026-08-28T09:00:00Z");
+
+  let assignments: {
+    findPaginated: jest.Mock;
+    findOneWithRelations: jest.Mock;
+    findByTransitAgent: jest.Mock;
+    findByTransitAgentPaginated: jest.Mock;
+    findByBooking: jest.Mock;
+    existsForPair: jest.Mock;
+    create: jest.Mock;
+    update: jest.Mock;
+    softDelete: jest.Mock;
+  };
+  let agents: { findById: jest.Mock; findByUserId: jest.Mock };
+  let bookings: { findOne: jest.Mock };
+  let files: {
+    findByResource: jest.Mock;
+    findByResourceIdsGrouped: jest.Mock;
+    upload: jest.Mock;
+    remove: jest.Mock;
+  };
+  let service: TransitAssignmentsService;
+  let milestones: { find: jest.Mock };
+  let trainSchedules: { find: jest.Mock };
+
+  const row = (over: Partial<TransitAssignment> = {}) =>
+    ({
+      id: "ta-1",
+      bookingId: "bk-1",
+      transitAgentId: "ag-1",
+      status: TransitAssignmentStatus.NotStarted,
+      startedAt: null,
+      finishedAt: null,
+      // DISPATCHED by default: uploads are gated on it, so a fixture without it
+      // would fail every document test for the wrong reason.
+      booking: {
+        id: "bk-1",
+        arrivedAt: ARRIVED,
+        schedulingStatus: "DISPATCHED",
+      },
+      ...over,
+    }) as TransitAssignment;
+
+  beforeEach(() => {
+    assignments = {
+      findPaginated: jest.fn(),
+      findOneWithRelations: jest.fn().mockResolvedValue(row()),
+      findByTransitAgent: jest.fn().mockResolvedValue([]),
+      findByTransitAgentPaginated: jest.fn().mockResolvedValue([[], 0]),
+      findByBooking: jest.fn().mockResolvedValue([]),
+      existsForPair: jest.fn().mockResolvedValue(false),
+      create: jest.fn(async (data) => ({ id: "ta-1", ...data })),
+      update: jest.fn(async (id, data) => ({ id, ...data })),
+      softDelete: jest.fn(),
+    };
+    agents = {
+      findById: jest.fn().mockResolvedValue({ id: "ag-1", name: "Ahmed" }),
+      findByUserId: jest.fn().mockResolvedValue({ id: "ag-1", name: "Ahmed" }),
+    };
+    bookings = { findOne: jest.fn().mockResolvedValue({ id: "bk-1" }) };
+    files = {
+      findByResource: jest.fn().mockResolvedValue([]),
+      findByResourceIdsGrouped: jest.fn().mockResolvedValue(new Map()),
+      upload: jest.fn(),
+      remove: jest.fn(),
+    };
+
+    milestones = { find: jest.fn().mockResolvedValue([]) };
+    trainSchedules = { find: jest.fn().mockResolvedValue([]) };
+
+    service = new TransitAssignmentsService(
+      assignments as never,
+      agents as never,
+      bookings as never,
+      files as never,
+      milestones as never,
+      trainSchedules as never,
+    );
+  });
+
+  describe("timeAfterTrainArrives", () => {
+    it("reports whole minutes between arrival and finish", async () => {
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({
+          status: TransitAssignmentStatus.Finished,
+          finishedAt: new Date("2026-08-28T14:30:00Z"),
+        }),
+      );
+
+      const view = await service.findById("ta-1");
+
+      expect(view.timeAfterTrainArrives).toBe(330);
+    });
+
+    it("is null while the work is unfinished", async () => {
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({ status: TransitAssignmentStatus.InProgress, startedAt: ARRIVED }),
+      );
+
+      expect((await service.findById("ta-1")).timeAfterTrainArrives).toBeNull();
+    });
+
+    it("is null when the booking never recorded an arrival", async () => {
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({
+          status: TransitAssignmentStatus.Finished,
+          finishedAt: new Date("2026-08-28T14:30:00Z"),
+          booking: {
+            id: "bk-1",
+            arrivedAt: null,
+            schedulingStatus: "DISPATCHED",
+          } as never,
+        }),
+      );
+
+      expect((await service.findById("ta-1")).timeAfterTrainArrives).toBeNull();
+    });
+  });
+
+  describe("status transitions", () => {
+    it("stamps startedAt on the move to IN_PROGRESS", async () => {
+      await service.update("ta-1", {
+        status: TransitAssignmentStatus.InProgress,
+      });
+
+      const patch = assignments.update.mock.calls[0][1];
+      expect(patch.startedAt).toBeInstanceOf(Date);
+      expect(patch.finishedAt).toBeNull();
+    });
+
+    it("keeps the ORIGINAL startedAt when finished work is reopened", async () => {
+      const original = new Date("2026-08-28T10:00:00Z");
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({
+          status: TransitAssignmentStatus.Finished,
+          startedAt: original,
+          finishedAt: new Date("2026-08-28T12:00:00Z"),
+        }),
+      );
+
+      await service.update("ta-1", {
+        status: TransitAssignmentStatus.InProgress,
+      });
+
+      const patch = assignments.update.mock.calls[0][1];
+      // Reopening must not restart the clock, or the elapsed time would only
+      // cover the second attempt rather than the whole job.
+      expect(patch.startedAt).toBe(original);
+      expect(patch.finishedAt).toBeNull();
+    });
+
+    it("stamps both clocks when finishing work that was never started", async () => {
+      await service.update("ta-1", {
+        status: TransitAssignmentStatus.Finished,
+      });
+
+      const patch = assignments.update.mock.calls[0][1];
+      expect(patch.startedAt).toBeInstanceOf(Date);
+      expect(patch.finishedAt).toBeInstanceOf(Date);
+    });
+
+    it("clears both clocks on a reset to NOT_STARTED", async () => {
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({
+          status: TransitAssignmentStatus.Finished,
+          startedAt: ARRIVED,
+          finishedAt: new Date(),
+        }),
+      );
+
+      await service.update("ta-1", {
+        status: TransitAssignmentStatus.NotStarted,
+      });
+
+      const patch = assignments.update.mock.calls[0][1];
+      expect(patch.startedAt).toBeNull();
+      expect(patch.finishedAt).toBeNull();
+    });
+  });
+
+  describe("create", () => {
+    it("refuses to assign the same agent to one booking twice", async () => {
+      assignments.existsForPair.mockResolvedValue(true);
+
+      await expect(
+        service.create({ bookingId: "bk-1", transitAgentId: "ag-1" }),
+      ).rejects.toThrow(ConflictException);
+      expect(assignments.create).not.toHaveBeenCalled();
+    });
+
+    it("rejects an unknown booking", async () => {
+      bookings.findOne.mockResolvedValue(null);
+
+      await expect(
+        service.create({ bookingId: "nope", transitAgentId: "ag-1" }),
+      ).rejects.toThrow(NotFoundException);
+    });
+  });
+
+  describe("files", () => {
+    it("refuses to delete a file belonging to another assignment", async () => {
+      files.findByResource.mockResolvedValue([{ id: "file-1" }]);
+
+      await expect(service.removeFile("ta-1", "file-2")).rejects.toThrow(
+        NotFoundException,
+      );
+      expect(files.remove).not.toHaveBeenCalled();
+    });
+
+    it("names each uploaded file from its positional title", async () => {
+      await service.uploadFiles(
+        "ta-1",
+        [
+          { originalname: "a.pdf" } as Express.Multer.File,
+          { originalname: "b.pdf" } as Express.Multer.File,
+          { originalname: "c.pdf" } as Express.Multer.File,
+        ],
+        {},
+        ["Bill of lading", "  ", "Packing list"],
+      );
+
+      const titles = files.upload.mock.calls.map((call) => call[0].title);
+      // Index N names file N; a blank entry falls back to null so the record
+      // shows its original filename rather than an empty label.
+      expect(titles).toEqual(["Bill of lading", null, "Packing list"]);
+    });
+
+    it("stores no title when none were sent", async () => {
+      await service.uploadFiles(
+        "ta-1",
+        [{ originalname: "a.pdf" } as Express.Multer.File],
+        {},
+      );
+
+      expect(files.upload.mock.calls[0][0].title).toBeNull();
+    });
+
+    it("refuses an upload before the booking is dispatched", async () => {
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({
+          booking: {
+            id: "bk-1",
+            arrivedAt: null,
+            schedulingStatus: "SCHEDULED",
+          } as never,
+        }),
+      );
+
+      await expect(
+        service.uploadFiles("ta-1", [{} as Express.Multer.File], {}),
+      ).rejects.toThrow(ForbiddenException);
+      expect(files.upload).not.toHaveBeenCalled();
+    });
+
+    it("refuses an upload once the assignment is finished", async () => {
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({
+          status: TransitAssignmentStatus.Finished,
+          finishedAt: new Date(),
+        }),
+      );
+
+      await expect(
+        service.uploadFiles("ta-1", [{} as Express.Multer.File], {}),
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it("refuses to remove a document once the assignment is finished", async () => {
+      assignments.findOneWithRelations.mockResolvedValue(
+        row({
+          status: TransitAssignmentStatus.Finished,
+          finishedAt: new Date(),
+        }),
+      );
+      files.findByResource.mockResolvedValue([{ id: "file-1" }]);
+
+      await expect(service.removeFile("ta-1", "file-1")).rejects.toThrow(
+        ForbiddenException,
+      );
+      expect(files.remove).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("myStats", () => {
+    const at = (iso: string) => new Date(iso);
+    const DEPARTED = at("2026-08-27T20:00:00Z");
+
+    const withRows = (rows: Record<string, unknown>[]) => {
+      assignments.findByTransitAgent.mockResolvedValue(
+        rows.map((r, i) => row({ id: `ta-${i}`, bookingId: `bk-${i}`, ...r } as never)),
+      );
+    };
+    const bookingFiles = (entries: Record<string, Array<[string, string]>>) => {
+      files.findByResourceIdsGrouped.mockImplementation(
+        async (_ids: string[], resource: string) =>
+          resource === "bookings"
+            ? new Map(
+                Object.entries(entries).map(([bookingId, list]) => [
+                  bookingId,
+                  list.map(([code, iso]) => ({ code, createdAt: at(iso) })),
+                ]),
+              )
+            : new Map(),
+      );
+    };
+
+    it("measures transit from the train's departure to its arrival, using the median", async () => {
+      withRows([
+        { booking: { loadedAt: DEPARTED, arrivedAt: at("2026-08-28T06:00:00Z"), tradeDirection: "EXPORT" } },
+        { booking: { loadedAt: DEPARTED, arrivedAt: at("2026-08-28T08:00:00Z"), tradeDirection: "EXPORT" } },
+        // 3-day outlier: a mean would describe none of the three.
+        { booking: { loadedAt: DEPARTED, arrivedAt: at("2026-08-30T20:00:00Z"), tradeDirection: "EXPORT" } },
+        // Still rolling: contributes nothing, not zero.
+        { booking: { loadedAt: DEPARTED, arrivedAt: null, tradeDirection: "EXPORT" } },
+      ]);
+      bookingFiles({});
+
+      const stats = await service.myStats("user-1");
+
+      expect(stats.timings.transit).toEqual({
+        median: 720,
+        fastest: 600,
+        slowest: 4320,
+        measured: 3,
+      });
+      expect(stats.totals.inTransit).toBe(1);
+      expect(stats.totals.arrived).toBe(3);
+    });
+
+    it("times the Release Order from the declaration to the LAST RO upload", async () => {
+      withRows([{ booking: { tradeDirection: "EXPORT", loadedAt: null, arrivedAt: null } }]);
+      milestones.find.mockResolvedValue([
+        {
+          bookingId: "bk-0",
+          milestoneCode: "DECLARED",
+          status: "COMPLETED",
+          triggeredAt: at("2026-08-27T08:00:00Z"),
+        },
+      ]);
+      bookingFiles({
+        "bk-0": [
+          ["release_order_0", "2026-08-27T09:30:00Z"],
+          // Replaced batch — the later stamp is the one that counts.
+          ["release_order_1", "2026-08-27T11:00:00Z"],
+        ],
+      });
+
+      const stats = await service.myStats("user-1");
+      const [item] = stats.items;
+
+      expect(item.declaredAt).toBe("2026-08-27T08:00:00.000Z");
+      expect(item.roAt).toBe("2026-08-27T11:00:00.000Z");
+      expect(item.timings.declarationToRo).toBe(180);
+      expect(stats.timings.declarationToRo.median).toBe(180);
+      expect(item.nextAction).toEqual({ kind: "wait", label: "Awaiting train departure" });
+    });
+
+    it("points the officer at the next upload the detail page would actually allow", async () => {
+      withRows([
+        // Import, nothing filed: the DO comes first.
+        { booking: { tradeDirection: "IMPORT", loadedAt: null, arrivedAt: null } },
+        // Import with a DO but no departure yet: T1 is still locked.
+        { booking: { tradeDirection: "IMPORT", loadedAt: null, arrivedAt: null } },
+        // Import, departed, no T1: upload it.
+        { booking: { tradeDirection: "IMPORT", loadedAt: DEPARTED, arrivedAt: null } },
+        // Export, arrived with an RO but no gate pass yet.
+        {
+          booking: {
+            tradeDirection: "EXPORT",
+            loadedAt: DEPARTED,
+            arrivedAt: at("2026-08-28T06:00:00Z"),
+          },
+        },
+      ]);
+      milestones.find.mockResolvedValue([
+        { bookingId: "bk-3", milestoneCode: "DECLARED", status: "COMPLETED", triggeredAt: at("2026-08-26T08:00:00Z") },
+      ]);
+      bookingFiles({
+        "bk-1": [["delivery_order_0", "2026-08-26T10:00:00Z"]],
+        "bk-2": [["delivery_order_0", "2026-08-26T10:00:00Z"]],
+        "bk-3": [["release_order_0", "2026-08-26T10:00:00Z"]],
+      });
+
+      const stats = await service.myStats("user-1");
+      const byBooking = new Map(stats.items.map((i) => [i.bookingId, i]));
+
+      expect(byBooking.get("bk-0")?.nextAction.document).toBe("do");
+      expect(byBooking.get("bk-1")?.nextAction).toEqual({
+        kind: "wait",
+        label: "Awaiting train departure",
+      });
+      expect(byBooking.get("bk-2")?.nextAction.document).toBe("t1");
+      expect(byBooking.get("bk-3")?.nextAction.document).toBe("gate_pass");
+      expect(stats.pending).toEqual({ ro: 0, do: 1, t1: 1, gatePass: 1, djiboutiT1: 0 });
+      expect(stats.totals.actionNeeded).toBe(3);
+    });
+
+    it("reports nulls rather than zero when nothing has been measured", async () => {
+      withRows([{ status: TransitAssignmentStatus.NotStarted, booking: { arrivedAt: null } }]);
+      bookingFiles({});
+
+      const stats = await service.myStats("user-1");
+
+      expect(stats.timings.transit.median).toBeNull();
+      expect(stats.timings.arrivalToFinish.median).toBeNull();
+      expect(stats.totals.open).toBe(1);
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.service.ts b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.service.ts
new file mode 100644
index 000000000..80f8d6be9
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/transit-assignments/transit-assignments.service.ts
@@ -0,0 +1,937 @@
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+
+import { InjectRepository } from "@nestjs/typeorm";
+import { In, Repository } from "typeorm";
+import {
+  isDeliveryOrderFileCode,
+  isDjiboutiT1FileCode,
+  isGatePassFileCode,
+  isReleaseOrderFileCode,
+  isT1TransportFileCode,
+} from "@edr/types";
+
+import { Booking } from "../bookings/entities/booking.entity";
+import { ClearanceMilestone } from "../contracts/entities/clearance-milestone.entity";
+import { FilesService } from "../files/files.service";
+import { TrainSchedule } from "../train-schedules/entities/train-schedule.entity";
+import { TransitAgentsRepository } from "../transit-agents/transit-agents.repository";
+import { FileRecord } from "../files/entities/file.entity";
+import { CreateTransitAssignmentDto } from "./dto/create-transit-assignment.dto";
+import { MyAssignmentsQueryDto } from "./dto/my-assignments-query.dto";
+import { TransitAssignmentQueryDto } from "./dto/transit-assignment-query.dto";
+import { UpdateTransitAssignmentDto } from "./dto/update-transit-assignment.dto";
+import {
+  TRANSIT_ASSIGNMENT_FILE_RESOURCE,
+  TransitAssignment,
+  TransitAssignmentStatus,
+} from "./entities/transit-assignment.entity";
+import { TransitAssignmentsRepository } from "./transit-assignments.repository";
+
+/** One attached document, flattened for the API. */
+export interface TransitAssignmentFileView {
+  id: string;
+  name: string;
+  title: string | null;
+  url: string;
+  size: number;
+  mimeType: string;
+  /** When the file was first uploaded. */
+  uploadedAt: string;
+  /** When its metadata was last edited — equal to `uploadedAt` if never. */
+  updatedAt: string;
+  uploadedByUserId: string | null;
+  uploadedByName: string | null;
+}
+
+export type TransitAssignmentView = TransitAssignment & {
+  /**
+   * Minutes between the train arriving and the transit work finishing —
+   * `finishedAt − booking.arrivedAt`, floored to whole minutes.
+   *
+   * Null until BOTH exist: an unfinished assignment has no end, and a booking
+   * whose arrival was never stamped has no start. Computed rather than stored
+   * so a corrected timestamp cannot leave a stale number behind.
+   */
+  timeAfterTrainArrives: number | null;
+  /**
+   * Whether documents may still be added or removed right now. Mirrors
+   * `assertUploadAllowed` so the portal can disable its controls instead of
+   * letting the agent discover the rule through a 403.
+   */
+  canUploadDocuments: boolean;
+  /**
+   * Whose cargo this is. Flattened off the joined company so the portal grid
+   * does not have to reach through `booking.company` — and so a booking with no
+   * company (shipping-line bookings carry none) renders as a blank rather than
+   * throwing.
+   */
+  customerName: string | null;
+  files?: TransitAssignmentFileView[];
+};
+
+export type TransitTradeDirection = "IMPORT" | "EXPORT";
+export type TransitDocumentKind = "ro" | "do" | "t1" | "gate_pass" | "djibouti_t1";
+
+export interface TransitNextAction {
+  kind: "upload" | "wait" | "done";
+  label: string;
+  document?: TransitDocumentKind;
+}
+
+/** Minutes, or null when nothing has been measured yet — never zero. */
+export interface TransitTimingSummary {
+  median: number | null;
+  fastest: number | null;
+  slowest: number | null;
+  measured: number;
+}
+
+export interface TransitStatItem {
+  id: string;
+  bookingId: string;
+  reference: string | null;
+  customerName: string | null;
+  tradeDirection: TransitTradeDirection;
+  status: TransitAssignmentStatus;
+  schedulingStatus: string | null;
+  trainLabel: string | null;
+  assignedAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+  bookingCreatedAt: string | null;
+  departedAt: string | null;
+  arrivedAt: string | null;
+  declaredAt: string | null;
+  roAt: string | null;
+  doAt: string | null;
+  t1At: string | null;
+  t1Closed: boolean;
+  gatePassAt: string | null;
+  djiboutiT1At: string | null;
+  documents: {
+    ro: number;
+    do: number;
+    t1: number;
+    gatePass: number;
+    djiboutiT1: number;
+    own: number;
+  };
+  timings: {
+    transit: number | null;
+    declarationToRo: number | null;
+    bookingToDo: number | null;
+    departureToT1: number | null;
+    arrivalToT1: number | null;
+    arrivalToGatePass: number | null;
+    arrivalToDjiboutiT1: number | null;
+    arrivalToFinish: number | null;
+  };
+  nextAction: TransitNextAction;
+}
+
+export interface TransitStats {
+  totals: {
+    assignments: number;
+    open: number;
+    notStarted: number;
+    inProgress: number;
+    finished: number;
+    imports: number;
+    exports: number;
+    awaitingDeparture: number;
+    inTransit: number;
+    arrived: number;
+    actionNeeded: number;
+  };
+  timings: Record<keyof TransitStatItem["timings"], TransitTimingSummary>;
+  documents: TransitStatItem["documents"];
+  pending: { ro: number; do: number; t1: number; gatePass: number; djiboutiT1: number };
+  items: TransitStatItem[];
+}
+
+@Injectable()
+export class TransitAssignmentsService {
+  constructor(
+    private readonly assignmentsRepository: TransitAssignmentsRepository,
+    private readonly transitAgentsRepository: TransitAgentsRepository,
+    // The Booking ENTITY, not BookingsModule: this only needs to confirm a
+    // booking id exists, and importing that module would pull its whole graph
+    // (billing, contracts, scheduling, first/last mile) in behind it.
+    @InjectRepository(Booking)
+    private readonly bookingsRepository: Repository<Booking>,
+    private readonly filesService: FilesService,
+    @InjectRepository(ClearanceMilestone)
+    private readonly milestonesRepository: Repository<ClearanceMilestone>,
+    @InjectRepository(TrainSchedule)
+    private readonly trainSchedulesRepository: Repository<TrainSchedule>,
+  ) {}
+
+  private static minutesBetween(
+    from?: Date | null,
+    to?: Date | null,
+  ): number | null {
+    if (!from || !to) return null;
+    return Math.floor((to.getTime() - from.getTime()) / 60_000);
+  }
+
+  private toView(assignment: TransitAssignment): TransitAssignmentView {
+    return {
+      ...assignment,
+      timeAfterTrainArrives: TransitAssignmentsService.minutesBetween(
+        assignment.booking?.arrivedAt,
+        assignment.finishedAt,
+      ),
+      canUploadDocuments:
+        assignment.status !== TransitAssignmentStatus.Finished &&
+        assignment.booking?.schedulingStatus === "DISPATCHED",
+      customerName: assignment.booking?.company?.name ?? null,
+    };
+  }
+
+  async findAll(query: TransitAssignmentQueryDto) {
+    const page = query.page ?? 1;
+    const pageSize = query.pageSize ?? 20;
+    const [items, total] = await this.assignmentsRepository.findPaginated(
+      {
+        bookingId: query.bookingId,
+        transitAgentId: query.transitAgentId,
+        status: query.status,
+      },
+      (page - 1) * pageSize,
+      pageSize,
+    );
+
+    return {
+      items: items.map((item) => this.toView(item)),
+      meta: {
+        total,
+        page,
+        pageSize,
+        totalPages: Math.max(1, Math.ceil(total / pageSize)),
+      },
+    };
+  }
+
+  /** Detail read — the only one that carries the attached documents. */
+  async findById(id: string): Promise<TransitAssignmentView> {
+    const assignment =
+      await this.assignmentsRepository.findOneWithRelations(id);
+    if (!assignment) {
+      throw new NotFoundException(`Transit assignment ${id} not found`);
+    }
+    return { ...this.toView(assignment), files: await this.listFiles(id) };
+  }
+
+  /** Every assignment handed to one transit agent — their workload list. */
+  async findByTransitAgent(
+    transitAgentId: string,
+  ): Promise<TransitAssignmentView[]> {
+    const agent = await this.transitAgentsRepository.findById(transitAgentId);
+    if (!agent) {
+      throw new NotFoundException(`Transit agent ${transitAgentId} not found`);
+    }
+    const rows =
+      await this.assignmentsRepository.findByTransitAgent(transitAgentId);
+    return rows.map((row) => this.toView(row));
+  }
+
+  /** Every agent assigned to one booking. */
+  async findByBooking(bookingId: string): Promise<TransitAssignmentView[]> {
+    const rows = await this.assignmentsRepository.findByBooking(bookingId);
+    return rows.map((row) => this.toView(row));
+  }
+
+  // ── Portal (the signed-in transit agent's own work) ───────────────────────
+  // Every one of these resolves the agent from the SESSION and never from a
+  // client-supplied id: an agent must not be able to read or edit another
+  // agent's assignments by guessing one.
+
+  /** The transit agent this portal user signs in as. */
+  private async requireAgentForUser(userId: string) {
+    const agent = await this.transitAgentsRepository.findByUserId(userId);
+    if (!agent) {
+      throw new ForbiddenException("This account is not a transit agent");
+    }
+    return agent;
+  }
+
+  /**
+   * Dashboard figures for the signed-in agent's own work.
+   *
+   * Every interval is derived from timestamps that already exist — nothing is
+   * stored, so a corrected arrival or finish time changes these on the next
+   * read rather than leaving a stale metric behind.
+   *
+   * The median is used rather than the mean on purpose: one assignment
+   * reopened days later drags an average far enough to make the whole panel
+   * lie about typical performance.
+   */
+  /**
+   * The agent's dashboard, every figure derived from stamps that already exist:
+   * the train's departure and arrival, the booking's clearance milestones, and
+   * the upload time of each document on the booking (RO / DO / T1 / gate pass /
+   * Djibouti T1). Replaced batches carry a fresh stamp, so an "uploaded" time
+   * here is always the LAST update, matching the detail page.
+   *
+   * Nothing is stored: a corrected timestamp cannot leave a stale number behind.
+   */
+  async myStats(userId: string): Promise<TransitStats> {
+    const agent = await this.requireAgentForUser(userId);
+    const rows = await this.assignmentsRepository.findByTransitAgent(agent.id);
+    const bookingIds = [...new Set(rows.map((r) => r.bookingId))];
+
+    const [ownDocs, bookingDocs, milestones, schedules] = await Promise.all([
+      rows.length
+        ? this.filesService.findByResourceIdsGrouped(
+            rows.map((r) => r.id),
+            TRANSIT_ASSIGNMENT_FILE_RESOURCE,
+          )
+        : new Map<string, FileRecord[]>(),
+      bookingIds.length
+        ? this.filesService.findByResourceIdsGrouped(bookingIds, "bookings")
+        : new Map<string, FileRecord[]>(),
+      bookingIds.length
+        ? this.milestonesRepository.find({
+            where: { bookingId: In(bookingIds) },
+            select: ["bookingId", "milestoneCode", "status", "triggeredAt"],
+          })
+        : [],
+      (() => {
+        const ids = [
+          ...new Set(
+            rows
+              .map((r) => r.booking?.trainScheduleId)
+              .filter((id): id is string => Boolean(id)),
+          ),
+        ];
+        return ids.length
+          ? this.trainSchedulesRepository.find({
+              where: { id: In(ids) },
+              select: [
+                "id",
+                "trainNumber",
+                "voyageNumber",
+                "actualDepartureAt",
+                "actualArrivalAt",
+              ],
+            })
+          : [];
+      })(),
+    ]);
+
+    const scheduleById = new Map(schedules.map((sch) => [sch.id, sch]));
+    const milestonesByBooking = new Map<string, ClearanceMilestone[]>();
+    for (const m of milestones) {
+      if (!m.bookingId) continue;
+      const bucket = milestonesByBooking.get(m.bookingId);
+      if (bucket) bucket.push(m);
+      else milestonesByBooking.set(m.bookingId, [m]);
+    }
+
+    const iso = (d?: Date | string | null): string | null =>
+      d ? new Date(d).toISOString() : null;
+    const minutes = (from?: string | null, to?: string | null): number | null =>
+      from && to
+        ? Math.floor((new Date(to).getTime() - new Date(from).getTime()) / 60_000)
+        : null;
+    /** Latest upload stamp among files matching a code family. */
+    const latest = (
+      files: FileRecord[],
+      matches: (code: string | null | undefined) => boolean,
+    ): { at: string | null; count: number } => {
+      const hits = files.filter((f) => matches(f.code));
+      return {
+        count: hits.length,
+        at: hits.reduce<string | null>((max, f) => {
+          const stamp = iso(f.createdAt);
+          return stamp && (!max || stamp > max) ? stamp : max;
+        }, null),
+      };
+    };
+    /** Earliest upload stamp — for append-only sets the FIRST document matters. */
+    const earliest = (
+      files: FileRecord[],
+      matches: (code: string | null | undefined) => boolean,
+    ): { at: string | null; count: number } => {
+      const hits = files.filter((f) => matches(f.code));
+      return {
+        count: hits.length,
+        at: hits.reduce<string | null>((min, f) => {
+          const stamp = iso(f.createdAt);
+          return stamp && (!min || stamp < min) ? stamp : min;
+        }, null),
+      };
+    };
+
+    const items: TransitStatItem[] = rows.map((row) => {
+      const booking = row.booking;
+      const tradeDirection: TransitTradeDirection =
+        booking?.tradeDirection === "EXPORT" ? "EXPORT" : "IMPORT";
+      const schedule = booking?.trainScheduleId
+        ? scheduleById.get(booking.trainScheduleId)
+        : undefined;
+
+      // Same rule as the clearance view's train state: the booking's own
+      // load/unload stamps first, the schedule's actuals only as a fallback for
+      // legacy bookings that predate per-booking loading.
+      const departedAt = iso(booking?.loadedAt ?? schedule?.actualDepartureAt);
+      const arrivedAt = iso(
+        booking?.arrivedAt ??
+          (booking?.loadedAt ? null : schedule?.actualArrivalAt),
+      );
+
+      const files = bookingDocs.get(row.bookingId) ?? [];
+      const ms = milestonesByBooking.get(row.bookingId) ?? [];
+      const milestone = (code: string) => ms.find((m) => m.milestoneCode === code);
+      const done = (code: string) => {
+        const m = milestone(code);
+        return m?.status === "COMPLETED" || m?.status === "SKIPPED";
+      };
+
+      const declared = done("DECLARED");
+      const declaredAt = iso(milestone("DECLARED")?.triggeredAt);
+      const ro = latest(files, isReleaseOrderFileCode);
+      const deliveryOrder = latest(files, isDeliveryOrderFileCode);
+      const t1 = latest(files, isT1TransportFileCode);
+      const gatePass = earliest(files, isGatePassFileCode);
+      const djiboutiT1 = earliest(files, isDjiboutiT1FileCode);
+      const t1Closed = milestone("T1_CLOSED")?.status === "COMPLETED";
+      const bookingCreatedAt = iso(booking?.createdAt);
+      const finishedAt = iso(row.finishedAt);
+      const finished = row.status === TransitAssignmentStatus.Finished;
+
+      const timings: TransitStatItem["timings"] = {
+        transit: minutes(departedAt, arrivedAt),
+        declarationToRo: tradeDirection === "EXPORT" ? minutes(declaredAt, ro.at) : null,
+        bookingToDo:
+          tradeDirection === "IMPORT" ? minutes(bookingCreatedAt, deliveryOrder.at) : null,
+        departureToT1: tradeDirection === "IMPORT" ? minutes(departedAt, t1.at) : null,
+        arrivalToT1: tradeDirection === "IMPORT" ? minutes(arrivedAt, t1.at) : null,
+        arrivalToGatePass:
+          tradeDirection === "EXPORT" ? minutes(arrivedAt, gatePass.at) : null,
+        arrivalToDjiboutiT1:
+          tradeDirection === "EXPORT" ? minutes(arrivedAt, djiboutiT1.at) : null,
+        arrivalToFinish: minutes(arrivedAt, finishedAt),
+      };
+
+      // What the officer should do next on this shipment — the same gates the
+      // detail page enforces, so the dashboard never points at a locked button.
+      let nextAction: TransitNextAction;
+      if (finished) {
+        nextAction = { kind: "done", label: "Assignment finished" };
+      } else if (tradeDirection === "EXPORT") {
+        if (!declared) {
+          nextAction = { kind: "wait", label: "Awaiting customs declaration" };
+        } else if (ro.count === 0) {
+          nextAction = { kind: "upload", label: "Upload Release Order", document: "ro" };
+        } else if (!departedAt) {
+          nextAction = { kind: "wait", label: "Awaiting train departure" };
+        } else if (!arrivedAt) {
+          nextAction = { kind: "wait", label: "Train in transit" };
+        } else if (gatePass.count === 0) {
+          nextAction = { kind: "upload", label: "Upload gate pass", document: "gate_pass" };
+        } else if (djiboutiT1.count === 0) {
+          nextAction = {
+            kind: "upload",
+            label: "Upload Djibouti T1",
+            document: "djibouti_t1",
+          };
+        } else {
+          nextAction = { kind: "done", label: "Paperwork complete" };
+        }
+      } else if (deliveryOrder.count === 0) {
+        nextAction = { kind: "upload", label: "Upload Delivery Order", document: "do" };
+      } else if (!departedAt) {
+        nextAction = { kind: "wait", label: "Awaiting train departure" };
+      } else if (t1.count === 0 && !t1Closed) {
+        nextAction = { kind: "upload", label: "Upload T1 documents", document: "t1" };
+      } else if (!arrivedAt) {
+        nextAction = { kind: "wait", label: "Train in transit" };
+      } else {
+        nextAction = { kind: "done", label: t1Closed ? "T1 closed" : "Paperwork complete" };
+      }
+
+      return {
+        id: row.id,
+        bookingId: row.bookingId,
+        reference: booking?.reference ?? null,
+        customerName: booking?.company?.name ?? null,
+        tradeDirection,
+        status: row.status,
+        schedulingStatus: booking?.schedulingStatus ?? null,
+        trainLabel: schedule?.voyageNumber ?? schedule?.trainNumber ?? null,
+        assignedAt: iso(row.assignedAt) ?? new Date(0).toISOString(),
+        startedAt: iso(row.startedAt),
+        finishedAt,
+        bookingCreatedAt,
+        departedAt,
+        arrivedAt,
+        declaredAt,
+        roAt: ro.at,
+        doAt: deliveryOrder.at,
+        t1At: t1.at,
+        t1Closed,
+        gatePassAt: gatePass.at,
+        djiboutiT1At: djiboutiT1.at,
+        documents: {
+          ro: ro.count,
+          do: deliveryOrder.count,
+          t1: t1.count,
+          gatePass: gatePass.count,
+          djiboutiT1: djiboutiT1.count,
+          own: (ownDocs.get(row.id) ?? []).length,
+        },
+        timings,
+        nextAction,
+      };
+    });
+
+    // Most recently moving shipment first: arrival, else departure, else when
+    // it was handed to the agent.
+    const activity = (i: TransitStatItem) =>
+      i.arrivedAt ?? i.departedAt ?? i.assignedAt;
+    items.sort((a, b) => activity(b).localeCompare(activity(a)));
+
+    const summarize = (values: Array<number | null>): TransitTimingSummary => {
+      const measured = values.filter((v): v is number => v !== null && v >= 0);
+      if (!measured.length) {
+        return { median: null, fastest: null, slowest: null, measured: 0 };
+      }
+      const sorted = [...measured].sort((a, b) => a - b);
+      const mid = Math.floor(sorted.length / 2);
+      return {
+        median:
+          sorted.length % 2
+            ? sorted[mid]
+            : Math.round((sorted[mid - 1] + sorted[mid]) / 2),
+        fastest: sorted[0],
+        slowest: sorted[sorted.length - 1],
+        measured: sorted.length,
+      };
+    };
+    const timing = (key: keyof TransitStatItem["timings"]) =>
+      summarize(items.map((i) => i.timings[key]));
+
+    const open = items.filter((i) => i.status !== TransitAssignmentStatus.Finished);
+    const pendingFor = (document: TransitDocumentKind) =>
+      items.filter(
+        (i) => i.nextAction.kind === "upload" && i.nextAction.document === document,
+      ).length;
+    const sumDocs = (key: keyof TransitStatItem["documents"]) =>
+      items.reduce((sum, i) => sum + i.documents[key], 0);
+
+    return {
+      totals: {
+        assignments: items.length,
+        open: open.length,
+        notStarted: items.filter((i) => i.status === TransitAssignmentStatus.NotStarted)
+          .length,
+        inProgress: items.filter((i) => i.status === TransitAssignmentStatus.InProgress)
+          .length,
+        finished: items.length - open.length,
+        imports: items.filter((i) => i.tradeDirection === "IMPORT").length,
+        exports: items.filter((i) => i.tradeDirection === "EXPORT").length,
+        awaitingDeparture: open.filter((i) => !i.departedAt).length,
+        inTransit: open.filter((i) => i.departedAt && !i.arrivedAt).length,
+        arrived: open.filter((i) => Boolean(i.arrivedAt)).length,
+        actionNeeded: items.filter((i) => i.nextAction.kind === "upload").length,
+      },
+      timings: {
+        transit: timing("transit"),
+        declarationToRo: timing("declarationToRo"),
+        bookingToDo: timing("bookingToDo"),
+        departureToT1: timing("departureToT1"),
+        arrivalToT1: timing("arrivalToT1"),
+        arrivalToGatePass: timing("arrivalToGatePass"),
+        arrivalToDjiboutiT1: timing("arrivalToDjiboutiT1"),
+        arrivalToFinish: timing("arrivalToFinish"),
+      },
+      documents: {
+        ro: sumDocs("ro"),
+        do: sumDocs("do"),
+        t1: sumDocs("t1"),
+        gatePass: sumDocs("gatePass"),
+        djiboutiT1: sumDocs("djiboutiT1"),
+        own: sumDocs("own"),
+      },
+      pending: {
+        ro: pendingFor("ro"),
+        do: pendingFor("do"),
+        t1: pendingFor("t1"),
+        gatePass: pendingFor("gate_pass"),
+        djiboutiT1: pendingFor("djibouti_t1"),
+      },
+      items: items.slice(0, 20),
+    };
+  }
+
+  async findMine(userId: string, query: MyAssignmentsQueryDto = {}) {
+    const agent = await this.requireAgentForUser(userId);
+    const page = query.page ?? 1;
+    const pageSize = query.pageSize ?? 20;
+
+    const [rows, total] =
+      await this.assignmentsRepository.findByTransitAgentPaginated(
+        agent.id,
+        {
+          status: query.status,
+          schedulingStatus: query.schedulingStatus,
+          search: query.search,
+        },
+        (page - 1) * pageSize,
+        pageSize,
+      );
+
+    // Documents come back with the list so the grid can show a per-row count.
+    // Batched deliberately: one lookup for the page, not one per assignment.
+    const grouped = rows.length
+      ? await this.filesService.findByResourceIdsGrouped(
+          rows.map((row) => row.id),
+          TRANSIT_ASSIGNMENT_FILE_RESOURCE,
+        )
+      : new Map();
+
+    return {
+      items: rows.map((row) => ({
+        ...this.toView(row),
+        files: (grouped.get(row.id) ?? []).map((record: FileRecord) => ({
+          id: record.id,
+          name: record.name,
+          title: record.title,
+          url: record.url,
+          size: record.size,
+          mimeType: record.mimeType,
+          uploadedAt: record.createdAt.toISOString(),
+          updatedAt: record.updatedAt.toISOString(),
+          uploadedByUserId: record.uploadedByUserId,
+          uploadedByName: record.uploadedByName,
+        })),
+      })),
+      meta: {
+        total,
+        page,
+        pageSize,
+        totalPages: Math.max(1, Math.ceil(total / pageSize)),
+      },
+    };
+  }
+
+  /**
+   * One of the signed-in agent's own assignments, with its documents.
+   * Ownership is asserted rather than filtered: a mismatch is hidden behind a
+   * NotFound so assignment ids cannot be probed.
+   */
+  async findMineById(
+    userId: string,
+    id: string,
+  ): Promise<TransitAssignmentView> {
+    const agent = await this.requireAgentForUser(userId);
+    const assignment =
+      await this.assignmentsRepository.findOneWithRelations(id);
+    if (!assignment || assignment.transitAgentId !== agent.id) {
+      throw new NotFoundException(`Transit assignment ${id} not found`);
+    }
+    return { ...this.toView(assignment), files: await this.listFiles(id) };
+  }
+
+  /** Assert the assignment is this user's before any write reaches it. */
+  private async assertMine(userId: string, id: string): Promise<void> {
+    await this.findMineById(userId, id);
+  }
+
+  async uploadMyFiles(
+    userId: string,
+    id: string,
+    files: Express.Multer.File[],
+    uploader: { userId?: string; name?: string },
+    titles?: string[],
+  ): Promise<TransitAssignmentFileView[]> {
+    await this.assertMine(userId, id);
+    return this.uploadFiles(id, files, uploader, titles);
+  }
+
+  async removeMyFile(
+    userId: string,
+    id: string,
+    fileId: string,
+  ): Promise<void> {
+    await this.assertMine(userId, id);
+    return this.removeFile(id, fileId);
+  }
+
+  /**
+   * The portal's Save / Finish action.
+   *
+   * Save keeps the assignment open (moving it to IN_PROGRESS so the work reads
+   * as under way); Finish closes it, which also locks its documents — see
+   * `assertUploadAllowed`.
+   */
+  async submitMine(
+    userId: string,
+    id: string,
+    input: { finish: boolean; note?: string },
+  ): Promise<TransitAssignmentView> {
+    const current = await this.findMineById(userId, id);
+    if (current.status === TransitAssignmentStatus.Finished) {
+      throw new ForbiddenException("This assignment is already finished.");
+    }
+    await this.update(id, {
+      status: input.finish
+        ? TransitAssignmentStatus.Finished
+        : TransitAssignmentStatus.InProgress,
+      note: input.note,
+    });
+    return this.findMineById(userId, id);
+  }
+
+  /**
+   * Make `transitAgentId` the officer working `bookingId`, as the clearance
+   * desk's "assign transit assignee" step means it.
+   *
+   * The booking itself only records the officer's NAME, which is all the
+   * clearance UI needs; the officer's own portal reads `transit_assignments`.
+   * This keeps the two in step, and is deliberately forgiving where `create()`
+   * is strict:
+   *  - assigning the same agent twice is a no-op, not a 409 — the desk may
+   *    re-save the step without meaning to start over;
+   *  - a REASSIGNMENT retires the previous officer's row, so a shipment does
+   *    not sit in the work list of someone who no longer handles it. Finished
+   *    rows stay, since they are that officer's record of work already done.
+   */
+  async ensureAssignment(
+    bookingId: string,
+    transitAgentId: string,
+    assignedByUserId?: string,
+  ): Promise<void> {
+    const existing =
+      await this.assignmentsRepository.findByBooking(bookingId);
+
+    for (const row of existing) {
+      if (
+        row.transitAgentId !== transitAgentId &&
+        row.status !== TransitAssignmentStatus.Finished
+      ) {
+        await this.assignmentsRepository.softDelete(row.id);
+      }
+    }
+
+    if (existing.some((row) => row.transitAgentId === transitAgentId)) return;
+
+    await this.assignmentsRepository.create({
+      bookingId,
+      transitAgentId,
+      status: TransitAssignmentStatus.NotStarted,
+      startedAt: null,
+      finishedAt: null,
+      assignedByUserId: assignedByUserId ?? null,
+      note: null,
+    });
+  }
+
+  async create(
+    dto: CreateTransitAssignmentDto,
+    assignedByUserId?: string,
+  ): Promise<TransitAssignmentView> {
+    const booking = await this.bookingsRepository.findOne({
+      where: { id: dto.bookingId },
+      select: { id: true },
+    });
+    if (!booking) {
+      throw new NotFoundException(`Booking ${dto.bookingId} not found`);
+    }
+    const agent = await this.transitAgentsRepository.findById(
+      dto.transitAgentId,
+    );
+    if (!agent) {
+      throw new NotFoundException(
+        `Transit agent ${dto.transitAgentId} not found`,
+      );
+    }
+    if (
+      await this.assignmentsRepository.existsForPair(
+        dto.bookingId,
+        dto.transitAgentId,
+      )
+    ) {
+      throw new ConflictException(
+        `${agent.name} is already assigned to this booking`,
+      );
+    }
+
+    const status = dto.status ?? TransitAssignmentStatus.NotStarted;
+    const created = await this.assignmentsRepository.create({
+      bookingId: dto.bookingId,
+      transitAgentId: dto.transitAgentId,
+      status,
+      // Creating straight into a working state still has to stamp its clock, or
+      // the assignment would report no start.
+      startedAt:
+        status === TransitAssignmentStatus.NotStarted ? null : new Date(),
+      finishedAt:
+        status === TransitAssignmentStatus.Finished ? new Date() : null,
+      assignedByUserId: assignedByUserId ?? null,
+      note: dto.note?.trim() || null,
+    });
+
+    return this.findById(created.id);
+  }
+
+  async update(
+    id: string,
+    dto: UpdateTransitAssignmentDto,
+  ): Promise<TransitAssignmentView> {
+    const current = await this.assignmentsRepository.findOneWithRelations(id);
+    if (!current) {
+      throw new NotFoundException(`Transit assignment ${id} not found`);
+    }
+
+    const patch: Partial<TransitAssignment> = {};
+    if (dto.note !== undefined) patch.note = dto.note.trim() || null;
+
+    if (dto.status && dto.status !== current.status) {
+      patch.status = dto.status;
+      if (dto.status === TransitAssignmentStatus.InProgress) {
+        // Only the FIRST start is recorded — reopening finished work keeps the
+        // original start, so the elapsed time still spans the whole job.
+        patch.startedAt = current.startedAt ?? new Date();
+        patch.finishedAt = null;
+      } else if (dto.status === TransitAssignmentStatus.Finished) {
+        patch.startedAt = current.startedAt ?? new Date();
+        patch.finishedAt = new Date();
+      } else {
+        // Back to NOT_STARTED — the work is being reset, so both clocks clear
+        // rather than leaving a duration for work that no longer happened.
+        patch.startedAt = null;
+        patch.finishedAt = null;
+      }
+    }
+
+    const updated = await this.assignmentsRepository.update(id, patch);
+    if (!updated) {
+      throw new NotFoundException(`Transit assignment ${id} not found`);
+    }
+    return this.findById(id);
+  }
+
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.assignmentsRepository.softDelete(id);
+  }
+
+  // ── Documents ─────────────────────────────────────────────────────────────
+  // Stored in `freight.files` under TRANSIT_ASSIGNMENT_FILE_RESOURCE rather
+  // than a table of their own: that one already carries the MinIO object, the
+  // upload time, the uploader and the supersede history.
+
+  /**
+   * Whether an assignment may still receive documents.
+   *
+   * Two gates, both business rules rather than UI conveniences:
+   *  - the booking must actually be on its way (`DISPATCHED`), since there is
+   *    nothing to clear before the train leaves;
+   *  - the assignment must not be FINISHED — filing closes with the work, so a
+   *    finished record cannot grow new paperwork afterwards.
+   */
+  private assertUploadAllowed(assignment: TransitAssignment): void {
+    if (assignment.status === TransitAssignmentStatus.Finished) {
+      throw new ForbiddenException(
+        "This assignment is finished — its documents can no longer be changed.",
+      );
+    }
+    if (assignment.booking?.schedulingStatus !== "DISPATCHED") {
+      throw new ForbiddenException(
+        "Documents can only be uploaded once the booking has been dispatched.",
+      );
+    }
+  }
+
+  async listFiles(id: string): Promise<TransitAssignmentFileView[]> {
+    const records = await this.filesService.findByResource(
+      id,
+      TRANSIT_ASSIGNMENT_FILE_RESOURCE,
+    );
+    return records.map((record) => ({
+      id: record.id,
+      name: record.name,
+      title: record.title,
+      url: record.url,
+      size: record.size,
+      mimeType: record.mimeType,
+      uploadedAt: record.createdAt.toISOString(),
+      updatedAt: record.updatedAt.toISOString(),
+      uploadedByUserId: record.uploadedByUserId,
+      uploadedByName: record.uploadedByName,
+    }));
+  }
+
+  async uploadFiles(
+    id: string,
+    files: Express.Multer.File[],
+    uploader: { userId?: string; name?: string },
+    /**
+     * A display name per file, positionally matched to `files`. Multer preserves
+     * the multipart part order, and the client appends one `titles` entry per
+     * file in the same order, so index N names file N. A missing or blank entry
+     * falls back to the original filename.
+     */
+    titles?: string[],
+  ): Promise<TransitAssignmentFileView[]> {
+    if (!files?.length) {
+      throw new BadRequestException("No files were uploaded");
+    }
+    // Asserts the assignment exists before anything reaches MinIO — an upload
+    // keyed to a missing row would be unreachable storage nobody ever lists.
+    const assignment =
+      await this.assignmentsRepository.findOneWithRelations(id);
+    if (!assignment) {
+      throw new NotFoundException(`Transit assignment ${id} not found`);
+    }
+    this.assertUploadAllowed(assignment);
+
+    await Promise.all(
+      files.map((file, index) =>
+        this.filesService.upload({
+          resourceId: id,
+          resource: TRANSIT_ASSIGNMENT_FILE_RESOURCE,
+          code: file.fieldname || "document",
+          file,
+          title: titles?.[index]?.trim() || null,
+          uploadedByUserId: uploader.userId ?? null,
+          uploadedByName: uploader.name ?? null,
+        }),
+      ),
+    );
+
+    return this.listFiles(id);
+  }
+
+  async removeFile(id: string, fileId: string): Promise<void> {
+    const assignment =
+      await this.assignmentsRepository.findOneWithRelations(id);
+    if (!assignment) {
+      throw new NotFoundException(`Transit assignment ${id} not found`);
+    }
+    // Same gate as upload: a finished assignment's paperwork is fixed, and
+    // removal is as much a change as adding.
+    this.assertUploadAllowed(assignment);
+
+    const files = await this.filesService.findByResource(
+      id,
+      TRANSIT_ASSIGNMENT_FILE_RESOURCE,
+    );
+    // Scoped to this assignment's own documents: a bare file id would let one
+    // assignment delete another's paperwork.
+    if (!files.some((file) => file.id === fileId)) {
+      throw new NotFoundException(
+        `File ${fileId} not found on this assignment`,
+      );
+    }
+    await this.filesService.remove(fileId);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/wagon-history/dto/wagon-history-query.dto.ts b/apps/edr-freight-api/src/modules/wagon-history/dto/wagon-history-query.dto.ts
new file mode 100644
index 000000000..3ad9748d4
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/wagon-history/dto/wagon-history-query.dto.ts
@@ -0,0 +1,47 @@
+import { WagonEventCategory, WagonEventType } from '@edr/types';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Transform, Type } from 'class-transformer';
+import { IsArray, IsDateString, IsEnum, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+
+export class WagonHistoryQueryDto {
+  @ApiPropertyOptional({ enum: WagonEventCategory, description: 'Only events of this category' })
+  @IsOptional()
+  @IsEnum(WagonEventCategory)
+  category?: WagonEventCategory;
+
+  @ApiPropertyOptional({
+    enum: WagonEventType,
+    isArray: true,
+    description: 'Only these event types (repeat the param or comma-separate)',
+  })
+  @IsOptional()
+  @Transform(({ value }) =>
+    Array.isArray(value) ? value : String(value).split(',').map((v) => v.trim()).filter(Boolean),
+  )
+  @IsArray()
+  @IsEnum(WagonEventType, { each: true })
+  types?: WagonEventType[];
+
+  @ApiPropertyOptional({ description: 'ISO timestamp — events at or after this moment' })
+  @IsOptional()
+  @IsDateString()
+  from?: string;
+
+  @ApiPropertyOptional({ description: 'ISO timestamp — events at or before this moment' })
+  @IsOptional()
+  @IsDateString()
+  to?: string;
+
+  @ApiPropertyOptional({ description: 'Opaque `nextCursor` from the previous page' })
+  @IsOptional()
+  @IsString()
+  cursor?: string;
+
+  @ApiPropertyOptional({ default: 50, minimum: 1, maximum: 200 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  limit?: number;
+}
diff --git a/apps/edr-freight-api/src/modules/wagon-history/wagon-event.entity.ts b/apps/edr-freight-api/src/modules/wagon-history/wagon-event.entity.ts
new file mode 100644
index 000000000..c0dedf760
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/wagon-history/wagon-event.entity.ts
@@ -0,0 +1,74 @@
+import { WagonEventCategory, WagonEventType } from '@edr/types';
+import { Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn } from 'typeorm';
+
+/**
+ * Append-only history of everything that happens to a wagon — one row per
+ * wagon per transition, written inside the same transaction as the change.
+ * Plain id columns, no foreign keys and no soft delete on purpose: the history
+ * must outlive the wagon, train, schedule or booking it refers to, exactly like
+ * `audit_logs` and `schedule_wagon_adjustment_logs`. Rows are never updated.
+ *
+ * Read path: `(wagon_id, occurred_at DESC, id DESC)` keyset pagination — one
+ * index range scan per page regardless of how long the wagon has been in
+ * service. Labels (yard, train, schedule, booking, actor) are joined at read
+ * time on primary keys, so the write path stays a single INSERT.
+ */
+@Entity({ schema: 'freight', name: 'wagon_events' })
+@Index('idx_wagon_events_wagon_time', ['wagonId', 'occurredAt', 'id'])
+@Index('idx_wagon_events_wagon_cat_time', ['wagonId', 'category', 'occurredAt', 'id'])
+export class WagonEvent {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  @Column({ name: 'wagon_id', type: 'uuid' })
+  wagonId!: string;
+
+  /** Snapshot so the row still reads after the wagon is purged or renumbered. */
+  @Column({ name: 'wagon_number', type: 'varchar', nullable: true })
+  wagonNumber?: string | null;
+
+  @Column({ name: 'event_type', type: 'varchar', length: 40 })
+  type!: WagonEventType;
+
+  /** Derived from `type` at write time; stored so the category filter hits the index. */
+  @Column({ name: 'category', type: 'varchar', length: 20 })
+  category!: WagonEventCategory;
+
+  @Column({ name: 'occurred_at', type: 'timestamptz' })
+  occurredAt!: Date;
+
+  @Column({ name: 'actor_user_id', type: 'uuid', nullable: true })
+  actorUserId?: string | null;
+
+  @Column({ name: 'from_yard_id', type: 'uuid', nullable: true })
+  fromYardId?: string | null;
+
+  @Column({ name: 'to_yard_id', type: 'uuid', nullable: true })
+  toYardId?: string | null;
+
+  @Column({ name: 'train_id', type: 'uuid', nullable: true })
+  trainId?: string | null;
+
+  @Column({ name: 'train_schedule_id', type: 'uuid', nullable: true })
+  trainScheduleId?: string | null;
+
+  @Column({ name: 'booking_id', type: 'uuid', nullable: true })
+  bookingId?: string | null;
+
+  /** Previous value of whatever the event changed (status, sequence, train code…). */
+  @Column({ name: 'from_value', type: 'varchar', length: 120, nullable: true })
+  fromValue?: string | null;
+
+  @Column({ name: 'to_value', type: 'varchar', length: 120, nullable: true })
+  toValue?: string | null;
+
+  /** Staff-entered reason / note, when the action carried one. */
+  @Column({ name: 'reason', type: 'text', nullable: true })
+  reason?: string | null;
+
+  @Column({ name: 'metadata', type: 'jsonb', nullable: true })
+  metadata?: Record<string, unknown> | null;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  createdAt!: Date;
+}
diff --git a/apps/edr-freight-api/src/modules/wagon-history/wagon-history.module.ts b/apps/edr-freight-api/src/modules/wagon-history/wagon-history.module.ts
new file mode 100644
index 000000000..d049578d3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/wagon-history/wagon-history.module.ts
@@ -0,0 +1,16 @@
+import { Global, Module } from '@nestjs/common';
+
+import { WagonHistoryService } from './wagon-history.service';
+
+/**
+ * Global, dependency-free (only the DataSource): every service that writes a
+ * wagon row — wagons desk, train builder, scheduling, booking journey,
+ * containers, cancellations — records history through WagonHistoryService
+ * without adding a module edge, the same pattern as FleetHistoryModule.
+ */
+@Global()
+@Module({
+  providers: [WagonHistoryService],
+  exports: [WagonHistoryService],
+})
+export class WagonHistoryModule {}
diff --git a/apps/edr-freight-api/src/modules/wagon-history/wagon-history.service.spec.ts b/apps/edr-freight-api/src/modules/wagon-history/wagon-history.service.spec.ts
new file mode 100644
index 000000000..0855d7c6a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/wagon-history/wagon-history.service.spec.ts
@@ -0,0 +1,135 @@
+import { BadRequestException } from '@nestjs/common';
+import { WagonEventCategory, WagonEventType } from '@edr/types';
+
+import { WagonHistoryService } from './wagon-history.service';
+
+/** Captures the INSERT query-builder chain and the raw list query. */
+function makeDataSource() {
+  const execute = jest.fn().mockResolvedValue(undefined);
+  const values = jest.fn();
+  const chain = { insert: jest.fn(), into: jest.fn(), values, updateEntity: jest.fn(), execute };
+  chain.insert.mockReturnValue(chain);
+  chain.into.mockReturnValue(chain);
+  values.mockReturnValue(chain);
+  chain.updateEntity.mockReturnValue(chain);
+  const manager = { createQueryBuilder: jest.fn(() => chain) };
+  const query = jest.fn().mockResolvedValue([]);
+  return { dataSource: { manager, query }, manager, values, execute, query };
+}
+
+describe('WagonHistoryService.record', () => {
+  it('writes a batch as one INSERT, deriving the category from the type', async () => {
+    const { dataSource, values, execute } = makeDataSource();
+    const service = new WagonHistoryService(dataSource as never);
+    const at = new Date('2026-09-01T10:00:00Z');
+
+    await service.record(dataSource.manager as never, [
+      { wagonId: 'w1', wagonNumber: 'W-1', type: WagonEventType.MovedManually, toYardId: 'y2', occurredAt: at },
+      { wagonId: 'w2', type: WagonEventType.CargoLoaded, bookingId: 'b1', toValue: 12.5 },
+      null,
+    ]);
+
+    expect(execute).toHaveBeenCalledTimes(1);
+    const rows = values.mock.calls[0][0];
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toMatchObject({
+      wagonId: 'w1',
+      wagonNumber: 'W-1',
+      type: WagonEventType.MovedManually,
+      category: WagonEventCategory.Yard,
+      toYardId: 'y2',
+      occurredAt: at,
+      actorUserId: null,
+    });
+    expect(rows[1]).toMatchObject({
+      wagonId: 'w2',
+      category: WagonEventCategory.Cargo,
+      bookingId: 'b1',
+      toValue: '12.5',
+    });
+    expect(rows[1].occurredAt).toBeInstanceOf(Date);
+  });
+
+  it('skips empty input without touching the database', async () => {
+    const { dataSource, execute } = makeDataSource();
+    const service = new WagonHistoryService(dataSource as never);
+    await service.record(dataSource.manager as never, []);
+    await service.record(null, null);
+    expect(execute).not.toHaveBeenCalled();
+  });
+
+  it('propagates a failure inside a caller transaction but swallows it outside one', async () => {
+    const { dataSource, execute } = makeDataSource();
+    execute.mockRejectedValue(new Error('db down'));
+    const service = new WagonHistoryService(dataSource as never);
+    const input = { wagonId: 'w1', type: WagonEventType.Registered };
+
+    await expect(service.record(dataSource.manager as never, input)).rejects.toThrow('db down');
+    await expect(service.record(null, input)).resolves.toBeUndefined();
+  });
+});
+
+describe('WagonHistoryService.list', () => {
+  const A = '11111111-1111-4111-8111-111111111111';
+  const B = '22222222-2222-4222-8222-222222222222';
+  const C = '33333333-3333-4333-8333-333333333333';
+  const row = (id: string, at: string) => ({
+    id,
+    wagonId: 'w1',
+    wagonNumber: 'W-1',
+    type: WagonEventType.PassedCheckpoint,
+    category: WagonEventCategory.Yard,
+    occurredAt: new Date(at),
+    actorUserId: null,
+    actorName: null,
+    fromYardId: 'y1',
+    fromYardLabel: 'Origin',
+    toYardId: 'y2',
+    toYardLabel: 'Stop',
+    trainId: null,
+    trainCode: null,
+    trainScheduleId: 's1',
+    scheduleLabel: 'V-100',
+    bookingId: null,
+    bookingReference: null,
+    fromValue: null,
+    toValue: null,
+    reason: null,
+    metadata: null,
+  });
+
+  it('returns a page with a cursor when more rows exist, and decodes that cursor on the next call', async () => {
+    const { dataSource, query } = makeDataSource();
+    const service = new WagonHistoryService(dataSource as never);
+    query.mockResolvedValueOnce([
+      row(A, '2026-09-01T10:00:00Z'),
+      row(B, '2026-09-01T09:00:00Z'),
+      row(C, '2026-09-01T08:00:00Z'), // the +1 probe row
+    ]);
+
+    const first = await service.list('w1', { limit: 2, category: WagonEventCategory.Yard });
+    expect(first.items.map((i) => i.id)).toEqual([A, B]);
+    expect(first.items[0].occurredAt).toBe('2026-09-01T10:00:00.000Z');
+    expect(first.nextCursor).toEqual(expect.any(String));
+    const [sql, params] = query.mock.calls[0];
+    expect(sql).toContain('e.wagon_id = $1');
+    expect(sql).toContain('e.category = $2');
+    expect(sql).toContain('LIMIT 3');
+    expect(params).toEqual(['w1', WagonEventCategory.Yard]);
+
+    query.mockResolvedValueOnce([row(C, '2026-09-01T08:00:00Z')]);
+    const second = await service.list('w1', { limit: 2, cursor: first.nextCursor! });
+    expect(second.items.map((i) => i.id)).toEqual([C]);
+    expect(second.nextCursor).toBeNull();
+    const [sql2, params2] = query.mock.calls[1];
+    expect(sql2).toContain('(e.occurred_at, e.id) < ($2, $3::uuid)');
+    expect(params2[1]).toEqual(new Date('2026-09-01T09:00:00Z'));
+    expect(params2[2]).toBe(B);
+  });
+
+  it('rejects a malformed cursor', async () => {
+    const { dataSource } = makeDataSource();
+    const service = new WagonHistoryService(dataSource as never);
+    await expect(service.list('w1', { cursor: 'not-a-cursor' })).rejects.toThrow(BadRequestException);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/wagon-history/wagon-history.service.ts b/apps/edr-freight-api/src/modules/wagon-history/wagon-history.service.ts
new file mode 100644
index 000000000..982e927ce
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/wagon-history/wagon-history.service.ts
@@ -0,0 +1,195 @@
+import {
+  WAGON_EVENT_CATEGORY,
+  WagonEventCategory,
+  WagonEventType,
+  WagonHistoryEvent,
+  WagonHistoryPage,
+} from '@edr/types';
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { DataSource, EntityManager } from 'typeorm';
+import { QueryDeepPartialEntity } from 'typeorm/query-builder/QueryPartialEntity';
+
+import { WagonHistoryQueryDto } from './dto/wagon-history-query.dto';
+import { WagonEvent } from './wagon-event.entity';
+
+/** One transition to append. Everything but the wagon and the type is optional context. */
+export interface WagonEventInput {
+  wagonId: string;
+  /** Snapshot for the row; pass it when the caller already holds the wagon (no lookup is made). */
+  wagonNumber?: string | null;
+  type: WagonEventType;
+  /** Defaults to now. Pass the business timestamp when the caller has one. */
+  occurredAt?: Date | null;
+  actorUserId?: string | null;
+  fromYardId?: string | null;
+  toYardId?: string | null;
+  trainId?: string | null;
+  trainScheduleId?: string | null;
+  bookingId?: string | null;
+  fromValue?: string | number | null;
+  toValue?: string | number | null;
+  reason?: string | null;
+  metadata?: Record<string, unknown> | null;
+}
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+
+/**
+ * The single write and read path for `freight.wagon_events`.
+ *
+ * Writes: {@link record} takes the caller's EntityManager so the history row
+ * commits (or rolls back) with the business change — a wagon can never end up
+ * moved without its history row or vice versa. A batch is one INSERT.
+ *
+ * Reads: {@link list} is keyset-paginated on `(occurred_at, id)` under the
+ * per-wagon index, so page N costs the same as page 1; labels come from
+ * primary-key LEFT JOINs on the page only.
+ */
+@Injectable()
+export class WagonHistoryService {
+  private readonly logger = new Logger(WagonHistoryService.name);
+
+  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
+
+  /**
+   * Append one or more events. Inside a transaction (manager given) a failure
+   * propagates — Postgres has already aborted the transaction at that point,
+   * so swallowing it would only hide the rollback. Outside a transaction the
+   * write is best-effort: logged, never thrown, so history can't break the
+   * operation that produced it.
+   */
+  async record(
+    manager: EntityManager | null | undefined,
+    input: WagonEventInput | null | Array<WagonEventInput | null>,
+  ): Promise<void> {
+    const inputs = (Array.isArray(input) ? input : [input]).filter(
+      (i): i is WagonEventInput => Boolean(i?.wagonId),
+    );
+    if (!inputs.length) return;
+    const now = new Date();
+    const rows = inputs.map((i) => ({
+      wagonId: i.wagonId,
+      wagonNumber: i.wagonNumber ?? null,
+      type: i.type,
+      category: WAGON_EVENT_CATEGORY[i.type] ?? WagonEventCategory.Lifecycle,
+      occurredAt: i.occurredAt ?? now,
+      actorUserId: i.actorUserId ?? null,
+      fromYardId: i.fromYardId ?? null,
+      toYardId: i.toYardId ?? null,
+      trainId: i.trainId ?? null,
+      trainScheduleId: i.trainScheduleId ?? null,
+      bookingId: i.bookingId ?? null,
+      fromValue: i.fromValue == null ? null : String(i.fromValue).slice(0, 120),
+      toValue: i.toValue == null ? null : String(i.toValue).slice(0, 120),
+      reason: i.reason?.trim() ? i.reason.trim() : null,
+      metadata: i.metadata ?? null,
+    }));
+    const mg = manager ?? this.dataSource.manager;
+    const write = () =>
+      mg
+        .createQueryBuilder()
+        .insert()
+        .into(WagonEvent)
+        .values(rows as unknown as QueryDeepPartialEntity<WagonEvent>[])
+        .updateEntity(false)
+        .execute();
+    if (manager) {
+      await write();
+      return;
+    }
+    try {
+      await write();
+    } catch (err) {
+      this.logger.error(
+        `Failed to record ${rows.length} wagon event(s) (${rows[0].type}): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+
+  /** One wagon's timeline, newest first, with labels resolved. */
+  async list(wagonId: string, query: WagonHistoryQueryDto = {}): Promise<WagonHistoryPage> {
+    const limit = Math.min(Math.max(query.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+    const params: unknown[] = [wagonId];
+    const where: string[] = ['e.wagon_id = $1'];
+    const push = (value: unknown) => {
+      params.push(value);
+      return `$${params.length}`;
+    };
+    if (query.category) where.push(`e.category = ${push(query.category)}`);
+    if (query.types?.length) where.push(`e.event_type = ANY(${push(query.types)}::text[])`);
+    if (query.from) where.push(`e.occurred_at >= ${push(new Date(query.from))}`);
+    if (query.to) where.push(`e.occurred_at <= ${push(new Date(query.to))}`);
+    const cursor = decodeCursor(query.cursor);
+    if (cursor) {
+      // Row-value comparison walks the (wagon_id, occurred_at DESC, id DESC) index directly.
+      where.push(`(e.occurred_at, e.id) < (${push(cursor.occurredAt)}, ${push(cursor.id)}::uuid)`);
+    }
+
+    const rows: Array<WagonHistoryEvent & { occurredAt: Date }> = await this.dataSource.query(
+      `SELECT e.id,
+              e.wagon_id            AS "wagonId",
+              e.wagon_number        AS "wagonNumber",
+              e.event_type          AS "type",
+              e.category,
+              e.occurred_at         AS "occurredAt",
+              e.actor_user_id       AS "actorUserId",
+              COALESCE(u.username, u.email) AS "actorName",
+              e.from_yard_id        AS "fromYardId",
+              fy.label              AS "fromYardLabel",
+              e.to_yard_id          AS "toYardId",
+              ty.label              AS "toYardLabel",
+              e.train_id            AS "trainId",
+              t.code                AS "trainCode",
+              e.train_schedule_id   AS "trainScheduleId",
+              COALESCE(s.voyage_number, s.train_number) AS "scheduleLabel",
+              e.booking_id          AS "bookingId",
+              b.reference           AS "bookingReference",
+              e.from_value          AS "fromValue",
+              e.to_value            AS "toValue",
+              e.reason,
+              e.metadata
+         FROM freight.wagon_events e
+         LEFT JOIN iam.users u              ON u.id = e.actor_user_id
+         LEFT JOIN freight.yards fy         ON fy.id = e.from_yard_id
+         LEFT JOIN freight.yards ty         ON ty.id = e.to_yard_id
+         LEFT JOIN freight.trains t         ON t.id = e.train_id
+         LEFT JOIN freight.train_schedules s ON s.id = e.train_schedule_id
+         LEFT JOIN freight.bookings b       ON b.id = e.booking_id
+        WHERE ${where.join(' AND ')}
+        ORDER BY e.occurred_at DESC, e.id DESC
+        LIMIT ${limit + 1}`,
+      params,
+    );
+
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const last = page[page.length - 1];
+    return {
+      items: page.map((r) => ({
+        ...r,
+        occurredAt: new Date(r.occurredAt).toISOString(),
+      })),
+      nextCursor: hasMore && last ? encodeCursor(new Date(last.occurredAt), last.id) : null,
+    };
+  }
+}
+
+function encodeCursor(occurredAt: Date, id: string): string {
+  return Buffer.from(`${occurredAt.toISOString()}|${id}`, 'utf8').toString('base64url');
+}
+
+function decodeCursor(cursor?: string): { occurredAt: Date; id: string } | null {
+  if (!cursor) return null;
+  const raw = Buffer.from(cursor, 'base64url').toString('utf8');
+  const sep = raw.indexOf('|');
+  const occurredAt = sep > 0 ? new Date(raw.slice(0, sep)) : new Date(NaN);
+  const id = sep > 0 ? raw.slice(sep + 1) : '';
+  if (Number.isNaN(occurredAt.getTime()) || !/^[0-9a-f-]{36}$/i.test(id)) {
+    throw new BadRequestException('Invalid history cursor');
+  }
+  return { occurredAt, id };
+}
diff --git a/apps/edr-freight-api/src/modules/wagons/purge-guard.spec.ts b/apps/edr-freight-api/src/modules/wagons/purge-guard.spec.ts
index ab86cea51..d86f65367 100644
--- a/apps/edr-freight-api/src/modules/wagons/purge-guard.spec.ts
+++ b/apps/edr-freight-api/src/modules/wagons/purge-guard.spec.ts
@@ -14,7 +14,12 @@ const makeService = (wagon: any, counts: [number, number, number], pinned = fals
       return [];
     }),
   };
-  const svc = new WagonsService(wagonRepo as any, {} as any, dataSource as any);
+  const svc = new WagonsService(
+    wagonRepo as any,
+    {} as any,
+    dataSource as any,
+    { record: jest.fn() } as any,
+  );
   return { svc, wagonRepo };
 };
 
@@ -54,7 +59,12 @@ describe('WagonsService.purge', () => {
 
   it('404s an unknown wagon', async () => {
     const wagonRepo = { findOne: jest.fn().mockResolvedValue(null), remove: jest.fn() };
-    const svc = new WagonsService(wagonRepo as any, {} as any, { query: jest.fn() } as any);
+    const svc = new WagonsService(
+      wagonRepo as any,
+      {} as any,
+      { query: jest.fn() } as any,
+      { record: jest.fn() } as any,
+    );
     await expect(svc.purge('nope')).rejects.toThrow(NotFoundException);
     expect(wagonRepo.remove).not.toHaveBeenCalled();
   });
diff --git a/apps/edr-freight-api/src/modules/wagons/wagons.controller.ts b/apps/edr-freight-api/src/modules/wagons/wagons.controller.ts
index e4492e5cb..89c2fd9f7 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagons.controller.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagons.controller.ts
@@ -27,6 +27,8 @@ import { AssignWagonToTrainDto } from './dto/assign-wagon-to-train.dto';
 import { BulkTransferWagonsDto } from './dto/bulk-transfer-wagons.dto';
 import { BulkSetWagonStatusDto } from './dto/bulk-set-wagon-status.dto';
 import { WagonsService } from './wagons.service';
+import { WagonHistoryQueryDto } from '../wagon-history/dto/wagon-history-query.dto';
+import { WagonHistoryService } from '../wagon-history/wagon-history.service';
 
 @ApiTags('wagons')
 // No class-level guard: reads (list, by-id, movements) are login-only reference
@@ -34,13 +36,16 @@ import { WagonsService } from './wagons.service';
 // fleet:view that drives the Fleet sidebar. Every mutation has its @FleetManage().
 @Controller('wagons')
 export class WagonsController {
-  constructor(private readonly wagonsService: WagonsService) {}
+  constructor(
+    private readonly wagonsService: WagonsService,
+    private readonly wagonHistory: WagonHistoryService,
+  ) {}
 
   @Post()
   @FleetManage(FREIGHT_PERMS.wagons.create)
   @ApiOperation({ summary: 'Create a new wagon' })
-  create(@Body() dto: CreateWagonDto) {
-    return this.wagonsService.create(dto);
+  create(@Body() dto: CreateWagonDto, @CurrentUser() user: TCurrentUser) {
+    return this.wagonsService.create(dto, user?.id);
   }
 
   @Get()
@@ -68,11 +73,26 @@ export class WagonsController {
     return this.wagonsService.listMovements(id);
   }
 
+  @Get(':id/history')
+  @FleetView(FREIGHT_PERMS.wagons.view)
+  @ApiOperation({
+    summary:
+      'Unified wagon history — yard moves, coupling, schedule pins/dispatch, status flips, cargo, lifecycle — newest first, keyset-paginated (`cursor`)',
+  })
+  history(@Param('id', ParseUUIDPipe) id: string, @Query() query: WagonHistoryQueryDto) {
+    // No existence check on purpose: a deleted or purged wagon keeps its history.
+    return this.wagonHistory.list(id, query);
+  }
+
   @Patch(':id')
   @FleetManage(FREIGHT_PERMS.wagons.update)
   @ApiOperation({ summary: 'Update a wagon' })
-  update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateWagonDto) {
-    return this.wagonsService.update(id, dto);
+  update(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: UpdateWagonDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.wagonsService.update(id, dto, user?.id);
   }
 
   // Declared before @Delete(':id') so "permanent" is never captured as an id.
@@ -86,29 +106,33 @@ export class WagonsController {
     summary:
       'Permanently delete a wagon (irreversible; refused if it has movements, containers or train-set slots)',
   })
-  purge(@Param('id', ParseUUIDPipe) id: string) {
-    return this.wagonsService.purge(id);
+  purge(@Param('id', ParseUUIDPipe) id: string, @CurrentUser() user: TCurrentUser) {
+    return this.wagonsService.purge(id, user?.id);
   }
 
   @Delete(':id')
   @FleetManage(FREIGHT_PERMS.wagons.delete)
   @ApiOperation({ summary: 'Delete a wagon' })
-  remove(@Param('id', ParseUUIDPipe) id: string) {
-    return this.wagonsService.remove(id);
+  remove(@Param('id', ParseUUIDPipe) id: string, @CurrentUser() user: TCurrentUser) {
+    return this.wagonsService.remove(id, user?.id);
   }
 
   @Post(':id/assign-train')
   @FleetManage(FREIGHT_PERMS.trains.assignWagons)
   @ApiOperation({ summary: 'Assign wagon to a train' })
-  assignToTrain(@Param('id', ParseUUIDPipe) id: string, @Body() dto: AssignWagonToTrainDto) {
-    return this.wagonsService.assignToTrain(id, dto);
+  assignToTrain(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: AssignWagonToTrainDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.wagonsService.assignToTrain(id, dto, user?.id);
   }
 
   @Post(':id/unassign-train')
   @FleetManage(FREIGHT_PERMS.trains.assignWagons)
   @ApiOperation({ summary: 'Unassign wagon from train' })
-  unassignFromTrain(@Param('id', ParseUUIDPipe) id: string) {
-    return this.wagonsService.unassignFromTrain(id);
+  unassignFromTrain(@Param('id', ParseUUIDPipe) id: string, @CurrentUser() user: TCurrentUser) {
+    return this.wagonsService.unassignFromTrain(id, user?.id);
   }
 
   @Post('bulk-transfer')
diff --git a/apps/edr-freight-api/src/modules/wagons/wagons.service.ts b/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
index 1ae1093f2..f15722b67 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
@@ -1,4 +1,10 @@
-import { Freight, PaginatedResponse, WagonMovementKind, WagonStatus } from '@edr/types';
+import {
+  Freight,
+  PaginatedResponse,
+  WagonEventType,
+  WagonMovementKind,
+  WagonStatus,
+} from '@edr/types';
 import {
   BadRequestException,
   Injectable,
@@ -19,6 +25,16 @@ import { WagonStatusLog } from './entities/wagon-status-log.entity';
 import { WagonMovement } from './entities/wagon-movement.entity';
 import { Train } from '../trains/entities/train.entity';
 import { Yard } from '../rule-engine/entities/yard.entity';
+import { WagonEventInput, WagonHistoryService } from '../wagon-history/wagon-history.service';
+
+/** Wagon columns whose manual edits are diffed into a DETAILS_UPDATED history row. */
+const TRACKED_DETAIL_FIELDS = [
+  'wagonNumber',
+  'wagonTypeId',
+  'exportTrainNumber',
+  'importTrainNumber',
+  'notes',
+] as const;
 
 @Injectable()
 export class WagonsService {
@@ -28,9 +44,10 @@ export class WagonsService {
     @InjectRepository(Train)
     private readonly trainRepo: Repository<Train>,
     private readonly dataSource: DataSource,
+    private readonly wagonHistory: WagonHistoryService,
   ) {}
 
-  async create(dto: CreateWagonDto): Promise<Wagon> {
+  async create(dto: CreateWagonDto, userId?: string | null): Promise<Wagon> {
     const wagon = this.wagonRepo.create({
       ...dto,
       status: dto.status ?? WagonStatus.Available,
@@ -41,7 +58,22 @@ export class WagonsService {
     if (dto.currentYardId === undefined) wagon.currentYardId = null;
     if (dto.exportTrainNumber === undefined) wagon.exportTrainNumber = null;
     if (dto.importTrainNumber === undefined) wagon.importTrainNumber = null;
-    return this.wagonRepo.save(wagon);
+    const saved = await this.wagonRepo.save(wagon);
+    await this.wagonHistory.record(null, {
+      wagonId: saved.id,
+      wagonNumber: saved.wagonNumber,
+      type: WagonEventType.Registered,
+      actorUserId: userId ?? null,
+      toYardId: saved.currentYardId ?? null,
+      trainId: saved.trainId ?? null,
+      toValue: saved.status,
+      metadata: {
+        wagonTypeId: saved.wagonTypeId,
+        exportTrainNumber: saved.exportTrainNumber ?? null,
+        importTrainNumber: saved.importTrainNumber ?? null,
+      },
+    });
+    return saved;
   }
 
   /** Shared filter/sort builder behind `findAll` (array) and `findAllPaged` (envelope). */
@@ -210,6 +242,10 @@ export class WagonsService {
       }
     }
     const previousYardId = wagon.currentYardId ?? null;
+    const previousStatus = wagon.status;
+    const before = Object.fromEntries(
+      TRACKED_DETAIL_FIELDS.map((f) => [f, (wagon as unknown as Record<string, unknown>)[f] ?? null]),
+    );
     Object.assign(wagon, dto);
     // `findById` eager-loads `currentYard`; when the DTO changes the scalar FK
     // TypeORM otherwise re-derives `current_yard_id` from the STALE relation
@@ -243,6 +279,47 @@ export class WagonsService {
         }),
       );
     }
+    // History: one row per kind of change — a yard move, a status flip, and
+    // the remaining field edits as a single diff.
+    const events: WagonEventInput[] = [];
+    const changes: Record<string, { from: unknown; to: unknown }> = {};
+    for (const f of TRACKED_DETAIL_FIELDS) {
+      if (dto[f] === undefined) continue;
+      const to = (wagon as unknown as Record<string, unknown>)[f] ?? null;
+      if (before[f] !== to) changes[f] = { from: before[f], to };
+    }
+    if (Object.keys(changes).length) {
+      events.push({
+        wagonId: id,
+        wagonNumber: wagon.wagonNumber,
+        type: WagonEventType.DetailsUpdated,
+        actorUserId: userId ?? null,
+        metadata: { changes },
+      });
+    }
+    if (dto.currentYardId !== undefined && dto.currentYardId !== previousYardId) {
+      events.push({
+        wagonId: id,
+        wagonNumber: wagon.wagonNumber,
+        type: WagonEventType.MovedManually,
+        actorUserId: userId ?? null,
+        fromYardId: previousYardId,
+        toYardId: dto.currentYardId ?? null,
+        reason: 'Wagon record edited',
+      });
+    }
+    if (dto.status !== undefined && dto.status !== previousStatus) {
+      events.push({
+        wagonId: id,
+        wagonNumber: wagon.wagonNumber,
+        type: WagonEventType.StatusChanged,
+        actorUserId: userId ?? null,
+        fromValue: previousStatus,
+        toValue: dto.status,
+        reason: 'Wagon record edited',
+      });
+    }
+    await this.wagonHistory.record(null, events);
     // Re-read with the relation so the response reflects the new yard label
     // instead of the stale relation object loaded before the assign.
     return this.findById(id);
@@ -258,7 +335,7 @@ export class WagonsService {
     });
   }
 
-  async remove(id: string): Promise<void> {
+  async remove(id: string, userId?: string | null): Promise<void> {
     const wagon = await this.findById(id);
     // A coupled wagon must be detached via train-builder before it can be
     // removed, so a built train never silently loses a wagon.
@@ -275,6 +352,14 @@ export class WagonsService {
     // Soft delete (deleted_at) — hard-deleting would strand ledger/schedule
     // history that references this wagon.
     await this.wagonRepo.softRemove(wagon);
+    await this.wagonHistory.record(null, {
+      wagonId: id,
+      wagonNumber: wagon.wagonNumber,
+      type: WagonEventType.Deleted,
+      actorUserId: userId ?? null,
+      fromYardId: wagon.currentYardId ?? null,
+      fromValue: wagon.status,
+    });
   }
 
   /**
@@ -288,7 +373,7 @@ export class WagonsService {
    *
    * Soft-deleted wagons are purgeable, so `withDeleted` is used to find them.
    */
-  async purge(id: string): Promise<void> {
+  async purge(id: string, userId?: string | null): Promise<void> {
     const wagon = await this.wagonRepo.findOne({
       where: { id },
       withDeleted: true,
@@ -343,6 +428,16 @@ export class WagonsService {
       );
     }
 
+    // Recorded BEFORE the row goes: wagon_events has no FK, so the history of
+    // a purged wagon survives under its id and number snapshot.
+    await this.wagonHistory.record(null, {
+      wagonId: id,
+      wagonNumber: wagon.wagonNumber,
+      type: WagonEventType.Purged,
+      actorUserId: userId ?? null,
+      fromYardId: wagon.currentYardId ?? null,
+      fromValue: wagon.status,
+    });
     await this.wagonRepo.remove(wagon);
   }
 
@@ -366,7 +461,11 @@ export class WagonsService {
     return rows.length > 0;
   }
 
-  async assignToTrain(wagonId: string, dto: AssignWagonToTrainDto): Promise<Wagon> {
+  async assignToTrain(
+    wagonId: string,
+    dto: AssignWagonToTrainDto,
+    userId?: string | null,
+  ): Promise<Wagon> {
     const wagon = await this.findById(wagonId);
     // Mirror train-builder attachWagons: only a truly free, available wagon
     // (any yard) can be coupled, and never onto a dispatched train.
@@ -399,13 +498,25 @@ export class WagonsService {
       );
     }
 
+    const previousStatus = wagon.status;
     wagon.trainId = train.id;
     wagon.sequenceNumber = nextSequence;
     wagon.status = WagonStatus.Assigned;
-    return this.wagonRepo.save(wagon);
+    const saved = await this.wagonRepo.save(wagon);
+    await this.wagonHistory.record(null, {
+      wagonId: wagon.id,
+      wagonNumber: wagon.wagonNumber,
+      type: WagonEventType.CoupledToTrain,
+      actorUserId: userId ?? null,
+      trainId: train.id,
+      fromYardId: wagon.currentYardId ?? null,
+      toValue: nextSequence,
+      metadata: { status: { from: previousStatus, to: WagonStatus.Assigned }, trainCode: train.code },
+    });
+    return saved;
   }
 
-  async unassignFromTrain(wagonId: string): Promise<Wagon> {
+  async unassignFromTrain(wagonId: string, userId?: string | null): Promise<Wagon> {
     const wagon = await this.findById(wagonId);
     // A wagon pinned to a live schedule is still operationally committed even
     // if the fleet train is being edited — don't free it out from under it.
@@ -414,10 +525,24 @@ export class WagonsService {
         `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be detached`,
       );
     }
+    const previousTrainId = wagon.trainId;
+    const previousSequence = wagon.sequenceNumber;
+    const previousStatus = wagon.status;
     wagon.trainId = null;
     wagon.sequenceNumber = null;
     wagon.status = WagonStatus.Available;
-    return this.wagonRepo.save(wagon);
+    const saved = await this.wagonRepo.save(wagon);
+    await this.wagonHistory.record(null, {
+      wagonId: wagon.id,
+      wagonNumber: wagon.wagonNumber,
+      type: WagonEventType.UncoupledFromTrain,
+      actorUserId: userId ?? null,
+      trainId: previousTrainId,
+      fromYardId: wagon.currentYardId ?? null,
+      fromValue: previousSequence,
+      metadata: { status: { from: previousStatus, to: WagonStatus.Available } },
+    });
+    return saved;
   }
 
   /**
@@ -464,9 +589,20 @@ export class WagonsService {
       }
 
       let moved = 0;
+      const events: WagonEventInput[] = [];
       for (const wagon of wagons) {
         const previousYardId = wagon.currentYardId ?? null;
         if (previousYardId === toYardId) continue;
+        events.push({
+          wagonId: wagon.id,
+          wagonNumber: wagon.wagonNumber,
+          type: WagonEventType.MovedManually,
+          actorUserId: userId ?? null,
+          fromYardId: previousYardId,
+          toYardId,
+          reason: opts?.transferRequestId ? 'Transfer request fulfilled' : 'Bulk transfer',
+          metadata: opts?.transferRequestId ? { transferRequestId: opts.transferRequestId } : null,
+        });
         wagon.currentYardId = toYardId;
         // Drop the eager relation so the scalar FK wins on save (see `update`).
         wagon.currentYard = null;
@@ -484,6 +620,7 @@ export class WagonsService {
         );
         moved++;
       }
+      await this.wagonHistory.record(queryRunner.manager, events);
 
       await queryRunner.commitTransaction();
       return { moved };
@@ -547,6 +684,18 @@ export class WagonsService {
       }
       await queryRunner.manager.save(Wagon, wagons);
       if (logs.length) await queryRunner.manager.save(WagonStatusLog, logs);
+      await this.wagonHistory.record(
+        queryRunner.manager,
+        logs.map((l) => ({
+          wagonId: l.wagonId,
+          wagonNumber: wagons.find((w) => w.id === l.wagonId)?.wagonNumber ?? null,
+          type: WagonEventType.StatusChanged,
+          actorUserId: changedByUserId ?? null,
+          fromValue: l.fromStatus,
+          toValue: l.toStatus,
+          reason: dto.note ?? null,
+        })),
+      );
 
       await queryRunner.commitTransaction();
       return { updated: wagons.length };
diff --git a/apps/edr-freight-api/src/modules/warehouses/dto/bulk-receive.dto.ts b/apps/edr-freight-api/src/modules/warehouses/dto/bulk-receive.dto.ts
index 8dd0681ce..85417ea87 100644
--- a/apps/edr-freight-api/src/modules/warehouses/dto/bulk-receive.dto.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/dto/bulk-receive.dto.ts
@@ -1,6 +1,19 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
-import { ArrayNotEmpty, IsArray, IsBoolean, IsIn, IsNumber, IsOptional, IsString, IsUUID, Min } from 'class-validator';
+import {
+  ArrayMaxSize,
+  ArrayNotEmpty,
+  ArrayUnique,
+  IsArray,
+  IsBoolean,
+  IsIn,
+  IsNumber,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Matches,
+  Min,
+} from 'class-validator';
 import { ValidateNested } from 'class-validator';
 
 export class TruckEntranceDto {
@@ -187,6 +200,22 @@ export class BulkReceiveDto {
   @IsUUID('all', { each: true })
   bookingIds!: string[];
 
+  /**
+   * The physical containers delivered by this truck. Container exports are
+   * received one truck at a time: either one 40ft box or up to two 20ft boxes.
+   */
+  @ApiPropertyOptional({ type: [String] })
+  @IsOptional()
+  @IsArray()
+  @ArrayNotEmpty()
+  @ArrayMaxSize(2)
+  @ArrayUnique()
+  @Matches(/^[A-Z]{4}\d{7}$/, {
+    each: true,
+    message: 'each container number must match ISO container format, e.g. ABCD1234567',
+  })
+  containerNumbers?: string[];
+
   @ApiPropertyOptional({ type: TruckEntranceDto })
   @IsOptional()
   @ValidateNested()
diff --git a/apps/edr-freight-api/src/modules/warehouses/train-loading-window-gate.spec.ts b/apps/edr-freight-api/src/modules/warehouses/train-loading-window-gate.spec.ts
new file mode 100644
index 000000000..fe9adb389
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/warehouses/train-loading-window-gate.spec.ts
@@ -0,0 +1,77 @@
+import { WarehouseInventoryService } from './warehouse-inventory.service';
+import type { TrainLoadableItemRow } from './warehouse-inventory.service';
+
+/**
+ * Cargo may only go onto a wagon inside a STARTED loading window at its
+ * boarding yard — the same rule the train schedule's own Load button enforces
+ * (assertStationWorkStarted). The warehouse loading queues load through a
+ * different service, so the rule is mirrored here; without it the two surfaces
+ * disagree and the queue offers a Load the schedule would refuse.
+ *
+ * Only the DataSource is touched, so the instance is built off the prototype
+ * rather than stubbing every collaborator.
+ */
+const row = (over: Partial<TrainLoadableItemRow> = {}): TrainLoadableItemRow =>
+  ({
+    id: 'inv-1',
+    bookingId: 'b-1',
+    bookingReference: 'BK-1',
+    customerName: 'Acme',
+    containerNumber: 'CN-1',
+    cargoType: 'General',
+    weight: 20,
+    grnNumber: 'GRN-1',
+    inspectionStatus: 'PASSED',
+    status: 'READY_FOR_LOADING',
+    wagonId: 'w-1',
+    wagonNumber: 'W-001',
+    sequenceNo: 1,
+    originYardId: 'yard-1',
+    originYardLabel: 'Modjo',
+    loadingWindowStarted: true,
+    loadable: true,
+    ...over,
+  }) as TrainLoadableItemRow;
+
+function makeService(items: TrainLoadableItemRow[]) {
+  const query = jest.fn().mockResolvedValue([
+    { trainNumber: 'T-100', origin: 'Modjo', destination: 'Djibouti', departure: null },
+  ]);
+  const load = jest.fn().mockResolvedValue(undefined);
+  const service = Object.create(WarehouseInventoryService.prototype) as Record<string, unknown>;
+  service.dataSource = { query };
+  service.load = load;
+  service.trainLoadableItems = jest.fn().mockResolvedValue(items);
+  return { service: service as unknown as WarehouseInventoryService, load };
+}
+
+describe('loadItemsOntoTrain() — station loading window gate', () => {
+  it('skips an item whose boarding yard has no started loading window', async () => {
+    const { service, load } = makeService([row({ loadingWindowStarted: false })]);
+
+    const result = await service.loadItemsOntoTrain('sched-1', ['inv-1']);
+
+    expect(load).not.toHaveBeenCalled();
+    expect(result.loadedCount).toBe(0);
+    expect(result.skippedCount).toBe(1);
+    expect(result.results[0].reason).toContain('Start loading at Modjo first');
+  });
+
+  it('loads once the window is started', async () => {
+    const { service, load } = makeService([row()]);
+
+    const result = await service.loadItemsOntoTrain('sched-1', ['inv-1']);
+
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(result.loadedCount).toBe(1);
+    expect(result.skippedCount).toBe(0);
+  });
+
+  it('still reports the wagon blocker first — the window is not the only gate', async () => {
+    const { service } = makeService([row({ wagonId: null, loadingWindowStarted: false })]);
+
+    const result = await service.loadItemsOntoTrain('sched-1', ['inv-1']);
+
+    expect(result.results[0].reason).toContain('No wagon allocated');
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
index 15a3f6c4a..77755fa2f 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
@@ -199,9 +199,14 @@ export class WarehouseInventoryController {
 
   @Get('loadable-trains')
   @BookingStaff(FREIGHT_PERMS.warehouseInventory.view)
-  @ApiOperation({ summary: 'EXPORT trains (pre-dispatch) with inventory waiting to be loaded' })
-  loadableTrains() {
-    return this.inventoryService.loadableTrains();
+  @ApiOperation({
+    summary:
+      'EXPORT trains with inventory waiting to be loaded — pre-dispatch by default; `includeDispatched=true` adds rolling trains still picking cargo up along the corridor',
+  })
+  loadableTrains(@Query('includeDispatched') includeDispatched?: string) {
+    return this.inventoryService.loadableTrains({
+      includeDispatched: includeDispatched === 'true' || includeDispatched === '1',
+    });
   }
 
   @Get('train/:scheduleId/loadable-items')
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
index aa032c17d..ef68f3673 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
@@ -17,8 +17,10 @@ import {
 
 import { deriveTradeDirection } from '../../common/derive-trade-direction.util';
 import { generateGrnNumber } from '../../common/grn.util';
+import { assertTruckLoad } from '../../common/truck-load.util';
 import { SCHEDULE_BOOKINGS_CTE } from '../../common/schedule-bookings.sql';
 import { Booking } from '../bookings/entities/booking.entity';
+import type { StationWorkLog } from '../train-schedules/entities/train-schedule.entity';
 import { Cargo } from '../cargoes/entities/cargoes.entity';
 import { Company } from '../companies/entities/company.entity';
 import { Container } from '../container-management/entities/container.entity';
@@ -127,6 +129,7 @@ interface BookingSummaryRow {
   id: string;
   reference: string | null;
   status: string | null;
+  paymentStatus: string | null;
   customer: string | null;
 }
 
@@ -274,12 +277,30 @@ export interface EligibleBookingRow {
   customerTruckType: string | null;
   customerTruckContainerNumber: string | null;
   customerTruckAssignedAt: string | null;
+  containerUnits: Array<{
+    containerNumber: string;
+    containerSize: string | null;
+    weightTons: number;
+    received: boolean;
+    grnNumber: string | null;
+  }>;
+  receivedContainerCount: number;
+  remainingContainerCount: number;
 }
 
 export interface BulkReceiveResult {
   receivedCount: number;
   skippedCount: number;
-  results: { bookingId: string; status: string; inventoryId?: string; grnNumber?: string; reason?: string }[];
+  results: {
+    bookingId: string;
+    status: string;
+    inventoryId?: string;
+    inventoryIds?: string[];
+    grnNumber?: string;
+    receivedContainers?: number;
+    remainingContainers?: number;
+    reason?: string;
+  }[];
 }
 
 
@@ -319,6 +340,14 @@ export interface LoadableTrainRow {
   destination: string | null;
   status: string;
   departureTime: string | Date | null;
+  /** freight.yards.id the train departs from — the default boarding yard. */
+  originStationId: string | null;
+  /**
+   * The schedule's per-yard loading/unloading time windows, exactly as the train
+   * schedule page stores them. The warehouse loading queues render the same
+   * Start/End controls off this, so both surfaces show one truth.
+   */
+  stationWorkLogs: Record<string, StationWorkLog> | null;
   /** Received/ready inventory not yet loaded onto this train. */
   readyCount: number;
   /** Inventory already loaded onto this train. */
@@ -340,7 +369,12 @@ export interface TrainLoadableItemRow {
   wagonId: string | null;
   wagonNumber: string | null;
   sequenceNo: number | null;
-  /** True only when the item is READY_FOR_LOADING and has an allocated wagon. */
+  /** The booking's boarding yard — the yard whose loading window gates this item. */
+  originYardId: string | null;
+  originYardLabel: string | null;
+  /** True once "Start loading" was clicked for this item's boarding yard on this train. */
+  loadingWindowStarted: boolean;
+  /** True only when the item is READY_FOR_LOADING, has an allocated wagon and GRN, and its yard's loading window is open. */
   loadable: boolean;
 }
 
@@ -1339,14 +1373,19 @@ export class WarehouseInventoryService {
     return this.findById(saved.id);
   }
 
-  /** Auto-load all READY_FOR_LOADING inventory whose booking is PAID. Unpaid stay pending. */
+  /**
+   * Auto-load all READY_FOR_LOADING inventory whose booking is paid (payment
+   * status PAID — the booking status is not consulted). Unpaid stay pending.
+   */
   async autoLoadReady(): Promise<AutoLoadResult> {
     const ready = await this.inventoryRepository.findAll({ where: { status: 'READY_FOR_LOADING' } });
     const result: AutoLoadResult = { loadedCount: 0, skippedCount: 0, results: [] };
 
     for (const item of ready) {
-      const bookingStatus = item.bookingId ? await this.getBookingStatus(item.bookingId) : null;
-      if (bookingStatus !== 'PAID') {
+      const paymentStatus = item.bookingId
+        ? await this.getBookingPaymentStatus(item.bookingId)
+        : null;
+      if (paymentStatus !== 'PAID') {
         result.skippedCount += 1;
         result.results.push({ inventoryId: item.id, status: 'SKIPPED', reason: 'Booking not PAID' });
         continue;
@@ -1392,6 +1431,9 @@ export class WarehouseInventoryService {
               ${companyNotifyPhoneExpr('company')} AS "customerPhone",
               COALESCE(bcu.unit_numbers, bc.container_numbers) AS "containerNumber",
               bcu.seal_numbers         AS "sealNumbers",
+              COALESCE(bcu.container_units, '[]'::json) AS "containerUnits",
+              COALESCE(bcu.received_count, 0)::int AS "receivedContainerCount",
+              COALESCE(bcu.remaining_count, 0)::int AS "remainingContainerCount",
               bc.container_quantity    AS "containerQuantity",
               bc.container_packaging_type AS "containerPackagingType",
               -- service_types.includes_last_mile/first_mile are NOT read here: every
@@ -1443,7 +1485,6 @@ export class WarehouseInventoryService {
          LEFT JOIN freight.yards oy ON oy.id = b.origin_yard_id
          LEFT JOIN freight.yards dy ON dy.id = b.destination_yard_id
          LEFT JOIN freight.cargo_types ct ON ct.id = b.cargo_type_id
-         LEFT JOIN freight.warehouse_inventory inv ON inv.booking_id = b.id AND inv.deleted_at IS NULL
          LEFT JOIN LATERAL (
            SELECT string_agg(NULLIF(booking_container.container_number, ''), ', ' ORDER BY booking_container.container_number) AS container_numbers,
                   SUM(booking_container.quantity)::int AS container_quantity,
@@ -1462,7 +1503,18 @@ export class WarehouseInventoryService {
          ) bc ON true
          LEFT JOIN LATERAL (
            SELECT string_agg(NULLIF(unit.container_number, ''), ', ' ORDER BY unit.container_number) AS unit_numbers,
-                  string_agg(DISTINCT NULLIF(unit.seal_number, ''), ', ') AS seal_numbers
+                  string_agg(DISTINCT NULLIF(unit.seal_number, ''), ', ') AS seal_numbers,
+                  COUNT(*) FILTER (WHERE unit.received_to_port)::int AS received_count,
+                  COUNT(*) FILTER (WHERE NOT unit.received_to_port)::int AS remaining_count,
+                  json_agg(
+                    json_build_object(
+                      'containerNumber', unit.container_number,
+                      'containerSize', line.container_size,
+                      'weightTons', unit.vgm_tons,
+                      'received', unit.received_to_port,
+                      'grnNumber', unit.grn_number
+                    ) ORDER BY unit.container_number
+                  ) AS container_units
              FROM freight.booking_container_units unit
              JOIN freight.booking_container line
                ON line.id = unit.booking_container_id AND line.deleted_at IS NULL
@@ -1479,7 +1531,14 @@ export class WarehouseInventoryService {
          LEFT JOIN freight.drivers driver ON driver.id = v.assigned_driver_id
         WHERE b.deleted_at IS NULL
           AND b.payment_status = 'PAID'
-          AND inv.id IS NULL
+          AND (
+            (b.freight_type = 'CONTAINER' AND COALESCE(bcu.remaining_count, 0) > 0)
+            OR
+            (b.freight_type <> 'CONTAINER' AND NOT EXISTS (
+              SELECT 1 FROM freight.warehouse_inventory inv
+               WHERE inv.booking_id = b.id AND inv.deleted_at IS NULL
+            ))
+          )
           -- Direct truck-to-train cargo never comes to the warehouse, so never
           -- offer it for receipt.
           AND COALESCE(b.export_handover_mode, 'WAREHOUSE') <> 'DIRECT_TO_TRAIN'
@@ -1509,6 +1568,7 @@ export class WarehouseInventoryService {
         grnNumber: string;
         direction?: string | null;
         warehouseId?: string | null;
+        bookingId?: string | null;
       };
       booking: {
         companyId?: string | null;
@@ -1635,9 +1695,6 @@ export class WarehouseInventoryService {
           }
         }
 
-        const existing = await manager.getRepository(WarehouseInventory).findOne({ where: { bookingId } });
-        if (existing) { skip('Already received'); continue; }
-
         const containerQuantity = Number(booking.containerQuantity ?? 0);
         if (booking.freightType === 'CONTAINER' && containerQuantity <= 0) {
           skip('Container booking has no container quantity');
@@ -1645,62 +1702,256 @@ export class WarehouseInventoryService {
         }
 
         const now = new Date();
-        const grnNumber = this.generateGrnNumber(dto.direction, bookingId, now, booking.customer);
         const truckEntrance = dto.truckEntrance
           ? this.mergeSystemTruckEntrance(dto.truckEntrance, booking)
           : undefined;
+        // Multi-truck self-haul is selected explicitly at the gate. The booking
+        // source contains comma-joined legacy summary fields, which must never
+        // replace the one physical truck the receiver selected.
+        if (truckEntrance && !booking.hasFirstMile && dto.truckEntrance) {
+          truckEntrance.truckPlateNumber = dto.truckEntrance.truckPlateNumber;
+          truckEntrance.driverName = dto.truckEntrance.driverName;
+          truckEntrance.driverPhone = dto.truckEntrance.driverPhone;
+          truckEntrance.truckType = dto.truckEntrance.truckType;
+        }
         if (dto.direction === 'EXPORT') {
           this.assertTruckEntrance(truckEntrance);
         }
+
+        type ReceiveContainerUnit = {
+          containerNumber: string;
+          containerSize: string | null;
+          weightTons: string | number;
+          sealNumber: string | null;
+          bookingContainerId: string;
+          containerTypeId: string | null;
+          received: boolean;
+        };
+        let selectedUnits: ReceiveContainerUnit[] = [];
+        let grnNumber = this.generateGrnNumber(dto.direction, bookingId, now, booking.customer);
+
+        if (booking.freightType === 'CONTAINER') {
+          if (dto.bookingIds.length !== 1) {
+            throw new BadRequestException(
+              'Receive one container booking per arriving truck so its containers and documents stay separate',
+            );
+          }
+          const selectedNumbers = (dto.containerNumbers ?? []).map((n) => n.trim().toUpperCase());
+          if (!selectedNumbers.length) {
+            throw new BadRequestException('Select the containers arriving on this truck');
+          }
+          const allUnits: ReceiveContainerUnit[] = await manager.query(
+            `SELECT UPPER(bcu.container_number) AS "containerNumber",
+                    bc.container_size AS "containerSize",
+                    bcu.vgm_tons AS "weightTons",
+                    bcu.seal_number AS "sealNumber",
+                    bc.id AS "bookingContainerId",
+                    bc.container_type_id AS "containerTypeId",
+                    bcu.received_to_port AS received
+               FROM freight.booking_container_units bcu
+               JOIN freight.booking_container bc
+                 ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
+              WHERE bc.booking_id = $1 AND bcu.deleted_at IS NULL
+              FOR UPDATE OF bcu`,
+            [bookingId],
+          );
+          assertTruckLoad({
+            containers: selectedNumbers,
+            bookingContainers: allUnits.map((unit) => unit.containerNumber),
+            sizes: allUnits
+              .filter((unit) => selectedNumbers.includes(unit.containerNumber))
+              .map((unit) => unit.containerSize ?? ''),
+          });
+          selectedUnits = allUnits.filter((unit) => selectedNumbers.includes(unit.containerNumber));
+          if (selectedUnits.some((unit) => unit.received)) {
+            const repeated = selectedUnits.filter((unit) => unit.received).map((unit) => unit.containerNumber);
+            throw new BadRequestException(`Container(s) already received: ${repeated.join(', ')}`);
+          }
+
+          // If this is a customer-assigned truck, it may only deliver the boxes
+          // assigned to that plate. Manual/unassigned arrivals retain the same
+          // physical capacity validation but have no assignment list to check.
+          if (truckEntrance?.truckPlateNumber) {
+            const assigned: Array<{ containerNumber: string }> = await manager.query(
+              `SELECT UPPER(ctc.container_number) AS "containerNumber"
+                 FROM freight.customer_truck_assignments cta
+                 JOIN freight.customer_truck_containers ctc
+                   ON ctc.assignment_id = cta.id AND ctc.deleted_at IS NULL
+                WHERE cta.booking_id = $1
+                  AND UPPER(cta.plate_number) = UPPER($2)
+                  AND cta.deleted_at IS NULL`,
+              [bookingId, truckEntrance.truckPlateNumber],
+            );
+            if (
+              assigned.length > 0 &&
+              selectedNumbers.some(
+                (number) => !assigned.some((container) => container.containerNumber === number),
+              )
+            ) {
+              throw new BadRequestException(
+                `Selected containers are not assigned to truck ${truckEntrance.truckPlateNumber}`,
+              );
+            }
+          }
+
+          const [{ batches }]: Array<{ batches: string }> = await manager.query(
+            `SELECT COUNT(DISTINCT inv.grn_number) AS batches
+               FROM freight.warehouse_inventory inv
+              WHERE inv.booking_id = $1
+                AND inv.grn_number IS NOT NULL
+                AND inv.deleted_at IS NULL`,
+            [bookingId],
+          );
+          grnNumber = `${grnNumber}-${String(Number(batches ?? 0) + 1).padStart(2, '0')}`;
+          if (truckEntrance) {
+            truckEntrance.assignedEquipmentNumber = selectedNumbers.join(', ');
+            truckEntrance.unitCount = selectedNumbers.length;
+            truckEntrance.netWeightKg = selectedUnits.reduce(
+              (total, unit) => total + Number(unit.weightTons || 0),
+              0,
+            );
+          }
+        } else {
+          const existing = await manager
+            .getRepository(WarehouseInventory)
+            .findOne({ where: { bookingId } });
+          if (existing) {
+            skip('Already received');
+            continue;
+          }
+        }
+
+        const receivedBefore =
+          booking.freightType === 'CONTAINER'
+            ? Number(
+                (
+                  await manager.query(
+                    `SELECT COUNT(*) AS count
+                       FROM freight.booking_container_units bcu
+                       JOIN freight.booking_container bc
+                         ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
+                      WHERE bc.booking_id = $1
+                        AND bcu.received_to_port = true
+                        AND bcu.deleted_at IS NULL`,
+                    [bookingId],
+                  )
+                )[0]?.count ?? 0,
+              )
+            : 0;
+        const receivedAfter = receivedBefore + selectedUnits.length;
+        const remainingAfter = Math.max(0, containerQuantity - receivedAfter);
         const receiveNote = this.buildReceiveNote({
           grnNumber,
           direction: dto.direction,
-          notes: `Bulk received (${dto.direction})`,
+          notes:
+            booking.freightType === 'CONTAINER'
+              ? `${selectedUnits.length} container(s) arrived: ${selectedUnits
+                  .map((unit) => unit.containerNumber)
+                  .join(', ')}. ${remainingAfter} container(s) left.`
+              : `Bulk received (${dto.direction})`,
           truckEntrance,
         });
 
         // Validate capacity before saving
-        const weight = Number(booking.weight) || 0;
-        const containerCount = booking.freightType === 'CONTAINER' ? containerQuantity : 0;
+        const weight =
+          booking.freightType === 'CONTAINER'
+            ? selectedUnits.reduce((total, unit) => total + Number(unit.weightTons || 0), 0)
+            : Number(booking.weight) || 0;
+        const containerCount = booking.freightType === 'CONTAINER' ? selectedUnits.length : 0;
         this.assertCapacity('Warehouse', warehouse, weight, 0, containerCount);
         this.assertCapacity('Yard', yard, weight, 0, containerCount);
         this.assertCapacity('Zone', zone, weight, 0, containerCount);
 
-        const saved = await manager.getRepository(WarehouseInventory).save(
-          manager.getRepository(WarehouseInventory).create({
-            warehouseId: dto.warehouseId,
-            yardId: dto.yardId,
-            zoneId: dto.zoneId,
-            bookingId,
-            quantity: booking.freightType === 'CONTAINER' ? containerQuantity : 1,
-            weight,
-            grnNumber,
-            status: 'RECEIVED',
-            arrivedAt: now,
-            notes: receiveNote,
-          }),
-        );
+        const inventoryIds: string[] = [];
+        if (booking.freightType === 'CONTAINER') {
+          const containers = manager.getRepository(Container);
+          for (const unit of selectedUnits) {
+            let container = await containers.findOne({
+              where: { containerNumber: unit.containerNumber },
+              withDeleted: true,
+            });
+            if (!container && !unit.containerTypeId) {
+              throw new BadRequestException(
+                `Container ${unit.containerNumber} has no container type and cannot be received`,
+              );
+            }
+            if (!container) {
+              container = await containers.save(
+                containers.create({
+                  containerNumber: unit.containerNumber,
+                  containerTypeId: unit.containerTypeId as string,
+                  bookingContainerId: unit.bookingContainerId,
+                  bookingId,
+                  sealNumber: unit.sealNumber,
+                  tareWeight: 0,
+                  maxGrossWeight: Number(unit.weightTons || 0),
+                  status: 'LOADED',
+                  wagonId: null,
+                  position: null,
+                  wagonBookingAllocationId: null,
+                }),
+              );
+            } else {
+              await containers.update(container.id, {
+                bookingId,
+                bookingContainerId: unit.bookingContainerId,
+                sealNumber: unit.sealNumber,
+                status: 'LOADED',
+                deletedAt: null,
+              });
+            }
+            const saved = await manager.getRepository(WarehouseInventory).save(
+              manager.getRepository(WarehouseInventory).create({
+                warehouseId: dto.warehouseId,
+                yardId: dto.yardId,
+                zoneId: dto.zoneId,
+                bookingId,
+                containerId: container.id,
+                quantity: 1,
+                weight: Number(unit.weightTons || 0),
+                grnNumber,
+                status: 'RECEIVED',
+                arrivedAt: now,
+                notes: receiveNote,
+              }),
+            );
+            inventoryIds.push(saved.id);
+          }
+          await manager.query(
+            `UPDATE freight.booking_container_units bcu
+                SET received_to_port = true,
+                    received_at = COALESCE(bcu.received_at, NOW()),
+                    grn_number = $3,
+                    updated_at = NOW()
+               FROM freight.booking_container bc
+              WHERE bc.id = bcu.booking_container_id
+                AND bc.booking_id = $1
+                AND UPPER(bcu.container_number) = ANY($2::varchar[])
+                AND bc.deleted_at IS NULL
+                AND bcu.deleted_at IS NULL`,
+            [bookingId, selectedUnits.map((unit) => unit.containerNumber), grnNumber],
+          );
+        } else {
+          const saved = await manager.getRepository(WarehouseInventory).save(
+            manager.getRepository(WarehouseInventory).create({
+              warehouseId: dto.warehouseId,
+              yardId: dto.yardId,
+              zoneId: dto.zoneId,
+              bookingId,
+              quantity: 1,
+              weight,
+              grnNumber,
+              status: 'RECEIVED',
+              arrivedAt: now,
+              notes: receiveNote,
+            }),
+          );
+          inventoryIds.push(saved.id);
+        }
 
         // Update warehouse/yard/zone capacity counters
         await this.applyCapacityDelta(manager, dto, weight, 0, containerCount);
 
-        // Receiving the booking flags every container unit as received into the
-        // port (self-haul export: the delivering truck's goods are now in) so
-        // staff can raise the per-container GRN over what's received.
-        await manager.query(
-          `UPDATE freight.booking_container_units bcu
-              SET received_to_port = true,
-                  received_at = COALESCE(bcu.received_at, NOW()),
-                  updated_at = NOW()
-             FROM freight.booking_container bc
-            WHERE bc.id = bcu.booking_container_id
-              AND bc.booking_id = $1
-              AND bc.deleted_at IS NULL
-              AND bcu.deleted_at IS NULL
-              AND bcu.received_to_port = false`,
-          [bookingId],
-        );
-
         // Export self-haul: this receive IS the truck's arrival — see
         // markCustomerTruckArrived / receive()'s single-booking mirror.
         if (dto.direction === 'EXPORT') {
@@ -1710,7 +1961,7 @@ export class WarehouseInventoryService {
         await this.activityLog.record(
           {
             activityType: 'INVENTORY_RECEIVED',
-            inventoryId: saved.id,
+            inventoryId: inventoryIds[0],
             warehouseId: dto.warehouseId,
             description: truckEntrance?.truckPlateNumber
               ? `GRN ${grnNumber}: bulk received ${dto.direction} booking via truck ${truckEntrance.truckPlateNumber}`
@@ -1730,13 +1981,26 @@ export class WarehouseInventoryService {
             grnNumber,
             direction: dto.direction,
             warehouseId: dto.warehouseId,
+            bookingId,
           },
           booking,
           bookingId,
         });
 
         result.receivedCount += 1;
-        result.results.push({ bookingId, status: 'RECEIVED', inventoryId: saved.id, grnNumber });
+        result.results.push({
+          bookingId,
+          status: 'RECEIVED',
+          inventoryId: inventoryIds[0],
+          inventoryIds,
+          grnNumber,
+          ...(booking.freightType === 'CONTAINER'
+            ? {
+                receivedContainers: receivedAfter,
+                remainingContainers: remainingAfter,
+              }
+            : {}),
+        });
       }
     });
 
@@ -1827,7 +2091,17 @@ export class WarehouseInventoryService {
    */
   private readonly SCHEDULE_BOOKINGS_CTE = SCHEDULE_BOOKINGS_CTE;
 
-  async loadableTrains(): Promise<LoadableTrainRow[]> {
+  /**
+   * @param includeDispatched also list DISPATCHED trains. Loading follows the
+   *   train after it rolls — a mid-corridor warehouse boards its cargo when the
+   *   train stands at its yard — so the warehouse's train-centric loading view
+   *   needs the same set the schedule workspace offers Load on. The default
+   *   (pre-dispatch only) keeps the existing auto-load picker unchanged.
+   */
+  async loadableTrains(opts: { includeDispatched?: boolean } = {}): Promise<LoadableTrainRow[]> {
+    const statuses = opts.includeDispatched
+      ? ['DRAFT', 'SCHEDULED', 'DISPATCHED']
+      : ['DRAFT', 'SCHEDULED'];
     const rows: Array<
       LoadableTrainRow & { originCountry: string | null; destinationCountry: string | null }
     > = await this.dataSource.query(
@@ -1840,6 +2114,8 @@ export class WarehouseInventoryService {
               dy.country                  AS "destinationCountry",
               ts.status                   AS "status",
               ts.scheduled_departure_date AS "departureTime",
+              ts.origin_station_id        AS "originStationId",
+              ts.station_work_logs        AS "stationWorkLogs",
               (SELECT count(*) FROM sched_bookings sb
                  JOIN freight.warehouse_inventory inv
                    ON inv.booking_id = sb.booking_id AND inv.deleted_at IS NULL
@@ -1863,7 +2139,7 @@ export class WarehouseInventoryService {
                AND inv2.status IN ('RECEIVED','STORED','READY_FOR_LOADING','LOADED')
           )
         ORDER BY ts.scheduled_departure_date ASC NULLS LAST`,
-      [['DRAFT', 'SCHEDULED']],
+      [statuses],
     );
 
     return rows
@@ -1903,7 +2179,15 @@ export class WarehouseInventoryService {
               inv.status                AS "status",
               wl.wagon_id               AS "wagonId",
               wl.wagon_number           AS "wagonNumber",
-              wl.sequence_no            AS "sequenceNo"
+              wl.sequence_no            AS "sequenceNo",
+              COALESCE(b.origin_yard_id, ts.origin_station_id) AS "originYardId",
+              COALESCE(oy.label, oy.code) AS "originYardLabel",
+              -- Same rule the train schedule's own Load button obeys
+              -- (assertStationWorkStarted): the yard's loading window must have
+              -- been started before its cargo may go on a wagon.
+              (ts.station_work_logs #>> ARRAY[
+                 COALESCE(b.origin_yard_id, ts.origin_station_id)::text, 'loading', 'startedAt'
+               ]) IS NOT NULL           AS "loadingWindowStarted"
          FROM sched_bookings sb
          JOIN freight.train_schedules ts ON ts.id = sb.schedule_id
          JOIN freight.bookings b ON b.id = sb.booking_id AND b.deleted_at IS NULL
@@ -1911,6 +2195,7 @@ export class WarehouseInventoryService {
          LEFT JOIN freight.companies company ON company.id = b.company_id
          LEFT JOIN freight.cargo_types cgt ON cgt.id = b.cargo_type_id
          LEFT JOIN freight.containers ct ON ct.id = inv.container_id
+         LEFT JOIN freight.yards oy ON oy.id = COALESCE(b.origin_yard_id, ts.origin_station_id)
          LEFT JOIN LATERAL (
            SELECT w.id AS wagon_id, w.wagon_number, tsw.sequence_no
              FROM freight.wagon_booking_allocations wba
@@ -1933,9 +2218,14 @@ export class WarehouseInventoryService {
       ...r,
       // Export flow: received at the warehouse -> GRN -> loaded onto its wagon.
       // The row only exists once the goods were received, so requiring a GRN and
-      // an allocated wagon completes the chain.
+      // an allocated wagon completes the chain. The yard's loading window is the
+      // fourth link — the warehouse queue must not offer what the train
+      // schedule's own Load button would refuse.
       loadable:
-        r.status === 'READY_FOR_LOADING' && Boolean(r.wagonId) && Boolean(r.grnNumber),
+        r.status === 'READY_FOR_LOADING' &&
+        Boolean(r.wagonId) &&
+        Boolean(r.grnNumber) &&
+        r.loadingWindowStarted,
     }));
   }
 
@@ -1992,6 +2282,11 @@ export class WarehouseInventoryService {
       // nothing rides a train without one.
       if (!item.grnNumber) { skip('No GRN — receive the goods and generate the GRN first'); continue; }
       if (!item.wagonId) { skip('No wagon allocated — allocate a wagon first'); continue; }
+      // Mirrors assertStationWorkStarted on the train-schedule load path.
+      if (!item.loadingWindowStarted) {
+        skip(`Start loading at ${item.originYardLabel ?? 'the boarding yard'} first — the loading time window has not been started`);
+        continue;
+      }
 
       try {
         await this.load(inventoryId, {
@@ -3107,6 +3402,7 @@ export class WarehouseInventoryService {
         grnNumber,
         direction: bookingDirection,
         warehouseId: dto.warehouseId,
+        bookingId: dto.bookingId ?? null,
       });
 
       return saved.id;
@@ -3491,12 +3787,14 @@ export class WarehouseInventoryService {
       throw new BadRequestException(`Inventory must be STORED to reserve (current: ${item.status})`);
     }
 
-    const status = await this.getBookingStatus(dto.bookingId);
-    if (!status) {
+    const paymentStatus = await this.getBookingPaymentStatus(dto.bookingId);
+    if (paymentStatus === null) {
       throw new NotFoundException(`Booking ${dto.bookingId} not found`);
     }
-    if (status !== 'PAID') {
-      throw new BadRequestException(`Booking must be PAID to reserve inventory (current: ${status})`);
+    if (paymentStatus !== 'PAID') {
+      throw new BadRequestException(
+        `Booking must be paid to reserve inventory (payment status: ${paymentStatus})`,
+      );
     }
 
     await this.dataSource.transaction(async (manager) => {
@@ -3988,7 +4286,7 @@ export class WarehouseInventoryService {
       `SELECT inv.id,
               inv.release_date AS "releaseDate",
               inv.release_order_reference AS "releaseOrderReference",
-              inv.quantity,
+              COALESCE(receipt_batch.quantity, inv.quantity) AS quantity,
               inv.weight,
               inv.status,
               inv.notes,
@@ -4317,11 +4615,12 @@ export class WarehouseInventoryService {
    */
   async bookingContainerWeights(
     bookingId: string,
-  ): Promise<Array<{ containerNumber: string; weightTons: number }>> {
-    const rows: Array<{ containerNumber: string; weightTons: string }> =
+  ): Promise<Array<{ containerNumber: string; weightTons: number; containerSize: string | null }>> {
+    const rows: Array<{ containerNumber: string; weightTons: string; containerSize: string | null }> =
       await this.dataSource.query(
         `SELECT bcu.container_number AS "containerNumber",
-                MAX(COALESCE(bcu.vgm_tons, 0)) AS "weightTons"
+                MAX(COALESCE(bcu.vgm_tons, 0)) AS "weightTons",
+                MAX(bc.container_size) AS "containerSize"
            FROM freight.booking_container_units bcu
            JOIN freight.booking_container bc
              ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
@@ -4333,6 +4632,7 @@ export class WarehouseInventoryService {
     return rows.map((r) => ({
       containerNumber: r.containerNumber,
       weightTons: Number(r.weightTons) || 0,
+      containerSize: r.containerSize ?? null,
     }));
   }
 
@@ -4534,7 +4834,7 @@ export class WarehouseInventoryService {
               -- An unweighed item still reports the cargo weight it holds: fall
               -- back to the item's container VGM, then the booking's declared
               -- weight, so a GRN never prints "0 t" for goods that are present.
-              COALESCE(NULLIF(inv.weight, 0), item_vgm.tons, b.cargo_total_weight_vgm, 0) AS weight,
+              COALESCE(NULLIF(receipt_batch.weight, 0), NULLIF(inv.weight, 0), item_vgm.tons, b.cargo_total_weight_vgm, 0) AS weight,
               inv.volume,
               inv.status,
               inv.notes,
@@ -4551,8 +4851,8 @@ export class WarehouseInventoryService {
               origin_yard.code AS "originYardCode",
               destination_yard.label AS "destinationYardLabel",
               destination_yard.code AS "destinationYardCode",
-              COALESCE(container.container_number, booking_container.container_number) AS "containerNumber",
-              booking_container."containerSummary" AS "bookingContainerSummary",
+              COALESCE(receipt_batch.container_numbers, container.container_number, booking_container.container_number) AS "containerNumber",
+              COALESCE(receipt_batch.container_summary, booking_container."containerSummary") AS "bookingContainerSummary",
               COALESCE(cargo_type.cargo_type_name, b.cargo_free_text, cargo.description) AS "cargoDescription",
               wh.name AS "warehouseName",
               wh.code AS "warehouseCode",
@@ -4582,6 +4882,40 @@ export class WarehouseInventoryService {
             WHERE bc.booking_id = b.id
               AND bc.deleted_at IS NULL
          ) booking_container ON true
+         LEFT JOIN LATERAL (
+           SELECT COUNT(*)::int AS quantity,
+                  SUM(batch.weight) AS weight,
+                  string_agg(batch.container_number, ', ' ORDER BY batch.container_number)
+                    FILTER (WHERE batch.container_number IS NOT NULL) AS container_numbers,
+                  string_agg(
+                    CONCAT(batch.container_number, ' (', COALESCE(batch.container_size, 'size unknown'), ')'),
+                    ', ' ORDER BY batch.container_number
+                  ) FILTER (WHERE batch.container_number IS NOT NULL) AS container_summary
+             FROM (
+               SELECT inv2.id,
+                      inv2.weight,
+                      c2.container_number,
+                      bc2.container_size
+                 FROM freight.warehouse_inventory inv2
+                 LEFT JOIN freight.containers c2
+                   ON c2.id = inv2.container_id AND c2.deleted_at IS NULL
+                 LEFT JOIN freight.booking_container_units bcu2
+                   ON bcu2.container_number = c2.container_number AND bcu2.deleted_at IS NULL
+                 LEFT JOIN freight.booking_container bc2
+                   ON bc2.id = bcu2.booking_container_id
+                  AND bc2.booking_id = inv2.booking_id
+                  AND bc2.deleted_at IS NULL
+                WHERE inv2.booking_id = inv.booking_id
+                  AND inv2.deleted_at IS NULL
+                  AND COALESCE(
+                        NULLIF(TRIM(inv2.grn_number), ''),
+                        substring(inv2.notes FROM 'GRN Number: ([^\\n\\r]+)')
+                      ) = COALESCE(
+                        NULLIF(TRIM(inv.grn_number), ''),
+                        substring(inv.notes FROM 'GRN Number: ([^\\n\\r]+)')
+                      )
+             ) batch
+         ) receipt_batch ON true
          LEFT JOIN LATERAL (
            SELECT SUM(bcu.vgm_tons) AS tons
              FROM freight.booking_container_units bcu
@@ -6614,10 +6948,9 @@ export class WarehouseInventoryService {
     grnNumber: string;
     direction?: string | null;
     warehouseId?: string | null;
+    /** Resolves the company, which unlocks in-app + email alongside the SMS. */
+    bookingId?: string | null;
   }): Promise<void> {
-    const phone = params.phone?.trim();
-    if (!phone) return;
-
     const ownerName = params.ownerName?.trim() || 'Customer';
     const bookingReference = params.bookingReference?.trim();
     const message =
@@ -6627,6 +6960,47 @@ export class WarehouseInventoryService {
       (params.direction ? `Direction: ${params.direction}. ` : '') +
       `Thank you.`;
 
+    // A booking gives us the company, and with it the customer's inbox and
+    // email — not just whatever phone number the gate clerk typed. Without one
+    // (manual or backlog receive) the typed phone is all there is, so the
+    // original SMS-only path stands.
+    let companyId: string | null = null;
+    if (params.bookingId) {
+      try {
+        const [row]: Array<{ companyId: string | null }> = await this.dataSource.query(
+          `SELECT company_id AS "companyId"
+             FROM freight.bookings
+            WHERE id = $1 AND deleted_at IS NULL`,
+          [params.bookingId],
+        );
+        companyId = row?.companyId ?? null;
+      } catch (error) {
+        this.logger.warn(`GRN ${params.grnNumber}: company lookup failed: ${String(error)}`);
+      }
+    }
+
+    if (companyId) {
+      try {
+        await this.inbox.notify({
+          recipients: { companyId },
+          audience: NotificationAudience.PORTAL,
+          type: NotificationType.DOCUMENT_ACTION,
+          title: 'Cargo received — GRN issued',
+          body: message,
+          link: params.bookingId ? `/bookings/${params.bookingId}` : undefined,
+          data: { grnNumber: params.grnNumber, bookingId: params.bookingId ?? null },
+        });
+        // Sends SMS *and* email to the company's own contacts, so the typed
+        // phone below is skipped to avoid texting the customer twice.
+        await sendCompanyChannels(this.dataSource, this.notifications, companyId, message);
+        return;
+      } catch (error) {
+        this.logger.error(`Failed to notify company for GRN ${params.grnNumber}: ${String(error)}`);
+      }
+    }
+
+    const phone = params.phone?.trim();
+    if (!phone) return;
     try {
       await this.notifications.directSend('sms', phone, message);
     } catch (error) {
@@ -7112,12 +7486,19 @@ export class WarehouseInventoryService {
     };
   }
 
-  private async getBookingStatus(bookingId: string): Promise<string | null> {
-    const [row]: Array<{ status: string | null }> = await this.dataSource.query(
-      'SELECT status FROM freight.bookings WHERE id = $1 AND deleted_at IS NULL LIMIT 1',
+  /**
+   * The booking's PAYMENT status — the only signal loading/reservation gates
+   * use to decide "paid". Returns null when the booking does not exist;
+   * an existing booking with no payment status yet reads as PENDING.
+   */
+  private async getBookingPaymentStatus(bookingId: string): Promise<string | null> {
+    const [row]: Array<{ paymentStatus: string | null }> = await this.dataSource.query(
+      `SELECT payment_status AS "paymentStatus"
+         FROM freight.bookings WHERE id = $1 AND deleted_at IS NULL LIMIT 1`,
       [bookingId],
     );
-    return row?.status ?? null;
+    if (!row) return null;
+    return row.paymentStatus ?? 'PENDING';
   }
 
   private async attachBookingSummaries(items: WarehouseInventory[]): Promise<void> {
@@ -7125,7 +7506,8 @@ export class WarehouseInventoryService {
     if (bookingIds.length === 0) return;
 
     const rows: BookingSummaryRow[] = await this.dataSource.query(
-      `SELECT b.id, b.reference, b.status, company.name AS customer
+      `SELECT b.id, b.reference, b.status, b.payment_status AS "paymentStatus",
+              company.name AS customer
          FROM freight.bookings b
          LEFT JOIN freight.companies company ON company.id = b.company_id
         WHERE b.id = ANY($1) AND b.deleted_at IS NULL`,
@@ -7139,6 +7521,7 @@ export class WarehouseInventoryService {
       Object.assign(item, {
         bookingReference: summary.reference,
         bookingStatus: summary.status,
+        bookingPaymentStatus: summary.paymentStatus,
         customerName: summary.customer,
       });
     });
diff --git a/apps/edr-freight-api/src/scripts/seed-mor-test-buyers.ts b/apps/edr-freight-api/src/scripts/seed-mor-test-buyers.ts
new file mode 100644
index 000000000..25ae2f038
--- /dev/null
+++ b/apps/edr-freight-api/src/scripts/seed-mor-test-buyers.ts
@@ -0,0 +1,100 @@
+import { AppDataSource } from "../data-source";
+
+/**
+ * Seeds the 30 test taxpayers the Ministry of Revenues issued for the EIMS/BSP
+ * **non-self buyer** certification run — the checklist item that needs a real
+ * invoice filed against a buyer that is not EDR itself.
+ *
+ * Every field comes from MoR's own roster, except the two location codes, which
+ * do not survive contact with the Ministry's own location master:
+ *
+ *   - MoR's sheet gives `Region = "1"`. `PARISH_NO 1` is not an Ethiopian region
+ *     at all (it is Djibouti), so the region is stored by name — `Bole` is an
+ *     Addis Ababa sub-city, which fixes the region unambiguously (PARISH_NO 13).
+ *   - MoR's sheet gives `City = "101"`, which is GOFA ZONE in SNNPRS. The buyer
+ *     is in Bole, so the sub-city is stored by name (CITY_NO 78).
+ *
+ * In other words MoR does not validate the geographic codes it sends itself;
+ * these rows carry the addresses that actually resolve. The roster carries no
+ * woreda, so every row takes `NO WOREDA-144` — MoR's *own* "not specified"
+ * locality under BOLE (LOCALITY_NO 574), the same code EDR's static seller
+ * details already file under. Nothing here is invented.
+ *
+ * Idempotent: `ON CONFLICT (tin) DO NOTHING`. TIN 0089238373 is already on file
+ * as a real customer (Afri Software Solutions) and is deliberately left alone.
+ */
+
+/**
+ * `[TIN, phone, legal name, email, kebele?, house number?]`, verbatim from MoR's roster. The two
+ * trailing fields default to the values 22 of the 30 rows share.
+ */
+const KEBELE = "Near Bole Airport";
+const HOUSE_NO = "123B";
+
+const MOR_TEST_BUYERS: Array<[string, string, string, string, string?, string?]> = [
+  ["0089238373", "251911091245", "Taxpayer A", "codethicaet@gmail.com", "Near Airport", "101"],
+  ["0054864576", "251911091245", "Taxpayer B", "shehir8@gmail.com", "Near Airport"],
+  ["0049056594", "251911091245", "Taxpayer C", "teme@odooethiopia.com", "Near Airport"],
+  ["0059819904", "251911091245", "Taxpayer D", "rubiethoplc@gmail.com", "Near Airport"],
+  ["0000018932", "251911091245", "Taxpayer E", "amanuelephremedu@gmail.com", "Near Airport"],
+  ["0088683375", "251911091245", "Taxpayer F", "ermiastegegn576@gmail.com", "Near Airport"],
+  ["0068421445", "251911091245", "Taxpayer G", "qelemmeda@gmail.com", "Near Airport"],
+  ["0004404844", "251911091245", "Taxpayer H", "dagnegamu24@gmail.com"],
+  ["0000037187", "251911091245", "Taxpayer I", "deresr.belay@gmail.com"],
+  ["0050167460", "251911091245", "Taxpayer J", "sera2013ec@gmail.com"],
+  ["0079690836", "251909978781", "Taxpayer K", "asmeradefa@gmail.com"],
+  ["0068180813", "251944310004", "Taxpayer L", "hailelt@gmail.com"],
+  ["0083907363", "251944310004", "Taxpayer M", "dawitfissha1@gmail.com"],
+  ["0089032785", "251944310004", "Taxpayer N", "tewahido11@gmail.com"],
+  ["0003826418", "251944310004", "Taxpayer O", "alemayehu.t@marakisoft.com"],
+  ["0053374665", "251944310004", "Taxpayer P", "getlelaw@gmail.com"],
+  ["0016175194", "251911463482", "Taxpayer Q", "abiye.abi@gmail.com", "Near Airport"],
+  ["0094542975", "251911463482", "Taxpayer R", "abelgebreananya@gmail.com"],
+  // MoR's roster carries an 11-digit phone here; kept verbatim rather than "corrected".
+  ["0088514835", "25191124368", "Taxpayer S", "ewnget77@gmail.com"],
+  ["0076217301", "251960403750", "Taxpayer T", "merontamirat.redcloud@gmail.com"],
+  ["0003826419", "251911516507", "Taxpayer 322", "alemayehu.t@marakisoft.com"],
+  ["0056961577", "251929020729", "Taxpayer 323", "ltictsolution@gmail.com", undefined, "1234B"],
+  ["0090853345", "251911376145", "Taxpayer 324", "kidusgoshu2be@gmail.com"],
+  ["0000028643", "251988899003", "Taxpayer 325", "mesaysisay10@gmail.com"],
+  ["0057751727", "251911437928", "Taxpayer 326", "zewdugeta@gmail.com"],
+  ["0082549522", "251907256543", "Taxpayer 327", "brookgm2@gmail.com"],
+  ["0093283311", "251953915419", "Taxpayer 328", "henock.ad@gmail.com"],
+  ["0078795374", "251911091245", "Taxpayer 329", "danielltadesse@gmail.com"],
+  ["0093346931", "251935724920", "Taxpayer 330", "halidabd63@gmail.com"],
+  ["0040887091", "251913792959", "Taxpayer 331", "milextech@gmail.com"],
+];
+
+async function seedMorTestBuyers(): Promise<void> {
+  await AppDataSource.initialize();
+  try {
+    for (const [tin, phone, name, email, kebele, houseNo] of MOR_TEST_BUYERS) {
+      await AppDataSource.query(
+        `INSERT INTO freight.companies
+           (name, type, kind, status, tin, country, region, zone, woreda, kebele,
+            house_no, phone, email)
+         VALUES ($1, 'customer', 'commercial', 'active', $2, 'Ethiopia', 'Addis Ababa', 'Bole',
+                 'NO WOREDA-144', $3, $4, $5, $6)
+         ON CONFLICT (tin) DO NOTHING`,
+        [name, tin, kebele ?? KEBELE, houseNo ?? HOUSE_NO, phone, email],
+      );
+    }
+
+    const summary = await AppDataSource.query(
+      `SELECT count(*)::int AS on_file,
+              count(*) FILTER (WHERE name LIKE 'Taxpayer %')::int AS seeded
+         FROM freight.companies
+        WHERE tin = ANY($1::text[])`,
+      [MOR_TEST_BUYERS.map(([tin]) => tin)],
+    );
+    console.table(summary);
+    console.log("Seeded MoR EIMS/BSP test buyers.");
+  } finally {
+    await AppDataSource.destroy();
+  }
+}
+
+seedMorTestBuyers().catch((err) => {
+  console.error("MoR test buyer seed failed:", err);
+  process.exit(1);
+});
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index bb83518df..0a3d26d71 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -465,6 +465,13 @@ export const CONTRACT_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:contracts:suspend",
     "Suspend / resume a signed contract",
   ),
+  // Terminal kill switch. Unlike suspend this cannot be undone — the customer
+  // re-submits a fresh contract with the same parameters instead.
+  perm(
+    "a3000001-0001-4000-8000-00000000001c",
+    "edr_freight_app:contracts:cancel",
+    "Cancel a contract (terminal)",
+  ),
 ];
 
 // Historical ids. EdrOrgSeeder no longer sends them — it upserts on `key` and
@@ -652,6 +659,32 @@ export const SHIPPING_LINE_PERMISSIONS: FreightPermissionSeed[] = [
   ),
 ];
 
+// C3. Transit assignments — a transit agent's work on one booking: status,
+// timings and documents. Separate from the booking's transit-assignee handshake,
+// which only decides who will handle customs.
+export const TRANSIT_ASSIGNMENT_PERMISSIONS: FreightPermissionSeed[] = [
+  perm(
+    "d1a00003-0001-4000-8000-000000000001",
+    "edr_freight_app:transit_assignments:view",
+    "View transit assignments",
+  ),
+  perm(
+    "d1a00003-0001-4000-8000-000000000002",
+    "edr_freight_app:transit_assignments:create",
+    "Assign a transit agent to a booking",
+  ),
+  perm(
+    "d1a00003-0001-4000-8000-000000000003",
+    "edr_freight_app:transit_assignments:update",
+    "Update a transit assignment and its documents",
+  ),
+  perm(
+    "d1a00003-0001-4000-8000-000000000004",
+    "edr_freight_app:transit_assignments:delete",
+    "Remove a transit assignment",
+  ),
+];
+
 // Internal chat (Matrix/Element) — sidebar visibility + manual reconcile trigger.
 export const CHAT_PERMISSIONS: FreightPermissionSeed[] = [
   perm(
@@ -1457,6 +1490,22 @@ export const ADDITIONAL_CHARGE_PERMISSIONS: FreightPermissionSeed[] = [
   ),
 ];
 
+// E''. Empty container return requests — customer asks to send empties back on
+// a booking that was sold without the return service; operations price and
+// approve it, the customer pays, then books the date and truck.
+export const EMPTY_RETURN_REQUEST_PERMISSIONS: FreightPermissionSeed[] = [
+  perm(
+    "f2e00002-0001-4000-8000-000000000001",
+    "edr_freight_app:empty_return_requests:view",
+    "View empty container return requests",
+  ),
+  perm(
+    "f2e00002-0001-4000-8000-000000000002",
+    "edr_freight_app:empty_return_requests:review",
+    "Approve or reject an empty container return request",
+  ),
+];
+
 // E'. Train-scheduling finer actions (augment existing view/manage)
 export const SCHEDULING_EXTRA_PERMISSIONS: FreightPermissionSeed[] = [
   perm(
@@ -1883,6 +1932,11 @@ export const NOTIFICATION_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:additional_charges:get_notification",
     "Receive additional charge notifications",
   ),
+  perm(
+    "f3a00001-0001-4000-8000-00000000000a",
+    "edr_freight_app:warehouse_inventory:get_notification",
+    "Receive warehouse desk notifications (containers left behind at loading)",
+  ),
 ];
 
 export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
@@ -1890,6 +1944,7 @@ export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
   ...OVERVIEW_LAYOUT_PERMISSIONS,
   ...CUSTOMER_PERMISSIONS,
   ...SHIPPING_LINE_PERMISSIONS,
+  ...TRANSIT_ASSIGNMENT_PERMISSIONS,
   ...CHAT_PERMISSIONS,
   ...FINANCE_PERMISSIONS,
   ...MILE_PERMISSIONS,
@@ -1898,6 +1953,7 @@ export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
   ...WAREHOUSE_PERMISSIONS,
   ...PORT_TERMINAL_PERMISSIONS,
   ...ADDITIONAL_CHARGE_PERMISSIONS,
+  ...EMPTY_RETURN_REQUEST_PERMISSIONS,
   ...SCHEDULING_EXTRA_PERMISSIONS,
   ...CONFIG_SETTINGS_PERMISSIONS,
   ...STAFF_IAM_PERMISSIONS,
@@ -2034,6 +2090,7 @@ export const FREIGHT_PERMS = {
     clearanceDjActions: "edr_freight_app:contracts:clearance_dj_actions",
     clearanceDutyAdvise: "edr_freight_app:contracts:clearance_duty_advise",
     suspend: "edr_freight_app:contracts:suspend",
+    cancel: "edr_freight_app:contracts:cancel",
     editDocument: "edr_freight_app:contracts:edit_document",
     finalInvoiceRaise: "edr_freight_app:contracts:final_invoice_raise",
     finalInvoiceConfirm: "edr_freight_app:contracts:final_invoice_confirm",
@@ -2118,6 +2175,12 @@ export const FREIGHT_PERMS = {
     // Notification selector, not a route guard — see NOTIFICATION_PERMISSIONS.
     getNotification: "edr_freight_app:customers:get_notification",
   },
+  transitAssignments: {
+    view: "edr_freight_app:transit_assignments:view",
+    create: "edr_freight_app:transit_assignments:create",
+    update: "edr_freight_app:transit_assignments:update",
+    delete: "edr_freight_app:transit_assignments:delete",
+  },
   shippingLines: {
     view: "edr_freight_app:shipping_lines:view",
     create: "edr_freight_app:shipping_lines:create",
@@ -2342,6 +2405,12 @@ export const FREIGHT_PERMS = {
     release: "edr_freight_app:warehouse_inventory:release",
     deliver: "edr_freight_app:warehouse_inventory:deliver",
     inspect: "edr_freight_app:warehouse_inventory:inspect",
+    /**
+     * Notification selector, not a route guard — who gets pinged when cargo is
+     * left behind at loading and needs warehouse space. Assign it to whichever
+     * desk owns that; it grants access to nothing.
+     */
+    getNotification: "edr_freight_app:warehouse_inventory:get_notification",
   },
   interchangeDocuments: {
     view: "edr_freight_app:interchange_documents:view",
@@ -2366,6 +2435,10 @@ export const FREIGHT_PERMS = {
     // Notification selector, not a route guard — see NOTIFICATION_PERMISSIONS.
     getNotification: "edr_freight_app:additional_charges:get_notification",
   },
+  emptyReturnRequests: {
+    view: "edr_freight_app:empty_return_requests:view",
+    review: "edr_freight_app:empty_return_requests:review",
+  },
   settings: {
     fileUpload: {
       view: "edr_freight_app:settings:file_upload:view",
@@ -2779,6 +2852,11 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.contracts.clearanceReview,
     FREIGHT_PERMS.contracts.finalizeClearance,
     FREIGHT_PERMS.contracts.createBooking,
+    // GL rebooks cancelled-wagon credits on the customer's behalf — whoever
+    // cancelled (customer or staff) and whichever side was at fault. Needs to
+    // see the ledger rows and to redeem the credit.
+    FREIGHT_PERMS.bookings.wagonCancellationView,
+    FREIGHT_PERMS.bookings.wagonCancellationRebook,
     FREIGHT_PERMS.contracts.clearanceEtActions,
     FREIGHT_PERMS.contracts.clearanceDutyAdvise,
     FREIGHT_PERMS.contracts.finalInvoiceConfirm,
@@ -2832,6 +2910,9 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.contracts.generateContract,
     ...bothFreightTypes(FREIGHT_PERMS.contracts.signStaff),
     FREIGHT_PERMS.contracts.suspend,
+    // Terminal kill switch, granted alongside suspend on the same desk that
+    // already rejects contracts and cancels bookings.
+    FREIGHT_PERMS.contracts.cancel,
     FREIGHT_PERMS.contracts.editDocument,
     ...BOOKING_DESK_NOTIFICATION_KEYS,
     // Marketing follows up with the customer when a reviewer sends profile
diff --git a/apps/edr-freight-web/backoffice/package.json b/apps/edr-freight-web/backoffice/package.json
index e0ef813e9..7674f924c 100644
--- a/apps/edr-freight-web/backoffice/package.json
+++ b/apps/edr-freight-web/backoffice/package.json
@@ -97,6 +97,7 @@
     "react-markdown": "^9.1.0",
     "react-pdf": "^10.4.1",
     "react-pdf-html": "^2.1.5",
+    "react-phone-number-input": "^3.4.17",
     "react-quill-new": "^3.8.3",
     "react-resizable-panels": "^3.0.6",
     "react-router-dom": "^6.27.0",
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 539f2ee98..f95fe7cca 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -96,6 +96,7 @@ import TrainBuilderDetailPage from "./pages/trainBuilder/TrainBuilderDetailPage"
 import TrainBuilderListPage from "./pages/trainBuilder/TrainBuilderListPage";
 import ArrivalQueuePage from "./pages/warehouses/ArrivalQueuePage";
 import ContainerReturnsPage from "./pages/warehouses/ContainerReturnsPage";
+import EmptyReturnRequestsPage from "./pages/warehouses/EmptyReturnRequestsPage";
 import RegisterFullContainersPage from "./pages/warehouses/RegisterFullContainersPage";
 import DispatchQueuePage from "./pages/warehouses/DispatchQueuePage";
 import ExportDjiboutiUnloadingQueuePage from "./pages/warehouses/ExportDjiboutiUnloadingQueuePage";
@@ -709,6 +710,19 @@ const App = () => {
             </RequirePermission>
           }
         />
+        <Route
+          path="empty-return-requests"
+          element={
+            <RequirePermission
+              permission={[
+                FREIGHT_PERMS.emptyReturnRequests.view,
+                FREIGHT_PERMS.warehouseInventory.view,
+              ]}
+            >
+              <EmptyReturnRequestsPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="register-full-containers"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/auth/cookies.ts b/apps/edr-freight-web/backoffice/src/auth/cookies.ts
index 0292f7f38..dd7edc5a4 100644
--- a/apps/edr-freight-web/backoffice/src/auth/cookies.ts
+++ b/apps/edr-freight-web/backoffice/src/auth/cookies.ts
@@ -1,3 +1,5 @@
+import { POSITION_COOKIE } from "@/shared/utils/positionCookie";
+
 const DEFAULT_PATH = "/";
 const SEVEN_DAYS_IN_SECONDS = 60 * 60 * 24 * 7;
 
@@ -32,6 +34,8 @@ export const clearSessionCookies = () => {
     AUTH_TOKEN_COOKIE,
     REFRESH_TOKEN_COOKIE,
     AUTH_USER_COOKIE,
+    POSITION_COOKIE,
+    // Pre-rename name, still cleared so a stale value cannot outlive logout.
     "current-position-id",
     "selected-position-id",
   ].forEach(clearCookie);
diff --git a/apps/edr-freight-web/backoffice/src/components/PhoneField.test.ts b/apps/edr-freight-web/backoffice/src/components/PhoneField.test.ts
new file mode 100644
index 000000000..b6576f946
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/PhoneField.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import { isSmsReachable, isValidPhone } from "./PhoneField";
+
+/**
+ * `isSmsReachable` mirrors `isDomesticPhone` in the API's otp.service. The two
+ * must agree: this one greys out the SMS option, that one decides whether the
+ * message is actually sent, and a disagreement means the UI promises a text
+ * nobody sends (or hides one that would have worked). These cases are the same
+ * ones the API spec asserts.
+ */
+describe("isSmsReachable", () => {
+  it.each(["+251986680099", "0986680099", "251986680099"])(
+    "accepts Ethiopian mobile form %s",
+    (phone) => expect(isSmsReachable(phone)).toBe(true),
+  );
+
+  it.each(["+25377123456", "25377123456", "77123456"])(
+    "accepts Djibouti mobile form %s",
+    (phone) => expect(isSmsReachable(phone)).toBe(true),
+  );
+
+  it.each([
+    "+14155550123",
+    "+447911123456",
+    "0712345678",
+    "+2519866",
+    "12345",
+    // Djibouti fixed line — valid number, not a mobile the gateway serves.
+    "+25321350000",
+    "+25366123456",
+  ])("rejects unreachable or malformed %s", (phone) =>
+    expect(isSmsReachable(phone)).toBe(false),
+  );
+
+  it.each([undefined, null, ""])("treats %s as unreachable", (phone) =>
+    expect(isSmsReachable(phone)).toBe(false),
+  );
+});
+
+/**
+ * The country-picker input emits a PARTIAL E.164 while the user is still
+ * typing — "+25377" is a non-empty string that will post happily and come back
+ * as a 400 from the API's own IsValidPhone. Forms must treat "non-empty" and
+ * "complete" as different questions, so this is the check they call.
+ */
+describe("isValidPhone", () => {
+  it.each(["+25377834567", "+251911223344"])(
+    "accepts the complete number %s",
+    (phone) => expect(isValidPhone(phone)).toBe(true),
+  );
+
+  it.each(["+253", "+25377", "+2537712", "+251", "+2519112"])(
+    "rejects the partial number %s the picker emits mid-typing",
+    (phone) => expect(isValidPhone(phone)).toBe(false),
+  );
+
+  it.each([undefined, null, ""])("treats %s as invalid", (phone) =>
+    expect(isValidPhone(phone)).toBe(false),
+  );
+});
diff --git a/apps/edr-freight-web/backoffice/src/components/PhoneField.tsx b/apps/edr-freight-web/backoffice/src/components/PhoneField.tsx
new file mode 100644
index 000000000..8714ccd8d
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/PhoneField.tsx
@@ -0,0 +1,107 @@
+import { Input, TextInput } from "@mantine/core";
+import RPNInput, { isValidPhoneNumber } from "react-phone-number-input";
+import "react-phone-number-input/style.css";
+import "./phone-field.css";
+
+/**
+ * The countries the railway operates between, and the only two the SMS gateway
+ * is contracted to reach (see `REACHABLE_MOBILE_PATTERNS` in the API's
+ * otp.service). Restricting the picker to them keeps staff from entering a
+ * number that would validate but could never receive an activation link.
+ */
+export const SUPPORTED_PHONE_COUNTRIES = ["DJ", "ET"] as const;
+
+/**
+ * Djibouti — most accounts entered here (transit agents above all) are
+ * Djibouti-side, so it saves the picker interaction on the common case.
+ */
+export const DEFAULT_PHONE_COUNTRY = "DJ";
+
+/**
+ * Re-exported so callers can validate before submitting.
+ *
+ * Needed because the input emits a PARTIAL E.164 while the user is still
+ * typing — "+25377" and "+2537712" are non-empty strings that reach a payload
+ * happily and then come back as a 400 from the API's own `IsValidPhone`. A
+ * caller must treat "non-empty" and "complete" as different questions.
+ */
+export const isValidPhone = (value?: string | null): boolean =>
+  !!value && isValidPhoneNumber(value);
+
+/**
+ * Whether the SMS gateway can actually reach this number.
+ *
+ * Mirrors `isDomesticPhone` in the API's otp.service — Ethiopian `+2519…` and
+ * Djiboutian `+25377…` mobiles. Anything else (a landline, another country) is
+ * queued and silently lost, so the UI offers email instead of promising an SMS.
+ */
+export function isSmsReachable(rawPhone?: string | null): boolean {
+  if (!rawPhone) return false;
+  const digits = rawPhone.trim().replace(/[^\d+]/g, "");
+  const bare = digits.replace(/^\+/, "").replace(/^0+/, "");
+  const normalized = digits.startsWith("+")
+    ? digits
+    : /^251\d{9}$|^253\d{8}$/.test(digits)
+      ? `+${digits}`
+      : /^9\d{8}$|^7\d{8}$/.test(bare)
+        ? `+251${bare}`
+        : /^77\d{6}$/.test(bare)
+          ? `+253${bare}`
+          : digits;
+  return /^\+2519\d{8}$/.test(normalized) || /^\+25377\d{6}$/.test(normalized);
+}
+
+export interface PhoneFieldProps {
+  label?: string;
+  value?: string;
+  onChange: (value: string | undefined) => void;
+  error?: string;
+  required?: boolean;
+  disabled?: boolean;
+  placeholder?: string;
+  description?: string;
+}
+
+/**
+ * Phone input with a country selector, limited to Ethiopia and Djibouti.
+ * Emits a single E.164 value (e.g. +251912345678, +25377123456) so the API
+ * never has to guess a country from a bare local number.
+ */
+export function PhoneField({
+  label,
+  value,
+  onChange,
+  error,
+  required,
+  disabled,
+  placeholder = "77 83 45 67",
+  description,
+}: PhoneFieldProps) {
+  return (
+    <Input.Wrapper
+      label={label}
+      required={required}
+      error={error}
+      description={description}
+      styles={{ label: { fontWeight: 600, fontSize: 14, color: "#10202F" } }}
+    >
+      <div
+        className={`edr-phone-wrapper${error ? " edr-phone-wrapper--error" : ""}`}
+      >
+        <RPNInput
+          international
+          defaultCountry={DEFAULT_PHONE_COUNTRY}
+          countries={[...SUPPORTED_PHONE_COUNTRIES]}
+          countryCallingCodeEditable={false}
+          value={value}
+          onChange={onChange}
+          inputComponent={TextInput}
+          disabled={disabled}
+          placeholder={placeholder}
+        />
+      </div>
+    </Input.Wrapper>
+  );
+}
+
+export default PhoneField;
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
index dc7286b5c..f2d6c07d4 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
@@ -30,6 +30,13 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
   );
 
   const isBulk = booking.freightType === "BULK";
+  // NUMBER_OF_WAGONS cargo is booked by a wagon COUNT, not by tonnage — the
+  // count the customer fixed is what allocation and per-wagon pricing use, so
+  // it belongs on the card next to the weight.
+  const requestedWagons =
+    isBulk && booking.cargoType?.unitOfMeasure === "NUMBER_OF_WAGONS"
+      ? Number(booking.bulkRequestedWagons ?? 0) || null
+      : null;
   // Bulk: the commodity itself (Wheat, Steel…) is the headline. Containers:
   // the freight kind, with the shipper's own description alongside.
   const cargoHeadline = isBulk
@@ -46,6 +53,11 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
         <Badge variant="light" color={isBulk ? "orange" : "blue"} radius="sm">
           {isBulk ? "Bulk" : "Container"}
         </Badge>
+        {requestedWagons != null ? (
+          <Badge variant="light" color="grape" radius="sm">
+            {requestedWagons} wagon{requestedWagons === 1 ? "" : "s"}
+          </Badge>
+        ) : null}
         {cargoDescription ? (
           <Text size="sm" c="dimmed">
             — {cargoDescription}
@@ -62,6 +74,9 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
           }
         />
         <MetricTile label="Total VGM" value={`${tons} tons`} />
+        {requestedWagons != null && (
+          <MetricTile label="Wagons booked" value={`${requestedWagons}`} />
+        )}
         {items != null && <MetricTile label="Items" value={`${items}`} />}
         <MetricTile
           label="Hazardous"
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingWagonsPanel.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingWagonsPanel.tsx
new file mode 100644
index 000000000..456c9f3d6
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingWagonsPanel.tsx
@@ -0,0 +1,255 @@
+import { useMemo, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import {
+  Badge,
+  Button,
+  Center,
+  Group,
+  Loader,
+  SimpleGrid,
+  Stack,
+  Table,
+  Text,
+} from "@mantine/core";
+import { Container, FileSpreadsheet, Train } from "lucide-react";
+import toast from "react-hot-toast";
+
+import { api } from "@/services/api";
+import { bookingsService } from "@/services/bookings.service";
+import { extractDownloadErrorMessage } from "@/components/warehouses/options";
+import { formatDate } from "@/lib/format";
+import type { BookingWagonRow } from "@/types/trainScheduling";
+
+import { SectionCard } from "./SectionCard";
+import { MetricTile } from "./MetricTile";
+
+/** pg returns numerics as strings; everything here is arithmetic on tons/metres. */
+const num = (value: number | string | null | undefined): number => {
+  const parsed = Number(value ?? 0);
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+
+const tons = (value: number | string | null | undefined): string =>
+  `${num(value).toLocaleString(undefined, { maximumFractionDigits: 3 })} t`;
+
+/** Allocation status → badge colour. PLANNED is the pre-loading default. */
+const STATUS_COLORS: Record<string, string> = {
+  PLANNED: "blue",
+  LOADED: "edr-green",
+  UNLOADED: "gray",
+  CANCELLED: "red",
+};
+
+/**
+ * The booking detail page's "Wagons" tab: every wagon allocated to this booking,
+ * with its containers or bulk load, plus an Excel export of the same list.
+ *
+ * A booking has no wagons until it is paid and placed on a train, so the empty
+ * state is the normal case for most of a booking's life — it explains the
+ * precondition rather than reading as an error.
+ */
+export function BookingWagonsPanel({
+  bookingId,
+  bookingReference,
+}: {
+  bookingId: string;
+  bookingReference: string;
+}) {
+  const [exporting, setExporting] = useState(false);
+
+  const { data, isLoading, isError } = useQuery(
+    api.trainScheduling.bookingWagons.queryOptions({ input: { bookingId } }),
+  );
+
+  const wagons = useMemo<BookingWagonRow[]>(() => data ?? [], [data]);
+
+  const totals = useMemo(() => {
+    const containerCount = wagons.reduce(
+      (sum, w) => sum + (w.containers?.length ?? 0),
+      0,
+    );
+    const allocated = wagons.reduce(
+      (sum, w) => sum + num(w.allocatedWeightTons),
+      0,
+    );
+    const capacity = wagons.reduce((sum, w) => sum + num(w.capacityTons), 0);
+    return { containerCount, allocated, capacity };
+  }, [wagons]);
+
+  // The train is a property of the allocation, so every wagon on this booking
+  // carries the same one — read it off the first row rather than per row.
+  const train = wagons[0];
+
+  const handleExport = async () => {
+    setExporting(true);
+    try {
+      const blob = await bookingsService.downloadWagonsWorkbook(bookingId);
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = `wagons-${bookingReference}.xlsx`;
+      a.click();
+      URL.revokeObjectURL(url);
+    } catch (error) {
+      // Blob response: the JSON reason is inside the Blob, so the sync path
+      // would surface only "Request failed with status code 400".
+      toast.error(await extractDownloadErrorMessage(error));
+    } finally {
+      setExporting(false);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <Center py="xl">
+        <Loader size="sm" />
+      </Center>
+    );
+  }
+
+  return (
+    <SectionCard
+      icon={Train}
+      title="Allocated wagons"
+      subtitle={
+        wagons.length
+          ? `${wagons.length} wagon${wagons.length === 1 ? "" : "s"}${
+              train?.trainNumber ? ` on train ${train.trainNumber}` : ""
+            }`
+          : "No wagons allocated yet"
+      }
+      extra={
+        <Button
+          size="compact-sm"
+          variant="light"
+          color="edr-green"
+          leftSection={<FileSpreadsheet size={15} />}
+          loading={exporting}
+          // The sheet would be headers with no rows — nothing to hand over.
+          disabled={wagons.length === 0}
+          onClick={() => void handleExport()}
+        >
+          Export Excel
+        </Button>
+      }
+    >
+      {isError ? (
+        <Text size="sm" c="red">
+          Could not load the wagon allocations for this booking.
+        </Text>
+      ) : wagons.length === 0 ? (
+        <Text size="sm" c="dimmed">
+          Wagons appear here once the booking is paid and allocated onto a train.
+        </Text>
+      ) : (
+        <Stack gap="lg">
+          <SimpleGrid cols={{ base: 2, sm: 4 }} spacing="sm">
+            <MetricTile label="Wagons" value={String(wagons.length)} />
+            <MetricTile
+              label="Containers"
+              value={String(totals.containerCount)}
+            />
+            <MetricTile label="Allocated" value={tons(totals.allocated)} />
+            <MetricTile label="Capacity" value={tons(totals.capacity)} />
+          </SimpleGrid>
+
+          {train?.departureAt ? (
+            <Group gap="xs">
+              <Text size="xs" c="dimmed">
+                Departs {formatDate(train.departureAt)}
+              </Text>
+              {train.originStation && train.destinationStation ? (
+                <Text size="xs" c="dimmed">
+                  · {train.originStation} → {train.destinationStation}
+                </Text>
+              ) : null}
+            </Group>
+          ) : null}
+
+          <Table.ScrollContainer minWidth={720}>
+            <Table striped highlightOnHover verticalSpacing="sm">
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th>Seq</Table.Th>
+                  <Table.Th>Wagon</Table.Th>
+                  <Table.Th>Type</Table.Th>
+                  <Table.Th>Status</Table.Th>
+                  <Table.Th ta="right">Allocated</Table.Th>
+                  <Table.Th ta="right">Capacity</Table.Th>
+                  <Table.Th>Load</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {wagons.map((w) => (
+                  <Table.Tr key={w.allocationId}>
+                    <Table.Td>
+                      <Text size="sm" c="dimmed">
+                        {w.sequenceNo ?? "—"}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td>
+                      <Text size="sm" fw={600}>
+                        {w.wagonNumber ?? "—"}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td>
+                      <Text size="sm">{w.wagonType ?? "—"}</Text>
+                    </Table.Td>
+                    <Table.Td>
+                      <Badge
+                        size="sm"
+                        variant="light"
+                        color={STATUS_COLORS[w.status] ?? "gray"}
+                      >
+                        {w.status}
+                      </Badge>
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Text size="sm">{tons(w.allocatedWeightTons)}</Text>
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Text size="sm" c="dimmed">
+                        {tons(w.capacityTons)}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td>
+                      {w.containers?.length ? (
+                        <Stack gap={2}>
+                          {w.containers.map((c, i) => (
+                            <Group
+                              key={`${w.allocationId}-${c.containerNumber ?? i}`}
+                              gap={6}
+                              wrap="nowrap"
+                            >
+                              <Container
+                                size={13}
+                                style={{ opacity: 0.5, flexShrink: 0 }}
+                              />
+                              <Text size="xs">
+                                {c.containerNumber ?? "—"}
+                                {c.sizeFt ? ` · ${c.sizeFt}ft` : ""}
+                              </Text>
+                            </Group>
+                          ))}
+                        </Stack>
+                      ) : w.bulkCargoDescription || w.loadType === "BULK" ? (
+                        <Text size="xs">
+                          {w.bulkCargoDescription ?? "Bulk"}
+                          {w.bulkQuantity ? ` · ${num(w.bulkQuantity)}` : ""}
+                        </Text>
+                      ) : (
+                        <Text size="xs" c="dimmed">
+                          —
+                        </Text>
+                      )}
+                    </Table.Td>
+                  </Table.Tr>
+                ))}
+              </Table.Tbody>
+            </Table>
+          </Table.ScrollContainer>
+        </Stack>
+      )}
+    </SectionCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts b/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
index 23f9b2bd8..d23b75f43 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
@@ -3,6 +3,7 @@ export * from "./SectionCard";
 export * from "./ClearanceReviewSection";
 export * from "./BookingDocumentsPanel";
 export * from "./BookingTrucksPanel";
+export * from "./BookingWagonsPanel";
 export * from "./ContractOrdersPanel";
 export * from "./MetricTile";
 export * from "./BookingDetailToolbar";
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/RebookWagonCancellationModal.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/RebookWagonCancellationModal.tsx
new file mode 100644
index 000000000..318ce3f9b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/RebookWagonCancellationModal.tsx
@@ -0,0 +1,407 @@
+import { useEffect, useMemo, useState } from "react";
+import { Button, Group, Modal, Select, Stack, Text, TextInput } from "@mantine/core";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import toast from "react-hot-toast";
+import { OperationDatePicker } from "@edr/ui-common";
+
+import { api } from "@/auth/http";
+import { api as rpc } from "@/services/api";
+import { formatMoney } from "@/lib/format";
+import {
+  hasOddFt20,
+  type RebookPartnerCandidate,
+  type WagonCancellation,
+} from "./types";
+
+
+/** Editable rebook unit — prefilled from the cancelled snapshot. */
+interface RebookUnitDraft {
+  containerSize: string;
+  containerNumber: string;
+  sealNumber: string;
+  vgmTons: number | "";
+}
+
+/** Editable unit on the consolidation partner — prefilled from its own cargo. */
+interface PartnerUnitDraft {
+  id: string;
+  containerSize: string;
+  containerNumber: string;
+  sealNumber: string;
+  vgmTons: number | "";
+}
+
+const partnerDraftsFrom = (c: RebookPartnerCandidate | undefined) =>
+  (c?.units ?? []).map((u) => ({
+    id: u.id,
+    containerSize: u.containerSize,
+    containerNumber: u.containerNumber,
+    sealNumber: u.sealNumber ?? "",
+    vgmTons: Number(u.vgmTons) || ("" as const),
+  }));
+
+/** Only the units GL actually changed are sent. */
+const partnerUnitsPayload = (
+  drafts: PartnerUnitDraft[],
+  original: PartnerUnitDraft[],
+) =>
+  drafts
+    .filter((d, i) => {
+      const o = original[i];
+      return (
+        !o ||
+        d.containerNumber !== o.containerNumber ||
+        d.sealNumber !== o.sealNumber ||
+        d.vgmTons !== o.vgmTons
+      );
+    })
+    .map((d) => ({
+      id: d.id,
+      containerNumber: d.containerNumber.trim(),
+      sealNumber: d.sealNumber.trim(),
+      ...(d.vgmTons !== "" ? { vgmTons: Number(d.vgmTons) } : {}),
+    }));
+
+const draftsFrom = (r: WagonCancellation): RebookUnitDraft[] =>
+  (r.cancelledQuantities?.units ?? []).map((u) => ({
+    containerSize: u.containerSize,
+    containerNumber: u.containerNumber,
+    sealNumber: u.sealNumber ?? "",
+    vgmTons: Number(u.vgmTons) || "",
+  }));
+
+const containersPayload = (drafts: RebookUnitDraft[]) => {
+  const bySize = new Map<string, RebookUnitDraft[]>();
+  for (const d of drafts) {
+    bySize.set(d.containerSize, [...(bySize.get(d.containerSize) ?? []), d]);
+  }
+  return [...bySize.entries()].map(([containerSize, units]) => ({
+    containerSize,
+    units: units.map((u) => ({
+      containerNumber: u.containerNumber.trim(),
+      ...(u.sealNumber.trim() ? { sealNumber: u.sealNumber.trim() } : {}),
+      ...(u.vgmTons !== "" ? { vgmTons: Number(u.vgmTons) } : {}),
+    })),
+  }));
+};
+
+/**
+ * Staff/GL rebook of a CREDIT_AVAILABLE wagon cancellation: pick the shipment
+ * day, correct container details if they changed, and — for an odd-20ft
+ * credit — pick the consolidation partner that shares the wagon. The server
+ * creates the new booking under the contract and marks it PAID from the credit.
+ * Used by the wagon-cancellations list, the GL clearance page and the staff
+ * booking page, so every desk gets the same flow.
+ */
+export function RebookWagonCancellationModal({
+  cancellation,
+  onClose,
+  onRebooked,
+}: {
+  cancellation: WagonCancellation | null;
+  onClose: () => void;
+  /** Called after a successful rebook with the new booking id (when the API returns it). */
+  onRebooked?: (result: { bookingId?: string }) => void;
+}) {
+  // Held as the picker's own `yyyy-MM-dd` string, never a Date: converting a
+  // local-midnight Date back with toISOString() shifts it into the previous day
+  // in any timezone east of UTC (EAT is +03), which both mis-rendered the
+  // selection and submitted the wrong shipment day.
+  const [date, setDate] = useState<string | null>(null);
+  const [partnerId, setPartnerId] = useState<string | null>(null);
+  const [partnerDrafts, setPartnerDrafts] = useState<PartnerUnitDraft[]>([]);
+  const [drafts, setDrafts] = useState<RebookUnitDraft[]>([]);
+
+  // Fresh form per row: the modal instance is long-lived on the host page.
+  useEffect(() => {
+    setDate(null);
+    setPartnerId(null);
+    setPartnerDrafts([]);
+    setDrafts(cancellation ? draftsFrom(cancellation) : []);
+  }, [cancellation]);
+
+  const needsPartner = cancellation ? hasOddFt20(cancellation) : false;
+
+  // The rebook rides the same lane with the same cargo as the cancelled
+  // shipment, so the shipment day must come from the days that lane actually
+  // runs — an arbitrary calendar day has no train and no wagon capacity.
+  const daysQuery = useMemo(() => {
+    const b = cancellation?.booking;
+    if (!b?.originYardId || !b?.destinationYardId) return null;
+    const containers = Object.entries(
+      cancellation?.cancelledQuantities?.bySize ?? {},
+    )
+      .map(([containerSize, quantity]) => ({
+        containerSize,
+        quantity: Number(quantity || 0),
+      }))
+      .filter((c) => c.quantity >= 1);
+    if (containers.length > 0) {
+      return {
+        originYardId: b.originYardId,
+        destinationYardId: b.destinationYardId,
+        freightType: "CONTAINER" as const,
+        containers,
+      };
+    }
+    const tons = Number(cancellation?.weightTons || 0);
+    if (tons <= 0) return null;
+    return {
+      originYardId: b.originYardId,
+      destinationYardId: b.destinationYardId,
+      freightType: "BULK" as const,
+      totalWeightTons: tons,
+    };
+  }, [cancellation]);
+
+  const { data: availableDays, isLoading: daysLoading } = useQuery({
+    ...rpc.trainScheduling.availableDaysForCargo.queryOptions({
+      input: daysQuery ?? { freightType: "BULK" as const },
+    }),
+    enabled: Boolean(cancellation) && daysQuery !== null,
+  });
+  const partners = useQuery({
+    queryKey: [
+      "wagon-cancellations",
+      cancellation?.id,
+      "rebook-partners",
+      date,
+    ],
+    enabled: Boolean(cancellation && needsPartner && date),
+    queryFn: async () => {
+      const res = await api.get<RebookPartnerCandidate[]>(
+        `/bookings/wagon-cancellations/${cancellation!.id}/rebook-partners`,
+        { params: { scheduledDate: date } },
+      );
+      return res.data;
+    },
+  });
+
+  const rebook = useMutation({
+    mutationFn: async () => {
+      const res = await api.post<{ bookingId?: string }>(
+        `/bookings/wagon-cancellations/${cancellation!.id}/rebook`,
+        {
+          scheduledDate: date,
+          ...(drafts.length ? { containers: containersPayload(drafts) } : {}),
+          ...(partnerId ? { partnerBookingId: partnerId } : {}),
+          ...(() => {
+            if (!partnerId) return {};
+            const original = partnerDraftsFrom(
+              (partners.data ?? []).find((c) => c.id === partnerId),
+            );
+            const changed = partnerUnitsPayload(partnerDrafts, original);
+            return changed.length ? { partnerUnits: changed } : {};
+          })(),
+        },
+      );
+      return res.data ?? {};
+    },
+  });
+
+  const patchPartnerDraft = (i: number, patch: Partial<PartnerUnitDraft>) =>
+    setPartnerDrafts((prev) =>
+      prev.map((d, idx) => (idx === i ? { ...d, ...patch } : d)),
+    );
+
+  const patchDraft = (i: number, patch: Partial<RebookUnitDraft>) =>
+    setDrafts((prev) => prev.map((x, idx) => (idx === i ? { ...x, ...patch } : x)));
+
+  return (
+    <Modal
+      opened={!!cancellation}
+      onClose={onClose}
+      title="Rebook cancelled wagons"
+      centered
+      radius="md"
+      // Wide enough for the calendar plus two container-unit editors side by
+      // side without the number / seal / VGM fields cramping.
+      size="xl"
+    >
+      {cancellation && (
+        <Stack gap="sm">
+          <Text size="sm">
+            {cancellation.booking?.reference ?? cancellation.bookingId} ·{" "}
+            {cancellation.wagonsCancelled} wagon(s) · credit{" "}
+            {formatMoney(cancellation.creditAmount, cancellation.feeCurrency, 2)}
+          </Text>
+          <Text size="sm" fw={600}>
+            Shipment day
+          </Text>
+          <OperationDatePicker
+            fullWidth
+            availableDays={daysQuery === null ? [] : (availableDays ?? [])}
+            isLoading={daysQuery !== null && daysLoading}
+            emptyMessage={
+              daysQuery === null
+                ? "This cancellation has no route or cargo on record — the available shipment days cannot be worked out."
+                : "No train day on this route can take this cargo right now."
+            }
+            value={date ?? ""}
+            onChange={(d) => {
+              setDate(d || null);
+              setPartnerId(null);
+              setPartnerDrafts([]);
+            }}
+          />
+          {needsPartner && (
+            <Select
+              label="Consolidation partner"
+              description="This credit has an odd 20ft container — pick the odd booking that shares its wagon. The rebooked booking is paid; it ships once the partner pays."
+              withAsterisk
+              placeholder={
+                !date
+                  ? "Pick the day first"
+                  : partners.isLoading
+                    ? "Loading…"
+                    : "Pick the partner booking"
+              }
+              data={(partners.data ?? []).map((c) => ({
+                value: c.id,
+                label: `${c.reference} · ${c.companyName ?? "—"} · ${c.ft20Quantity}×20ft`,
+              }))}
+              value={partnerId}
+              onChange={(v) => {
+                setPartnerId(v);
+                setPartnerDrafts(
+                  partnerDraftsFrom(
+                    (partners.data ?? []).find((c) => c.id === v),
+                  ),
+                );
+              }}
+              disabled={!date}
+              searchable
+              radius="md"
+            />
+          )}
+          {needsPartner &&
+            date &&
+            !partners.isLoading &&
+            (partners.data ?? []).length === 0 && (
+              <Text size="xs" c="orange">
+                No odd-20ft booking rides that day — pick another day, or wait
+                for a booking that can share this wagon.
+              </Text>
+            )}
+          {partnerId && partnerDrafts.length > 0 && (
+            <Stack gap={6}>
+              <Text size="xs" fw={600}>
+                Partner containers
+              </Text>
+              <Text size="xs" c="dimmed">
+                Correct the partner booking's own container details if they
+                changed — sizes and quantities stay as booked.
+              </Text>
+              {partnerDrafts.map((d, i) => (
+                <Group key={d.id} gap={8} wrap="nowrap" align="flex-end">
+                  <TextInput
+                    label={`${d.containerSize || "Container"}`}
+                    value={d.containerNumber}
+                    onChange={(e) =>
+                      patchPartnerDraft(i, {
+                        containerNumber: e.currentTarget.value,
+                      })
+                    }
+                    size="xs"
+                    radius="md"
+                    style={{ flex: 1.4 }}
+                  />
+                  <TextInput
+                    label="Seal no."
+                    value={d.sealNumber}
+                    onChange={(e) =>
+                      patchPartnerDraft(i, { sealNumber: e.currentTarget.value })
+                    }
+                    size="xs"
+                    radius="md"
+                    style={{ flex: 1 }}
+                  />
+                  <TextInput
+                    label="VGM (t)"
+                    type="number"
+                    value={d.vgmTons === "" ? "" : String(d.vgmTons)}
+                    onChange={(e) => {
+                      const raw = e.currentTarget.value;
+                      patchPartnerDraft(i, {
+                        vgmTons: raw === "" ? "" : Number(raw),
+                      });
+                    }}
+                    size="xs"
+                    radius="md"
+                    style={{ width: 90 }}
+                  />
+                </Group>
+              ))}
+            </Stack>
+          )}
+          {drafts.length > 0 && (
+            <Stack gap={6}>
+              <Text size="xs" fw={600}>
+                This booking's containers
+              </Text>
+              <Text size="xs" c="dimmed">
+                Correct the container details if they changed — sizes and
+                quantities stay as cancelled.
+              </Text>
+              {drafts.map((d, i) => (
+                <Group key={i} gap={8} wrap="nowrap" align="flex-end">
+                  <TextInput
+                    label={`${d.containerSize} container`}
+                    value={d.containerNumber}
+                    onChange={(e) => patchDraft(i, { containerNumber: e.currentTarget.value })}
+                    size="xs"
+                    radius="md"
+                    style={{ flex: 1.4 }}
+                  />
+                  <TextInput
+                    label="Seal no."
+                    value={d.sealNumber}
+                    onChange={(e) => patchDraft(i, { sealNumber: e.currentTarget.value })}
+                    size="xs"
+                    radius="md"
+                    style={{ flex: 1 }}
+                  />
+                  <TextInput
+                    label="VGM (t)"
+                    type="number"
+                    value={d.vgmTons === "" ? "" : String(d.vgmTons)}
+                    onChange={(e) => {
+                      const raw = e.currentTarget.value;
+                      patchDraft(i, { vgmTons: raw === "" ? "" : Number(raw) });
+                    }}
+                    size="xs"
+                    radius="md"
+                    style={{ width: 90 }}
+                  />
+                </Group>
+              ))}
+            </Stack>
+          )}
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" radius="md" onClick={onClose}>
+              Close
+            </Button>
+            <Button
+              color="green"
+              radius="md"
+              disabled={!date || (needsPartner && !partnerId)}
+              loading={rebook.isPending}
+              onClick={async () => {
+                try {
+                  const result = await rebook.mutateAsync();
+                  toast.success("Credit rebooked as a new paid booking");
+                  onClose();
+                  onRebooked?.(result);
+                } catch {
+                  // interceptor surfaces the reason
+                }
+              }}
+            >
+              Rebook
+            </Button>
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/WagonCancellationCreditCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/WagonCancellationCreditCard.tsx
new file mode 100644
index 000000000..4bca7cced
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/WagonCancellationCreditCard.tsx
@@ -0,0 +1,141 @@
+import { useState } from "react";
+import { Badge, Button, Group, Stack, Text } from "@mantine/core";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { RotateCcw } from "lucide-react";
+import { Link } from "react-router-dom";
+
+import { api } from "@/auth/http";
+import { useAuth } from "@/auth/useAuth";
+import { SectionCard } from "@/components/bookings/detail/SectionCard";
+import { formatDate, formatMoney } from "@/lib/format";
+import { RebookWagonCancellationModal } from "./RebookWagonCancellationModal";
+import {
+  canRebookWagonCancellations,
+  isRebookableCredit,
+  WAGON_CANCELLATION_STATUS_CHIP,
+  type WagonCancellation,
+  type WagonCancellationListResponse,
+} from "./types";
+
+/**
+ * Per-booking wagon-cancellation ledger with the GL/staff "Rebook" action.
+ * Rendered on the booking pages GL and staff actually work from, so a credit
+ * never sits unredeemed just because the customer cannot rebook it from the
+ * portal (customs bookings, odd-20ft credits) — whoever cancelled the wagons
+ * and whichever side was at fault. Renders nothing when the booking has no
+ * cancellations.
+ */
+export function WagonCancellationCreditCard({
+  bookingId,
+  onRebooked,
+}: {
+  bookingId: string;
+  onRebooked?: () => void;
+}) {
+  const { user } = useAuth();
+  const qc = useQueryClient();
+  const canRebook = canRebookWagonCancellations(user);
+  const [rebooking, setRebooking] = useState<WagonCancellation | null>(null);
+
+  const { data, refetch } = useQuery({
+    queryKey: ["bookings", bookingId, "wagon-cancellations"],
+    queryFn: async () => {
+      const res = await api.get<WagonCancellationListResponse | WagonCancellation[]>(
+        `/bookings/${bookingId}/wagon-cancellations`,
+      );
+      const body = res.data;
+      return Array.isArray(body) ? body : (body?.items ?? []);
+    },
+  });
+
+  const rows = data ?? [];
+  if (rows.length === 0) return null;
+
+  return (
+    <>
+      <SectionCard
+        icon={RotateCcw}
+        title="Cancelled wagons"
+        subtitle="Credits from cancelled wagons are rebooked here on the customer's behalf."
+        accent="grape"
+      >
+        <Stack gap="sm">
+          {rows.map((r) => {
+            const chip = WAGON_CANCELLATION_STATUS_CHIP[r.status] ?? {
+              label: r.status,
+              color: "gray",
+            };
+            const feeOpen =
+              r.fault === "CUSTOMER" && Number(r.feeAmount) > 0 && !r.feePaidAt;
+            return (
+              <Group key={r.id} justify="space-between" align="flex-start" wrap="nowrap">
+                <Stack gap={2} style={{ minWidth: 0 }}>
+                  <Group gap={8} wrap="nowrap">
+                    <Text size="sm" fw={600}>
+                      {Number(r.wagonsCancelled)} wagon(s) · credit{" "}
+                      {formatMoney(Number(r.creditAmount), r.feeCurrency, 2)}
+                    </Text>
+                    <Badge color={chip.color} variant="light" size="sm" radius="md">
+                      {chip.label}
+                    </Badge>
+                  </Group>
+                  <Text size="xs" c="dimmed">
+                    Cancelled {formatDate(r.createdAt)}
+                    {r.fault ? ` · ${r.fault === "EDR" ? "EDR fault (no fee)" : "customer fault"}` : ""}
+                    {Number(r.feeAmount) > 0
+                      ? ` · fee ${formatMoney(Number(r.feeAmount), r.feeCurrency, 2)}${
+                          r.feePaidAt ? " paid" : " unpaid"
+                        }`
+                      : ""}
+                    {r.reason ? ` · ${r.reason}` : ""}
+                  </Text>
+                  {r.status === "FEE_PENDING" && (
+                    <Text size="xs" c="orange">
+                      The customer must pay the cancellation fee from the portal
+                      Payments tab before the credit can be rebooked.
+                    </Text>
+                  )}
+                  {isRebookableCredit(r) && feeOpen && (
+                    <Text size="xs" c="orange">
+                      The cancellation fee invoice is still open — the rebook is
+                      allowed once it is paid.
+                    </Text>
+                  )}
+                  {r.rebookedBookingId && (
+                    <Text size="xs">
+                      Rebooked as{" "}
+                      <Link to={`/dashboard/booking-requests/${r.rebookedBookingId}`}>
+                        {r.rebookedBooking?.reference ?? r.rebookedBookingId}
+                      </Link>
+                    </Text>
+                  )}
+                </Stack>
+                {isRebookableCredit(r) && canRebook && (
+                  <Button
+                    size="xs"
+                    radius="md"
+                    variant="light"
+                    color="green"
+                    leftSection={<RotateCcw size={14} />}
+                    onClick={() => setRebooking(r)}
+                  >
+                    Rebook
+                  </Button>
+                )}
+              </Group>
+            );
+          })}
+        </Stack>
+      </SectionCard>
+      <RebookWagonCancellationModal
+        cancellation={rebooking}
+        onClose={() => setRebooking(null)}
+        onRebooked={() => {
+          void refetch();
+          void qc.invalidateQueries({ queryKey: ["bookings"] });
+          onRebooked?.();
+        }}
+      />
+    </>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/index.ts b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/index.ts
new file mode 100644
index 000000000..981050f54
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/index.ts
@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./RebookWagonCancellationModal";
+export * from "./WagonCancellationCreditCard";
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/types.ts b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/types.ts
new file mode 100644
index 000000000..c6a78cc8d
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/wagon-cancellation/types.ts
@@ -0,0 +1,108 @@
+import type { AuthUser } from "@/auth/types";
+import { FREIGHT_PERMS, hasPermission, isDjiboutiGl } from "@/lib/permissions";
+
+export type WagonCancellationStatus =
+  | "FEE_PENDING"
+  | "CREDIT_AVAILABLE"
+  | "REBOOKED"
+  | "WITHDRAWN"
+  | "EXPIRED";
+
+export interface WagonCancellation {
+  id: string;
+  bookingId: string;
+  rebookedBookingId?: string | null;
+  wagonsCancelled: number;
+  weightTons: number;
+  creditAmount: number;
+  feeAmount: number;
+  feeCurrency: string;
+  feeInvoiceId?: string | null;
+  feePaidAt?: string | null;
+  fault?: "CUSTOMER" | "EDR" | string | null;
+  status: WagonCancellationStatus;
+  reason?: string | null;
+  rebookedAt?: string | null;
+  createdAt: string;
+  booking?: {
+    id: string;
+    reference: string;
+    customsClearingEnabled?: boolean;
+    company?: { name: string };
+    /** Route of the cancelled shipment — the rebook rides the same lane, so the
+     *  shipment-day picker offers only days that lane actually runs. */
+    originYardId?: string | null;
+    destinationYardId?: string | null;
+    freightType?: string | null;
+  };
+  rebookedBooking?: { id: string; reference: string };
+  feeInvoice?: { invoiceNumber: string; status: string };
+  cancelledQuantities?: {
+    bySize?: Record<string, number>;
+    units?: Array<{
+      containerSize: string;
+      containerNumber: string;
+      sealNumber?: string | null;
+      vgmTons: number;
+    }>;
+  };
+}
+
+export interface WagonCancellationListResponse {
+  items: WagonCancellation[];
+  total: number;
+}
+
+export interface RebookPartnerUnit {
+  id: string;
+  containerSize: string;
+  containerNumber: string;
+  sealNumber: string | null;
+  vgmTons: number;
+}
+
+export interface RebookPartnerCandidate {
+  id: string;
+  reference: string;
+  companyName: string | null;
+  status: string;
+  scheduledDate: string | null;
+  ft20Quantity: number;
+  /** The partner's own container units — editable while pairing. */
+  units?: RebookPartnerUnit[];
+}
+
+export const WAGON_CANCELLATION_STATUS_CHIP: Record<
+  WagonCancellationStatus,
+  { label: string; color: string }
+> = {
+  FEE_PENDING: { label: "Fee pending", color: "yellow" },
+  CREDIT_AVAILABLE: { label: "Credit available", color: "edr-green" },
+  REBOOKED: { label: "Rebooked", color: "indigo" },
+  WITHDRAWN: { label: "Withdrawn", color: "gray" },
+  EXPIRED: { label: "Expired", color: "red" },
+};
+
+/** Odd 20ft in the credit ⇒ the rebooked booking shares a wagon and GL must pick the partner. */
+export const hasOddFt20 = (r: WagonCancellation): boolean =>
+  Object.entries(r.cancelledQuantities?.bySize ?? {})
+    .filter(([size]) => parseInt(size, 10) === 20)
+    .reduce((sum, [, qty]) => sum + Number(qty || 0), 0) %
+    2 ===
+  1;
+
+/**
+ * Who may redeem a cancelled-wagon credit from the backoffice: anyone holding
+ * the dedicated rebook key, plus GL Ethiopia through its booking-creation key
+ * (a rebook is a new booking under the contract). GL Djibouti never creates
+ * bookings. Mirrors the API's rebook gate.
+ */
+export const canRebookWagonCancellations = (
+  user: AuthUser | null | undefined,
+): boolean =>
+  hasPermission(user, FREIGHT_PERMS.bookings.wagonCancellationRebook) ||
+  (hasPermission(user, FREIGHT_PERMS.contracts.createBooking) && !isDjiboutiGl(user));
+
+/** A CREDIT_AVAILABLE row with real credit — whoever cancelled and whoever was at fault. */
+export const isRebookableCredit = (r: WagonCancellation): boolean =>
+  r.status === "CREDIT_AVAILABLE" && Number(r.creditAmount) > 0;
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ContractActionsToolbar.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ContractActionsToolbar.tsx
index d2a245f24..be70ffe4d 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/ContractActionsToolbar.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/ContractActionsToolbar.tsx
@@ -3,6 +3,7 @@ import { useNavigate } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
 import { Button, Group, Modal, Stack, Text, Textarea } from "@mantine/core";
 import {
+  Ban,
   Check,
   Eye,
   // FilePen, // ponytail: back with the "Edit contract articles" button
@@ -81,6 +82,8 @@ export function ContractActionsToolbar({
   const mayReject = hasPermission(user, FREIGHT_PERMS.contracts.reject[arm]);
   // One key both ways — whoever can freeze a contract can unfreeze it.
   const maySuspend = hasPermission(user, FREIGHT_PERMS.contracts.suspend);
+  // Cancel is its own key — it is terminal, so it is NOT implied by suspend.
+  const mayCancel = hasPermission(user, FREIGHT_PERMS.contracts.cancel);
 
   const [editorOpen, setEditorOpen] = useState(false);
   const [editorMode, setEditorMode] = useState<"accept" | "edit">("accept");
@@ -93,6 +96,67 @@ export function ContractActionsToolbar({
   const [suspendReason, setSuspendReason] = useState("");
   const [resumeOpen, setResumeOpen] = useState(false);
   const [resumeNote, setResumeNote] = useState("");
+  const [cancelOpen, setCancelOpen] = useState(false);
+  const [cancelReason, setCancelReason] = useState("");
+
+  // Shared by the suspended branch and the normal toolbar — both can cancel.
+  const cancelModal = (
+    <Modal
+      opened={cancelOpen}
+      onClose={() => setCancelOpen(false)}
+      title="Cancel this contract?"
+      centered
+    >
+      <Stack gap="md">
+        <Text size="sm">
+          Contract <b>{contract.reference}</b> will be cancelled permanently.
+          This cannot be undone — there is no way to reactivate it. A new
+          contract with the same details can be submitted afterwards. The
+          customer is notified.
+        </Text>
+        <Textarea
+          label="Reason for cancellation"
+          placeholder="Explain why this contract is being cancelled…"
+          autosize
+          minRows={3}
+          value={cancelReason}
+          onChange={(e) => setCancelReason(e.currentTarget.value)}
+        />
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" onClick={() => setCancelOpen(false)}>
+            Keep contract
+          </Button>
+          <Button
+            color="red"
+            disabled={!cancelReason.trim()}
+            loading={mutations.cancelByStaff.isPending}
+            onClick={() =>
+              mutations.cancelByStaff.mutate(cancelReason, {
+                onSuccess: () => {
+                  setCancelOpen(false);
+                  setCancelReason("");
+                },
+              })
+            }
+          >
+            Cancel contract
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+
+  const cancelButton = mayCancel ? (
+    <Button
+      fullWidth
+      variant="light"
+      color="red"
+      leftSection={<Ban size={16} />}
+      onClick={() => setCancelOpen(true)}
+    >
+      Cancel contract
+    </Button>
+  ) : null;
 
   // Whether the document is editable depends on WHO is viewing — only the
   // approver whose turn it is may edit — so the server decides, not the client.
@@ -126,9 +190,13 @@ export function ContractActionsToolbar({
   if (status === "CHANGES_REQUESTED") {
     return (
       <SectionCard icon={Zap} title="Awaiting customer">
-        <Text size="sm" c="dimmed">
-          No staff actions until the customer resubmits the contract.
-        </Text>
+        <Stack gap="sm">
+          <Text size="sm" c="dimmed">
+            No staff actions until the customer resubmits the contract.
+          </Text>
+          {cancelButton}
+        </Stack>
+        {cancelModal}
       </SectionCard>
     );
   }
@@ -166,6 +234,7 @@ export function ContractActionsToolbar({
               You do not have permission to lift a suspension.
             </Text>
           )}
+          {cancelButton}
         </Stack>
 
         <Modal
@@ -209,6 +278,8 @@ export function ContractActionsToolbar({
             </Group>
           </Stack>
         </Modal>
+
+        {cancelModal}
       </SectionCard>
     );
   }
@@ -362,11 +433,16 @@ export function ContractActionsToolbar({
           </Button>
         )}
 
+        {/* Available at every non-terminal status — the early returns above
+            already cover the statuses where cancelling makes no sense. */}
+        {cancelButton}
+
         {!canAccept &&
           !inApproval &&
           !canViewContract &&
           !canReviewClearance &&
-          !canSuspend && (
+          !canSuspend &&
+          !mayCancel && (
             <Text size="sm" c="dimmed">
               No staff actions available for this status. Monitor until the
               workflow advances.
@@ -515,6 +591,8 @@ export function ContractActionsToolbar({
           </Button>
         </Stack>
       </Modal>
+
+      {cancelModal}
     </SectionCard>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
index 86641c7be..0d5a7046a 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
@@ -887,7 +887,9 @@ export default function GlCreateBookingForm() {
         } else if ((numberCounts.get(key) ?? 0) > 1) {
           errs.containerNumber = "Duplicate container number in this shipment.";
         }
-        if (u.sealNumber.trim() === "") {
+        // Every container ships sealed and the yard checks the seal against
+        // the booking — required alongside number and VGM (portal parity).
+        if (!u.sealNumber.trim()) {
           errs.sealNumber = "Seal number is required.";
         }
         const vgm = Number(u.vgmTons);
@@ -1051,6 +1053,12 @@ export default function GlCreateBookingForm() {
 
   const dateError =
     !isIntercity && !scheduledDate ? "Select a shipment date." : undefined;
+  // EXPORT completion locks the booking onto a train. Only raised once a day is
+  // chosen — the picker is hidden until then and the date error covers it.
+  const trainError =
+    isExportPick && scheduledDate && !trainScheduleId
+      ? "Select a train for the shipment day."
+      : undefined;
   const routeError =
     multiRoute && !contractRouteId ? "Select a route." : undefined;
 
@@ -1069,7 +1077,7 @@ export default function GlCreateBookingForm() {
           !e.returnQuantity,
       ) &&
       unitErrors.every((line) =>
-        line.every((e) => !e.containerNumber && !e.vgmTons),
+        line.every((e) => !e.containerNumber && !e.sealNumber && !e.vgmTons),
       ) &&
       !cargoDescriptionError
     : !bulkErrors.quantity &&
@@ -1116,11 +1124,12 @@ export default function GlCreateBookingForm() {
       line.units.some(
         (u) =>
           !ISO_CONTAINER_NUMBER_REGEX.test(u.containerNumber.trim().toUpperCase()) ||
+          !u.sealNumber.trim() ||
           !(Number(u.vgmTons) > 0),
       ),
     );
     if (badUnit) {
-      return `Every ${partner.reference} container needs a valid container number and a VGM above 0.`;
+      return `Every ${partner.reference} container needs a valid container number, a seal number and a VGM above 0.`;
     }
     if (!partnerCargoDescription.trim()) {
       return `Describe the cargo carried in ${partner.reference}'s containers.`;
@@ -1146,6 +1155,7 @@ export default function GlCreateBookingForm() {
     cargoValid &&
     !oddBlocksSubmit &&
     !dateError &&
+    !trainError &&
     !routeError &&
     !partnerError &&
     !currencyError;
@@ -1905,7 +1915,7 @@ export default function GlCreateBookingForm() {
                             style={{ flex: 1 }}
                           />
                           <TextInput
-                            placeholder="e.g. SL-0099231"
+                            placeholder="e.g. SL0123456"
                             value={unit.sealNumber}
                             error={
                               showErrors
@@ -2314,12 +2324,19 @@ export default function GlCreateBookingForm() {
                 </Text>
               )}
               {isExportPick && scheduledDate ? (
-                <ExportTrainPicker
-                  options={exportTrainsQuery.data ?? []}
-                  loading={exportTrainsQuery.isLoading}
-                  value={trainScheduleId}
-                  onChange={setTrainScheduleId}
-                />
+                <>
+                  <ExportTrainPicker
+                    options={exportTrainsQuery.data ?? []}
+                    loading={exportTrainsQuery.isLoading}
+                    value={trainScheduleId}
+                    onChange={setTrainScheduleId}
+                  />
+                  {showErrors && trainError && (
+                    <Text fz="xs" c="red" mt={6}>
+                      {trainError}
+                    </Text>
+                  )}
+                </>
               ) : null}
             </Box>
           </StepCard>
@@ -2410,7 +2427,11 @@ export default function GlCreateBookingForm() {
                     style={{ flexShrink: 0 }}
                   />
                   <Text fz={13} fw={500} c="#C0392B">
-                    Fix the highlighted fields to review the price.
+                    {trainError
+                      ? "Select a train for the shipment day to review the price."
+                      : dateError && isExportPick
+                        ? "Select a shipment day and a train to review the price."
+                        : "Fix the highlighted fields to review the price."}
                   </Text>
                 </>
               )}
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/GlExchangePanel.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/GlExchangePanel.tsx
index 852a89cc1..4845d3798 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/GlExchangePanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/GlExchangePanel.tsx
@@ -42,6 +42,9 @@ const SIDES: Record<Freight.GlExchangeDocument["side"], { label: string; color:
   {
     ET: { label: "GL Ethiopia", color: "edr-green" },
     DJ: { label: "GL Djibouti", color: "blue" },
+    // The transit officer assigned to the shipment can post here too — both
+    // desks see it, and it is never attributed to either of them.
+    TRANSIT: { label: "Transit agent", color: "grape" },
   };
 
 function formatBytes(bytes: number): string {
@@ -99,6 +102,7 @@ export function GlExchangePanel({ entityId }: GlExchangePanelProps) {
     () => ({
       et: documents.filter((d) => d.side === "ET").length,
       dj: documents.filter((d) => d.side === "DJ").length,
+      transit: documents.filter((d) => d.side === "TRANSIT").length,
       shared: documents.filter((d) => d.visibleToCustomer).length,
     }),
     [documents],
@@ -141,6 +145,11 @@ export function GlExchangePanel({ entityId }: GlExchangePanelProps) {
             <Badge variant="light" color="blue" radius="sm" tt="none">
               {stats.dj} from GL Djibouti
             </Badge>
+            {stats.transit > 0 ? (
+              <Badge variant="light" color="grape" radius="sm" tt="none">
+                {stats.transit} from the transit agent
+              </Badge>
+            ) : null}
             <Badge variant="light" color="gray" radius="sm" tt="none">
               {stats.shared} visible to customer
             </Badge>
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx
index 07ca7f735..313645db3 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx
@@ -782,7 +782,7 @@ export function PhasedClearanceActionPanel({
 
             <Stepper.Step
               label="T1 transport documents"
-              description="GL Djibouti uploads after the gate pass is secured"
+              description="GL Djibouti uploads after the train departs"
               icon={
                 t1Uploaded || clearance.t1?.closed ? (
                   <CheckCircle2 size={14} />
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx
index a3be22ea1..270bce219 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx
@@ -196,8 +196,13 @@ export function ConsolidationPartnerPanel({
                   }
                 />
                 <TextInput
-                  label="Seal number"
+                  label="Seal number *"
                   value={unit.sealNumber}
+                  error={
+                    showErrors && !unit.sealNumber.trim()
+                      ? "Seal number is required."
+                      : undefined
+                  }
                   onChange={(e) =>
                     patchUnit(lineIdx, unitIdx, {
                       sealNumber: e.currentTarget.value,
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx
index c20c08994..b1d73d716 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx
@@ -18,8 +18,8 @@ import type { ConsolidationCandidate } from "@/services/contracts.service";
 /**
  * Picker for the booking that shares this booking's wagon. The server has
  * already narrowed the list to bookings that can legally pair — same route and
- * direction, customs clearing, an odd 20ft count of their own and not already
- * linked to someone else — so every row here is a valid choice.
+ * direction, same booking day, customs clearing, an odd 20ft count of their own
+ * and not already linked to someone else — so every row here is a valid choice.
  */
 interface Props {
   opened: boolean;
@@ -55,8 +55,8 @@ export function ConsolidationPartnerPicker({
               Pick the parent booking
             </Text>
             <Text fz="xs" c="dimmed">
-              Customs bookings on the same route that also carry an odd number of
-              20ft containers.
+              Customs bookings on the same route and booking day that also carry
+              an odd number of 20ft containers.
             </Text>
           </Box>
         </Group>
@@ -84,9 +84,10 @@ export function ConsolidationPartnerPicker({
           title="No booking available to share this wagon"
         >
           <Text fz="sm">
-            No other customs booking on this route currently carries an odd
-            number of 20ft containers. Either wait for one, or switch the
-            shared-wagon option off and book an even number of 20ft containers.
+            No other customs booking on this route and booking day currently
+            carries an odd number of 20ft containers. Either wait for one, or
+            switch the shared-wagon option off and book an even number of 20ft
+            containers.
           </Text>
         </Alert>
       ) : (
@@ -113,9 +114,7 @@ export function ConsolidationPartnerPicker({
                       ? ` · ${candidate.tradeDirection}`
                       : ""}
                     {" · "}
-                    {candidate.hasCargo
-                      ? `${candidate.ft20Quantity} × 20ft`
-                      : "cargo not entered yet"}
+                    {`${candidate.ft20Quantity} × 20ft`}
                   </Text>
                 </Box>
                 <Button
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx b/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
index 7f4cf30ce..88cbc1769 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
@@ -174,6 +174,10 @@ export function DiffRow({
   from: string;
   to: string;
 }) {
+  // No real "before" (field went from unset straight to a value, e.g. the
+  // onboarding wizard's first save) — show the value alone rather than a
+  // fake "— → value" that implies a prior state that never existed.
+  const hadBefore = from !== "—";
   const changed = from !== to;
   return (
     <Stack gap={2}>
@@ -181,24 +185,24 @@ export function DiffRow({
         {label}
       </Text>
       <Group gap={8} wrap="nowrap" align="center">
-        <Text
-          size="sm"
-          c="dimmed"
-          td={changed ? "line-through" : undefined}
-          style={{ wordBreak: "break-word" }}
-        >
-          {from}
-        </Text>
-        {changed && (
-          <>
-            <Text size="sm" c="edr-muted">
-              →
-            </Text>
-            <Text size="sm" fw={600} c="edr-text">
-              {to}
-            </Text>
-          </>
+        {hadBefore && (
+          <Text
+            size="sm"
+            c="dimmed"
+            td={changed ? "line-through" : undefined}
+            style={{ wordBreak: "break-word" }}
+          >
+            {from}
+          </Text>
         )}
+        {hadBefore && changed && (
+          <Text size="sm" c="edr-muted">
+            →
+          </Text>
+        )}
+        <Text size="sm" fw={changed ? 600 : undefined} c={changed ? "edr-text" : "dimmed"}>
+          {to}
+        </Text>
       </Group>
     </Stack>
   );
diff --git a/apps/edr-freight-web/backoffice/src/components/fleet/WagonMovementHistoryModal.tsx b/apps/edr-freight-web/backoffice/src/components/fleet/WagonMovementHistoryModal.tsx
index 7ad92fa7a..2975b2e91 100644
--- a/apps/edr-freight-web/backoffice/src/components/fleet/WagonMovementHistoryModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/fleet/WagonMovementHistoryModal.tsx
@@ -1,11 +1,38 @@
-import type { ReactNode } from "react";
-import { Badge, Center, Group, Loader, Modal, Text, Timeline } from "@mantine/core";
-import { useQuery } from "@tanstack/react-query";
-import { ArrowRight, PackageCheck, TrainFront, Wrench } from "lucide-react";
+import { useMemo, useState, type ReactNode } from "react";
+import { Freight } from "@edr/types";
+import {
+  Badge,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Modal,
+  SegmentedControl,
+  Stack,
+  Text,
+  Timeline,
+} from "@mantine/core";
+import { useInfiniteQuery } from "@tanstack/react-query";
+import {
+  Activity,
+  ArrowRight,
+  CalendarClock,
+  Container,
+  FileEdit,
+  Link2,
+  Link2Off,
+  MapPin,
+  PackageCheck,
+  PackageX,
+  Pin,
+  PinOff,
+  Route,
+  TrainFront,
+  Trash2,
+} from "lucide-react";
 
 import { api } from "@/services/api";
 import type { FleetRecord } from "@/services/fleet/fleet.service";
-import type { WagonMovementRecord } from "@/services/wagon.service";
 
 export interface WagonMovementHistoryModalProps {
   opened: boolean;
@@ -15,43 +42,116 @@ export interface WagonMovementHistoryModalProps {
 
 const asObj = (r: FleetRecord | null) => (r ?? {}) as Record<string, unknown>;
 
-/** Chip style per wagon_movements ledger kind. */
-const KIND_META: Record<string, { label: string; color: string; icon: ReactNode }> = {
-  LOADED: {
-    label: "Loaded leg",
-    color: "edr-green",
-    icon: <PackageCheck size={14} />,
-  },
-  EMPTY_REPOSITION: {
-    label: "Empty reposition",
-    color: "blue",
-    icon: <TrainFront size={14} />,
-  },
-  MANUAL: {
-    label: "Manual move",
-    color: "orange",
-    icon: <Wrench size={14} />,
-  },
-  MAINTENANCE: {
-    label: "Sent to maintenance",
-    color: "red",
-    icon: <Wrench size={14} />,
-  },
+const PAGE_SIZE = 50;
+
+type EventMeta = { label: string; color: string; icon: ReactNode };
+
+/** Chip style per history event type. */
+const EVENT_META: Record<Freight.WagonEventType, EventMeta> = {
+  REGISTERED: { label: "Registered", color: "gray", icon: <FileEdit size={14} /> },
+  DETAILS_UPDATED: { label: "Details updated", color: "gray", icon: <FileEdit size={14} /> },
+  DELETED: { label: "Deleted", color: "red", icon: <Trash2 size={14} /> },
+  PURGED: { label: "Purged", color: "red", icon: <Trash2 size={14} /> },
+  MOVED_MANUALLY: { label: "Moved manually", color: "orange", icon: <MapPin size={14} /> },
+  MOVED_WITH_TRAIN: { label: "Moved with train", color: "orange", icon: <TrainFront size={14} /> },
+  PASSED_CHECKPOINT: { label: "Passed checkpoint", color: "blue", icon: <Route size={14} /> },
+  CUT_AT_YARD: { label: "Cut at yard", color: "yellow", icon: <Link2Off size={14} /> },
+  SETTLED_ON_ARRIVAL: { label: "Arrived", color: "edr-green", icon: <MapPin size={14} /> },
+  RELEASED_AT_UNLOAD: { label: "Released after unload", color: "edr-green", icon: <PackageX size={14} /> },
+  RETURNED_ON_CANCEL: { label: "Schedule cancelled", color: "red", icon: <CalendarClock size={14} /> },
+  COUPLED_TO_TRAIN: { label: "Coupled to train", color: "indigo", icon: <Link2 size={14} /> },
+  UNCOUPLED_FROM_TRAIN: { label: "Uncoupled from train", color: "indigo", icon: <Link2Off size={14} /> },
+  SEQUENCE_CHANGED: { label: "Position changed", color: "indigo", icon: <Link2 size={14} /> },
+  TRAIN_MERGED: { label: "Train merged", color: "indigo", icon: <TrainFront size={14} /> },
+  TRAIN_DISBANDED: { label: "Train disbanded", color: "indigo", icon: <Link2Off size={14} /> },
+  PINNED_TO_SCHEDULE: { label: "Pinned to schedule", color: "cyan", icon: <Pin size={14} /> },
+  UNPINNED_FROM_SCHEDULE: { label: "Unpinned", color: "cyan", icon: <PinOff size={14} /> },
+  DISPATCHED: { label: "Dispatched", color: "cyan", icon: <TrainFront size={14} /> },
+  RELEASED_FROM_SCHEDULE: { label: "Released from schedule", color: "cyan", icon: <PinOff size={14} /> },
+  STATUS_CHANGED: { label: "Status changed", color: "violet", icon: <Activity size={14} /> },
+  CARGO_LOADED: { label: "Cargo loaded", color: "edr-green", icon: <PackageCheck size={14} /> },
+  CARGO_UNLOADED: { label: "Cargo unloaded", color: "teal", icon: <PackageX size={14} /> },
+  BOOKING_UNASSIGNED: { label: "Booking removed", color: "teal", icon: <PackageX size={14} /> },
+  BOOKING_CANCELLED: { label: "Booking cancelled", color: "red", icon: <PackageX size={14} /> },
+  LOAD_MOVED_IN: { label: "Load moved in", color: "teal", icon: <PackageCheck size={14} /> },
+  LOAD_MOVED_OUT: { label: "Load moved out", color: "teal", icon: <PackageX size={14} /> },
+  CONTAINER_PLACED: { label: "Container placed", color: "teal", icon: <Container size={14} /> },
+  CONTAINER_REMOVED: { label: "Container removed", color: "teal", icon: <Container size={14} /> },
 };
 
-const yardLabel = (
-  yard: { label?: string; code?: string } | null | undefined,
-  yardId: string | null,
-) => yard?.label ?? yard?.code ?? yardId ?? "Unknown";
+const CATEGORY_OPTIONS: Array<{ label: string; value: string }> = [
+  { label: "All", value: "" },
+  { label: "Yard", value: Freight.WagonEventCategory.Yard },
+  { label: "Train", value: Freight.WagonEventCategory.Train },
+  { label: "Schedule", value: Freight.WagonEventCategory.Schedule },
+  { label: "Status", value: Freight.WagonEventCategory.Status },
+  { label: "Cargo", value: Freight.WagonEventCategory.Cargo },
+  { label: "Record", value: Freight.WagonEventCategory.Lifecycle },
+];
 
 const fmt = (iso: string) => {
   const d = new Date(iso);
   return Number.isNaN(d.getTime()) ? iso : d.toLocaleString();
 };
 
+const STATUS_LABEL: Record<string, string> = {
+  AVAILABLE: "Available",
+  ASSIGNED: "Assigned",
+  IMPORT_READY: "Import ready",
+  EXPORT_READY: "Export ready",
+  MAINTENANCE: "Maintenance",
+  DETAINED: "Detained",
+  OUT_OF_SERVICE: "Out of service",
+};
+const statusLabel = (v: string | null) => (v ? (STATUS_LABEL[v] ?? v) : null);
+
+/** Headline for one event: the from → to pair that best describes it. */
+const headline = (e: Freight.WagonHistoryEvent): { from: string | null; to: string | null } => {
+  const fromYard = e.fromYardLabel ?? e.fromYardId;
+  const toYard = e.toYardLabel ?? e.toYardId;
+  switch (e.category) {
+    case Freight.WagonEventCategory.Yard:
+      return { from: fromYard, to: toYard };
+    case Freight.WagonEventCategory.Status:
+      return { from: statusLabel(e.fromValue), to: statusLabel(e.toValue) };
+    case Freight.WagonEventCategory.Train:
+      if (e.type === "SEQUENCE_CHANGED") {
+        return { from: e.fromValue ? `#${e.fromValue}` : null, to: e.toValue ? `#${e.toValue}` : null };
+      }
+      if (e.type === "TRAIN_MERGED") return { from: null, to: e.toValue ?? e.trainCode };
+      return {
+        from: e.trainCode ? `Train ${e.trainCode}` : null,
+        to: e.type === "COUPLED_TO_TRAIN" && e.toValue ? `position #${e.toValue}` : null,
+      };
+    case Freight.WagonEventCategory.Schedule:
+      return { from: e.scheduleLabel ? `Run ${e.scheduleLabel}` : null, to: toYard };
+    case Freight.WagonEventCategory.Cargo:
+      if (e.type === "CONTAINER_PLACED" || e.type === "CONTAINER_REMOVED") {
+        return { from: e.toValue ?? e.fromValue, to: null };
+      }
+      if (e.type === "LOAD_MOVED_IN") return { from: e.fromValue ? `from ${e.fromValue}` : null, to: null };
+      if (e.type === "LOAD_MOVED_OUT") return { from: e.toValue ? `to ${e.toValue}` : null, to: null };
+      return { from: e.bookingReference ? `Booking ${e.bookingReference}` : null, to: null };
+    default:
+      return { from: null, to: null };
+  }
+};
+
+/** Secondary line: the linked records this event touched, deduplicated against the headline. */
+const context = (e: Freight.WagonHistoryEvent): string[] => {
+  const parts: string[] = [];
+  if (e.trainCode && e.category !== Freight.WagonEventCategory.Train) parts.push(`Train ${e.trainCode}`);
+  if (e.scheduleLabel && e.category !== Freight.WagonEventCategory.Schedule) parts.push(`Run ${e.scheduleLabel}`);
+  if (e.bookingReference && e.category !== Freight.WagonEventCategory.Cargo) parts.push(`Booking ${e.bookingReference}`);
+  if (e.actorName) parts.push(`by ${e.actorName}`);
+  return parts;
+};
+
 /**
- * Movement ledger for one wagon: every relocation between yards — booking legs,
- * empty reposition rides, and manual staff corrections — newest first.
+ * Full history of one wagon — every yard move, coupling, schedule pin and
+ * dispatch, status flip, cargo load/unload, container placement and record
+ * edit — newest first, filterable by category, paged with a cursor so a
+ * long-serving wagon never loads its whole life at once.
  */
 const WagonMovementHistoryModal = ({
   opened,
@@ -61,15 +161,27 @@ const WagonMovementHistoryModal = ({
   const r = asObj(record);
   const id = r.id ? String(r.id) : "";
   const wagonNumber = r.wagonNumber ? String(r.wagonNumber) : "";
+  const [category, setCategory] = useState<string>("");
 
-  const { data, isLoading } = useQuery(
-    api.wagons.movements.queryOptions({
-      input: { id },
-      enabled: opened && Boolean(id),
+  const input = useMemo(
+    () => ({
+      id,
+      category: (category || undefined) as Freight.WagonEventCategory | undefined,
+      limit: PAGE_SIZE,
     }),
+    [id, category],
   );
 
-  const movements: WagonMovementRecord[] = data ?? [];
+  const { data, isLoading, isFetchingNextPage, hasNextPage, fetchNextPage } = useInfiniteQuery({
+    queryKey: [...api.wagons.history.queryKey(input), "infinite"],
+    queryFn: ({ pageParam }) =>
+      api.wagons.history.call({ ...input, cursor: pageParam || undefined }),
+    initialPageParam: "" as string,
+    getNextPageParam: (last) => last.nextCursor ?? undefined,
+    enabled: opened && Boolean(id),
+  });
+
+  const events = useMemo(() => data?.pages.flatMap((p) => p.items) ?? [], [data]);
 
   return (
     <Modal
@@ -80,63 +192,86 @@ const WagonMovementHistoryModal = ({
       size="lg"
       centered
     >
-      {isLoading ? (
-        <Center py="xl">
-          <Loader size="sm" />
-        </Center>
-      ) : movements.length === 0 ? (
-        <Text c="dimmed" ta="center" py="lg" size="sm">
-          No movements recorded yet. Every yard-to-yard move appears here — a
-          booking's loaded leg, an empty reposition ride, or a manual correction.
-        </Text>
-      ) : (
-        <Timeline active={movements.length} bulletSize={24} lineWidth={2}>
-          {movements.map((movement) => {
-            const meta = KIND_META[movement.kind] ?? {
-              label: movement.kind,
-              color: "gray",
-              icon: <TrainFront size={14} />,
-            };
-            const from = yardLabel(movement.fromYard, movement.fromYardId);
-            const to = yardLabel(movement.toYard, movement.toYardId);
-            return (
-              <Timeline.Item
-                key={movement.id}
-                bullet={meta.icon}
-                title={
-                  <Group gap={6} wrap="nowrap">
-                    <Text size="sm" fw={600}>
-                      {from}
-                    </Text>
-                    {/* Status events (maintenance) sit in one yard — an arrow
-                        pointing at the same yard reads as a broken row. */}
-                    {movement.fromYardId !== movement.toYardId && (
-                      <>
-                        <ArrowRight size={13} />
+      <Stack gap="md">
+        <SegmentedControl
+          size="xs"
+          value={category}
+          onChange={setCategory}
+          data={CATEGORY_OPTIONS}
+          fullWidth
+        />
+
+        {isLoading ? (
+          <Center py="xl">
+            <Loader size="sm" />
+          </Center>
+        ) : events.length === 0 ? (
+          <Text c="dimmed" ta="center" py="lg" size="sm">
+            Nothing recorded yet{category ? " in this category" : ""}. Every yard move,
+            coupling, schedule pin, dispatch, status change and load appears here as it
+            happens.
+          </Text>
+        ) : (
+          <Timeline active={events.length} bulletSize={24} lineWidth={2}>
+            {events.map((e) => {
+              const meta = EVENT_META[e.type] ?? {
+                label: e.type,
+                color: "gray",
+                icon: <TrainFront size={14} />,
+              };
+              const { from, to } = headline(e);
+              const extra = context(e);
+              return (
+                <Timeline.Item
+                  key={e.id}
+                  bullet={meta.icon}
+                  title={
+                    <Group gap={6} wrap="nowrap">
+                      {from && (
+                        <Text size="sm" fw={600}>
+                          {from}
+                        </Text>
+                      )}
+                      {from && to && from !== to && <ArrowRight size={13} />}
+                      {to && to !== from && (
                         <Text size="sm" fw={600}>
                           {to}
                         </Text>
-                      </>
-                    )}
-                    <Badge size="xs" variant="light" color={meta.color}>
-                      {meta.label}
-                    </Badge>
-                  </Group>
-                }
-              >
-                {movement.note && (
-                  <Text size="sm" c="dimmed">
-                    {movement.note}
+                      )}
+                      <Badge size="xs" variant="light" color={meta.color}>
+                        {meta.label}
+                      </Badge>
+                    </Group>
+                  }
+                >
+                  {e.reason && (
+                    <Text size="sm" c="dimmed">
+                      {e.reason}
+                    </Text>
+                  )}
+                  <Text size="xs" mt={4} c="dimmed">
+                    {fmt(e.occurredAt)}
+                    {extra.length ? ` · ${extra.join(" · ")}` : ""}
                   </Text>
-                )}
-                <Text size="xs" mt={4} c="dimmed">
-                  {fmt(movement.occurredAt)}
-                </Text>
-              </Timeline.Item>
-            );
-          })}
-        </Timeline>
-      )}
+                </Timeline.Item>
+              );
+            })}
+          </Timeline>
+        )}
+
+        {hasNextPage && (
+          <Center>
+            <Button
+              size="compact-sm"
+              variant="subtle"
+              loading={isFetchingNextPage}
+              onClick={() => void fetchNextPage()}
+            >
+              Load older events
+            </Button>
+          </Center>
+        )}
+      </Stack>
     </Modal>
   );
 };
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/FreightDashboardHeader.tsx b/apps/edr-freight-web/backoffice/src/components/layout/FreightDashboardHeader.tsx
index 0144db306..45c2f36f1 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/FreightDashboardHeader.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/FreightDashboardHeader.tsx
@@ -22,6 +22,7 @@ import { type ReactNode } from "react";
 import { useNavigate } from "react-router-dom";
 
 import DocReviewAlertButton from "@/features/bookingWindows/DocReviewAlertButton";
+import { PositionSelect } from "@/record-management/components/positionSelection";
 import NotificationBellContainer from "@/features/notifications/NotificationBellContainer";
 
 import type { PageMeta } from "./types";
@@ -111,6 +112,10 @@ const FreightDashboardHeader = ({
             renders only during a review phase that still has undecided
             requests, so it never competes for space otherwise. */}
         <Group gap={10} wrap="nowrap" align="center">
+          {/* Staff holding two posts switch desks here. Renders nothing for the
+              single-position majority, so it costs the header no space. */}
+          <PositionSelect />
+
           <DocReviewAlertButton />
 
           <Tooltip label="Language" withArrow openDelay={300}>
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 8ae6b6c47..1180518fc 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -31,6 +31,7 @@ import {
   SlidersHorizontal,
   Train,
   Truck,
+  Undo2,
   Users,
   Wallet,
   LifeBuoy,
@@ -367,6 +368,18 @@ export const buildSidebarSections = (
               icon: <Container />,
               permission: FREIGHT_PERMS.warehouseInventory.view,
             },
+            {
+              label: "Empty Return Requests",
+              href: "/dashboard/empty-return-requests",
+              icon: <Undo2 />,
+              // Visible to whoever already runs container returns, OR'd with
+              // the queue's own key — so the dedicated permission can be handed
+              // out per position later without the menu disappearing now.
+              permission: [
+                FREIGHT_PERMS.emptyReturnRequests.view,
+                FREIGHT_PERMS.warehouseInventory.view,
+              ],
+            },
             {
               label: "Register Full Containers",
               href: "/dashboard/register-full-containers",
diff --git a/apps/edr-freight-web/backoffice/src/components/phone-field.css b/apps/edr-freight-web/backoffice/src/components/phone-field.css
new file mode 100644
index 000000000..3a0396ffd
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/phone-field.css
@@ -0,0 +1,82 @@
+/* Align react-phone-number-input with the portal's Mantine field styling:
+   44px height, 10px radius, edr border, brand-green focus ring. */
+
+.edr-phone-wrapper .PhoneInput {
+  display: flex;
+  align-items: stretch;
+  gap: 8px;
+}
+
+/* Country selector — a compact pill matching the input height/radius. */
+.edr-phone-wrapper .PhoneInputCountry {
+  margin: 0;
+  padding: 0 10px;
+  height: 2.25rem;
+  border: 0.0625rem  solid #b0bfce;
+  border-radius: 6px;
+  background: #fff;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  transition:
+    border-color 120ms ease,
+    box-shadow 120ms ease;
+}
+
+.edr-phone-wrapper .PhoneInputCountryIcon {
+  width: 22px;
+  height: 16px;
+  box-shadow: none;
+}
+
+.edr-phone-wrapper .PhoneInputCountrySelectArrow {
+  color: #6b7c8e;
+  opacity: 0.8;
+}
+
+/* The number input itself. */
+.edr-phone-input {
+  flex: 1;
+  min-width: 0;
+  height: 44px;
+  padding: 0 12px;
+  border: 1px solid #e6ecf2;
+  border-radius: 10px;
+  font-size: 14px;
+  color: #10202f;
+  background: #fff;
+  outline: none;
+  transition:
+    border-color 120ms ease,
+    box-shadow 120ms ease;
+}
+
+.edr-phone-input::placeholder {
+  color: #9aa8b5;
+}
+
+.edr-phone-input:focus {
+  border-color: #0ea371;
+  box-shadow: 0 0 0 3px rgba(14, 163, 113, 0.15);
+}
+
+.edr-phone-wrapper .PhoneInputCountry:focus-within {
+  border-color: #0ea371;
+  box-shadow: 0 0 0 3px rgba(14, 163, 113, 0.15);
+}
+
+.edr-phone-input:disabled,
+.edr-phone-wrapper .PhoneInputCountrySelect:disabled + .PhoneInputCountryIcon {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+/* Error state mirrors Mantine's invalid styling. */
+.edr-phone-wrapper--error .edr-phone-input,
+.edr-phone-wrapper--error .PhoneInputCountry {
+  border-color: #e03131;
+}
+
+.edr-phone-wrapper--error .edr-phone-input:focus {
+  box-shadow: 0 0 0 3px rgba(224, 49, 49, 0.12);
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
index e3bf11375..e3a3445c3 100644
--- a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
@@ -22,6 +22,7 @@ import {
   RULE_ENGINE_SELECT_NONE,
   type FormFieldDef,
 } from "@/pages/ruleEngine/config/resources";
+import PhoneField, { isValidPhone } from "@/components/PhoneField";
 import type { RuleEngineRecord } from "@/types/rule-engine";
 import { RULE_ENGINE_POSITION_END } from "./ruleEngineOrder.utils";
 
@@ -46,7 +47,11 @@ type FormRow =
 /** One editable distance tier of a tierList field (raw input strings). */
 type TierRow = { minKm: string; maxKm: string; rateValue: string };
 
-const emptyTier = (fromKm = ""): TierRow => ({ minKm: fromKm, maxKm: "", rateValue: "" });
+const emptyTier = (fromKm = ""): TierRow => ({
+  minKm: fromKm,
+  maxKm: "",
+  rateValue: "",
+});
 
 /**
  * Validate a tier set before submit: every tier complete, ranges sane, no
@@ -87,7 +92,11 @@ const buildFormRows = (fields: FormFieldDef[]): FormRow[] => {
   while (index < fields.length) {
     const field = fields[index];
 
-    if (field.type === "textarea" || field.type === "boolean" || field.type === "tierList") {
+    if (
+      field.type === "textarea" ||
+      field.type === "boolean" ||
+      field.type === "tierList"
+    ) {
       rows.push({ kind: "single", field });
       index += 1;
       continue;
@@ -113,9 +122,10 @@ const buildInitialValues = (
 ): Record<string, unknown> => {
   const values: Record<string, unknown> = {};
   for (const field of fields) {
-    const raw = field.getInitialValue && record
-      ? field.getInitialValue(record)
-      : record?.[field.name];
+    const raw =
+      field.getInitialValue && record
+        ? field.getInitialValue(record)
+        : record?.[field.name];
     if (field.type === "multiselect") {
       values[field.name] = Array.isArray(raw) ? raw.map(String) : [];
     } else if (field.type === "tierList") {
@@ -160,10 +170,13 @@ const resolveSelectValue = (
 };
 
 const inputStyles = {
-  label: { fontWeight: 600, marginBottom: 6, color: "var(--mantine-color-gray-8)" },
+  label: {
+    fontWeight: 600,
+    marginBottom: 6,
+    color: "var(--mantine-color-gray-8)",
+  },
 } as const;
 
-
 const RuleEngineFormDialog = ({
   open,
   onOpenChange,
@@ -195,13 +208,17 @@ const RuleEngineFormDialog = ({
       fields.filter((field) => {
         if (
           field.hideWhen &&
-          field.hideWhen.equals.includes(String(values[field.hideWhen.field] ?? ""))
+          field.hideWhen.equals.includes(
+            String(values[field.hideWhen.field] ?? ""),
+          )
         ) {
           return false;
         }
         if (
           field.showWhen &&
-          !field.showWhen.equals.includes(String(values[field.showWhen.field] ?? ""))
+          !field.showWhen.equals.includes(
+            String(values[field.showWhen.field] ?? ""),
+          )
         ) {
           return false;
         }
@@ -228,7 +245,10 @@ const RuleEngineFormDialog = ({
       // Changing what a rate applies to (or its surcharge trigger) can invalidate
       // the previously-chosen unit — reset it so the admin re-picks from the new
       // allowed set instead of submitting a stale, rejected unit.
-      if ((name === "appliesTo" || name === "trigger") && "rateUnit" in current) {
+      if (
+        (name === "appliesTo" || name === "trigger") &&
+        "rateUnit" in current
+      ) {
         next.rateUnit = "";
       }
       // The legal yards depend on what the rate is for and which way it runs, so
@@ -342,6 +362,20 @@ const RuleEngineFormDialog = ({
           [field.name]: `${field.label} is required.`,
         }));
         blocked = true;
+      } else if (field.type === "phone" && raw !== "" && raw !== undefined) {
+        // The country-picker input emits a PARTIAL E.164 while the user is
+        // still typing ("+25377"), which is non-empty and would post straight
+        // through to a 400 from the API's own validator. Reject it here, on the
+        // field, instead of as a server error the admin has to decode.
+        if (!isValidPhone(String(raw))) {
+          setFieldErrors((current) => ({
+            ...current,
+            [field.name]: `${field.label} is not a complete phone number.`,
+          }));
+          blocked = true;
+        } else {
+          payload[field.name] = raw;
+        }
       } else if (raw === "" || raw === undefined) {
         if (!field.required) continue;
         payload[field.name] = raw;
@@ -350,13 +384,19 @@ const RuleEngineFormDialog = ({
       }
     }
 
-    if (fields.some((f) => f.name === "code" && typeof payload.code === "string")) {
+    if (
+      fields.some((f) => f.name === "code" && typeof payload.code === "string")
+    ) {
       payload.code = String(payload.code).toUpperCase();
     }
 
     if (blocked) return;
 
-    if (!initialRecord && positionOptions && position !== RULE_ENGINE_POSITION_END) {
+    if (
+      !initialRecord &&
+      positionOptions &&
+      position !== RULE_ENGINE_POSITION_END
+    ) {
       payload.insertAfterId = position;
     }
 
@@ -421,7 +461,9 @@ const RuleEngineFormDialog = ({
       const setRows = (next: TierRow[]) => setField(field.name, next);
       const setRow = (index: number, key: keyof TierRow, value: string) => {
         if (value.trim().startsWith("-")) return;
-        setRows(rows.map((row, i) => (i === index ? { ...row, [key]: value } : row)));
+        setRows(
+          rows.map((row, i) => (i === index ? { ...row, [key]: value } : row)),
+        );
       };
       return (
         <Box key={field.name}>
@@ -443,7 +485,9 @@ const RuleEngineFormDialog = ({
                   step="any"
                   placeholder="0"
                   value={row.minKm}
-                  onChange={(e) => setRow(index, "minKm", e.currentTarget.value)}
+                  onChange={(e) =>
+                    setRow(index, "minKm", e.currentTarget.value)
+                  }
                   size="md"
                   radius="md"
                   styles={inputStyles}
@@ -456,7 +500,9 @@ const RuleEngineFormDialog = ({
                   step="any"
                   placeholder="No limit"
                   value={row.maxKm}
-                  onChange={(e) => setRow(index, "maxKm", e.currentTarget.value)}
+                  onChange={(e) =>
+                    setRow(index, "maxKm", e.currentTarget.value)
+                  }
                   size="md"
                   radius="md"
                   styles={inputStyles}
@@ -469,7 +515,9 @@ const RuleEngineFormDialog = ({
                   step="any"
                   placeholder="Rate per km"
                   value={row.rateValue}
-                  onChange={(e) => setRow(index, "rateValue", e.currentTarget.value)}
+                  onChange={(e) =>
+                    setRow(index, "rateValue", e.currentTarget.value)
+                  }
                   size="md"
                   radius="md"
                   styles={inputStyles}
@@ -494,7 +542,12 @@ const RuleEngineFormDialog = ({
                 size="xs"
                 leftSection={<Plus size={14} />}
                 // The next tier naturally starts where the previous one ends.
-                onClick={() => setRows([...rows, emptyTier(rows[rows.length - 1]?.maxKm ?? "")])}
+                onClick={() =>
+                  setRows([
+                    ...rows,
+                    emptyTier(rows[rows.length - 1]?.maxKm ?? ""),
+                  ])
+                }
               >
                 Add tier
               </Button>
@@ -531,7 +584,10 @@ const RuleEngineFormDialog = ({
           onChange={(v) => setField(field.name, v)}
           disabled={selectOptionsLoading}
           data={options
-            .filter((opt) => opt.value !== "" && opt.value !== RULE_ENGINE_SELECT_NONE)
+            .filter(
+              (opt) =>
+                opt.value !== "" && opt.value !== RULE_ENGINE_SELECT_NONE,
+            )
             .map((opt) => ({ label: opt.label, value: opt.value }))}
           searchable
           clearable
@@ -545,7 +601,9 @@ const RuleEngineFormDialog = ({
     if (field.type === "select") {
       // Dynamic options (e.g. rate unit) resolve from the live form values so
       // the choices track the other fields the admin has picked.
-      const options = field.optionsFromValues ? field.optionsFromValues(values) : (field.options ?? []);
+      const options = field.optionsFromValues
+        ? field.optionsFromValues(values)
+        : (field.options ?? []);
       // A derived select shows (and submits) its computed value and is locked,
       // matching the text-input branch — used by fields the shape decides on the
       // admin's behalf, e.g. a shipping-line rate's import-only direction.
@@ -558,14 +616,18 @@ const RuleEngineFormDialog = ({
           label={label}
           description={field.description}
           placeholder={
-            selectOptionsLoading ? "Loading options..." : (field.placeholder ?? "Select an option")
+            selectOptionsLoading
+              ? "Loading options..."
+              : (field.placeholder ?? "Select an option")
           }
           value={
             computedSelect !== undefined
               ? computedSelect
               : resolveSelectValue(field, values)
           }
-          onChange={(v) => setField(field.name, v === RULE_ENGINE_SELECT_NONE ? "" : v)}
+          onChange={(v) =>
+            setField(field.name, v === RULE_ENGINE_SELECT_NONE ? "" : v)
+          }
           disabled={
             selectOptionsLoading ||
             field.disabled ||
@@ -635,8 +697,29 @@ const RuleEngineFormDialog = ({
       );
     }
 
+    if (field.type === "phone") {
+      // Country-picker input restricted to Ethiopia and Djibouti — the two the
+      // SMS gateway reaches. Emits E.164, so the API never guesses a country
+      // from a bare local number.
+      return (
+        <PhoneField
+          key={field.name}
+          label={label}
+          description={field.description}
+          value={String(values[field.name] ?? "")}
+          onChange={(v) => setField(field.name, v ?? "")}
+          disabled={field.disabled || (field.disabledOnEdit && !!initialRecord)}
+          required={field.required}
+          error={fieldErrors[field.name] || undefined}
+          placeholder={field.placeholder}
+        />
+      );
+    }
+
     const isNumber = field.type === "number";
-    const computed = field.computeValue ? field.computeValue(values) : undefined;
+    const computed = field.computeValue
+      ? field.computeValue(values)
+      : undefined;
 
     return (
       <TextInput
@@ -654,8 +737,14 @@ const RuleEngineFormDialog = ({
         // numbers (@IsInt on points/sizes/order, @IsNumber on money, tons, km),
         // so let the field carry decimals and let a 400 catch the rest.
         step={isNumber ? "any" : undefined}
-        disabled={field.disabled || (field.disabledOnEdit && !!initialRecord) || computed !== undefined}
-        value={String((computed !== undefined ? computed : values[field.name]) ?? "")}
+        disabled={
+          field.disabled ||
+          (field.disabledOnEdit && !!initialRecord) ||
+          computed !== undefined
+        }
+        value={String(
+          (computed !== undefined ? computed : values[field.name]) ?? "",
+        )}
         onChange={(e) => {
           const next = e.currentTarget.value;
           if (isNumber && next.trim().startsWith("-")) return;
@@ -703,16 +792,27 @@ const RuleEngineFormDialog = ({
     >
       <form onSubmit={handleSubmit}>
         <Stack gap="lg">
-          <Box style={{ maxHeight: "calc(65vh - 120px)", overflowY: "auto", paddingRight: 4 }}>
+          <Box
+            style={{
+              maxHeight: "calc(65vh - 120px)",
+              overflowY: "auto",
+              paddingRight: 4,
+            }}
+          >
             <Stack gap="md">
               {!initialRecord && positionOptions ? (
                 <Select
                   label="Position"
                   description="New items are appended to the end by default."
                   value={position}
-                  onChange={(value) => setPosition(value ?? RULE_ENGINE_POSITION_END)}
+                  onChange={(value) =>
+                    setPosition(value ?? RULE_ENGINE_POSITION_END)
+                  }
                   data={[
-                    { label: "At end (default)", value: RULE_ENGINE_POSITION_END },
+                    {
+                      label: "At end (default)",
+                      value: RULE_ENGINE_POSITION_END,
+                    },
                     ...positionOptions,
                   ]}
                   searchable
@@ -724,9 +824,17 @@ const RuleEngineFormDialog = ({
               ) : null}
               {formRows.map((row) =>
                 row.kind === "pair" ? (
-                  <SimpleGrid key={`${row.fields[0].name}-${row.fields[1].name}`} cols={2} spacing="md">
-                    <Box style={{ minWidth: 0 }}>{renderField(row.fields[0])}</Box>
-                    <Box style={{ minWidth: 0 }}>{renderField(row.fields[1])}</Box>
+                  <SimpleGrid
+                    key={`${row.fields[0].name}-${row.fields[1].name}`}
+                    cols={2}
+                    spacing="md"
+                  >
+                    <Box style={{ minWidth: 0 }}>
+                      {renderField(row.fields[0])}
+                    </Box>
+                    <Box style={{ minWidth: 0 }}>
+                      {renderField(row.fields[1])}
+                    </Box>
                   </SimpleGrid>
                 ) : (
                   <Box key={row.field.name}>{renderField(row.field)}</Box>
@@ -752,7 +860,10 @@ const RuleEngineFormDialog = ({
               disabled={isSubmitting}
               leftSection={
                 isSubmitting ? (
-                  <Loader2 size={18} style={{ animation: "spin 1s linear infinite" }} />
+                  <Loader2
+                    size={18}
+                    style={{ animation: "spin 1s linear infinite" }}
+                  />
                 ) : undefined
               }
               radius="md"
diff --git a/apps/edr-freight-web/backoffice/src/components/ruleEngine/ruleEngineFormat.tsx b/apps/edr-freight-web/backoffice/src/components/ruleEngine/ruleEngineFormat.tsx
index 529f53a43..3a600cd5b 100644
--- a/apps/edr-freight-web/backoffice/src/components/ruleEngine/ruleEngineFormat.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/ruleEngine/ruleEngineFormat.tsx
@@ -25,12 +25,20 @@ export const formatCell = (
   row?: Record<string, unknown>,
 ): ReactNode => {
   if (value === null || value === undefined || value === "") {
-    return <Text size="sm" c="dimmed">—</Text>;
+    return (
+      <Text size="sm" c="dimmed">
+        —
+      </Text>
+    );
   }
 
   // Handle stringified objects (e.g., "[object Object]")
   if (typeof value === "string" && value.trim() === "[object Object]") {
-    return <Text size="sm" c="dimmed">—</Text>;
+    return (
+      <Text size="sm" c="dimmed">
+        —
+      </Text>
+    );
   }
 
   if (format === "boolean") {
@@ -75,9 +83,17 @@ export const formatCell = (
   if (format === "validityBadge") {
     const status = String(value);
     const label =
-      status === "VALID" ? "Valid" : status === "EXPIRED" ? "Expired" : "Not started";
+      status === "VALID"
+        ? "Valid"
+        : status === "EXPIRED"
+          ? "Expired"
+          : "Not started";
     const color =
-      status === "VALID" ? "edr-green" : status === "EXPIRED" ? "red" : "yellow";
+      status === "VALID"
+        ? "edr-green"
+        : status === "EXPIRED"
+          ? "red"
+          : "yellow";
     return (
       <Badge color={color} variant="filled" size="sm" radius="md">
         {label}
@@ -85,6 +101,20 @@ export const formatCell = (
     );
   }
 
+  if (format === "accountBadge") {
+    // `hasAccount` — whether a portal login backs this row. Roster-only rows
+    // predate accounts and stay legal, so "no" is a neutral dash, not a warning.
+    return value ? (
+      <Badge color="edr-green" variant="filled" size="sm" radius="md">
+        Invited
+      </Badge>
+    ) : (
+      <Text size="sm" c="dimmed">
+        —
+      </Text>
+    );
+  }
+
   if (format === "code") {
     return (
       <Badge
@@ -110,7 +140,11 @@ export const formatCell = (
 
   if (format === "number") {
     const num = Number(value);
-    return <Text size="sm">{Number.isNaN(num) ? String(value) : num.toLocaleString()}</Text>;
+    return (
+      <Text size="sm">
+        {Number.isNaN(num) ? String(value) : num.toLocaleString()}
+      </Text>
+    );
   }
 
   if (format === "currency") {
@@ -125,14 +159,13 @@ export const formatCell = (
 
   if (format === "date") {
     const d = new Date(String(value));
-    if (Number.isNaN(d.getTime())) return <Text size="sm">{String(value)}</Text>;
+    if (Number.isNaN(d.getTime()))
+      return <Text size="sm">{String(value)}</Text>;
     return <Text size="sm">{d.toLocaleDateString()}</Text>;
   }
 
   if (Array.isArray(value)) {
-    return (
-      <Text size="sm">{value.length > 0 ? value.join(", ") : "—"}</Text>
-    );
+    return <Text size="sm">{value.length > 0 ? value.join(", ") : "—"}</Text>;
   }
 
   if (format === "entityLabel" && value && typeof value === "object") {
@@ -140,7 +173,11 @@ export const formatCell = (
     if (label) {
       return <Text size="sm">{label}</Text>;
     }
-    return <Text size="sm" c="dimmed">—</Text>;
+    return (
+      <Text size="sm" c="dimmed">
+        —
+      </Text>
+    );
   }
 
   if (format === "rateLabel") {
@@ -150,7 +187,9 @@ export const formatCell = (
           {String(value)}
         </Text>
       ) : (
-        <Text size="sm" c="dimmed">—</Text>
+        <Text size="sm" c="dimmed">
+          —
+        </Text>
       );
     }
     const rate = value as {
@@ -168,14 +207,20 @@ export const formatCell = (
     return parts.length > 0 ? (
       <Text size="sm">{parts.join(" · ")}</Text>
     ) : (
-      <Text size="sm" c="dimmed">—</Text>
+      <Text size="sm" c="dimmed">
+        —
+      </Text>
     );
   }
 
   if (typeof value === "object") {
     const label = extractLabel(value);
     if (label) return <Text size="sm">{label}</Text>;
-    return <Text size="sm" c="dimmed">—</Text>;
+    return (
+      <Text size="sm" c="dimmed">
+        —
+      </Text>
+    );
   }
 
   return <Text size="sm">{String(value)}</Text>;
diff --git a/apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx b/apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx
index ae271a57b..e68725b52 100644
--- a/apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx
@@ -10,9 +10,10 @@ import {
 } from "@mantine/core";
 import { useMutation } from "@tanstack/react-query";
 import { Send } from "lucide-react";
-import { useState } from "react";
+import { useState, type ReactNode } from "react";
 
 import { useAuth } from "@/auth/useAuth";
+import { isSmsReachable } from "@/components/PhoneField";
 import { useToast } from "@/hooks/use-toast";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { api } from "@/services/api";
@@ -21,27 +22,19 @@ import type {
   ShippingLineCompany,
 } from "@/types/shippingLineCompany";
 
-/**
- * Whether the SMS gateway can actually reach this number.
- *
- * The carrier integration is domestic-only: anything else is queued and
- * silently lost, so a foreign number counts as unavailable rather than as a
- * send that quietly fails. Mirrors `isDomesticPhone` in the API's otp.service.
- */
-function isDomesticPhone(rawPhone: string): boolean {
-  const digits = rawPhone.trim().replace(/[^\d+]/g, "");
-  const normalized = digits.startsWith("+")
-    ? digits
-    : /^251\d{9}$/.test(digits)
-      ? `+${digits}`
-      : /^9\d{8}$|^7\d{8}$/.test(digits.replace(/^0+/, ""))
-        ? `+251${digits.replace(/^0+/, "")}`
-        : digits;
-  return /^\+2519\d{8}$/.test(normalized);
+/** The minimum an account needs for the link dialog to describe its channels. */
+export interface ActivationTarget {
+  id: string;
+  name: string;
+  email?: string | null;
+  phoneNumber?: string | null;
 }
 
 export interface ResendActivationActionProps {
-  shippingLine: Pick<ShippingLineCompany, "id" | "name" | "email" | "phoneNumber">;
+  shippingLine: Pick<
+    ShippingLineCompany,
+    "id" | "name" | "email" | "phoneNumber"
+  >;
 }
 
 /**
@@ -56,15 +49,13 @@ export default function ResendActivationAction({
 }: ResendActivationActionProps) {
   const { user } = useAuth();
   const { toast } = useToast();
-  const [opened, setOpened] = useState(false);
-  const [channel, setChannel] = useState<ResetChannel>("email");
-
-  const allowed = hasPermission(user, FREIGHT_PERMS.shippingLines.resetPassword);
-
+  const allowed = hasPermission(
+    user,
+    FREIGHT_PERMS.shippingLines.resetPassword,
+  );
   const { mutate, isPending } = useMutation(
     api.shippingLineCompanies.resendActivation.mutationOptions({
       onSuccess: (result) => {
-        setOpened(false);
         toast({
           title: "Activation link sent",
           description: `The shipping line can set their password using the link sent to ${result.maskedTarget}. It expires in 24 hours.`,
@@ -82,42 +73,100 @@ export default function ResendActivationAction({
 
   if (!allowed) return null;
 
-  const phoneUsable =
-    !!shippingLine.phoneNumber && isDomesticPhone(shippingLine.phoneNumber);
+  return (
+    <ActivationLinkDialog
+      target={shippingLine}
+      audienceLabel="shipping line"
+      isPending={isPending}
+      onSend={(channel, onDone) =>
+        mutate({ id: shippingLine.id, channel }, { onSuccess: onDone })
+      }
+    />
+  );
+}
+
+export interface ActivationLinkDialogProps {
+  target: ActivationTarget;
+  /** How the account is described in the dialog copy ("shipping line", "transit agent"). */
+  audienceLabel: string;
+  isPending: boolean;
+  /**
+   * Perform the send. `onDone` closes the dialog — the caller owns the mutation
+   * (and its toast) because each audience posts to its own endpoint.
+   */
+  onSend: (channel: ResetChannel, onDone: () => void) => void;
+  /** Overrides the icon-button trigger, e.g. a labelled "Invite" button. */
+  trigger?: (open: () => void) => ReactNode;
+  title?: string;
+  submitLabel?: string;
+  /** Extra fields above the channel picker — the invite flow collects the address here. */
+  children?: ReactNode;
+  /** Blocks the send button, e.g. while a required address is still empty. */
+  submitDisabled?: boolean;
+}
+
+/**
+ * The channel picker behind every activation-link send.
+ *
+ * Extracted from the shipping-line action so transit agents get the identical
+ * dialog — including the domestic-only SMS rule, which is the part most likely
+ * to be re-implemented subtly wrong.
+ */
+export function ActivationLinkDialog({
+  target,
+  audienceLabel,
+  isPending,
+  onSend,
+  trigger,
+  title = "Resend activation link",
+  submitLabel = "Send activation link",
+  children,
+  submitDisabled,
+}: ActivationLinkDialogProps) {
+  const [opened, setOpened] = useState(false);
+  const [channel, setChannel] = useState<ResetChannel>("email");
+
+  const phoneUsable = isSmsReachable(target.phoneNumber);
   const channelMissing = channel === "phone" && !phoneUsable;
 
   return (
     <>
-      <Tooltip label="Resend activation link" withArrow>
-        <ActionIcon
-          variant="subtle"
-          color="gray"
-          aria-label={`Resend activation link to ${shippingLine.name}`}
-          onClick={(event) => {
-            // The row itself is not clickable today, but stop here anyway so
-            // adding a detail-page navigation later cannot swallow this click.
-            event.stopPropagation();
-            setOpened(true);
-          }}
-        >
-          <Send size={16} />
-        </ActionIcon>
-      </Tooltip>
+      {trigger ? (
+        trigger(() => setOpened(true))
+      ) : (
+        <Tooltip label={title} withArrow>
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            aria-label={`${title} to ${target.name}`}
+            onClick={(event) => {
+              // The row itself is not clickable today, but stop here anyway so
+              // adding a detail-page navigation later cannot swallow this click.
+              event.stopPropagation();
+              setOpened(true);
+            }}
+          >
+            <Send size={16} />
+          </ActionIcon>
+        </Tooltip>
+      )}
 
       <Modal
         opened={opened}
         onClose={() => setOpened(false)}
-        title="Resend activation link"
+        title={title}
         centered
       >
         <Stack gap="md">
           <Text size="sm" c="dimmed">
-            We&apos;ll send a single-use link to {shippingLine.name}. They choose
-            their own password — you will not see it. The link expires in 24
-            hours, and sending a new one invalidates nothing they haven&apos;t
-            already used.
+            We&apos;ll send a single-use link to this {audienceLabel},{" "}
+            {target.name}. They choose their own password — you will not see it.
+            The link expires in 24 hours, and sending a new one invalidates
+            nothing they haven&apos;t already used.
           </Text>
 
+          {children}
+
           <Radio.Group
             value={channel}
             onChange={(v) => setChannel(v as ResetChannel)}
@@ -127,18 +176,19 @@ export default function ResendActivationAction({
               <Radio
                 value="email"
                 label="Email"
-                description={shippingLine.email}
+                disabled={!target.email}
+                description={target.email ?? "No email on this account"}
               />
               <Radio
                 value="phone"
                 label="SMS"
                 disabled={!phoneUsable}
                 description={
-                  !shippingLine.phoneNumber
+                  !target.phoneNumber
                     ? "No phone number on this account"
                     : !phoneUsable
-                      ? `${shippingLine.phoneNumber} — foreign number, SMS unavailable; use email`
-                      : shippingLine.phoneNumber
+                      ? `${target.phoneNumber} — the SMS gateway does not reach this number; use email`
+                      : target.phoneNumber
                 }
               />
             </Stack>
@@ -156,10 +206,10 @@ export default function ResendActivationAction({
           <Button
             color="edr-green"
             loading={isPending}
-            disabled={channelMissing}
-            onClick={() => mutate({ id: shippingLine.id, channel })}
+            disabled={channelMissing || submitDisabled}
+            onClick={() => onSend(channel, () => setOpened(false))}
           >
-            Send activation link
+            {submitLabel}
           </Button>
         </Stack>
       </Modal>
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/AllocateBookingWizard.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/AllocateBookingWizard.tsx
index 69dc7f2b8..b0034f2a9 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/AllocateBookingWizard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/AllocateBookingWizard.tsx
@@ -277,8 +277,15 @@ export function AllocateBookingWizard({
     if (!routeId || !scheduleDate || locomotiveIds.length < 2) {
       throw new Error("Select route, date, and at least two locomotives");
     }
+    // This ad-hoc path has no built train (and so no run number) and no voyage
+    // input, but voyage number is required at creation — default it to a
+    // date-stamped placeholder that staff can edit later on the schedule.
+    const voyageNumber = `V-${new Date(scheduleDate)
+      .toISOString()
+      .slice(0, 10)
+      .replace(/-/g, "")}`;
     const created = await create.mutateAsync({
-      payload: { routeId, scheduleDate, locomotiveIds },
+      payload: { routeId, scheduleDate, voyageNumber, locomotiveIds },
     });
     showScheduleWarnings(created.warnings);
     setSelectedScheduleId(created.id);
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/IntercityRideAlongPanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/IntercityRideAlongPanel.tsx
index 0342b9ae9..74f376db4 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/IntercityRideAlongPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/IntercityRideAlongPanel.tsx
@@ -382,7 +382,12 @@ export function IntercityRideAlongPanel({
                       </Table.Td>
                       <Table.Td>
                         <Group gap="xs" justify="flex-end">
-                          {row.status === "PAID" && (
+                          {/* Paid = PAYMENT status only; still show Load only
+                              while the cargo has not ridden yet. */}
+                          {row.paymentStatus === "PAID" &&
+                            row.status !== "IN_TRANSIT" &&
+                            row.status !== "ARRIVED" &&
+                            row.status !== "COMPLETED" && (
                             <Tooltip
                               label={
                                 canLoad
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx
index d09cf06c8..d6b8afc5d 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx
@@ -1,6 +1,7 @@
 import {
   Alert,
   Button,
+  Checkbox,
   Divider,
   Group,
   Loader,
@@ -24,6 +25,11 @@ import { useEffect, useState } from "react";
 import { Freight } from "@edr/types";
 
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
+import {
+  PartiallyLoadedDecisionModal,
+  parsePartiallyLoaded,
+  type PartiallyLoadedPayload,
+} from "@/components/trainScheduling/PartiallyLoadedDecisionModal";
 import { StationWorkControls } from "@/components/trainScheduling/StationWorkControls";
 import { Chip } from "./trackPrimitives";
 import { DIRECTION_TONE, track as T } from "./trackTheme";
@@ -98,6 +104,7 @@ export function LogPassYardWorkModal({
   onClose,
   scheduleId,
   station,
+  stations,
   isFinal,
   alreadyLogged,
 }: {
@@ -105,6 +112,8 @@ export function LogPassYardWorkModal({
   onClose: () => void;
   scheduleId: string;
   station: TrackStation | null;
+  /** Whole corridor — used to find the yard the train has just left. */
+  stations: TrackStation[];
   isFinal: boolean;
   /** True when opened for the current station (pass already logged). */
   alreadyLogged: boolean;
@@ -151,6 +160,33 @@ export function LogPassYardWorkModal({
   const loadingStarted = Boolean(workLog?.loading?.startedAt);
   const unloadingStarted = Boolean(workLog?.unloading?.startedAt);
 
+  // The yard the train is LEAVING by logging this pass. Its boarders have had
+  // their last chance to load, so this is where the leave-behind decision is
+  // made. The origin (seq 0) belongs to dispatch, so there is nothing before it.
+  const departedStation =
+    station && station.sequenceNo > 0
+      ? stations.find((s) => s.sequenceNo === station.sequenceNo - 1)
+      : undefined;
+  const departedYard = departedStation
+    ? yardWorkQuery.data?.yards.find((y) => y.yardId === departedStation.yardId)
+    : undefined;
+  const departedPendingBoarders: YardWorkBookingRow[] = (departedYard?.toLoad ?? []).filter(
+    (r) => !r.loadedAt,
+  );
+  // Ticked = rides on. Seeded to everyone each time the modal opens on a new
+  // station, so the default is the historic "nobody is left behind".
+  const [departedRidingIds, setDepartedRidingIds] = useState<Set<string>>(new Set());
+  useEffect(() => {
+    setDepartedRidingIds(new Set(departedPendingBoarders.map((r) => r.id)));
+    // Re-seed when the station changes or the rows finish loading.
+  }, [station?.sequenceNo, opened, departedPendingBoarders.length]);
+  const departedLeftBehind = departedPendingBoarders.filter(
+    (r) => !r.isGovernment && !departedRidingIds.has(r.id),
+  );
+  // Set when the pass is rejected because a booking at the departed yard is
+  // part-loaded — drives the EDR-fault / customer-fault decision.
+  const [partialGate, setPartialGate] = useState<PartiallyLoadedPayload | null>(null);
+
   const doLogPass = () => {
     if (!station) return;
     recordCheckpoint.mutate(
@@ -159,11 +195,30 @@ export function LogPassYardWorkModal({
         payload: {
           sequenceNo: station.sequenceNo,
           ...(passAt ? { occurredAt: passAt.toISOString() } : {}),
+          // Logging THIS station means the train left the previous one, so the
+          // cargo that boarded back there has had its last chance to load.
+          // Only the ticked ones ride on; the rest are unassigned and returned
+          // to the pool. Government bookings always ride — the server refuses
+          // to unassign them.
+          ...(departedYard
+            ? {
+                loadedBookingIds: departedPendingBoarders
+                  .filter((r) => r.isGovernment || departedRidingIds.has(r.id))
+                  .map((r) => r.id),
+              }
+            : {}),
         },
       },
       {
         onSuccess: () => {
           setJustLogged(true);
+          if (departedLeftBehind.length) {
+            toast({
+              title: `${departedLeftBehind.length} booking${departedLeftBehind.length === 1 ? "" : "s"} left behind at ${departedYard?.yard ?? "the previous yard"}`,
+              description:
+                "Removed from this train — wagons freed, bookings returned to the pool for a later schedule.",
+            });
+          }
           toast({
             title: isFinal
               ? "Train arrived — remaining bookings marked arrived, assets freed"
@@ -178,12 +233,21 @@ export function LogPassYardWorkModal({
           });
           void yardWorkQuery.refetch();
         },
-        onError: (err) =>
+        onError: (err) => {
+          // A part-loaded booking at the departed yard blocks the pass until
+          // its never-loaded wagons are cut — offer the fault decision instead
+          // of a dead-end error.
+          const gate = parsePartiallyLoaded(err);
+          if (gate) {
+            setPartialGate(gate);
+            return;
+          }
           toast({
             title: "Could not log checkpoint",
             description: parseError(err, "Please try again"),
             variant: "destructive",
-          }),
+          });
+        },
       },
     );
   };
@@ -558,6 +622,66 @@ export function LogPassYardWorkModal({
           </>
         )}
 
+        {!logged && departedStation && departedPendingBoarders.length > 0 ? (
+          <Stack
+            gap={10}
+            p={14}
+            style={{
+              background: T.amberDim,
+              border: `1px solid ${T.amberBorder}`,
+              borderRadius: 14,
+            }}
+          >
+            <Group gap={9} align="center" wrap="nowrap">
+              <PackageCheck size={16} color={T.amber} style={{ flexShrink: 0 }} />
+              <Text size="13px" fw={700} c={T.amber}>
+                {departedPendingBoarders.length} booking
+                {departedPendingBoarders.length === 1 ? "" : "s"} not loaded at{" "}
+                {departedStation.label}
+              </Text>
+            </Group>
+            <Text size="11.5px" c={T.amberText} lh={1.45}>
+              Logging this pass means the train has left {departedStation.label}. Untick
+              anything that never made it onto the train — it is removed and returned to the
+              booking pool.
+            </Text>
+            {departedPendingBoarders.map((r) => (
+              <Group key={r.id} justify="space-between" wrap="nowrap">
+                <Checkbox
+                  checked={r.isGovernment || departedRidingIds.has(r.id)}
+                  disabled={r.isGovernment || !canLeave}
+                  onChange={(e) => {
+                    const next = new Set(departedRidingIds);
+                    if (e.currentTarget.checked) next.add(r.id);
+                    else next.delete(r.id);
+                    setDepartedRidingIds(next);
+                  }}
+                  label={
+                    <Text size="12.5px">
+                      {r.reference ?? r.id}
+                      {r.isGovernment ? (
+                        <Text span size="11px" c={T.muted}>
+                          {" "}
+                          · government, cannot be removed
+                        </Text>
+                      ) : null}
+                    </Text>
+                  }
+                />
+                <Text size="11px" c={T.muted}>
+                  {r.customer}
+                </Text>
+              </Group>
+            ))}
+            {departedLeftBehind.length ? (
+              <Text size="11.5px" fw={700} c={T.amber}>
+                {departedLeftBehind.length} booking
+                {departedLeftBehind.length === 1 ? "" : "s"} will be removed from this train.
+              </Text>
+            ) : null}
+          </Stack>
+        ) : null}
+
         {!logged ? (
           <DateTimePicker
             label={isFinal ? "Arrival time" : "Time at station"}
@@ -602,6 +726,13 @@ export function LogPassYardWorkModal({
           </Group>
         </Group>
       </Stack>
+      {/* Part-loaded gate. Cutting the wagons does NOT log the pass — the
+          operator confirms the pass again once the consist is clean. */}
+      <PartiallyLoadedDecisionModal
+        payload={partialGate}
+        onClose={() => setPartialGate(null)}
+        onResolved={() => void yardWorkQuery.refetch()}
+      />
     </Modal>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/PartiallyLoadedDecisionModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/PartiallyLoadedDecisionModal.tsx
new file mode 100644
index 000000000..ff083faea
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/PartiallyLoadedDecisionModal.tsx
@@ -0,0 +1,250 @@
+import {
+  Alert,
+  Button,
+  Divider,
+  Group,
+  Modal,
+  Paper,
+  Radio,
+  Stack,
+  Text,
+  Textarea,
+} from "@mantine/core";
+import { useMutation } from "@tanstack/react-query";
+import { AlertTriangle, PackageX } from "lucide-react";
+import { useEffect, useState } from "react";
+
+import { useToast } from "@/hooks/use-toast";
+import { api } from "@/services/api";
+
+/**
+ * One partially-loaded booking, as the server reports it in the
+ * PARTIALLY_LOADED_BOOKINGS error payload.
+ */
+export interface PartiallyLoadedBooking {
+  bookingId: string;
+  reference: string;
+  loadedWagons: number;
+  totalWagons: number;
+  unloadedAllocationIds: string[];
+}
+
+export interface PartiallyLoadedPayload {
+  scheduleId: string;
+  boardingYardId: string;
+  yardLabel: string | null;
+  action: string;
+  bookings: PartiallyLoadedBooking[];
+}
+
+/**
+ * Reads the structured `partiallyLoaded` block off a rejected dispatch or
+ * log-pass. Returns null for every other error so callers can fall through to
+ * their normal toast.
+ */
+export function parsePartiallyLoaded(
+  error: unknown,
+): PartiallyLoadedPayload | null {
+  const data = (
+    error as {
+      response?: {
+        data?: { code?: string; partiallyLoaded?: PartiallyLoadedPayload };
+      };
+    }
+  )?.response?.data;
+  if (data?.code !== "PARTIALLY_LOADED_BOOKINGS") return null;
+  return data.partiallyLoaded ?? null;
+}
+
+type Fault = "EDR" | "CUSTOMER";
+
+/**
+ * The gate a partly-loaded booking hits at dispatch or log-pass.
+ *
+ * A booking with some wagons loaded and some never loaded can neither ride
+ * (the empty wagons would leave as ghosts) nor be left behind (unassigning
+ * would strand cargo physically on the train). So the operator decides here:
+ * cut the never-loaded wagons at EDR's fault (no fee, rebookable credit) or
+ * the customer's (cancellation fee invoiced) — or block, and go finish loading.
+ *
+ * Cancelling does NOT then log the pass. The modal closes, the caller refetches,
+ * and the operator clicks their action again with the gate cleared — two
+ * deliberate commits rather than one compound one.
+ */
+export function PartiallyLoadedDecisionModal({
+  payload,
+  onClose,
+  onResolved,
+}: {
+  payload: PartiallyLoadedPayload | null;
+  onClose: () => void;
+  /** Cut succeeded — refetch, so the retry sees the cleared gate. */
+  onResolved: () => void;
+}) {
+  const { toast } = useToast();
+  const [fault, setFault] = useState<Fault | null>(null);
+  const [reason, setReason] = useState("");
+  const cancelRemaining = useMutation(
+    api.trainScheduling.cancelRemainingWagons.mutationOptions(),
+  );
+
+  useEffect(() => {
+    setFault(null);
+    setReason("");
+  }, [payload?.boardingYardId, payload?.bookings.length]);
+
+  if (!payload) return null;
+
+  const { bookings, yardLabel, action } = payload;
+  const totalUnloaded = bookings.reduce(
+    (n, b) => n + b.unloadedAllocationIds.length,
+    0,
+  );
+  const where = yardLabel ? ` at ${yardLabel}` : "";
+
+  const submit = async () => {
+    if (!fault) return;
+    const edrFault = fault === "EDR";
+    try {
+      // Cut every partly-loaded booking's never-loaded wagons under the one
+      // decision — they are all stuck behind the same gate for the same reason.
+      for (const b of bookings) {
+        await cancelRemaining.mutateAsync({
+          bookingId: b.bookingId,
+          scheduleId: payload.scheduleId,
+          reason: reason.trim(),
+          edrFault,
+          wagonAllocationIds: b.unloadedAllocationIds,
+        });
+      }
+      toast({
+        title: `${totalUnloaded} wagon${totalUnloaded === 1 ? "" : "s"} cancelled`,
+        description: edrFault
+          ? "EDR's fault — no fee charged; the credit is rebookable."
+          : "Customer's fault — the cancellation fee was invoiced; the credit is rebookable.",
+      });
+      onResolved();
+      onClose();
+    } catch (err) {
+      const message = (
+        err as { response?: { data?: { message?: string | string[] } } }
+      )?.response?.data?.message;
+      toast({
+        title: "Cancellation failed",
+        description: Array.isArray(message)
+          ? message.join("; ")
+          : message || (err as Error)?.message || "Please try again",
+        variant: "destructive",
+      });
+    }
+  };
+
+  return (
+    <Modal
+      opened
+      onClose={onClose}
+      centered
+      radius="lg"
+      size="lg"
+      title={
+        <Group gap={8}>
+          <PackageX size={18} />
+          <Text fw={700}>Partly loaded — a decision is needed</Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <Alert
+          color="orange"
+          variant="light"
+          radius="md"
+          icon={<AlertTriangle size={18} />}
+          title={`Cannot ${action}${where}`}
+        >
+          <Text size="sm">
+            A booking with some wagons loaded and some never loaded can neither
+            ride nor be removed — the loaded cargo is physically on the train.
+          </Text>
+        </Alert>
+
+        <Stack gap={8}>
+          {bookings.map((b) => (
+            <Paper key={b.bookingId} withBorder radius="md" p="sm">
+              <Group justify="space-between" wrap="nowrap">
+                <Text fw={700} size="sm">
+                  {b.reference}
+                </Text>
+                <Text size="sm" c="dimmed">
+                  {b.loadedWagons} of {b.totalWagons} wagons loaded
+                </Text>
+              </Group>
+              <Text size="xs" c="dimmed" mt={4}>
+                {b.unloadedAllocationIds.length} wagon
+                {b.unloadedAllocationIds.length === 1 ? "" : "s"} never loaded —
+                to be cancelled. The {b.loadedWagons} loaded wagon
+                {b.loadedWagons === 1 ? "" : "s"} stay on the train.
+              </Text>
+            </Paper>
+          ))}
+        </Stack>
+
+        <Divider />
+
+        <Radio.Group
+          label={`What happens to the ${totalUnloaded} never-loaded wagon${totalUnloaded === 1 ? "" : "s"}?`}
+          value={fault ?? ""}
+          onChange={(v) => setFault(v as Fault)}
+        >
+          <Stack gap={8} mt={8}>
+            <Radio
+              value="EDR"
+              label="Cancel — EDR's fault"
+              description="Wagon shortage, yard problem. No fee charged; the credit is rebookable."
+            />
+            <Radio
+              value="CUSTOMER"
+              label="Cancel — customer's fault"
+              description="Cargo not ready, no-show. The cancellation fee is invoiced; the credit is rebookable."
+            />
+          </Stack>
+        </Radio.Group>
+
+        {fault ? (
+          <Textarea
+            label="Reason"
+            placeholder="Why are these wagons not riding?"
+            value={reason}
+            onChange={(e) => setReason(e.currentTarget.value)}
+            minRows={2}
+            required
+          />
+        ) : null}
+
+        <Text size="xs" c="dimmed">
+          Cancelling does not {action} — you will confirm that separately once
+          the wagons are cut.
+        </Text>
+
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" radius="md" onClick={onClose}>
+            Block — go finish loading
+          </Button>
+          <Button
+            color="red"
+            radius="md"
+            disabled={!fault || !reason.trim()}
+            loading={cancelRemaining.isPending}
+            onClick={() => void submit()}
+          >
+            Cancel {totalUnloaded} wagon{totalUnloaded === 1 ? "" : "s"}
+            {fault === "EDR"
+              ? " (no fee)"
+              : fault === "CUSTOMER"
+                ? " (fee applies)"
+                : ""}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
index f63abe12d..a7d8f0323 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
@@ -303,6 +303,7 @@ export function ScheduleWorkspacePanel({
   const [moveBookingId, setMoveBookingId] = useState<string | null>(null);
   // Per-wagon loading/unloading modal for one booking.
   const [wagonModal, setWagonModal] = useState<{
+    isExport: boolean;
     bookingId: string;
     ref: string;
     phase: "load" | "unload";
@@ -908,7 +909,12 @@ export function ScheduleWorkspacePanel({
                                   radius="md"
                                   disabled={!canLoad || !loadWindowStarted}
                                   onClick={() =>
-                                    setWagonModal({ bookingId: b.id, ref, phase: "load" })
+                                    setWagonModal({
+                                      bookingId: b.id,
+                                      ref,
+                                      phase: "load",
+                                      isExport: b.tradeDirection === "EXPORT",
+                                    })
                                   }
                                 >
                                   Wagons
@@ -987,7 +993,12 @@ export function ScheduleWorkspacePanel({
                                   radius="md"
                                   disabled={!canUnload || !unloadWindowStarted}
                                   onClick={() =>
-                                    setWagonModal({ bookingId: b.id, ref, phase: "unload" })
+                                    setWagonModal({
+                                      bookingId: b.id,
+                                      ref,
+                                      phase: "unload",
+                                      isExport: b.tradeDirection === "EXPORT",
+                                    })
                                   }
                                 >
                                   Wagons
@@ -1035,6 +1046,7 @@ export function ScheduleWorkspacePanel({
           bookingId={wagonModal.bookingId}
           reference={wagonModal.ref}
           phase={wagonModal.phase}
+          isExport={wagonModal.isExport}
           onClose={() => setWagonModal(null)}
           onChanged={onChanged}
         />
@@ -1423,6 +1435,7 @@ function PerWagonModal({
   bookingId,
   reference,
   phase,
+  isExport,
   onClose,
   onChanged,
 }: {
@@ -1430,13 +1443,35 @@ function PerWagonModal({
   bookingId: string;
   reference: string;
   phase: "load" | "unload";
+  /**
+   * EXPORT booking — only these may use the truck-to-train submit, which is
+   * what the server's handover-mode endpoint enforces too (it 400s on any
+   * other direction).
+   */
+  isExport: boolean;
   onClose: () => void;
   onChanged: () => void;
 }) {
   const { toast } = useToast();
-  const [cancelOpen, setCancelOpen] = useState(false);
+
   const [reason, setReason] = useState("");
   const [edrFault, setEdrFault] = useState(false);
+  // Wagons ticked for this submit. Load is a batch action now: pick the wagons
+  // that physically went on, then submit once.
+  const [picked, setPicked] = useState<Set<string>>(new Set());
+  // Which submit is in flight — also decides whether the handover mode is set
+  // first ("truck") or the GRN gate is left to reject ("load").
+  const [submitting, setSubmitting] = useState<null | "load" | "truck">(null);
+  // Submit awaiting confirmation. Loading is irreversible from this screen —
+  // there is no "unload back to the yard" here — and truck-to-train also drops
+  // the booking's GRN requirement for good, so both go through a confirm step.
+  // The one open panel, if any. A single slot rather than a flag per panel:
+  // separate booleans let the cancel form and a submit confirm show at the same
+  // time, each with its own buttons.
+  const [confirmSubmit, setConfirmSubmit] = useState<null | "load" | "truck" | "cancel">(
+    null,
+  );
+  const cancelOpen = confirmSubmit === "cancel";
 
   const wagonsQuery = useQuery(api.trainScheduling.bookingWagons.queryOptions({
     input: { bookingId },
@@ -1463,41 +1498,118 @@ function PerWagonModal({
       ? ((err.response?.data as { message?: string })?.message ?? err.message)
       : String(err);
 
-  const onWagon = (allocationId: string) => {
-    act
-      .mutateAsync({ scheduleId, bookingId, allocationId })
-      .then((r) => {
-        void wagonsQuery.refetch();
-        if (r.completed) {
-          toast({
-            title: phase === "load" ? "Booking fully loaded" : "Booking fully unloaded",
-            description: `${reference}: every wagon is ${phase === "load" ? "loaded — the booking is in transit" : "unloaded — the booking arrived"}.`,
+  const toggle = (allocationId: string) =>
+    setPicked((prev) => {
+      const next = new Set(prev);
+      if (next.has(allocationId)) next.delete(allocationId);
+      else next.add(allocationId);
+      return next;
+    });
+
+  const pickedPending = pending.filter((w) => picked.has(w.allocationId));
+
+  /**
+   * Submit the ticked wagons. There is no batch endpoint, so they go one at a
+   * time in order — the server flips the booking to IN_TRANSIT on whichever
+   * call clears the last unloaded wagon, so sequential is required, not just
+   * convenient. The first failure stops the run: the wagons already sent stay
+   * loaded (each call is its own transaction) and the toast names the survivor
+   * count, so a retry only resends what is left.
+   *
+   * `mode: "truck"` first sets DIRECT_TO_TRAIN, which is what makes the GRN
+   * gate let this booking through — see assertExportReceivedWithGrn. Plain
+   * "load" sends nothing extra and lets that gate reject unreceived cargo.
+   */
+  const onSubmit = (mode: "load" | "truck") => {
+    const targets = pickedPending;
+    if (!targets.length) return;
+    setConfirmSubmit(null);
+    setSubmitting(mode);
+
+    const run = async () => {
+      if (mode === "truck") {
+        await bookingsService.setExportHandoverMode(bookingId, "DIRECT_TO_TRAIN");
+      }
+      let done = 0;
+      let completed = false;
+      try {
+        for (const w of targets) {
+          const r = await act.mutateAsync({
+            scheduleId,
+            bookingId,
+            allocationId: w.allocationId,
           });
-          onChanged();
-          onClose();
-        } else {
+          done += 1;
+          if (r.completed) completed = true;
+        }
+      } catch (err) {
+        // Partial success is a real outcome here, not a rollback candidate:
+        // report what landed so the operator knows what to retry.
+        if (done > 0) {
+          void wagonsQuery.refetch();
           onChanged();
         }
+        throw Object.assign(err as Error, { partial: done });
+      }
+      return { done, completed };
+    };
+
+    run()
+      .then(({ done, completed }) => {
+        void wagonsQuery.refetch();
+        onChanged();
+        setPicked(new Set());
+        if (completed) {
+          toast({
+            title: phase === "load" ? "Booking fully loaded" : "Booking fully unloaded",
+            description:
+              phase === "load"
+                ? `${reference}: every wagon is loaded — the booking is in transit${mode === "truck" ? " (direct truck-to-train handover)" : ""}.`
+                : `${reference}: every wagon is unloaded — the booking arrived.`,
+          });
+          onClose();
+        } else {
+          toast({
+            title: phase === "load" ? "Wagons loaded" : "Wagons unloaded",
+            description: `${reference}: ${done} wagon${done === 1 ? "" : "s"} ${phase === "load" ? "loaded" : "unloaded"}.`,
+          });
+        }
       })
-      .catch((err) =>
+      .catch((err) => {
+        const sent = (err as { partial?: number }).partial ?? 0;
         toast({
           title: phase === "load" ? "Wagon load failed" : "Wagon unload failed",
-          description: errText(err),
+          description: sent
+            ? `${sent} wagon(s) went through before this: ${errText(err)}`
+            : errText(err),
           variant: "destructive",
-        }),
-      );
+        });
+      })
+      .finally(() => setSubmitting(null));
   };
 
   const onCancelRemaining = () => {
+    // Cut exactly the ticked wagons. Sending the ids (rather than omitting them
+    // and letting the server cut the whole remainder) is what makes a partial
+    // cancel possible while other wagons are still waiting to load.
+    const ids = pickedPending.map((w) => w.allocationId);
+    const count = ids.length;
     cancelRemaining
-      .mutateAsync({ bookingId, scheduleId, reason: reason.trim(), edrFault })
+      .mutateAsync({
+        bookingId,
+        scheduleId,
+        reason: reason.trim(),
+        edrFault,
+        wagonAllocationIds: ids,
+      })
       .then(() => {
         toast({
-          title: "Remaining wagons cancelled",
+          title: "Wagons cancelled",
           description: edrFault
-            ? `${reference}: ${pending.length} wagon(s) cancelled at EDR's fault — no fee charged; the credit is rebookable.`
-            : `${reference}: ${pending.length} wagon(s) cancelled — the cancellation fee was invoiced to the customer; the credit is rebookable.`,
+            ? `${reference}: ${count} wagon(s) cancelled at EDR's fault — no fee charged; the credit is rebookable.`
+            : `${reference}: ${count} wagon(s) cancelled — the cancellation fee was invoiced to the customer; the credit is rebookable.`,
         });
+        setPicked(new Set());
         onChanged();
         onClose();
       })
@@ -1550,6 +1662,15 @@ function PerWagonModal({
             <Paper key={w.allocationId} withBorder radius="md" p="xs">
               <Group justify="space-between" wrap="nowrap">
                 <Group gap={8} wrap="nowrap" style={{ minWidth: 0 }}>
+                  {!isDone(w) ? (
+                    <Checkbox
+                      checked={picked.has(w.allocationId)}
+                      onChange={() => toggle(w.allocationId)}
+                      disabled={submitting != null}
+                      color={phase === "load" ? "edr-green" : "orange"}
+                      aria-label={`Select wagon ${w.sequenceNo ?? ""} to ${phase}`}
+                    />
+                  ) : null}
                   <Badge size="sm" radius="sm" variant="outline" color="gray">
                     {w.sequenceNo != null ? `#${w.sequenceNo}` : "—"}
                   </Badge>
@@ -1574,50 +1695,216 @@ function PerWagonModal({
                   >
                     {phase === "load" ? "Loaded" : "Unloaded"}
                   </Badge>
-                ) : (
-                  <Button
-                    size="compact-sm"
-                    variant="filled"
-                    color={phase === "load" ? "edr-green" : "orange"}
-                    radius="md"
-                    leftSection={
-                      phase === "load" ? <PackageCheck size={13} /> : <PackageOpen size={13} />
-                    }
-                    loading={
-                      act.isPending && act.variables?.allocationId === w.allocationId
-                    }
-                    onClick={() => onWagon(w.allocationId)}
-                  >
-                    {phase === "load" ? "Load" : "Unload"}
-                  </Button>
-                )}
+                ) : null}
               </Group>
             </Paper>
           ))
         )}
 
-        {phase === "load" && doneCount > 0 && pending.length > 0 ? (
-          !cancelOpen ? (
-            <Button
-              variant="light"
-              color="red"
-              radius="md"
-              leftSection={<X size={14} />}
-              onClick={() => setCancelOpen(true)}
-            >
-              Cancel the {pending.length} remaining wagon{pending.length === 1 ? "" : "s"}…
-            </Button>
-          ) : (
-            <Paper withBorder radius="md" p="sm">
+        {pending.length > 0 && !confirmSubmit ? (
+          <Group justify="space-between" wrap="wrap" gap="sm">
+            <Group gap={8}>
+              <Button
+                size="compact-sm"
+                variant="subtle"
+                radius="md"
+                disabled={submitting != null}
+                onClick={() =>
+                  setPicked(
+                    picked.size === pending.length
+                      ? new Set()
+                      : new Set(pending.map((w) => w.allocationId)),
+                  )
+                }
+              >
+                {picked.size === pending.length ? "Clear all" : "Select all"}
+              </Button>
+              <Text size="xs" c="dimmed">
+                {pickedPending.length} of {pending.length} selected
+              </Text>
+            </Group>
+            <Group gap="sm">
+              {phase === "load" ? (
+                <Tooltip
+                  label="Cancel the selected wagons — they will not ride. Customer fault invoices the cancellation fee; EDR fault charges nothing."
+                  withArrow
+                >
+                  <Button
+                    variant="light"
+                    color="red"
+                    radius="md"
+                    leftSection={<X size={14} />}
+                    disabled={!pickedPending.length || submitting != null}
+                    onClick={() => setConfirmSubmit("cancel")}
+                  >
+                    Cancel
+                  </Button>
+                </Tooltip>
+              ) : null}
+              {phase === "load" && isExport ? (
+                <Tooltip
+                  label="Customer truck loaded straight onto the wagon — no warehouse receipt, no GRN. Sets direct truck-to-train handover, then loads the selected wagons."
+                  withArrow
+                >
+                  <Button
+                    variant="light"
+                    color="blue"
+                    radius="md"
+                    leftSection={<Truck size={14} />}
+                    disabled={!pickedPending.length || submitting != null}
+                    loading={submitting === "truck"}
+                    onClick={() => setConfirmSubmit("truck")}
+                  >
+                    Truck to train
+                  </Button>
+                </Tooltip>
+              ) : null}
+              <Tooltip
+                label={
+                  phase === "load"
+                    ? "Load the selected wagons — export cargo must already be received at the warehouse with a GRN."
+                    : "Unload the selected wagons."
+                }
+                withArrow
+              >
+                <Button
+                  color={phase === "load" ? "edr-green" : "orange"}
+                  radius="md"
+                  leftSection={
+                    phase === "load" ? <PackageCheck size={14} /> : <PackageOpen size={14} />
+                  }
+                  disabled={!pickedPending.length || submitting != null}
+                  loading={submitting === "load"}
+                  onClick={() => setConfirmSubmit("load")}
+                >
+                  {phase === "load" ? "Load" : "Unload"} {pickedPending.length || ""}
+                </Button>
+              </Tooltip>
+            </Group>
+          </Group>
+        ) : null}
+
+        {confirmSubmit && confirmSubmit !== "cancel" ? (
+          <Paper withBorder radius="md" p="sm">
+            <Stack gap="xs">
+              <Group gap={10} wrap="nowrap">
+                <ThemeIcon
+                  size={40}
+                  radius="md"
+                  variant="light"
+                  color={
+                    confirmSubmit === "truck"
+                      ? "blue"
+                      : phase === "load"
+                        ? "edr-green"
+                        : "orange"
+                  }
+                >
+                  {confirmSubmit === "truck" ? (
+                    <Truck size={21} />
+                  ) : phase === "load" ? (
+                    <PackageCheck size={21} />
+                  ) : (
+                    <PackageOpen size={21} />
+                  )}
+                </ThemeIcon>
+                <div>
+                  <Text fw={800}>
+                    {confirmSubmit === "truck"
+                      ? "Load as direct truck-to-train?"
+                      : phase === "load"
+                        ? `Load ${pickedPending.length} wagon${pickedPending.length === 1 ? "" : "s"}?`
+                        : `Unload ${pickedPending.length} wagon${pickedPending.length === 1 ? "" : "s"}?`}
+                  </Text>
+                  <Text size="xs" c="dimmed">
+                    {reference}
+                  </Text>
+                </div>
+              </Group>
+              <Text size="sm">
+                {confirmSubmit === "truck"
+                  ? `Sets direct truck-to-train handover for the whole booking (no warehouse receipt, no GRN — the carriage acceptance sheet becomes the handover document), then loads the ${pickedPending.length} selected wagon${pickedPending.length === 1 ? "" : "s"}.`
+                  : phase === "load"
+                    ? "Stamps the selected wagons as loaded at this yard. Export cargo must already be received at the warehouse with a GRN."
+                    : "Stamps the selected wagons as unloaded and frees them for reuse."}
+              </Text>
+              {confirmSubmit === "truck" ? (
+                <Group
+                  gap={8}
+                  p="xs"
+                  wrap="nowrap"
+                  style={{
+                    borderRadius: 10,
+                    background: "var(--mantine-color-yellow-0)",
+                    border: "1px solid var(--mantine-color-yellow-3)",
+                  }}
+                >
+                  <AlertTriangle size={16} color="#B54708" />
+                  <Text size="xs" c="yellow.9" fw={500}>
+                    The handover mode applies to the whole booking and stays set
+                    even if a wagon then fails to load — its GRN requirement is
+                    dropped for good.
+                  </Text>
+                </Group>
+              ) : null}
+              {pickedPending.length < pending.length ? (
+                <Text size="xs" c="dimmed">
+                  {pending.length - pickedPending.length} wagon
+                  {pending.length - pickedPending.length === 1 ? "" : "s"} left
+                  un{phase === "load" ? "loaded" : "unloaded"} — the train cannot
+                  dispatch until they are {phase === "load" ? "loaded" : "unloaded"} or
+                  cancelled.
+                </Text>
+              ) : null}
+              <Group justify="flex-end" gap="sm">
+                <Button variant="default" radius="md" onClick={() => setConfirmSubmit(null)}>
+                  Back
+                </Button>
+                <Button
+                  color={
+                    confirmSubmit === "truck"
+                      ? "blue"
+                      : phase === "load"
+                        ? "edr-green"
+                        : "orange"
+                  }
+                  radius="md"
+                  leftSection={
+                    confirmSubmit === "truck" ? (
+                      <Truck size={14} />
+                    ) : phase === "load" ? (
+                      <PackageCheck size={14} />
+                    ) : (
+                      <PackageOpen size={14} />
+                    )
+                  }
+                  onClick={() => onSubmit(confirmSubmit === "truck" ? "truck" : "load")}
+                >
+                  {confirmSubmit === "truck"
+                    ? "Load direct"
+                    : phase === "load"
+                      ? "Load"
+                      : "Unload"}
+                </Button>
+              </Group>
+            </Stack>
+          </Paper>
+        ) : null}
+
+        {phase === "load" && cancelOpen && pickedPending.length > 0 ? (
+          <Paper withBorder radius="md" p="sm">
               <Stack gap="xs">
                 <Text size="sm" fw={600}>
-                  Cancel {pending.length} unloaded wagon
-                  {pending.length === 1 ? "" : "s"} of {reference}
+                  Cancel {pickedPending.length} selected wagon
+                  {pickedPending.length === 1 ? "" : "s"} of {reference}
                 </Text>
                 <Text size="xs" c="dimmed">
-                  The booking shrinks to its loaded wagons and the freed freight
+                  These wagons are cut from the booking and the freed freight
                   becomes a rebookable credit. Customer fault: the cancellation
                   fee is invoiced, payable afterwards. EDR fault: no fee.
+                  {pending.length > pickedPending.length
+                    ? ` The other ${pending.length - pickedPending.length} unloaded wagon(s) stay on the booking and still have to be loaded or cancelled before dispatch.`
+                    : ""}
                 </Text>
                 <Textarea
                   label="Reason"
@@ -1633,7 +1920,7 @@ function PerWagonModal({
                   onChange={(e) => setEdrFault(e.currentTarget.checked)}
                 />
                 <Group justify="flex-end" gap="sm">
-                  <Button variant="default" radius="md" onClick={() => setCancelOpen(false)}>
+                  <Button variant="default" radius="md" onClick={() => setConfirmSubmit(null)}>
                     Back
                   </Button>
                   <Button
@@ -1647,8 +1934,7 @@ function PerWagonModal({
                   </Button>
                 </Group>
               </Stack>
-            </Paper>
-          )
+          </Paper>
         ) : null}
       </Stack>
     </Modal>
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/Train3DVisualization.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/Train3DVisualization.tsx
index 38295a393..cff287169 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/Train3DVisualization.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/Train3DVisualization.tsx
@@ -534,7 +534,8 @@ function LocoDetailPanel({
             <Text size="sm" c="gray.5">No locomotive assigned yet.</Text>
           )}
           <Divider color="rgba(255,255,255,0.1)" label="Train" labelPosition="left" />
-          <InfoRow label="Voyage / reference" value={schedule.reference} />
+          <InfoRow label="Voyage number" value={schedule.voyageNumber} />
+          <InfoRow label="Reference" value={schedule.reference} />
           <InfoRow label="Train number" value={schedule.trainNumber} />
           <InfoRow
             label="Train"
diff --git a/apps/edr-freight-web/backoffice/src/components/transit-agents/TransitAgentAccountAction.tsx b/apps/edr-freight-web/backoffice/src/components/transit-agents/TransitAgentAccountAction.tsx
new file mode 100644
index 000000000..65bcc0fce
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/transit-agents/TransitAgentAccountAction.tsx
@@ -0,0 +1,156 @@
+import { Button, Stack, TextInput, Tooltip } from "@mantine/core";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+
+import PhoneField, { isValidPhone } from "@/components/PhoneField";
+import { ActivationLinkDialog } from "@/components/shipping-lines/ResendActivationAction";
+import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
+import { useToast } from "@/hooks/use-toast";
+import { transitAgentsService } from "@/services/transit-agents.service";
+import type { TransitAgent } from "@/services/transit-agents.service";
+import type { ResetChannel } from "@/types/shippingLineCompany";
+
+export interface TransitAgentAccountActionProps {
+  agent: TransitAgent;
+  /** Hidden entirely without the update permission, matching the other row controls. */
+  disabled?: boolean;
+}
+
+/**
+ * The account column's row control: **Invite** for an agent that has no portal
+ * login yet, **Resend** for one that has.
+ *
+ * Inviting is deliberately its own action rather than a side effect of editing
+ * the email: it mints an IAM user, and a field edit must never do that
+ * implicitly — the roster rows that predate portal logins would start growing
+ * accounts the first time anyone corrected a typo.
+ */
+export default function TransitAgentAccountAction({
+  agent,
+  disabled,
+}: TransitAgentAccountActionProps) {
+  const { toast } = useToast();
+  const queryClient = useQueryClient();
+  const [email, setEmail] = useState(agent.email ?? "");
+  const [phoneNumber, setPhoneNumber] = useState(agent.phoneNumber ?? "");
+
+  const invalidate = () =>
+    queryClient.invalidateQueries({ queryKey: QUERY_KEYS.RULE_ENGINE.ROOT });
+
+  const invite = useMutation({
+    mutationFn: () =>
+      transitAgentsService.invite(agent.id, {
+        email: email.trim(),
+        phoneNumber: phoneNumber.trim() || undefined,
+      }),
+    onSuccess: async (result) => {
+      await invalidate();
+      toast({
+        title: "Portal account created",
+        description: result.activationSentTo
+          ? `${agent.name} can set their password using the link sent to ${result.activationSentTo}. It expires in 24 hours.`
+          : `${agent.name} now has a portal account, but the activation link could not be sent — resend it.`,
+      });
+    },
+    onError: (error: Error) =>
+      toast({
+        title: "Could not create the portal account",
+        description: error.message,
+        variant: "destructive",
+      }),
+  });
+
+  const resend = useMutation({
+    mutationFn: (channel: ResetChannel) =>
+      transitAgentsService.resendActivation(agent.id, channel),
+    onSuccess: (result) =>
+      toast({
+        title: "Activation link sent",
+        description: `${agent.name} can set their password using the link sent to ${result.maskedTarget}. It expires in 24 hours.`,
+      }),
+    onError: (error: Error) =>
+      toast({
+        title: "Could not send activation link",
+        description: error.message,
+        variant: "destructive",
+      }),
+  });
+
+  if (disabled) return null;
+
+  // Already has a login — the only thing left is another copy of the link, so
+  // this is exactly the shipping-line dialog with a different endpoint behind it.
+  if (agent.hasAccount) {
+    return (
+      <ActivationLinkDialog
+        target={agent}
+        audienceLabel="transit agent"
+        isPending={resend.isPending}
+        onSend={(channel, onDone) =>
+          resend.mutate(channel, { onSuccess: onDone })
+        }
+        trigger={(open) => (
+          <Tooltip label="Resend activation link" withArrow>
+            <Button size="compact-xs" variant="light" onClick={open}>
+              Resend
+            </Button>
+          </Tooltip>
+        )}
+      />
+    );
+  }
+
+  return (
+    <ActivationLinkDialog
+      // Show the addresses being typed, not the (empty) stored ones, so the
+      // channel picker enables SMS as soon as a domestic number is entered.
+      target={{
+        ...agent,
+        email: email.trim() || null,
+        phoneNumber: phoneNumber.trim() || null,
+      }}
+      audienceLabel="transit agent"
+      isPending={invite.isPending}
+      title="Create portal account"
+      submitLabel="Create account and send link"
+      // The channel choice is the dialog's, but invite always emails (and texts
+      // a domestic number) — the API picks both. Sending is what matters here.
+      // A half-typed number is a non-empty partial E.164 the API rejects with a
+      // 400 — block it here rather than posting it.
+      submitDisabled={
+        !email.trim() || (!!phoneNumber.trim() && !isValidPhone(phoneNumber))
+      }
+      onSend={(_channel, onDone) =>
+        invite.mutate(undefined, { onSuccess: onDone })
+      }
+      trigger={(open) => (
+        <Tooltip label="Give this agent a portal login" withArrow>
+          <Button size="compact-xs" variant="light" onClick={open}>
+            Invite
+          </Button>
+        </Tooltip>
+      )}
+    >
+      <Stack gap="sm">
+        <TextInput
+          label="Email"
+          placeholder="a.bourhan@transit.dj"
+          required
+          value={email}
+          onChange={(e) => setEmail(e.currentTarget.value)}
+        />
+        <PhoneField
+          label="Phone number"
+          value={phoneNumber}
+          onChange={(v) => setPhoneNumber(v ?? "")}
+          error={
+            phoneNumber.trim() && !isValidPhone(phoneNumber)
+              ? "Enter the complete number"
+              : undefined
+          }
+          description="Ethiopian and Djiboutian mobiles also receive the link by SMS"
+        />
+      </Stack>
+    </ActivationLinkDialog>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/LoadToTrainPanel.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/LoadToTrainPanel.tsx
index 828f4ab44..6b0e0f1b2 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/LoadToTrainPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/LoadToTrainPanel.tsx
@@ -22,6 +22,7 @@ import {
   type TrainLoadableItem,
 } from '@/services/warehouse.service';
 import { extractErrorMessage } from './options';
+import { YardLoadingWindows } from './YardLoadingWindows';
 
 const STAGE_COLOR: Record<string, string> = {
   RECEIVED: 'blue',
@@ -161,6 +162,11 @@ function TrainRow({ train, expanded, onToggle }: { train: LoadableTrain; expande
                 </Alert>
               ) : (
                 <Stack gap="xs">
+                  <YardLoadingWindows
+                    scheduleId={train.scheduleId}
+                    items={items}
+                    logs={train.stationWorkLogs}
+                  />
                   {bookings.map((b) => (
                     <BookingBlock key={b.bookingId ?? b.bookingReference} scheduleId={train.scheduleId} booking={b} />
                   ))}
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx
index f87d6d24d..1f3a1cf81 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/ReceiveInventoryModal.tsx
@@ -11,8 +11,10 @@ import {
   Loader,
   Menu,
   Modal,
+  MultiSelect,
   NumberInput,
   ScrollArea,
+  SegmentedControl,
   Select,
   SimpleGrid,
   Stack,
@@ -58,6 +60,7 @@ import { QUERY_KEYS } from '@/constants/QUERY_KEYS';
 import { useToast } from '@/hooks/use-toast';
 import { useAllWarehouseYards, useAllWarehouseZones, useInventoryInquiry } from '@/hooks/useWarehouses';
 import { firstMileService } from '@/services/first-mile.service';
+import { bookingsService } from '@/services/bookings.service';
 import { warehouseService } from '@/services/warehouse.service';
 import type {
   EligibleBooking,
@@ -90,6 +93,8 @@ import { MoveInventoryModal } from './MoveInventoryModal';
 import { ReleaseOrderModal } from './ReleaseOrderModal';
 import { StoreInventoryModal } from './StoreInventoryModal';
 import { WarehouseInquiryTable } from './WarehouseInquiryTable';
+import { TrainLoadingWorkspace } from './TrainLoadingWorkspace';
+import { YardLoadingWindows } from './YardLoadingWindows';
 import { extractDownloadErrorMessage, extractErrorMessage, formatDate, formatNumber, inventoryStatusOptions, warehousesAtStation, yardsForBooking } from './options';
 import { openPdfBlob } from './pdf';
 import ListControls from '@/components/common/ListControls';
@@ -857,6 +862,8 @@ function EligibleTab({
   const [truckForm, setTruckForm] = useState<TruckEntranceFormState>(emptyTruckEntrance());
   const [lockedTruckFields, setLockedTruckFields] = useState<LockedTruckEntranceFields>({});
   const [packagingFreightType, setPackagingFreightType] = useState<PackagingFreightType>('MIXED');
+  const [selectedCustomerTruckId, setSelectedCustomerTruckId] = useState<string | null>(null);
+  const [selectedContainerNumbers, setSelectedContainerNumbers] = useState<string[]>([]);
 
   const locationReady = Boolean(location.warehouseId && location.yardId && location.zoneId);
   const canReceiveBooking = (row: EligibleBooking) =>
@@ -943,6 +950,105 @@ function EligibleTab({
   const pendingHasFirstMile = pendingReceiveRows.some((row) => row.hasFirstMile);
   const pendingUsesFirstMile =
     pendingReceiveRows.length > 0 && pendingReceiveRows.every((row) => row.hasFirstMile);
+  const pendingContainerBooking =
+    pendingReceiveRows.length === 1 && pendingReceiveRows[0]?.freightType === 'CONTAINER'
+      ? pendingReceiveRows[0]
+      : null;
+  const { data: assignedCustomerTrucks = [] } = useQuery({
+    queryKey: ['receive-customer-trucks', pendingContainerBooking?.id],
+    queryFn: () => warehouseService.getCustomerTrucks(pendingContainerBooking?.id as string),
+    enabled: truckOpen && Boolean(pendingContainerBooking) && !pendingUsesFirstMile,
+  });
+  const pendingContainerUnits = (pendingContainerBooking?.containerUnits ?? []).filter(
+    (unit) => !unit.received,
+  );
+  const selectedCustomerTruck = assignedCustomerTrucks.find(
+    (truck) => truck.id === selectedCustomerTruckId,
+  );
+  const assignedNumbersForSelectedTruck = new Set(
+    (selectedCustomerTruck?.containers ?? []).map((container) => container.containerNumber.toUpperCase()),
+  );
+  const selectableContainerUnits = pendingContainerUnits.filter(
+    (unit) =>
+      assignedNumbersForSelectedTruck.size === 0 ||
+      assignedNumbersForSelectedTruck.has(unit.containerNumber.toUpperCase()),
+  );
+  const selectedContainerUnits = pendingContainerUnits.filter((unit) =>
+    selectedContainerNumbers.includes(unit.containerNumber),
+  );
+  const selectedContainerWeight = selectedContainerUnits.reduce(
+    (total, unit) => total + Number(unit.weightTons || 0),
+    0,
+  );
+  const containerCapacityError =
+    selectedContainerNumbers.length > 2
+      ? 'A truck carries no more than 2 containers.'
+      : selectedContainerNumbers.length > 1 &&
+          selectedContainerUnits.some((unit) => !String(unit.containerSize ?? '').includes('20'))
+        ? 'Truck capacity is either 1 x 40ft container or up to 2 x 20ft containers.'
+        : null;
+
+  useEffect(() => {
+    if (!truckOpen || pendingUsesFirstMile || !pendingContainerBooking) return;
+    if (selectedCustomerTruckId || assignedCustomerTrucks.length === 0) return;
+    const pendingNumbers = new Set(
+      pendingContainerUnits.map((unit) => unit.containerNumber.toUpperCase()),
+    );
+    const truck =
+      assignedCustomerTrucks.find(
+        (candidate) =>
+          !candidate.arrivedAt &&
+          (candidate.containers ?? []).some((container) =>
+            pendingNumbers.has(container.containerNumber.toUpperCase()),
+          ),
+      ) ?? assignedCustomerTrucks[0];
+    const truckContainers = (truck.containers ?? [])
+      .map((container) => container.containerNumber.toUpperCase())
+      .filter((number) => pendingNumbers.has(number));
+    setSelectedCustomerTruckId(truck.id);
+    setSelectedContainerNumbers(truckContainers);
+    setTruckForm((current) => ({
+      ...current,
+      truckPlateNumber: truck.plateNumber,
+      driverName: truck.driverName,
+      truckType: truck.truckType,
+      assignedEquipmentNumber: truckContainers.join(', '),
+      unitCount: truckContainers.length,
+      netWeightKg: pendingContainerUnits
+        .filter((unit) => truckContainers.includes(unit.containerNumber.toUpperCase()))
+        .reduce((total, unit) => total + Number(unit.weightTons || 0), 0),
+    }));
+    setLockedTruckFields((current) => ({
+      ...current,
+      truckPlateNumber: true,
+      driverName: true,
+      truckType: true,
+      assignedEquipmentNumber: true,
+      unitCount: true,
+    }));
+  }, [
+    assignedCustomerTrucks,
+    pendingContainerBooking,
+    pendingContainerUnits,
+    pendingUsesFirstMile,
+    selectedCustomerTruckId,
+    truckOpen,
+  ]);
+
+  useEffect(() => {
+    if (!truckOpen || !pendingContainerBooking) return;
+    setTruckForm((current) => ({
+      ...current,
+      assignedEquipmentNumber: selectedContainerNumbers.join(', '),
+      unitCount: selectedContainerNumbers.length,
+      netWeightKg: selectedContainerWeight,
+    }));
+  }, [
+    pendingContainerBooking,
+    selectedContainerNumbers,
+    selectedContainerWeight,
+    truckOpen,
+  ]);
 
   const toggleAll = () =>
     setSelected(allSelected ? new Set() : new Set(selectableRows.map((r) => r.id)));
@@ -953,29 +1059,60 @@ function EligibleTab({
       return next;
     });
 
-  const receiveBookings = async (bookingIds: string[], truckEntrance?: TruckEntrancePayload) => {
+  const receiveBookings = async (
+    bookingIds: string[],
+    truckEntrance?: TruckEntrancePayload,
+    containerNumbers?: string[],
+  ) => {
+    const documentBookingId = direction === 'EXPORT' && bookingIds.length === 1 ? bookingIds[0] : null;
+    const grnWindow = documentBookingId ? window.open('', '_blank') : null;
+    const acceptanceWindow = documentBookingId ? window.open('', '_blank') : null;
     try {
       const r = await bulkReceive.mutateAsync({
         direction,
         ...location,
         bookingIds,
+        ...(containerNumbers?.length ? { containerNumbers } : {}),
         ...(truckEntrance ? { truckEntrance } : {}),
       });
+      const receivedProgress = r.results.find(
+        (item) => item.receivedContainers != null && item.remainingContainers != null,
+      );
       toast({
         title: `${r.receivedCount} received at ${direction === 'EXPORT' ? 'facility' : 'warehouse'}`,
-        description: r.results.find((item) => item.grnNumber)?.grnNumber ?? skippedSummary(r.skippedCount, r.results),
+        description: receivedProgress
+          ? `${containerNumbers?.length ?? 0} container(s) arrived. ${receivedProgress.remainingContainers} container(s) left. GRN ${receivedProgress.grnNumber}.`
+          : r.results.find((item) => item.grnNumber)?.grnNumber ?? skippedSummary(r.skippedCount, r.results),
       });
       const firstGrn = r.results.find((item) => item.inventoryId && item.grnNumber);
-      if (focusedBookingId && firstGrn?.inventoryId && firstGrn.grnNumber) {
-        const pdfWindow = window.open('', '_blank');
+      if (documentBookingId && firstGrn?.inventoryId && firstGrn.grnNumber) {
         try {
           const response = await warehouseService.downloadGrnDocument(firstGrn.inventoryId);
-          const opened = openPdfBlob(response.data, `grn-${firstGrn.grnNumber}.pdf`, pdfWindow);
+          const opened = openPdfBlob(response.data, `grn-${firstGrn.grnNumber}.pdf`, grnWindow);
           toast({ title: opened ? 'GRN document opened' : 'GRN document downloaded' });
         } catch (error) {
-          pdfWindow?.close();
+          grnWindow?.close();
           toast({ variant: 'destructive', title: 'GRN document failed', description: await extractDownloadErrorMessage(error) });
         }
+        try {
+          const acceptance = await bookingsService.downloadCarriageAcceptanceSheet(documentBookingId);
+          const opened = openPdfBlob(
+            acceptance,
+            `carriage-acceptance-${pendingReceiveRows[0]?.reference ?? documentBookingId}.pdf`,
+            acceptanceWindow,
+          );
+          toast({ title: opened ? 'Carriage acceptance sheet opened' : 'Carriage acceptance sheet downloaded' });
+        } catch (error) {
+          acceptanceWindow?.close();
+          toast({
+            variant: 'destructive',
+            title: 'Carriage acceptance sheet failed',
+            description: await extractDownloadErrorMessage(error),
+          });
+        }
+      } else {
+        grnWindow?.close();
+        acceptanceWindow?.close();
       }
       setSelected(new Set());
       setTruckOpen(false);
@@ -983,8 +1120,12 @@ function EligibleTab({
       setReceivedAt(null);
       setLockedTruckFields({});
       setPackagingFreightType('MIXED');
+      setSelectedCustomerTruckId(null);
+      setSelectedContainerNumbers([]);
       onChanged?.();
     } catch (error) {
+      grnWindow?.close();
+      acceptanceWindow?.close();
       toast({ variant: 'destructive', title: 'Receive failed', description: extractErrorMessage(error) });
     }
   };
@@ -1011,6 +1152,18 @@ function EligibleTab({
       void receiveBookings(filteredIds);
       return;
     }
+    if (
+      direction === 'EXPORT' &&
+      selectedRows.some((row) => row.freightType === 'CONTAINER') &&
+      selectedRows.length !== 1
+    ) {
+      toast({
+        variant: 'destructive',
+        title: 'Receive one container booking per truck',
+        description: 'Select the arriving truck and its 1 x 40ft or up to 2 x 20ft containers.',
+      });
+      return;
+    }
     const hasFirstMileRows = selectedRows.some((row) => row.hasFirstMile);
     const hasCustomerTruckRows = selectedRows.some((row) => !row.hasFirstMile);
     if (hasFirstMileRows && hasCustomerTruckRows) {
@@ -1040,6 +1193,8 @@ function EligibleTab({
             ...form,
           };
     setPendingReceiveIds(filteredIds);
+    setSelectedCustomerTruckId(null);
+    setSelectedContainerNumbers([]);
     setReceivedAt(new Date().toISOString());
     setTruckForm(normalizedForm);
     setLockedTruckFields({
@@ -1072,7 +1227,70 @@ function EligibleTab({
       toast({ variant: 'destructive', title: 'Gross weight and exit tare weight are required when weighing is Yes' });
       return;
     }
-    await receiveBookings(pendingReceiveIds, toTruckEntrancePayload(truckForm));
+    if (pendingContainerBooking && selectedContainerNumbers.length === 0) {
+      toast({ variant: 'destructive', title: 'Select the containers arriving on this truck' });
+      return;
+    }
+    if (containerCapacityError) {
+      toast({ variant: 'destructive', title: 'Truck capacity exceeded', description: containerCapacityError });
+      return;
+    }
+    await receiveBookings(
+      pendingReceiveIds,
+      toTruckEntrancePayload({
+        ...truckForm,
+        ...(pendingContainerBooking
+          ? {
+              assignedEquipmentNumber: selectedContainerNumbers.join(', '),
+              unitCount: selectedContainerNumbers.length,
+              netWeightKg: selectedContainerWeight,
+            }
+          : {}),
+      }),
+      pendingContainerBooking ? selectedContainerNumbers : undefined,
+    );
+  };
+
+  const chooseCustomerTruck = (truckId: string | null) => {
+    setSelectedCustomerTruckId(truckId);
+    const truck = assignedCustomerTrucks.find((candidate) => candidate.id === truckId);
+    if (!truck) {
+      setSelectedContainerNumbers([]);
+      setLockedTruckFields((current) => ({
+        ...current,
+        truckPlateNumber: false,
+        driverName: false,
+        truckType: false,
+      }));
+      return;
+    }
+    const pendingNumbers = new Set(
+      pendingContainerUnits.map((unit) => unit.containerNumber.toUpperCase()),
+    );
+    const containers = (truck.containers ?? [])
+      .map((container) => container.containerNumber.toUpperCase())
+      .filter((number) => pendingNumbers.has(number));
+    const weight = pendingContainerUnits
+      .filter((unit) => containers.includes(unit.containerNumber.toUpperCase()))
+      .reduce((total, unit) => total + Number(unit.weightTons || 0), 0);
+    setSelectedContainerNumbers(containers);
+    setTruckForm((current) => ({
+      ...current,
+      truckPlateNumber: truck.plateNumber,
+      driverName: truck.driverName,
+      truckType: truck.truckType,
+      assignedEquipmentNumber: containers.join(', '),
+      unitCount: containers.length,
+      netWeightKg: weight,
+    }));
+    setLockedTruckFields((current) => ({
+      ...current,
+      truckPlateNumber: true,
+      driverName: true,
+      truckType: true,
+      assignedEquipmentNumber: true,
+      unitCount: true,
+    }));
   };
 
 
@@ -1295,6 +1513,76 @@ function EligibleTab({
                 : 'Register the customer or third-party truck and driver before export receiving and GRN.'}
             </Text>
           </Alert>
+          {pendingContainerBooking && (
+            <Stack gap="sm">
+              <Alert icon={<PackageCheck size={16} />} color="teal" variant="light">
+                <Group gap="xs">
+                  <Text size="sm" fw={600}>
+                    {pendingContainerBooking.receivedContainerCount + selectedContainerNumbers.length} containers arrived
+                  </Text>
+                  <Text size="sm">
+                    · {Math.max(
+                      0,
+                      pendingContainerBooking.remainingContainerCount - selectedContainerNumbers.length,
+                    )} left after this receipt
+                  </Text>
+                  <Badge variant="light" color="blue">
+                    This truck: {selectedContainerNumbers.length}
+                  </Badge>
+                </Group>
+              </Alert>
+              {assignedCustomerTrucks.length > 0 && !pendingUsesFirstMile && (
+                <Select
+                  label="Arriving assigned truck"
+                  description="Choose the physical truck at the gate; its assigned containers are selected below."
+                  placeholder="Select truck"
+                  data={assignedCustomerTrucks.map((truck) => ({
+                    value: truck.id,
+                    label: `${truck.plateNumber} · ${truck.driverName} · ${(truck.containers ?? [])
+                      .map((container) => container.containerNumber)
+                      .join(', ') || 'no containers'}`,
+                  }))}
+                  value={selectedCustomerTruckId}
+                  onChange={chooseCustomerTruck}
+                  searchable
+                  required
+                />
+              )}
+              <MultiSelect
+                label="Containers arriving on this truck"
+                description="Required: select either 1 x 40ft container or up to 2 x 20ft containers."
+                placeholder="Select the containers physically arriving"
+                data={selectableContainerUnits.map((unit) => {
+                  const selected = selectedContainerNumbers.includes(unit.containerNumber);
+                  const selectedHasNon20 = selectedContainerUnits.some(
+                    (selectedUnit) => !String(selectedUnit.containerSize ?? '').includes('20'),
+                  );
+                  const candidateIs20 = String(unit.containerSize ?? '').includes('20');
+                  return {
+                    value: unit.containerNumber,
+                    label: `${unit.containerNumber} · ${unit.containerSize ?? 'size unknown'} · ${Number(
+                      unit.weightTons || 0,
+                    ).toLocaleString()} t`,
+                    disabled:
+                      !selected &&
+                      (selectedContainerNumbers.length >= 2 ||
+                        (selectedContainerNumbers.length === 1 &&
+                          (selectedHasNon20 || !candidateIs20))),
+                  };
+                })}
+                value={selectedContainerNumbers}
+                onChange={setSelectedContainerNumbers}
+                maxValues={2}
+                searchable
+                required
+              />
+              {containerCapacityError && (
+                <Alert color="red" variant="light">
+                  {containerCapacityError}
+                </Alert>
+              )}
+            </Stack>
+          )}
           <Table.ScrollContainer minWidth={900}>
             <Table withTableBorder highlightOnHover verticalSpacing="xs">
               <Table.Thead>
@@ -1353,7 +1641,9 @@ function EligibleTab({
               Cancel
             </Button>
             <Button leftSection={<Truck size={16} />} loading={bulkReceive.isPending} onClick={receive}>
-              Register Arrival & Generate GRN
+              {pendingContainerBooking
+                ? 'Receive Selected Containers & Generate CAS + GRN'
+                : 'Register Arrival & Generate GRN'}
             </Button>
           </Group>
         </Stack>
@@ -1574,6 +1864,9 @@ function ReadyToLoadTab({ enabled, onChanged }: { enabled: boolean; onChanged?:
     api.warehouses.readyToLoadExport.queryOptions({ enabled }),
   );
   const qc = useQueryClient();
+  // "Items" is the inventory list with the auto-load picker; "By train" mirrors
+  // the train schedule's per-booking Load / Wagons / Unload workspace here.
+  const [view, setView] = useState<'items' | 'train'>('items');
   const [trainPickerOpen, setTrainPickerOpen] = useState(false);
   const [expandedRow, setExpandedRow] = useState<string | null>(null);
   const [targetScheduleId, setTargetScheduleId] = useState<string | null>(null);
@@ -1598,6 +1891,11 @@ function ReadyToLoadTab({ enabled, onChanged }: { enabled: boolean; onChanged?:
     queryFn: () => warehouseService.getLoadableTrains(),
     enabled: enabled && trainPickerOpen,
   });
+  const { data: pickerItems = [] } = useQuery({
+    queryKey: ['train-loadable-items', targetScheduleId],
+    queryFn: () => warehouseService.getTrainLoadableItems(targetScheduleId!),
+    enabled: Boolean(targetScheduleId) && trainPickerOpen,
+  });
   const loadOntoTrain = useMutation({
     mutationFn: async ({ scheduleId, onlyIds }: { scheduleId: string; onlyIds: string[] }) => {
       const items = await warehouseService.getTrainLoadableItems(scheduleId);
@@ -1608,6 +1906,17 @@ function ReadyToLoadTab({ enabled, onChanged }: { enabled: boolean; onChanged?:
         loadableIds = loadableIds.filter((id) => picked.has(id));
       }
       if (!loadableIds.length) {
+        const scope = onlyIds.length
+          ? items.filter((i) => onlyIds.includes(i.id))
+          : items.filter((i) => i.status === 'READY_FOR_LOADING');
+        // A closed loading window is the blocker staff hit most, and the old
+        // wagon-only message sent them to fix the wrong thing.
+        const shut = scope.find((i) => !i.loadingWindowStarted);
+        if (shut) {
+          throw new Error(
+            `Start loading at ${shut.originYardLabel ?? 'the boarding yard'} first — the loading time window has not been started`,
+          );
+        }
         throw new Error(
           onlyIds.length
             ? 'None of the selected items have an allocated wagon on this train'
@@ -1649,16 +1958,50 @@ function ReadyToLoadTab({ enabled, onChanged }: { enabled: boolean; onChanged?:
     }
   };
 
+  if (view === 'train') {
+    return (
+      <Stack gap="sm" mt="sm">
+        <Group justify="space-between" wrap="wrap">
+          <SegmentedControl
+            size="xs"
+            value={view}
+            onChange={(v) => setView(v as 'items' | 'train')}
+            data={[
+              { value: 'items', label: 'Items' },
+              { value: 'train', label: 'By train' },
+            ]}
+          />
+          <Text size="xs" c="dimmed">
+            Per-booking Load, wagon-by-wagon loading and unloading — the train schedule&apos;s own
+            actions, run from the warehouse.
+          </Text>
+        </Group>
+        <TrainLoadingWorkspace enabled={enabled} onChanged={onChanged} />
+      </Stack>
+    );
+  }
+
   return (
     <Stack gap="sm" mt="sm">
-      <Group justify="space-between">
-        <Text size="sm" c="dimmed">
-          {selected.size > 0 ? (
-            <><b>{selected.size}</b> of {controls.filteredRows.length} selected</>
-          ) : (
-            <><b>{controls.filteredRows.length}</b> item{controls.filteredRows.length !== 1 ? 's' : ''} ready to load</>
-          )}
-        </Text>
+      <Group justify="space-between" wrap="wrap">
+        <Group gap="sm" wrap="wrap">
+          <SegmentedControl
+            size="xs"
+            value={view}
+            onChange={(v) => setView(v as 'items' | 'train')}
+            data={[
+              { value: 'items', label: 'Items' },
+              { value: 'train', label: 'By train' },
+            ]}
+          />
+          <Text size="sm" c="dimmed">
+            {selected.size > 0 ? (
+              <><b>{selected.size}</b> of {controls.filteredRows.length} selected</>
+            ) : (
+              <><b>{controls.filteredRows.length}</b> item{controls.filteredRows.length !== 1 ? 's' : ''} ready to load</>
+            )}
+          </Text>
+        </Group>
         <Tooltip label={canLoad ? undefined : "You don't have permission to load cargo"} disabled={canLoad} withArrow>
           <Button
             size="compact-sm"
@@ -1701,6 +2044,13 @@ function ReadyToLoadTab({ enabled, onChanged }: { enabled: boolean; onChanged?:
               searchable
             />
           )}
+          {targetScheduleId ? (
+            <YardLoadingWindows
+              scheduleId={targetScheduleId}
+              items={pickerItems}
+              logs={trains.find((t) => t.scheduleId === targetScheduleId)?.stationWorkLogs}
+            />
+          ) : null}
           <Group justify="flex-end">
             <Button variant="default" onClick={() => setTrainPickerOpen(false)} disabled={loadOntoTrain.isPending}>
               Cancel
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
index 7633e4dcd..ce1debd5b 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
@@ -387,6 +387,9 @@ export function ReleaseOrderModal({ opened, onClose, item, truckPrefill }: Relea
   const containerWeightByNumber = new Map(
     containerWeights.map((c) => [c.containerNumber.toUpperCase(), Number(c.weightTons) || 0]),
   );
+  const containerSizeByNumber = new Map(
+    containerWeights.map((c) => [c.containerNumber.toUpperCase(), c.containerSize ?? '']),
+  );
   // A truck may only carry out its OWN assigned containers — when the selected
   // truck has an assigned load, other trucks' containers are not offered.
   const assignedLoad = (selectedOption?.containerNumbers ?? []).map((n) => n.toUpperCase());
@@ -398,7 +401,7 @@ export function ReleaseOrderModal({ opened, onClose, item, truckPrefill }: Relea
         c.containerNumber,
         {
           value: c.containerNumber,
-          label: `${c.containerNumber} · ${(Number(c.weightTons) || 0).toLocaleString()} t`,
+          label: `${c.containerNumber} · ${c.containerSize ?? 'size unknown'} · ${(Number(c.weightTons) || 0).toLocaleString()} t`,
         },
       ]),
     ).values(),
@@ -409,6 +412,15 @@ export function ReleaseOrderModal({ opened, onClose, item, truckPrefill }: Relea
       containerNumbers.some((n) => n.trim().toUpperCase() === option.value.toUpperCase()),
   );
   const selectedContainerNumbers = containerNumbers.map((n) => n.trim()).filter(Boolean);
+  const selectedContainerSizes = selectedContainerNumbers.map(
+    (number) => containerSizeByNumber.get(number.toUpperCase()) ?? '',
+  );
+  const containerCapacityError =
+    selectedContainerNumbers.length > 2
+      ? 'A truck carries no more than 2 containers.'
+      : selectedContainerNumbers.length > 1 && selectedContainerSizes.some((size) => !size.includes('20'))
+        ? 'Truck capacity is either 1 x 40ft container or up to 2 x 20ft containers.'
+        : null;
   const selectedCargoWeight = Number(
     selectedContainerNumbers
       .reduce((sum, n) => sum + (containerWeightByNumber.get(n.toUpperCase()) ?? 0), 0)
@@ -470,6 +482,10 @@ export function ReleaseOrderModal({ opened, onClose, item, truckPrefill }: Relea
       toast({ variant: 'destructive', title: 'Select the containers loaded on this truck' });
       return;
     }
+    if (isExitStep && containerCapacityError) {
+      toast({ variant: 'destructive', title: 'Truck capacity exceeded', description: containerCapacityError });
+      return;
+    }
     if (isExitStep && !skipWeighing && systemNetWeight === '') {
       toast({ variant: 'destructive', title: 'System recorded net weight is missing' });
       return;
@@ -636,14 +652,15 @@ export function ReleaseOrderModal({ opened, onClose, item, truckPrefill }: Relea
               label="Containers on this truck"
               description={
                 isExitStep
-                  ? 'Select the containers loaded on this truck — their cargo weight must match gross − tare.'
-                  : 'Containers this truck will carry.'
+                  ? 'Select what is leaving: 1 x 40ft or up to 2 x 20ft. Their cargo weight must match gross - tare.'
+                  : 'Truck capacity: 1 x 40ft container or up to 2 x 20ft containers.'
               }
               placeholder="Select containers"
               searchable
               data={containerSelectData}
               value={selectedContainerNumbers}
               onChange={(values) => setContainerNumbers(values.length ? values : [''])}
+              maxValues={2}
               disabled={hasTruckLeft}
             />
           ) : (
@@ -708,6 +725,11 @@ export function ReleaseOrderModal({ opened, onClose, item, truckPrefill }: Relea
             </Text>
           </Alert>
         )}
+        {containerCapacityError && (
+          <Alert icon={<Info size={16} />} color="red" variant="light">
+            <Text size="sm">{containerCapacityError}</Text>
+          </Alert>
+        )}
         <Group justify="flex-end" mt="sm">
           <Button variant="default" onClick={onClose} disabled={releaseMutation.isPending || downloading}>
             Cancel
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/TrainLoadingWorkspace.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/TrainLoadingWorkspace.tsx
new file mode 100644
index 000000000..634b71bdd
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/TrainLoadingWorkspace.tsx
@@ -0,0 +1,927 @@
+import { useEffect, useMemo, useState } from 'react';
+import { isAxiosError } from 'axios';
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Checkbox,
+  Group,
+  Loader,
+  Modal,
+  Paper,
+  Select,
+  Stack,
+  Text,
+  ThemeIcon,
+  Tooltip,
+} from '@mantine/core';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import {
+  ArrowRight,
+  CheckCircle2,
+  Circle,
+  ExternalLink,
+  Info,
+  MapPin,
+  PackageCheck,
+  PackageOpen,
+  Train,
+  TrainFront,
+  Weight,
+  XCircle,
+} from 'lucide-react';
+
+import { useAuth } from '@/auth/useAuth';
+import { BookingStatusBadge } from '@/components/bookings/BookingStatusBadge';
+import { EntityLink } from '@/components/detail';
+import { StationWorkControls } from '@/components/trainScheduling/StationWorkControls';
+import { useToast } from '@/hooks/use-toast';
+import { FREIGHT_PERMS, hasPermission } from '@/lib/permissions';
+import { api } from '@/services/api';
+import { warehouseService, type TrainLoadableItem } from '@/services/warehouse.service';
+import type { YardWorkBookingRow } from '@/types/trainScheduling';
+import { extractErrorMessage, formatDate } from './options';
+import { TrainWagonLoadModal } from './TrainWagonLoadModal';
+
+/**
+ * Train-centric loading workspace for the warehouse — a mirror of the train
+ * schedule's "On this train" column, placed where the warehouse actually
+ * loads.
+ *
+ * Nothing here has its own rules. The train position, the per-yard loading /
+ * unloading windows, and the per-booking Load / Wagons / Unload actions all
+ * come from the train-scheduling endpoints the schedule workspace uses
+ * (`yard-work`, `schedules/:id/bookings/:bookingId/load|unload`, the per-wagon
+ * variants). The warehouse only ADDS what the schedule cannot see: which of the
+ * train's bookings are physically in the shed, with GRN and inspection state.
+ * So the two screens can never disagree — a Load that would be refused on the
+ * schedule is disabled here with the same reason.
+ *
+ * International port-ops shape the layout follows: cargo is worked per stop,
+ * only where the train stands, inside an opened work window, wagon by wagon,
+ * with a pre-load checklist (paid → received/GRN → inspected → wagon pinned →
+ * window open → train here) visible before anyone presses Load.
+ */
+
+const PAID_OR_LATER = new Set([
+  'PAID',
+  'FULLY_EXECUTED',
+  'IN_TRANSIT',
+  'ARRIVED',
+  'COMPLETED',
+  'DELIVERED',
+]);
+
+interface WarehouseSummary {
+  items: TrainLoadableItem[];
+  loaded: number;
+  ready: number;
+  hasGrn: boolean;
+  inspection: string | null;
+  wagons: string[];
+  weight: number;
+}
+
+function summarise(items: TrainLoadableItem[]): WarehouseSummary {
+  const wagons = [
+    ...new Set(items.map((i) => i.wagonNumber).filter((w): w is string => Boolean(w))),
+  ];
+  const inspections = items.map((i) => i.inspectionStatus).filter(Boolean) as string[];
+  return {
+    items,
+    loaded: items.filter((i) => i.status === 'LOADED').length,
+    ready: items.filter((i) => i.status === 'READY_FOR_LOADING').length,
+    hasGrn: items.some((i) => Boolean(i.grnNumber)),
+    inspection: inspections.includes('FAILED')
+      ? 'FAILED'
+      : inspections.length && inspections.every((s) => s === 'PASSED')
+        ? 'PASSED'
+        : (inspections[0] ?? null),
+    wagons,
+    weight: items.reduce((sum, i) => sum + (Number(i.weight) || 0), 0),
+  };
+}
+
+/** One pre-load gate: green when met, red when blocking, grey when only informative. */
+function Gate({
+  ok,
+  label,
+  neutral,
+  hint,
+}: {
+  ok: boolean;
+  label: string;
+  neutral?: boolean;
+  hint?: string;
+}) {
+  const color = ok ? 'edr-green' : neutral ? 'gray' : 'red';
+  const Icon = ok ? CheckCircle2 : neutral ? Circle : XCircle;
+  const badge = (
+    <Badge
+      size="xs"
+      radius="sm"
+      variant={ok ? 'light' : 'outline'}
+      color={color}
+      leftSection={<Icon size={10} />}
+      style={{ textTransform: 'none' }}
+    >
+      {label}
+    </Badge>
+  );
+  return hint ? (
+    <Tooltip label={hint} withArrow>
+      {badge}
+    </Tooltip>
+  ) : (
+    badge
+  );
+}
+
+const FLOW_STEPS = [
+  'Receive · GRN',
+  'Inspect',
+  'Ready',
+  'Open loading window',
+  'Train at yard',
+  'Load per wagon',
+  'Dispatch',
+  'Unload at port',
+];
+
+export function TrainLoadingWorkspace({
+  enabled = true,
+  onChanged,
+}: {
+  enabled?: boolean;
+  onChanged?: () => void;
+}) {
+  const { toast } = useToast();
+  const { user } = useAuth();
+  const qc = useQueryClient();
+  const canView = hasPermission(user, FREIGHT_PERMS.trainScheduling.view);
+  const canLoad = hasPermission(user, FREIGHT_PERMS.trainScheduling.load);
+  const canUnload = hasPermission(user, FREIGHT_PERMS.trainScheduling.unload);
+
+  // Trains with warehouse cargo, rolling ones included: loading follows the
+  // train along the corridor, exactly as the schedule workspace allows.
+  const trainsQuery = useQuery({
+    queryKey: ['loadable-trains', { includeDispatched: true }],
+    queryFn: () => warehouseService.getLoadableTrains({ includeDispatched: true }),
+    enabled,
+  });
+  const trains = trainsQuery.data ?? [];
+
+  const [scheduleId, setScheduleId] = useState<string | null>(null);
+  useEffect(() => {
+    if (!trains.length) return;
+    if (scheduleId && trains.some((t) => t.scheduleId === scheduleId)) return;
+    // Prefer a train that still has cargo waiting; otherwise the first one.
+    const pick = trains.find((t) => t.readyCount > 0) ?? trains[0];
+    setScheduleId(pick.scheduleId);
+  }, [trains, scheduleId]);
+  const train = trains.find((t) => t.scheduleId === scheduleId) ?? null;
+
+  const ready = enabled && canView && Boolean(scheduleId);
+  const detailQuery = useQuery(
+    api.trainScheduling.scheduleDetail.queryOptions({
+      input: { id: scheduleId ?? '' },
+      enabled: ready,
+    }),
+  );
+  const yardWorkQuery = useQuery(
+    api.trainScheduling.yardWork.queryOptions({
+      input: { scheduleId: scheduleId ?? '' },
+      enabled: ready,
+      refetchInterval: 60_000,
+    }),
+  );
+  const itemsQuery = useQuery({
+    queryKey: ['train-loadable-items', scheduleId],
+    queryFn: () => warehouseService.getTrainLoadableItems(scheduleId!),
+    enabled: enabled && Boolean(scheduleId),
+  });
+
+  const schedule = detailQuery.data ?? null;
+  const yardWork = yardWorkQuery.data ?? null;
+  const items = itemsQuery.data ?? [];
+
+  const [onlyInWarehouse, setOnlyInWarehouse] = useState(false);
+
+  // ── Corridor + position (same derivation as the schedule workspace) ───────
+  const stations = useMemo(() => {
+    const stops = schedule?.stops ?? [];
+    if (stops.length) return stops;
+    return [
+      {
+        yardId: schedule?.originStation?.id ?? train?.originStationId ?? 'origin',
+        label: schedule?.originStation?.label ?? train?.origin ?? 'Origin',
+      },
+      {
+        yardId: schedule?.destinationStation?.id ?? 'destination',
+        label: schedule?.destinationStation?.label ?? train?.destination ?? 'Destination',
+      },
+    ];
+  }, [schedule, train]);
+  const stationIdx = useMemo(() => new Map(stations.map((s, i) => [s.yardId, i])), [stations]);
+  const trainAtYardId = yardWork?.trainAtYardId ?? null;
+  const trainIdx = trainAtYardId != null ? (stationIdx.get(trainAtYardId) ?? null) : null;
+  const trainAtLabel = trainIdx != null ? stations[trainIdx]?.label : null;
+  const workLogs = yardWork?.stationWorkLogs ?? schedule?.stationWorkLogs ?? {};
+
+  const journeyById = useMemo(() => {
+    const map = new Map<string, YardWorkBookingRow>();
+    for (const yard of yardWork?.yards ?? []) {
+      for (const row of [...yard.toLoad, ...yard.toUnload]) map.set(row.id, row);
+    }
+    return map;
+  }, [yardWork]);
+
+  const warehouseByBooking = useMemo(() => {
+    const groups = new Map<string, TrainLoadableItem[]>();
+    for (const item of items) {
+      if (!item.bookingId) continue;
+      const list = groups.get(item.bookingId) ?? [];
+      list.push(item);
+      groups.set(item.bookingId, list);
+    }
+    return new Map([...groups.entries()].map(([id, list]) => [id, summarise(list)]));
+  }, [items]);
+
+  const onTrain = useMemo(() => {
+    const all = schedule?.bookings ?? [];
+    return onlyInWarehouse ? all.filter((b) => warehouseByBooking.has(b.id)) : all;
+  }, [schedule, onlyInWarehouse, warehouseByBooking]);
+
+  const corridorGroups = useMemo(() => {
+    const groups = new Map<string, { yardId: string; label: string; rows: typeof onTrain }>();
+    for (const b of onTrain) {
+      const yardId =
+        b.originYardId && stationIdx.has(b.originYardId)
+          ? b.originYardId
+          : (stations[0]?.yardId ?? 'origin');
+      let group = groups.get(yardId);
+      if (!group) {
+        group = {
+          yardId,
+          label: stations[stationIdx.get(yardId) ?? 0]?.label ?? b.origin ?? 'Origin',
+          rows: [],
+        };
+        groups.set(yardId, group);
+      }
+      group.rows.push(b);
+    }
+    return [...groups.values()].sort(
+      (a, b) => (stationIdx.get(a.yardId) ?? 0) - (stationIdx.get(b.yardId) ?? 0),
+    );
+  }, [onTrain, stationIdx, stations]);
+
+  // Bookings alighting where the train stands — the unload side of the mirror.
+  const alightingHere = useMemo(
+    () =>
+      trainAtYardId
+        ? (schedule?.bookings ?? []).filter(
+            (b) => b.destinationYardId === trainAtYardId && b.status === 'IN_TRANSIT',
+          )
+        : [],
+    [schedule, trainAtYardId],
+  );
+
+  const canWork = ['DRAFT', 'SCHEDULED', 'DISPATCHED'].includes(schedule?.status ?? '');
+
+  // ── Actions — the schedule's own endpoints ────────────────────────────────
+  const loadJourney = useMutation(api.trainScheduling.loadScheduleBooking.mutationOptions());
+  const unloadJourney = useMutation(api.trainScheduling.unloadScheduleBooking.mutationOptions());
+  const [confirmAction, setConfirmAction] = useState<{
+    kind: 'load' | 'unload';
+    bookingId: string;
+    ref: string;
+  } | null>(null);
+  const [wagonModal, setWagonModal] = useState<{
+    bookingId: string;
+    ref: string;
+    phase: 'load' | 'unload';
+  } | null>(null);
+
+  const afterChange = () => {
+    void qc.invalidateQueries({ queryKey: ['warehouse-inventory'] });
+    void qc.invalidateQueries({ queryKey: ['train-loadable-items'] });
+    void qc.invalidateQueries({ queryKey: ['loadable-trains'] });
+    void yardWorkQuery.refetch();
+    void detailQuery.refetch();
+    onChanged?.();
+  };
+
+  const runConfirmedAction = () => {
+    if (!confirmAction || !scheduleId) return;
+    const { kind, bookingId, ref } = confirmAction;
+    setConfirmAction(null);
+    const mutation = kind === 'load' ? loadJourney : unloadJourney;
+    mutation
+      .mutateAsync({ scheduleId, bookingId })
+      .then(() => {
+        toast({
+          title: kind === 'load' ? `${ref} loaded onto the train` : `${ref} unloaded at this yard`,
+        });
+        afterChange();
+      })
+      .catch((error) =>
+        toast({
+          variant: 'destructive',
+          title: kind === 'load' ? 'Could not load booking' : 'Could not unload booking',
+          description: extractErrorMessage(
+            error,
+            kind === 'load'
+              ? 'The train must be at the boarding yard with its loading window started.'
+              : 'The train must be at the destination yard with its unloading window started.',
+          ),
+        }),
+      );
+  };
+
+  // ── Empty / blocked states ────────────────────────────────────────────────
+  if (!canView) {
+    return (
+      <Alert color="yellow" variant="light" icon={<Info size={16} />}>
+        This view reads the train&apos;s position and journey from train scheduling. Ask for the
+        <b> train scheduling: view</b> permission to use it.
+      </Alert>
+    );
+  }
+  if (trainsQuery.isLoading) {
+    return (
+      <Group justify="center" py="lg">
+        <Loader size="sm" />
+      </Group>
+    );
+  }
+  if (trains.length === 0) {
+    return (
+      <Alert color="gray" variant="light" icon={<Info size={16} />}>
+        No train is boarding warehouse cargo right now. A train appears here once it is scheduled
+        with wagons allocated to bookings whose goods have been received at the warehouse.
+      </Alert>
+    );
+  }
+  const forbidden =
+    (isAxiosError(detailQuery.error) && detailQuery.error.response?.status === 403) ||
+    (isAxiosError(yardWorkQuery.error) && yardWorkQuery.error.response?.status === 403);
+
+  const trainOptions = trains.map((t) => ({
+    value: t.scheduleId,
+    label: `${t.trainNumber ?? t.scheduleId.slice(0, 8)} · ${t.origin ?? '?'} → ${t.destination ?? '?'} · dep ${
+      t.departureTime ? formatDate(t.departureTime) : '—'
+    } · ${t.readyCount} to load · ${t.loadedCount} loaded${t.status === 'DISPATCHED' ? ' · rolling' : ''}`,
+  }));
+
+  return (
+    <Stack gap="md">
+      {/* Train picker + position */}
+      <Paper withBorder radius="lg" p="md">
+        <Group justify="space-between" align="flex-end" wrap="wrap" gap="md">
+          <Select
+            label="Train"
+            description="Trains with cargo of this warehouse allocated to their wagons"
+            data={trainOptions}
+            value={scheduleId}
+            onChange={(v) => v && setScheduleId(v)}
+            searchable
+            allowDeselect={false}
+            miw={420}
+            maw={640}
+            style={{ flex: 1 }}
+          />
+          <Group gap={8} wrap="wrap">
+            {schedule ? (
+              <Badge size="sm" radius="sm" variant="light" color={canWork ? 'edr-green' : 'gray'}>
+                {String(schedule.status).replace(/_/g, ' ')}
+              </Badge>
+            ) : null}
+            <Badge
+              size="sm"
+              radius="sm"
+              variant={trainAtLabel ? 'filled' : 'outline'}
+              color={trainAtLabel ? 'edr-green' : 'gray'}
+              leftSection={<TrainFront size={11} />}
+            >
+              {trainAtLabel ? `Train at ${trainAtLabel}` : 'Position unknown'}
+            </Badge>
+            {scheduleId ? (
+              <EntityLink
+                to={`/dashboard/operations/train-scheduling-v2/${scheduleId}`}
+                label="Open schedule"
+                icon={ExternalLink}
+                size="xs"
+              />
+            ) : null}
+          </Group>
+        </Group>
+
+        {/* Port-ops flow the actions below follow */}
+        <Group gap={4} mt="sm" wrap="wrap" align="center">
+          {FLOW_STEPS.map((step, i) => (
+            <Group key={step} gap={4} wrap="nowrap" align="center">
+              <Text size="xs" c="dimmed">
+                {step}
+              </Text>
+              {i < FLOW_STEPS.length - 1 ? (
+                <ArrowRight size={11} color="var(--mantine-color-gray-5)" />
+              ) : null}
+            </Group>
+          ))}
+        </Group>
+      </Paper>
+
+      {forbidden ? (
+        <Alert color="yellow" variant="light" icon={<Info size={16} />}>
+          The train-scheduling API refused the journey read for this train. The
+          <b> train scheduling: view</b> permission is required to load from here.
+        </Alert>
+      ) : detailQuery.isLoading || yardWorkQuery.isLoading ? (
+        <Group justify="center" py="lg">
+          <Loader size="sm" />
+        </Group>
+      ) : (
+        <Stack gap="sm">
+          <Group justify="space-between" wrap="wrap">
+            <Text size="xs" c="dimmed">
+              Load is only offered where the train actually stands, inside a started loading window
+              — the same rule the train schedule enforces. Removing a booking from the train,
+              cancelling wagons and direct truck-to-train stay on the schedule workspace.
+            </Text>
+            <Checkbox
+              size="xs"
+              label="Only bookings with cargo in the warehouse"
+              checked={onlyInWarehouse}
+              onChange={(e) => setOnlyInWarehouse(e.currentTarget.checked)}
+            />
+          </Group>
+
+          {corridorGroups.length === 0 ? (
+            <Text size="sm" c="dimmed" ta="center" py="lg">
+              {onlyInWarehouse
+                ? 'None of this train’s bookings have cargo in the warehouse yet.'
+                : 'No bookings allocated to this train yet.'}
+            </Text>
+          ) : null}
+
+          {corridorGroups.map((group) => {
+            const groupIdx = stationIdx.get(group.yardId) ?? 0;
+            const trainHere = trainAtYardId === group.yardId;
+            const passed = trainIdx != null && groupIdx < trainIdx;
+            const loadLog = workLogs[group.yardId]?.loading;
+            return (
+              <Paper key={group.yardId} withBorder radius="md" p="sm">
+                <Stack gap={8}>
+                  <Group gap={8} align="center" wrap="wrap">
+                    <MapPin size={13} color="var(--mantine-color-gray-6)" />
+                    <Text size="xs" fw={700}>
+                      {group.label}
+                    </Text>
+                    {trainHere ? (
+                      <Badge
+                        size="sm"
+                        radius="sm"
+                        variant="filled"
+                        color="edr-green"
+                        leftSection={<TrainFront size={11} />}
+                      >
+                        Train here
+                      </Badge>
+                    ) : passed ? (
+                      <Badge size="sm" radius="sm" variant="light" color="gray">
+                        Passed
+                      </Badge>
+                    ) : (
+                      <Badge size="sm" radius="sm" variant="outline" color="gray">
+                        Ahead
+                      </Badge>
+                    )}
+                    <Badge size="sm" radius="sm" variant="light" color="gray">
+                      {group.rows.length}
+                    </Badge>
+                  </Group>
+
+                  {/* The yard's loading window — same store the schedule writes. */}
+                  {scheduleId && (trainHere || loadLog?.startedAt) ? (
+                    <Box
+                      p="xs"
+                      style={{
+                        border: '1px solid var(--mantine-color-gray-3)',
+                        borderRadius: 8,
+                        background: 'var(--mantine-color-gray-0)',
+                      }}
+                    >
+                      <StationWorkControls
+                        scheduleId={scheduleId}
+                        yardId={group.yardId}
+                        phase="loading"
+                        log={loadLog}
+                      />
+                    </Box>
+                  ) : null}
+
+                  {group.rows.map((b) => {
+                    const ref = b.reference ?? b.id.slice(0, 8);
+                    const journey = journeyById.get(b.id);
+                    const wh = warehouseByBooking.get(b.id) ?? null;
+                    const loadWindowStarted = Boolean(loadLog?.startedAt);
+                    const riding = b.status === 'IN_TRANSIT';
+                    const done = ['ARRIVED', 'COMPLETED', 'DELIVERED'].includes(b.status ?? '');
+                    const boardHere = trainHere;
+                    const showLoad = canWork && !riding && !done && (journey?.canLoad ?? false);
+                    const paid = PAID_OR_LATER.has(b.status ?? '');
+                    const wagonPinned = Boolean(b.wagonAssigned) || Boolean(wh?.wagons.length);
+                    const allLoaded =
+                      riding ||
+                      Boolean(b.loadedAt) ||
+                      (wh != null && wh.loaded === wh.items.length && wh.items.length > 0);
+                    return (
+                      <Paper key={b.id} withBorder radius="md" p="sm">
+                        <Group justify="space-between" align="flex-start" wrap="nowrap" gap="sm">
+                          <Stack gap={4} style={{ minWidth: 0, flex: 1 }}>
+                            <Group gap={8} align="center" wrap="wrap">
+                              <EntityLink
+                                to={`/dashboard/booking-requests/${b.id}`}
+                                label={ref}
+                                size="sm"
+                                fw={700}
+                              />
+                              {b.status ? <BookingStatusBadge status={b.status} /> : null}
+                              {b.tradeDirection === 'DOMESTIC' ? (
+                                <Badge size="sm" radius="sm" variant="filled" color="indigo">
+                                  Intercity
+                                </Badge>
+                              ) : null}
+                              {riding || Boolean(b.loadedAt) || wagonPinned ? (
+                                <Badge
+                                  size="sm"
+                                  radius="sm"
+                                  variant={allLoaded ? 'filled' : 'light'}
+                                  color={allLoaded ? 'edr-green' : 'gray'}
+                                >
+                                  {allLoaded
+                                    ? 'Loaded'
+                                    : wh && wh.loaded > 0
+                                      ? `Partly loaded ${wh.loaded}/${wh.items.length}`
+                                      : 'Unloaded'}
+                                </Badge>
+                              ) : null}
+                            </Group>
+                            <Group gap={10} align="center" wrap="wrap">
+                              <Text size="xs" c="dimmed" truncate>
+                                {b.customer ?? '—'}
+                              </Text>
+                              {b.weightTons != null ? (
+                                <Group gap={3} align="center" wrap="nowrap">
+                                  <Weight size={11} color="var(--mantine-color-gray-5)" />
+                                  <Text size="xs" c="dimmed">
+                                    {Number(b.weightTons).toFixed(1)}T
+                                  </Text>
+                                </Group>
+                              ) : null}
+                              {b.origin &&
+                              b.destination &&
+                              (b.originYardId !== schedule?.originStation?.id ||
+                                b.destinationYardId !== schedule?.destinationStation?.id) ? (
+                                <Text
+                                  size="xs"
+                                  c="indigo.7"
+                                  fw={600}
+                                  style={{ whiteSpace: 'nowrap' }}
+                                >
+                                  {b.origin} → {b.destination}
+                                </Text>
+                              ) : null}
+                              {wh ? (
+                                <Text size="xs" c="dimmed">
+                                  {wh.items.length} item
+                                  {wh.items.length === 1 ? '' : 's'} in warehouse
+                                  {wh.wagons.length ? ` · wagon ${wh.wagons.join(', ')}` : ''}
+                                  {wh.items[0]?.grnNumber ? ` · ${wh.items[0].grnNumber}` : ''}
+                                </Text>
+                              ) : (
+                                <Text size="xs" c="orange.7">
+                                  Not received at the warehouse
+                                </Text>
+                              )}
+                            </Group>
+                            {/* Pre-load checklist — every server gate, visible before Load. */}
+                            {!riding && !done ? (
+                              <Group gap={4} wrap="wrap">
+                                <Gate ok={paid} label="Paid" hint="Only a paid booking may board" />
+                                <Gate
+                                  ok={Boolean(wh?.hasGrn)}
+                                  label="Received · GRN"
+                                  hint="Export cargo rides only after it was received at the warehouse and a GRN was raised"
+                                />
+                                <Gate
+                                  ok={wh?.inspection === 'PASSED'}
+                                  neutral={wh?.inspection !== 'FAILED'}
+                                  label={
+                                    wh?.inspection === 'PASSED'
+                                      ? 'Inspected'
+                                      : wh?.inspection === 'FAILED'
+                                        ? 'Inspection failed'
+                                        : 'Not inspected'
+                                  }
+                                  hint="Inspection is recorded on the goods; it does not block loading"
+                                />
+                                <Gate
+                                  ok={wagonPinned}
+                                  label="Wagon"
+                                  hint="A wagon must be pinned to the booking on this train"
+                                />
+                                <Gate
+                                  ok={loadWindowStarted}
+                                  label="Loading window"
+                                  hint={`Start loading at ${group.label} on this train first`}
+                                />
+                                <Gate
+                                  ok={boardHere}
+                                  label="Train here"
+                                  neutral={!passed}
+                                  hint={
+                                    boardHere
+                                      ? `The train stands at ${group.label}`
+                                      : passed
+                                        ? `The train already passed ${group.label}`
+                                        : `The train is ${trainAtLabel ? `at ${trainAtLabel}` : 'not here yet'}`
+                                  }
+                                />
+                              </Group>
+                            ) : null}
+                          </Stack>
+
+                          <Group gap={6} wrap="nowrap" justify="flex-end" style={{ flexShrink: 0 }}>
+                            {showLoad ? (
+                              <Tooltip
+                                label={
+                                  !canLoad
+                                    ? "You don't have permission to load cargo"
+                                    : boardHere && !loadWindowStarted
+                                      ? `Start loading at ${group.label} first`
+                                      : boardHere
+                                        ? `Load cargo onto the train at ${group.label}`
+                                        : passed
+                                          ? `Train already passed ${group.label} — this cargo missed its stop`
+                                          : `Loads at ${group.label} — train is ${
+                                              trainAtLabel ? `at ${trainAtLabel}` : 'not there yet'
+                                            }`
+                                }
+                                withArrow
+                              >
+                                <Button
+                                  size="compact-sm"
+                                  variant="filled"
+                                  color="edr-green"
+                                  radius="md"
+                                  disabled={!boardHere || !canLoad || !loadWindowStarted}
+                                  leftSection={<PackageCheck size={13} />}
+                                  loading={
+                                    loadJourney.isPending &&
+                                    loadJourney.variables?.bookingId === b.id
+                                  }
+                                  onClick={() =>
+                                    setConfirmAction({
+                                      kind: 'load',
+                                      bookingId: b.id,
+                                      ref,
+                                    })
+                                  }
+                                >
+                                  Load
+                                </Button>
+                              </Tooltip>
+                            ) : null}
+                            {showLoad && boardHere ? (
+                              <Tooltip label="Load wagon by wagon" withArrow>
+                                <Button
+                                  size="compact-sm"
+                                  variant="light"
+                                  color="edr-green"
+                                  radius="md"
+                                  disabled={!canLoad || !loadWindowStarted}
+                                  onClick={() =>
+                                    setWagonModal({
+                                      bookingId: b.id,
+                                      ref,
+                                      phase: 'load',
+                                    })
+                                  }
+                                >
+                                  Wagons
+                                </Button>
+                              </Tooltip>
+                            ) : null}
+                          </Group>
+                        </Group>
+                      </Paper>
+                    );
+                  })}
+                </Stack>
+              </Paper>
+            );
+          })}
+
+          {/* Unload side — bookings alighting where the train stands (port arrival). */}
+          {trainAtYardId && alightingHere.length > 0 ? (
+            <Paper withBorder radius="md" p="sm">
+              <Stack gap={8}>
+                <Group gap={8} align="center" wrap="wrap">
+                  <PackageOpen size={13} color="var(--mantine-color-orange-6)" />
+                  <Text size="xs" fw={700}>
+                    Unload at {trainAtLabel ?? 'this yard'}
+                  </Text>
+                  <Badge size="sm" radius="sm" variant="light" color="orange">
+                    {alightingHere.length}
+                  </Badge>
+                </Group>
+                {scheduleId ? (
+                  <Box
+                    p="xs"
+                    style={{
+                      border: '1px solid var(--mantine-color-gray-3)',
+                      borderRadius: 8,
+                      background: 'var(--mantine-color-gray-0)',
+                    }}
+                  >
+                    <StationWorkControls
+                      scheduleId={scheduleId}
+                      yardId={trainAtYardId}
+                      phase="unloading"
+                      log={workLogs[trainAtYardId]?.unloading}
+                    />
+                  </Box>
+                ) : null}
+                {alightingHere.map((b) => {
+                  const ref = b.reference ?? b.id.slice(0, 8);
+                  const journey = journeyById.get(b.id);
+                  const unloadWindowStarted = Boolean(
+                    workLogs[trainAtYardId]?.unloading?.startedAt,
+                  );
+                  const showUnload = canWork && (journey?.canUnload ?? false);
+                  return (
+                    <Paper key={b.id} withBorder radius="md" p="sm">
+                      <Group justify="space-between" align="center" wrap="nowrap" gap="sm">
+                        <Stack gap={3} style={{ minWidth: 0 }}>
+                          <Group gap={8} align="center" wrap="nowrap">
+                            <EntityLink
+                              to={`/dashboard/booking-requests/${b.id}`}
+                              label={ref}
+                              size="sm"
+                              fw={700}
+                            />
+                            {b.status ? <BookingStatusBadge status={b.status} /> : null}
+                          </Group>
+                          <Group gap={10} wrap="nowrap">
+                            <Text size="xs" c="dimmed" truncate>
+                              {b.customer ?? '—'}
+                            </Text>
+                            {b.weightTons != null ? (
+                              <Text size="xs" c="dimmed">
+                                {Number(b.weightTons).toFixed(1)}T
+                              </Text>
+                            ) : null}
+                          </Group>
+                        </Stack>
+                        <Group gap={6} wrap="nowrap" justify="flex-end">
+                          {showUnload ? (
+                            <>
+                              <Tooltip
+                                label={
+                                  !canUnload
+                                    ? "You don't have permission to unload cargo"
+                                    : !unloadWindowStarted
+                                      ? 'Start unloading at this yard first'
+                                      : "Unload at this yard — stamps the booking's arrival"
+                                }
+                                withArrow
+                              >
+                                <Button
+                                  size="compact-sm"
+                                  variant="light"
+                                  color="orange"
+                                  radius="md"
+                                  disabled={!canUnload || !unloadWindowStarted}
+                                  leftSection={<PackageOpen size={13} />}
+                                  loading={
+                                    unloadJourney.isPending &&
+                                    unloadJourney.variables?.bookingId === b.id
+                                  }
+                                  onClick={() =>
+                                    setConfirmAction({
+                                      kind: 'unload',
+                                      bookingId: b.id,
+                                      ref,
+                                    })
+                                  }
+                                >
+                                  Unload
+                                </Button>
+                              </Tooltip>
+                              <Tooltip label="Unload wagon by wagon" withArrow>
+                                <Button
+                                  size="compact-sm"
+                                  variant="light"
+                                  color="orange"
+                                  radius="md"
+                                  disabled={!canUnload || !unloadWindowStarted}
+                                  onClick={() =>
+                                    setWagonModal({
+                                      bookingId: b.id,
+                                      ref,
+                                      phase: 'unload',
+                                    })
+                                  }
+                                >
+                                  Wagons
+                                </Button>
+                              </Tooltip>
+                            </>
+                          ) : null}
+                        </Group>
+                      </Group>
+                    </Paper>
+                  );
+                })}
+              </Stack>
+            </Paper>
+          ) : null}
+        </Stack>
+      )}
+
+      {wagonModal && scheduleId ? (
+        <TrainWagonLoadModal
+          scheduleId={scheduleId}
+          bookingId={wagonModal.bookingId}
+          reference={wagonModal.ref}
+          phase={wagonModal.phase}
+          onClose={() => setWagonModal(null)}
+          onChanged={afterChange}
+        />
+      ) : null}
+
+      {/* Confirm load / unload — same wording as the schedule workspace */}
+      <Modal
+        opened={Boolean(confirmAction)}
+        onClose={() => setConfirmAction(null)}
+        centered
+        radius="lg"
+        size="md"
+        withCloseButton={false}
+        title={
+          confirmAction ? (
+            <Group gap={10} wrap="nowrap">
+              <ThemeIcon
+                size={40}
+                radius="md"
+                variant="light"
+                color={confirmAction.kind === 'unload' ? 'orange' : 'edr-green'}
+              >
+                {confirmAction.kind === 'unload' ? (
+                  <PackageOpen size={21} />
+                ) : (
+                  <PackageCheck size={21} />
+                )}
+              </ThemeIcon>
+              <div>
+                <Text fw={800}>
+                  {confirmAction.kind === 'unload'
+                    ? 'Unload cargo at this yard?'
+                    : 'Load cargo onto the train?'}
+                </Text>
+                <Text size="xs" c="dimmed">
+                  {confirmAction.ref}
+                </Text>
+              </div>
+            </Group>
+          ) : null
+        }
+      >
+        {confirmAction ? (
+          <Stack gap="md">
+            <Text size="sm">
+              {confirmAction.kind === 'unload'
+                ? "Stamps the booking's arrival at this yard and frees its wagons for reuse."
+                : 'Stamps the booking as loaded at this yard and moves its warehouse inventory to LOADED. The server checks the train is actually standing here.'}
+            </Text>
+            <Group justify="flex-end" gap="sm">
+              <Button variant="default" radius="md" onClick={() => setConfirmAction(null)}>
+                Cancel
+              </Button>
+              <Button
+                color={confirmAction.kind === 'unload' ? 'orange' : 'edr-green'}
+                radius="md"
+                leftSection={<Train size={14} />}
+                onClick={runConfirmedAction}
+              >
+                {confirmAction.kind === 'unload' ? 'Unload' : 'Load'}
+              </Button>
+            </Group>
+          </Stack>
+        ) : null}
+      </Modal>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/TrainWagonLoadModal.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/TrainWagonLoadModal.tsx
new file mode 100644
index 000000000..92d397a59
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/TrainWagonLoadModal.tsx
@@ -0,0 +1,320 @@
+import { useState } from 'react';
+import {
+  Alert,
+  Badge,
+  Button,
+  Checkbox,
+  Group,
+  Modal,
+  Paper,
+  Stack,
+  Text,
+  ThemeIcon,
+  Tooltip,
+} from '@mantine/core';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { CheckCircle2, Info, PackageCheck, PackageOpen, Train } from 'lucide-react';
+
+import { useToast } from '@/hooks/use-toast';
+import { api } from '@/services/api';
+import type { BookingWagonRow } from '@/types/trainScheduling';
+import { extractErrorMessage } from './options';
+
+/**
+ * Wagon-by-wagon load / unload of one booking on one train — the warehouse
+ * mirror of the train schedule's "Wagons" button.
+ *
+ * It calls the SAME per-wagon journey endpoints the schedule workspace calls
+ * (`schedules/:id/bookings/:bookingId/wagons/:allocationId/load|unload`), so
+ * every server gate — train at the yard, loading window started, PAID, GRN —
+ * is the schedule's own, and the two surfaces can never disagree on what got
+ * loaded. Wagons go one at a time in order: the server flips the booking to
+ * IN_TRANSIT / ARRIVED on whichever call clears the last wagon, so sequential
+ * is required, not just convenient. A failure stops the run; the wagons
+ * already sent stay done and the toast says how many, so a retry only resends
+ * the rest.
+ *
+ * Deliberately NOT mirrored here: cancelling wagons that will not ride and the
+ * direct truck-to-train handover. Both are commercial/allocation decisions
+ * (fees, credits, GRN waiver) that belong to the train schedule workspace, not
+ * the warehouse floor.
+ */
+export function TrainWagonLoadModal({
+  scheduleId,
+  bookingId,
+  reference,
+  phase,
+  onClose,
+  onChanged,
+}: {
+  scheduleId: string;
+  bookingId: string;
+  reference: string;
+  phase: 'load' | 'unload';
+  onClose: () => void;
+  onChanged?: () => void;
+}) {
+  const { toast } = useToast();
+  const qc = useQueryClient();
+  const [picked, setPicked] = useState<Set<string>>(new Set());
+  const [submitting, setSubmitting] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+
+  const wagonsQuery = useQuery(
+    api.trainScheduling.bookingWagons.queryOptions({ input: { bookingId } }),
+  );
+  const wagons: BookingWagonRow[] = wagonsQuery.data ?? [];
+  const isDone = (w: BookingWagonRow) =>
+    phase === 'load' ? w.status === 'LOADED' || w.status === 'DEPARTED' : w.status === 'DEPARTED';
+  const doneCount = wagons.filter(isDone).length;
+  const pending = wagons.filter((w) => !isDone(w));
+  const pickedPending = pending.filter((w) => picked.has(w.allocationId));
+
+  const loadWagon = useMutation(api.trainScheduling.loadScheduleBookingWagon.mutationOptions());
+  const unloadWagon = useMutation(api.trainScheduling.unloadScheduleBookingWagon.mutationOptions());
+  const act = phase === 'load' ? loadWagon : unloadWagon;
+
+  const toggle = (allocationId: string) =>
+    setPicked((prev) => {
+      const next = new Set(prev);
+      if (next.has(allocationId)) next.delete(allocationId);
+      else next.add(allocationId);
+      return next;
+    });
+
+  const afterChange = () => {
+    void wagonsQuery.refetch();
+    // The warehouse queues read inventory status, which the journey load moves.
+    void qc.invalidateQueries({ queryKey: ['warehouse-inventory'] });
+    void qc.invalidateQueries({ queryKey: ['train-loadable-items'] });
+    void qc.invalidateQueries({ queryKey: ['loadable-trains'] });
+    onChanged?.();
+  };
+
+  const submit = async () => {
+    const targets = pickedPending;
+    if (!targets.length) return;
+    setConfirmOpen(false);
+    setSubmitting(true);
+    let done = 0;
+    let completed = false;
+    try {
+      for (const w of targets) {
+        const r = await act.mutateAsync({
+          scheduleId,
+          bookingId,
+          allocationId: w.allocationId,
+        });
+        done += 1;
+        if (r.completed) completed = true;
+      }
+      afterChange();
+      setPicked(new Set());
+      if (completed) {
+        toast({
+          title: phase === 'load' ? 'Booking fully loaded' : 'Booking fully unloaded',
+          description:
+            phase === 'load'
+              ? `${reference}: every wagon is loaded — the booking is in transit.`
+              : `${reference}: every wagon is unloaded — the booking arrived.`,
+        });
+        onClose();
+      } else {
+        toast({
+          title: phase === 'load' ? 'Wagons loaded' : 'Wagons unloaded',
+          description: `${reference}: ${done} wagon${done === 1 ? '' : 's'} ${phase === 'load' ? 'loaded' : 'unloaded'}.`,
+        });
+      }
+    } catch (error) {
+      if (done > 0) afterChange();
+      toast({
+        variant: 'destructive',
+        title: phase === 'load' ? 'Wagon load failed' : 'Wagon unload failed',
+        description: done
+          ? `${done} wagon(s) went through before this: ${extractErrorMessage(error)}`
+          : extractErrorMessage(error),
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const color = phase === 'load' ? 'edr-green' : 'orange';
+  const Icon = phase === 'load' ? PackageCheck : PackageOpen;
+
+  return (
+    <Modal
+      opened
+      onClose={onClose}
+      title={
+        <Group gap={8}>
+          <Train size={18} />
+          <Text fw={700}>
+            {phase === 'load' ? 'Load' : 'Unload'} {reference} wagon by wagon
+          </Text>
+        </Group>
+      }
+      centered
+      radius="lg"
+      size="lg"
+    >
+      <Stack gap="sm">
+        <Group gap={8}>
+          <Badge size="sm" radius="sm" variant="light" color={doneCount ? color : 'gray'}>
+            {doneCount}/{wagons.length} {phase === 'load' ? 'loaded' : 'unloaded'}
+          </Badge>
+          {phase === 'load' && doneCount > 0 && pending.length > 0 ? (
+            <Text size="xs" c="dimmed">
+              The train cannot dispatch until the rest are loaded or cancelled.
+            </Text>
+          ) : null}
+        </Group>
+
+        {wagonsQuery.isLoading ? (
+          <Text size="sm" c="dimmed">
+            Loading wagons…
+          </Text>
+        ) : wagons.length === 0 ? (
+          <Text size="sm" c="dimmed">
+            No wagon allocations yet — use the whole-booking button instead.
+          </Text>
+        ) : (
+          wagons.map((w) => (
+            <Paper key={w.allocationId} withBorder radius="md" p="xs">
+              <Group justify="space-between" wrap="nowrap">
+                <Group gap={8} wrap="nowrap" style={{ minWidth: 0 }}>
+                  {!isDone(w) ? (
+                    <Checkbox
+                      checked={picked.has(w.allocationId)}
+                      onChange={() => toggle(w.allocationId)}
+                      disabled={submitting}
+                      color={color}
+                      aria-label={`Select wagon ${w.sequenceNo ?? ''} to ${phase}`}
+                    />
+                  ) : null}
+                  <Badge size="sm" radius="sm" variant="outline" color="gray">
+                    {w.sequenceNo != null ? `#${w.sequenceNo}` : '—'}
+                  </Badge>
+                  <Text size="sm" fw={600} truncate>
+                    {w.wagonNumber ?? w.wagonType ?? 'Wagon'}
+                  </Text>
+                  <Text size="xs" c="dimmed">
+                    {w.wagonTypeCode ?? ''}
+                    {w.allocatedWeightTons ? ` · ${Number(w.allocatedWeightTons).toFixed(1)}T` : ''}
+                    {w.containers?.length ? ` · ${w.containers.length} ctr` : ''}
+                  </Text>
+                </Group>
+                {isDone(w) ? (
+                  <Badge
+                    size="sm"
+                    radius="sm"
+                    variant="filled"
+                    color={color}
+                    leftSection={<CheckCircle2 size={11} />}
+                  >
+                    {phase === 'load' ? 'Loaded' : 'Unloaded'}
+                  </Badge>
+                ) : null}
+              </Group>
+            </Paper>
+          ))
+        )}
+
+        {pending.length > 0 && !confirmOpen ? (
+          <Group justify="space-between" wrap="wrap" gap="sm">
+            <Group gap={8}>
+              <Button
+                size="compact-sm"
+                variant="subtle"
+                radius="md"
+                disabled={submitting}
+                onClick={() =>
+                  setPicked(
+                    picked.size === pending.length
+                      ? new Set()
+                      : new Set(pending.map((w) => w.allocationId)),
+                  )
+                }
+              >
+                {picked.size === pending.length ? 'Clear all' : 'Select all'}
+              </Button>
+              <Text size="xs" c="dimmed">
+                {pickedPending.length} of {pending.length} selected
+              </Text>
+            </Group>
+            <Tooltip
+              label={
+                phase === 'load'
+                  ? 'Load the selected wagons — export cargo must already be received at the warehouse with a GRN.'
+                  : 'Unload the selected wagons.'
+              }
+              withArrow
+            >
+              <Button
+                color={color}
+                radius="md"
+                leftSection={<Icon size={14} />}
+                disabled={!pickedPending.length || submitting}
+                loading={submitting}
+                onClick={() => setConfirmOpen(true)}
+              >
+                {phase === 'load' ? 'Load' : 'Unload'} {pickedPending.length || ''}
+              </Button>
+            </Tooltip>
+          </Group>
+        ) : null}
+
+        {confirmOpen ? (
+          <Paper withBorder radius="md" p="sm">
+            <Stack gap="xs">
+              <Group gap={10} wrap="nowrap">
+                <ThemeIcon size={40} radius="md" variant="light" color={color}>
+                  <Icon size={21} />
+                </ThemeIcon>
+                <div>
+                  <Text fw={800}>
+                    {phase === 'load' ? 'Load' : 'Unload'} {pickedPending.length} wagon
+                    {pickedPending.length === 1 ? '' : 's'}?
+                  </Text>
+                  <Text size="xs" c="dimmed">
+                    {reference}
+                  </Text>
+                </div>
+              </Group>
+              <Text size="sm">
+                {phase === 'load'
+                  ? 'Stamps the selected wagons as loaded at this yard. Export cargo must already be received at the warehouse with a GRN.'
+                  : 'Stamps the selected wagons as unloaded and frees them for reuse.'}
+              </Text>
+              {pickedPending.length < pending.length ? (
+                <Text size="xs" c="dimmed">
+                  {pending.length - pickedPending.length} wagon
+                  {pending.length - pickedPending.length === 1 ? '' : 's'} left un
+                  {phase === 'load' ? 'loaded' : 'unloaded'} — the train cannot dispatch until they
+                  are {phase === 'load' ? 'loaded' : 'unloaded'} or cancelled.
+                </Text>
+              ) : null}
+              <Group justify="flex-end" gap="sm">
+                <Button variant="default" radius="md" onClick={() => setConfirmOpen(false)}>
+                  Back
+                </Button>
+                <Button color={color} radius="md" leftSection={<Icon size={14} />} onClick={submit}>
+                  {phase === 'load' ? 'Load' : 'Unload'}
+                </Button>
+              </Group>
+            </Stack>
+          </Paper>
+        ) : null}
+
+        {phase === 'load' && pending.length > 0 ? (
+          <Alert color="gray" variant="light" icon={<Info size={14} />} p="xs">
+            <Text size="xs">
+              A wagon that will not ride (cancel with fee / EDR fault) and direct truck-to-train
+              loading are decided on the train schedule workspace, not here.
+            </Text>
+          </Alert>
+        ) : null}
+      </Stack>
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/YardLoadingWindows.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/YardLoadingWindows.tsx
new file mode 100644
index 000000000..0a02cd8b6
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/YardLoadingWindows.tsx
@@ -0,0 +1,77 @@
+import { useMemo } from 'react';
+import { Alert, Badge, Group, Stack, Text } from '@mantine/core';
+import { Info, MapPin } from 'lucide-react';
+
+import { StationWorkControls } from '@/components/trainScheduling/StationWorkControls';
+import type { TrainLoadableItem } from '@/services/warehouse.service';
+import type { StationWorkLog } from '@/types/trainScheduling';
+
+/**
+ * The train schedule's per-yard loading window, shown where the warehouse
+ * actually loads. Cargo may only go onto a wagon inside a started window
+ * (assertStationWorkStarted on the API side), so the same Start/End loading
+ * controls the train schedule page carries belong here too — otherwise the
+ * warehouse operator sees a Load button that the server refuses.
+ *
+ * One block per boarding yard of the items waiting to load, since a train can
+ * pick cargo up at more than one stop and each stop has its own window.
+ */
+export function YardLoadingWindows({
+  scheduleId,
+  items,
+  logs,
+}: {
+  scheduleId: string;
+  items: TrainLoadableItem[];
+  logs: Record<string, StationWorkLog> | null | undefined;
+}) {
+  const yards = useMemo(() => {
+    const byYard = new Map<string, { label: string; count: number }>();
+    for (const item of items) {
+      // Everything still queued for this train, not only the ready ones — the
+      // operator starts the window before the cargo finishes becoming ready.
+      if (item.status === 'LOADED' || !item.originYardId) continue;
+      const entry = byYard.get(item.originYardId);
+      if (entry) entry.count += 1;
+      else byYard.set(item.originYardId, { label: item.originYardLabel ?? 'Boarding yard', count: 1 });
+    }
+    return [...byYard.entries()].map(([yardId, v]) => ({ yardId, ...v }));
+  }, [items]);
+
+  if (yards.length === 0) return null;
+
+  const anyOpen = yards.some((y) => logs?.[y.yardId]?.loading?.startedAt);
+
+  return (
+    <Stack gap="xs">
+      <Text size="sm" fw={600}>
+        Loading window
+      </Text>
+      {!anyOpen ? (
+        <Alert color="yellow" variant="light" icon={<Info size={16} />}>
+          Start loading at the yard before loading cargo — the train schedule records the same
+          window, and the server refuses cargo outside it.
+        </Alert>
+      ) : null}
+      {yards.map((yard) => (
+        <Stack key={yard.yardId} gap={6} p="xs" style={{ border: '1px solid var(--mantine-color-gray-3)', borderRadius: 8 }}>
+          <Group gap={8} align="center">
+            <MapPin size={13} />
+            <Text size="xs" fw={700}>
+              {yard.label}
+            </Text>
+            <Badge size="sm" radius="sm" variant="light" color="gray">
+              {yard.count} queued
+            </Badge>
+          </Group>
+          <StationWorkControls
+            scheduleId={scheduleId}
+            yardId={yard.yardId}
+            phase="loading"
+            log={logs?.[yard.yardId]?.loading}
+          />
+        </Stack>
+      ))}
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/index.ts b/apps/edr-freight-web/backoffice/src/components/warehouses/index.ts
index 4e0ebd7f8..4302cc979 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/index.ts
@@ -38,3 +38,5 @@ export { AccrualDashboard } from './AccrualDashboard';
 export { DwellAgingCard } from './DwellAgingCard';
 export { CycleTimeCard } from './CycleTimeCard';
 export { GateThroughputCard } from './GateThroughputCard';
+export { TrainLoadingWorkspace } from './TrainLoadingWorkspace';
+export { TrainWagonLoadModal } from './TrainWagonLoadModal';
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 32eb6b798..0dafb926f 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -226,6 +226,7 @@ export const URL_CONSTANTS = {
     CONTRACT_DOWNLOAD: (id: string) => `/bookings/${id}/contract`,
     CARRIAGE_ACCEPTANCE_SHEET: (id: string) =>
       `/bookings/${id}/carriage-acceptance-sheet`,
+    WAGONS_EXPORT: (id: string) => `/bookings/${id}/wagons/export`,
     EXPORT_HANDOVER_MODE: (id: string) =>
       `/bookings/${id}/export-handover-mode`,
     SUMMARY: (id: string) => `/bookings/${id}/summary`,
@@ -281,6 +282,7 @@ export const URL_CONSTANTS = {
     STAFF_REQUEST_CHANGES: (id: string) =>
       `/contracts/${id}/staff/request-changes`,
     STAFF_REJECT: (id: string) => `/contracts/${id}/staff/reject`,
+    STAFF_CANCEL: (id: string) => `/contracts/${id}/staff/cancel`,
     SUSPEND: (id: string) => `/contracts/${id}/suspend`,
     RESUME: (id: string) => `/contracts/${id}/resume`,
     APPROVE_STEP: (id: string, stepId: string) =>
@@ -615,6 +617,10 @@ export const URL_CONSTANTS = {
     TRANSIT_AGENTS: "/transit-agents",
     TRANSIT_AGENT_BY_ID: (id: string) => `/transit-agents/${id}`,
     TRANSIT_AGENTS_ASSIGNABLE: "/transit-agents/assignable",
+    /** Give an existing roster-only agent a portal account and send the link. */
+    TRANSIT_AGENT_INVITE: (id: string) => `/transit-agents/${id}/invite`,
+    TRANSIT_AGENT_RESEND_ACTIVATION: (id: string) =>
+      `/transit-agents/${id}/resend-activation`,
   },
   RATE_MATRIX: {
     BASE: "/api/rate-matrices",
@@ -795,6 +801,15 @@ export const URL_CONSTANTS = {
     CANCEL: (id: string) => `/interchange-documents/${id}/cancel`,
   },
 
+  EMPTY_RETURN_REQUESTS: {
+    BASE: "/empty-return-requests",
+    PLANNED: "/empty-return-requests/planned",
+    ELIGIBILITY: (bookingId: string) => `/empty-return-requests/eligibility/${bookingId}`,
+    BY_BOOKING: (bookingId: string) => `/empty-return-requests/by-booking/${bookingId}`,
+    APPROVE: (id: string) => `/empty-return-requests/${id}/approve`,
+    REJECT: (id: string) => `/empty-return-requests/${id}/reject`,
+  },
+
   IMPORT_OPERATIONS: {
     DJIBOUTI_INCIDENTS: "/import-operations/djibouti-incidents",
     CUSTOMS: (bookingId: string) => `/import-operations/customs/${bookingId}`,
@@ -811,6 +826,7 @@ export const URL_CONSTANTS = {
     CUSTOMS_RELEASE_PERMITTED: (bookingId: string) =>
       `/import-operations/customs/${bookingId}/release-permitted`,
     EMPTY_CONTAINER_RETURNS: "/import-operations/empty-container-returns",
+    EMPTY_RETURN_BOOKINGS: "/import-operations/empty-return-bookings",
     EMPTY_CONTAINER_RETURNS_BULK: "/import-operations/empty-container-returns/bulk",
     EMPTY_CONTAINER_RETURN_STATUS: (id: string) =>
       `/import-operations/empty-container-returns/${id}/status`,
diff --git a/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts b/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts
index 66f991989..fd86498a2 100644
--- a/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts
+++ b/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts
@@ -44,6 +44,18 @@ export function toBookingListRow(booking: BookingDetail): BookingListRow {
       booking.serviceType?.name ??
       booking.serviceType?.code,
     trainScheduleId: booking.trainScheduleId ?? null,
+    // List rows carry the flat departure date; detail responses carry the fuller
+    // summary object instead — fall back to it so a row mapped from either shape
+    // shows the same date.
+    trainScheduleDepartureDate:
+      booking.trainScheduleDepartureDate ??
+      booking.trainScheduleSummary?.scheduledDepartureDate ??
+      null,
+    trainScheduleReference:
+      booking.trainScheduleReference ??
+      booking.trainScheduleSummary?.reference ??
+      booking.trainScheduleSummary?.trainNumber ??
+      null,
     isGovernment: booking.isGovernment ?? false,
     governmentInstitution: booking.governmentInstitution ?? null,
     consolidationPartnerId: booking.consolidationPartnerId ?? null,
diff --git a/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts b/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
index bc0697996..3ee56f916 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
@@ -151,6 +151,14 @@ export function useContractMutations(contractId: string) {
     onError: (error) => toast.error(extractErrorMessage(error, "Failed to reject contract")),
   });
 
+  const cancelByStaff = useMutation({
+    mutationFn: (reason: string) =>
+      contractsService.cancelByStaff(contractId, reason),
+    onSuccess: (data) => onSuccess(data, "Contract cancelled"),
+    onError: (error) =>
+      toast.error(extractErrorMessage(error, "Failed to cancel contract")),
+  });
+
   const suspend = useMutation({
     mutationFn: (reason: string) => contractsService.suspend(contractId, reason),
     onSuccess: (data) => onSuccess(data, "Contract suspended"),
@@ -269,6 +277,7 @@ export function useContractMutations(contractId: string) {
     updateDocument,
     requestChanges,
     reject,
+    cancelByStaff,
     suspend,
     resume,
     approveStep,
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 38af63785..bc03bfcb5 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -96,6 +96,7 @@ export const FREIGHT_PERMS = {
     clearanceEtActions: "edr_freight_app:contracts:clearance_et_actions",
     clearanceDjActions: "edr_freight_app:contracts:clearance_dj_actions",
     suspend: "edr_freight_app:contracts:suspend",
+    cancel: "edr_freight_app:contracts:cancel",
     editDocument: "edr_freight_app:contracts:edit_document",
     finalInvoiceRaise: "edr_freight_app:contracts:final_invoice_raise",
     finalInvoiceConfirm: "edr_freight_app:contracts:final_invoice_confirm",
@@ -357,6 +358,10 @@ export const FREIGHT_PERMS = {
     send: "edr_freight_app:additional_charges:send",
     cancel: "edr_freight_app:additional_charges:cancel",
   },
+  emptyReturnRequests: {
+    view: "edr_freight_app:empty_return_requests:view",
+    review: "edr_freight_app:empty_return_requests:review",
+  },
   /**
    * Audit trail. View-only — the API exposes no write routes for audit rows,
    * so there is no manage/delete counterpart to grant.
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index 88ac1218d..a75e242e1 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -16,6 +16,7 @@ import {
   Receipt,
   RefreshCw,
   Ship,
+  Train,
   Truck,
   Wallet,
   Weight,
@@ -40,6 +41,7 @@ import {
 } from "@mantine/core";
 
 import { PageContainer, PageHeader, KpiStrip } from "@/components/page";
+import { extractDownloadErrorMessage } from "@/components/warehouses/options";
 import type { KpiItem } from "@/components/page";
 import { EntityLink } from "@/components/detail";
 import { BookingActionsToolbar } from "@/components/bookings/BookingActionsToolbar";
@@ -62,6 +64,7 @@ import {
   BookingSchedulingWindowCard,
   BookingDocumentsPanel,
   BookingTrucksPanel,
+  BookingWagonsPanel,
   ContractOrdersPanel,
 } from "@/components/bookings/detail";
 import { WarehouseInfoCard } from "@/components/warehouses";
@@ -80,6 +83,7 @@ import { useFileViewer } from "@/hooks/useFileViewer";
 import { bookingsService } from "@/services/bookings.service";
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission as hasFreightPermission } from "@/lib/permissions";
+import { WagonCancellationCreditCard } from "@/components/bookings/wagon-cancellation";
 
 export default function BookingRequestDetailPage() {
   const { id } = useParams<{ id: string }>();
@@ -217,9 +221,11 @@ export default function BookingRequestDetailPage() {
         ? "documents"
         : requestedTab === "trucks"
           ? "trucks"
-          : requestedTab === "additional-charges"
-            ? "additional-charges"
-            : "overview";
+          : requestedTab === "wagons"
+            ? "wagons"
+            : requestedTab === "additional-charges"
+              ? "additional-charges"
+              : "overview";
   const setActiveTab = (tab: string | null) => {
     const next = new URLSearchParams(searchParams);
     if (tab && tab !== "overview") next.set("tab", tab);
@@ -374,11 +380,9 @@ export default function BookingRequestDetailPage() {
                       a.click();
                       URL.revokeObjectURL(url);
                     } catch (error) {
-                      toast.error(
-                        error instanceof Error
-                          ? error.message
-                          : "Carriage acceptance sheet is not available yet",
-                      );
+                      // Blob response: the JSON reason is inside the Blob, so
+                      // the sync path would show only "status code 400".
+                      toast.error(await extractDownloadErrorMessage(error));
                     }
                   }}
                 >
@@ -522,6 +526,9 @@ export default function BookingRequestDetailPage() {
                   <Tabs.Tab value="trucks" leftSection={<Truck size={16} />}>
                     Trucks
                   </Tabs.Tab>
+                  <Tabs.Tab value="wagons" leftSection={<Train size={16} />}>
+                    Wagons
+                  </Tabs.Tab>
                   {canSeeAdditionalCharges && (
                     <Tabs.Tab
                       value="additional-charges"
@@ -549,6 +556,12 @@ export default function BookingRequestDetailPage() {
                 <Tabs.Panel value="trucks">
                   <BookingTrucksPanel bookingId={booking.id} />
                 </Tabs.Panel>
+                <Tabs.Panel value="wagons">
+                  <BookingWagonsPanel
+                    bookingId={booking.id}
+                    bookingReference={booking.reference}
+                  />
+                </Tabs.Panel>
                 {canSeeAdditionalCharges && (
                   <Tabs.Panel value="additional-charges">
                     <AdditionalPaymentsTab bookingId={booking.id} onViewFile={view} />
@@ -653,6 +666,7 @@ function OverviewPanel({
       />
       <BookingCargoCard booking={booking} />
       <BookingContainerUnitsCard booking={booking} />
+      <WagonCancellationCreditCard bookingId={booking.id} onRebooked={onRefetch} />
     </Stack>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index a277d0570..1d86d9a7e 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -13,6 +13,7 @@ import {
   Plus,
   RefreshCw,
   Ship,
+  Train,
   User,
 } from "lucide-react";
 import { useCallback, useMemo, useRef, useState } from "react";
@@ -609,7 +610,7 @@ export default function BookingRequestsPage() {
     },
     {
       id: "scheduled",
-      header: () => <span className={bookingTable.headerCell}>Scheduled</span>,
+      header: () => <span className={bookingTable.headerCell}>Requested</span>,
       cell: ({ row }) => (
         <span className="inline-flex items-center gap-1.5 text-sm text-muted-foreground">
           <Calendar className="size-3.5" />
@@ -617,6 +618,50 @@ export default function BookingRequestsPage() {
         </span>
       ),
     },
+    {
+      // The date of the train the booking is actually allocated to. Empty until
+      // allocation, which is why it is separate from the requested date above —
+      // the two differ whenever staff move a booking to another day.
+      id: "scheduledDate",
+      header: () => (
+        <span className={bookingTable.headerCell}>Scheduled date</span>
+      ),
+      cell: ({ row }) => {
+        const b = row.original;
+        if (!b.trainScheduleDepartureDate) {
+          return (
+            <span className="text-sm text-muted-foreground">
+              Not scheduled
+            </span>
+          );
+        }
+        const movedFromRequest =
+          b.scheduledDate &&
+          new Date(b.trainScheduleDepartureDate).toDateString() !==
+            new Date(b.scheduledDate).toDateString();
+        return (
+          <div className="space-y-0.5 py-1">
+            <span className="inline-flex items-center gap-1.5 text-sm font-medium text-foreground">
+              <Train className="size-3.5 text-muted-foreground" />
+              {formatDate(b.trainScheduleDepartureDate)}
+            </span>
+            {b.trainScheduleReference ? (
+              <p className="truncate text-xs text-muted-foreground">
+                {b.trainScheduleReference}
+              </p>
+            ) : null}
+            {movedFromRequest ? (
+              <Badge
+                variant="outline"
+                className="h-4 px-1 text-[9px] font-medium"
+              >
+                Date changed
+              </Badge>
+            ) : null}
+          </div>
+        );
+      },
+    },
     {
       id: "priority",
       header: () => <span className={bookingTable.headerCell}>Priority</span>,
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
index cfd108c5b..f2fdd2f58 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
@@ -37,6 +37,7 @@ import {
 } from "@/components/bookings/detail";
 import { ClearanceReviewSection } from "@/components/bookings/detail/ClearanceReviewSection";
 import { AdditionalDocsRequestCard } from "@/components/bookings/detail/AdditionalDocsRequestCard";
+import { WagonCancellationCreditCard } from "@/components/bookings/wagon-cancellation";
 import { ClearancePhaseStepper } from "@/components/contracts/ClearancePhaseStepper";
 import { PhasedClearanceActionPanel } from "@/components/contracts/PhasedClearanceActionPanel";
 import { ClearanceMilestoneTimeline } from "@/components/contracts/ClearanceMilestoneTimeline";
@@ -374,6 +375,13 @@ export default function DocumentClearanceDetailPage() {
                     />
                     {booking ? <BookingCompanyCard booking={booking} /> : null}
                     {booking ? <BookingContractCard booking={booking} /> : null}
+                    {/* Cancelled-wagon credits: GL rebooks them for the customer. */}
+                    {id ? (
+                      <WagonCancellationCreditCard
+                        bookingId={id}
+                        onRebooked={() => void refetch()}
+                      />
+                    ) : null}
                     {isPhasedGeneral ? (
                       <PhasedClearanceActionPanel
                         bookingId={id!}
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
index 4ca8100a2..1a18d4cf0 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
@@ -33,87 +33,15 @@ import {
   type ColumnDef,
 } from "@edr/ui-common";
 
-type WagonCancellationStatus =
-  | "FEE_PENDING"
-  | "CREDIT_AVAILABLE"
-  | "REBOOKED"
-  | "WITHDRAWN"
-  | "EXPIRED";
-
-interface WagonCancellation {
-  id: string;
-  bookingId: string;
-  rebookedBookingId?: string | null;
-  wagonsCancelled: number;
-  weightTons: number;
-  creditAmount: number;
-  feeAmount: number;
-  feeCurrency: string;
-  feeInvoiceId?: string | null;
-  feePaidAt?: string | null;
-  status: WagonCancellationStatus;
-  reason?: string | null;
-  rebookedAt?: string | null;
-  createdAt: string;
-  booking?: {
-    id: string;
-    reference: string;
-    customsClearingEnabled?: boolean;
-    company?: { name: string };
-  };
-  rebookedBooking?: { id: string; reference: string };
-  feeInvoice?: { invoiceNumber: string; status: string };
-  cancelledQuantities?: {
-    bySize?: Record<string, number>;
-    units?: Array<{
-      containerSize: string;
-      containerNumber: string;
-      sealNumber?: string | null;
-      vgmTons: number;
-    }>;
-  };
-}
-
-interface RebookPartnerCandidate {
-  id: string;
-  reference: string;
-  companyName: string | null;
-  status: string;
-  scheduledDate: string | null;
-  ft20Quantity: number;
-}
-
-/** Odd 20ft in the credit ⇒ the rebooked booking shares a wagon and GL must pick the partner. */
-const hasOddFt20 = (r: WagonCancellation): boolean =>
-  Object.entries(r.cancelledQuantities?.bySize ?? {})
-    .filter(([size]) => parseInt(size, 10) === 20)
-    .reduce((sum, [, qty]) => sum + Number(qty || 0), 0) %
-    2 ===
-  1;
-
-/** Editable rebook unit — prefilled from the cancelled snapshot. */
-interface RebookUnitDraft {
-  containerSize: string;
-  containerNumber: string;
-  sealNumber: string;
-  vgmTons: number | "";
-}
-
-interface WagonCancellationListResponse {
-  items: WagonCancellation[];
-  total: number;
-}
-
-const STATUS_CHIP: Record<
-  WagonCancellationStatus,
-  { label: string; color: string }
-> = {
-  FEE_PENDING: { label: "Fee pending", color: "yellow" },
-  CREDIT_AVAILABLE: { label: "Credit available", color: "edr-green" },
-  REBOOKED: { label: "Rebooked", color: "indigo" },
-  WITHDRAWN: { label: "Withdrawn", color: "gray" },
-  EXPIRED: { label: "Expired", color: "red" },
-};
+import {
+  canRebookWagonCancellations,
+  isRebookableCredit,
+  RebookWagonCancellationModal,
+  WAGON_CANCELLATION_STATUS_CHIP as STATUS_CHIP,
+  type WagonCancellation,
+  type WagonCancellationListResponse,
+  type WagonCancellationStatus,
+} from "@/components/bookings/wagon-cancellation";
 
 const STATUS_FILTER_OPTIONS = (
   Object.keys(STATUS_CHIP) as WagonCancellationStatus[]
@@ -155,72 +83,11 @@ export default function WagonCancellationsPage() {
   const [from, setFrom] = useState<Date | null>(null);
   const [to, setTo] = useState<Date | null>(null);
   const [voiding, setVoiding] = useState<WagonCancellation | null>(null);
-  // GL rebook of a customs (Path B) credit: pick the day; container number /
-  // seal / VGM may be corrected. Non-customs credits are rebooked by the
-  // customer from the portal.
-  const canRebook = hasPermission(
-    user,
-    FREIGHT_PERMS.bookings.wagonCancellationRebook,
-  );
+  // Rebook of a CREDIT_AVAILABLE row — any desk holding the rebook key, or GL
+  // Ethiopia through its booking-creation key. The modal handles the day pick,
+  // container corrections and the odd-20ft partner choice.
+  const canRebook = canRebookWagonCancellations(user);
   const [rebooking, setRebooking] = useState<WagonCancellation | null>(null);
-  const [rebookDate, setRebookDate] = useState<Date | null>(null);
-  const [rebookPartnerId, setRebookPartnerId] = useState<string | null>(null);
-  const [rebookDrafts, setRebookDrafts] = useState<RebookUnitDraft[]>([]);
-  const openRebook = (r: WagonCancellation) => {
-    setRebooking(r);
-    setRebookDate(null);
-    setRebookPartnerId(null);
-    setRebookDrafts(
-      (r.cancelledQuantities?.units ?? []).map((u) => ({
-        containerSize: u.containerSize,
-        containerNumber: u.containerNumber,
-        sealNumber: u.sealNumber ?? "",
-        vgmTons: Number(u.vgmTons) || "",
-      })),
-    );
-  };
-  const rebookContainersPayload = () => {
-    const bySize = new Map<string, RebookUnitDraft[]>();
-    for (const d of rebookDrafts) {
-      bySize.set(d.containerSize, [...(bySize.get(d.containerSize) ?? []), d]);
-    }
-    return [...bySize.entries()].map(([containerSize, units]) => ({
-      containerSize,
-      units: units.map((u) => ({
-        containerNumber: u.containerNumber.trim(),
-        ...(u.sealNumber.trim() ? { sealNumber: u.sealNumber.trim() } : {}),
-        ...(u.vgmTons !== "" ? { vgmTons: Number(u.vgmTons) } : {}),
-      })),
-    }));
-  };
-  const rebook = useMutation({
-    mutationFn: () =>
-      api.post(`/bookings/wagon-cancellations/${rebooking!.id}/rebook`, {
-        scheduledDate: toDayString(rebookDate!),
-        ...(rebookDrafts.length ? { containers: rebookContainersPayload() } : {}),
-        ...(rebookPartnerId ? { partnerBookingId: rebookPartnerId } : {}),
-      }),
-  });
-
-  // Odd-20ft credit: the rebooked booking shares a wagon again, so GL must pick
-  // the odd partner booking riding the chosen day. It ships once that partner pays.
-  const rebookNeedsPartner = rebooking ? hasOddFt20(rebooking) : false;
-  const rebookPartners = useQuery({
-    queryKey: [
-      "wagon-cancellations",
-      rebooking?.id,
-      "rebook-partners",
-      rebookDate ? toDayString(rebookDate) : null,
-    ],
-    enabled: Boolean(rebooking && rebookNeedsPartner && rebookDate),
-    queryFn: async () => {
-      const res = await api.get<RebookPartnerCandidate[]>(
-        `/bookings/wagon-cancellations/${rebooking!.id}/rebook-partners`,
-        { params: { scheduledDate: toDayString(rebookDate!) } },
-      );
-      return res.data;
-    },
-  });
 
   const resetPage = () =>
     setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
@@ -340,14 +207,12 @@ export default function WagonCancellationsPage() {
       cell: ({ row }) => {
         const r = row.original;
         const showVoid = r.status === "FEE_PENDING" && canVoid;
-        // Customs credits are GL's to rebook; non-customs ones the customer
-        // rebooks from the portal — EXCEPT odd-20ft credits: those must be
-        // re-paired with a partner booking, which only GL can pick.
-        const showRebook =
-          r.status === "CREDIT_AVAILABLE" &&
-          canRebook &&
-          (Boolean(r.booking?.customsClearingEnabled) || hasOddFt20(r)) &&
-          Number(r.creditAmount) > 0;
+        // Every available credit is rebookable from here — customs or not,
+        // customer- or staff-cancelled, EDR or customer fault. The customer can
+        // also self-rebook plain non-customs credits from the portal, but GL
+        // must be able to do it for them (customs bookings and odd-20ft
+        // credits are never self-booked). The API enforces the fee gate.
+        const showRebook = isRebookableCredit(r) && canRebook;
         if (!showVoid && !showRebook) return null;
         return (
           <Group justify="flex-end" wrap="nowrap">
@@ -357,7 +222,7 @@ export default function WagonCancellationsPage() {
                 radius="md"
                 variant="light"
                 color="green"
-                onClick={() => openRebook(r)}
+                onClick={() => setRebooking(r)}
               >
                 Rebook
               </Button>
@@ -518,153 +383,11 @@ export default function WagonCancellationsPage() {
           </Stack>
         )}
       </Modal>
-      <Modal
-        opened={!!rebooking}
+      <RebookWagonCancellationModal
+        cancellation={rebooking}
         onClose={() => setRebooking(null)}
-        title="Rebook cancelled wagons"
-        centered
-        radius="md"
-      >
-        {rebooking && (
-          <Stack gap="sm">
-            <Text size="sm">
-              {rebooking.booking?.reference ?? rebooking.bookingId} ·{" "}
-              {rebooking.wagonsCancelled} wagon(s) · credit{" "}
-              {formatMoney(rebooking.creditAmount, rebooking.feeCurrency, 2)}
-            </Text>
-            <DatePickerInput
-              label="Shipment day"
-              placeholder="Pick the day"
-              value={rebookDate}
-              onChange={(v) => {
-                setRebookDate(v ? new Date(v) : null);
-                setRebookPartnerId(null);
-              }}
-              radius="md"
-            />
-            {rebookNeedsPartner && (
-              <Select
-                label="Consolidation partner"
-                description="This credit has an odd 20ft container — pick the odd booking that shares its wagon. The rebooked booking is paid; it ships once the partner pays."
-                placeholder={
-                  !rebookDate
-                    ? "Pick the day first"
-                    : rebookPartners.isLoading
-                      ? "Loading…"
-                      : "Pick the partner booking"
-                }
-                data={(rebookPartners.data ?? []).map((c) => ({
-                  value: c.id,
-                  label: `${c.reference} · ${c.companyName ?? "—"} · ${c.ft20Quantity}×20ft`,
-                }))}
-                value={rebookPartnerId}
-                onChange={setRebookPartnerId}
-                disabled={!rebookDate}
-                searchable
-                radius="md"
-              />
-            )}
-            {rebookNeedsPartner &&
-              rebookDate &&
-              !rebookPartners.isLoading &&
-              (rebookPartners.data ?? []).length === 0 && (
-                <Text size="xs" c="orange">
-                  No odd-20ft booking rides that day — pick another day or wait
-                  for a partner booking.
-                </Text>
-              )}
-            {rebookDrafts.length > 0 && (
-              <Stack gap={6}>
-                <Text size="xs" c="dimmed">
-                  Correct the container details if they changed — sizes and
-                  quantities stay as cancelled.
-                </Text>
-                {rebookDrafts.map((d, i) => (
-                  <Group key={i} gap={8} wrap="nowrap" align="flex-end">
-                    <TextInput
-                      label={`${d.containerSize} container`}
-                      value={d.containerNumber}
-                      onChange={(e) => {
-                        const v = e.currentTarget.value;
-                        setRebookDrafts((prev) =>
-                          prev.map((x, idx) =>
-                            idx === i ? { ...x, containerNumber: v } : x,
-                          ),
-                        );
-                      }}
-                      size="xs"
-                      radius="md"
-                      style={{ flex: 1.4 }}
-                    />
-                    <TextInput
-                      label="Seal no."
-                      value={d.sealNumber}
-                      onChange={(e) => {
-                        const v = e.currentTarget.value;
-                        setRebookDrafts((prev) =>
-                          prev.map((x, idx) =>
-                            idx === i ? { ...x, sealNumber: v } : x,
-                          ),
-                        );
-                      }}
-                      size="xs"
-                      radius="md"
-                      style={{ flex: 1 }}
-                    />
-                    <TextInput
-                      label="VGM (t)"
-                      type="number"
-                      value={d.vgmTons === "" ? "" : String(d.vgmTons)}
-                      onChange={(e) => {
-                        const raw = e.currentTarget.value;
-                        setRebookDrafts((prev) =>
-                          prev.map((x, idx) =>
-                            idx === i
-                              ? { ...x, vgmTons: raw === "" ? "" : Number(raw) }
-                              : x,
-                          ),
-                        );
-                      }}
-                      size="xs"
-                      radius="md"
-                      style={{ width: 90 }}
-                    />
-                  </Group>
-                ))}
-              </Stack>
-            )}
-            <Group justify="flex-end" gap="sm">
-              <Button
-                variant="default"
-                radius="md"
-                onClick={() => setRebooking(null)}
-              >
-                Close
-              </Button>
-              <Button
-                color="green"
-                radius="md"
-                disabled={
-                  !rebookDate || (rebookNeedsPartner && !rebookPartnerId)
-                }
-                loading={rebook.isPending}
-                onClick={async () => {
-                  try {
-                    await rebook.mutateAsync();
-                    toast.success("Credit rebooked as a new paid booking");
-                    setRebooking(null);
-                    void refetch();
-                  } catch {
-                    // interceptor surfaces the reason
-                  }
-                }}
-              >
-                Rebook
-              </Button>
-            </Group>
-          </Stack>
-        )}
-      </Modal>
+        onRebooked={() => void refetch()}
+      />
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
index e664f1bd3..c5bf55c79 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
@@ -58,6 +58,12 @@ import {
   summarizeRequestedCargo,
 } from "@/features/clearance/requestedCargo";
 import { contractsService } from "@/services/contracts.service";
+import { api } from "@/auth/http";
+import {
+  RebookWagonCancellationModal,
+  canRebookWagonCancellations,
+  type WagonCancellation,
+} from "@/components/bookings/wagon-cancellation";
 import "./contract-clearance-table.css";
 
 /** Yards carry `label` (API) — older shapes used `name`/`code`. */
@@ -214,6 +220,7 @@ export default function ContractClearanceListPage() {
   const canCreateBooking =
     hasPermission(user, FREIGHT_PERMS.contracts.createBooking) &&
     !isDjiboutiGl(user);
+  const canRebookCredit = canRebookWagonCancellations(user);
 
   const [query, setQuery] = useState("");
   const [tab, setTab] = useState<TabKey>("all");
@@ -234,6 +241,21 @@ export default function ContractClearanceListPage() {
     refetch,
   } = useBookingEtClearanceQueue(true);
 
+  // Credit rebook opens the shared modal, which needs the full cancellation
+  // row — the queue only carries its id, so fetch it on demand.
+  const [creditRebook, setCreditRebook] = useState<WagonCancellation | null>(
+    null,
+  );
+  const openCreditRebook = useCallback(async (row: ShipmentBookingRow) => {
+    const res = await api.get<
+      { items?: WagonCancellation[] } | WagonCancellation[]
+    >(`/bookings/${row.id}/wagon-cancellations`);
+    const body = res.data;
+    const list = Array.isArray(body) ? body : (body?.items ?? []);
+    const match = list.find((c) => c.id === row.rebookableCancellationId);
+    if (match) setCreditRebook(match);
+  }, []);
+
   // Shipment requests carry the requested quantities (per container type, or
   // bulk weight/items). Map them onto the booking rows by createdBookingId so
   // the queue shows what each shipment was requested for.
@@ -272,6 +294,7 @@ export default function ContractClearanceListPage() {
       // A bare initiated instance has no cargo/price yet — GL still has to
       // create (complete) the booking.
       bookingCreated: Number(b.totalAmount ?? 0) > 0,
+      rebookableCancellationId: b.rebookableCancellationId ?? null,
     })) as ShipmentBookingRow[];
   }, [bookingQueue, requestedByBooking]);
 
@@ -602,12 +625,14 @@ export default function ContractClearanceListPage() {
               hasFilters={hasFilters}
               onClearFilters={clearFilters}
               canCreateBooking={canCreateBooking}
+              canRebookCredit={canRebookCredit}
               onOpen={openBooking}
               onCreateBooking={(row) =>
                 navigate(
                   `/dashboard/contracts/${row.contractId}/bookings/${row.id}/complete`,
                 )
               }
+              onRebookCredit={openCreditRebook}
               onRebook={(row) =>
                 // Re-complete the SAME expired booking (new day, same finished
                 // per-booking clearance) — a fresh instance would force the
@@ -623,6 +648,15 @@ export default function ContractClearanceListPage() {
           </Stack>
         </Card>
       </Stack>
+      <RebookWagonCancellationModal
+        cancellation={creditRebook}
+        onClose={() => setCreditRebook(null)}
+        onRebooked={() => {
+          setCreditRebook(null);
+          // The credit is spent and a new booking exists — both change the queue.
+          void refetch();
+        }}
+      />
     </PageContainer>
   );
 }
@@ -650,6 +684,8 @@ interface ShipmentBookingRow {
   createdAt: string | null;
   /** true once GL has actually created (completed) the booking. */
   bookingCreated: boolean;
+  /** Unspent wagon-cancellation credit on this booking, if any. */
+  rebookableCancellationId: string | null;
 }
 
 type PaginationState = ReturnType<typeof usePagination>["pagination"];
@@ -666,9 +702,11 @@ function ShipmentBookingsTable({
   hasFilters,
   onClearFilters,
   canCreateBooking,
+  canRebookCredit,
   onOpen,
   onCreateBooking,
   onRebook,
+  onRebookCredit,
   onViewContract,
 }: {
   rows: ShipmentBookingRow[];
@@ -681,9 +719,11 @@ function ShipmentBookingsTable({
   hasFilters: boolean;
   onClearFilters: () => void;
   canCreateBooking: boolean;
+  canRebookCredit: boolean;
   onOpen: (id: string) => void;
   onCreateBooking: (row: ShipmentBookingRow) => void;
   onRebook: (row: ShipmentBookingRow) => void;
+  onRebookCredit: (row: ShipmentBookingRow) => void;
   onViewContract: (contractId: string) => void;
 }) {
   // A bare initiated instance that has cleared but not yet been created by GL.
@@ -701,6 +741,14 @@ function ShipmentBookingsTable({
     r.customs &&
     r.status === "EXPIRED";
 
+  // A cancelled booking whose wagon-cancellation credit is paid for and unspent.
+  // Redeeming it is a different action from re-completing an expired booking —
+  // it opens the credit rebook modal rather than the completion form. Gated on
+  // the rebook permission (not booking-creation) so the button matches exactly
+  // who the API lets through.
+  const hasRebookableCredit = (r: ShipmentBookingRow) =>
+    canRebookCredit && Boolean(r.rebookableCancellationId);
+
   const columns = useMemo<ColumnDef<ShipmentBookingRow>[]>(
     () => [
       {
@@ -840,6 +888,7 @@ function ShipmentBookingsTable({
           const r = row.original;
           const bookable = isBookable(r);
           const rebookable = isRebookable(r);
+          const creditRebookable = hasRebookableCredit(r);
           return (
             <Group
               justify="flex-end"
@@ -870,6 +919,17 @@ function ShipmentBookingsTable({
                   Rebook
                 </Button>
               ) : null}
+              {creditRebookable ? (
+                <Button
+                  size="compact-sm"
+                  color="teal"
+                  radius="md"
+                  leftSection={<RefreshCw size={14} />}
+                  onClick={() => onRebookCredit(r)}
+                >
+                  Rebook credit
+                </Button>
+              ) : null}
               <Menu shadow="md" radius="md" position="bottom-end" withinPortal>
                 <Menu.Target>
                   <ActionIcon
@@ -904,6 +964,14 @@ function ShipmentBookingsTable({
                       Rebook (GL)
                     </Menu.Item>
                   ) : null}
+                  {creditRebookable ? (
+                    <Menu.Item
+                      leftSection={<RefreshCw size={14} />}
+                      onClick={() => onRebookCredit(r)}
+                    >
+                      Rebook cancellation credit
+                    </Menu.Item>
+                  ) : null}
                   {r.contractId ? (
                     <Menu.Item
                       leftSection={<ExternalLink size={14} />}
diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
index 9f7198609..87f098dc6 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
@@ -1226,7 +1226,9 @@ const LastMilePage = () => {
   // (same as "Mark In Transit") alongside the warehouse exit-weighing flow.
   const handleTruckLeaving = (record: LastMileRecord) => {
     openTruckArrival(record);
-    if (record.status === "READY_TO_TRANSIT") {
+    // Legs recorded before the advance gate can still sit at READY_TO_TRANSIT
+    // with the advance unpaid; the API would refuse the hop, so don't fire it.
+    if (record.status === "READY_TO_TRANSIT" && !record.advanceOutstanding) {
       updateMutation.mutate({ id: record.id, data: { status: "IN_TRANSIT" } });
     }
   };
@@ -1414,10 +1416,17 @@ const LastMilePage = () => {
           const hasDistance = row.original.exactKm != null;
           // Advance: PAYMENT_PENDING→Ready, READY_TO_TRANSIT→In-transit (needs a
           // vehicle), IN_TRANSIT→Delivered (needs distance/invoice).
+          // Mirrors the server's advance gate: nothing becomes dispatchable and
+          // nothing moves until the approved advance is paid. Delivery (the
+          // IN_TRANSIT step) is not gated, so only the two transit hops are.
+          const advanceBlocked =
+            Boolean(row.original.advanceOutstanding) &&
+            (nextStatus === "READY_TO_TRANSIT" || nextStatus === "IN_TRANSIT");
           const canAdvance =
-            status === "PAYMENT_PENDING" ||
-            (status === "READY_TO_TRANSIT" && assigned) ||
-            (status === "IN_TRANSIT" && hasDistance);
+            !advanceBlocked &&
+            (status === "PAYMENT_PENDING" ||
+              (status === "READY_TO_TRANSIT" && assigned) ||
+              (status === "IN_TRANSIT" && hasDistance));
           // Assign stays active until the whole load has trucks: container
           // bookings until every container is on a truck; bulk until the
           // tonnage is drawn down (trucks depart one by one). Already-departed
@@ -1470,9 +1479,11 @@ const LastMilePage = () => {
                     disabled={!nextStatus || !canAdvance}
                     onClick={() => handleAdvanceStatus(row.original)}
                   >
-                    {nextStatus
-                      ? `Mark ${STATUS_META[nextStatus].label}`
-                      : STATUS_META[row.original.status].label}
+                    {advanceBlocked
+                      ? "Awaiting advance payment"
+                      : nextStatus
+                        ? `Mark ${STATUS_META[nextStatus].label}`
+                        : STATUS_META[row.original.status].label}
                   </Menu.Item>
                   <Menu.Divider />
                   <Menu.Item
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
index 6ec28c27b..02b3979d7 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
@@ -26,6 +26,8 @@ import { PageContainer, PageHeader } from "@/components/page";
 import ManageRuleEngineOrderDialog from "@/components/ruleEngine/ManageRuleEngineOrderDialog";
 import PriorityRuleApprovalsSection from "@/pages/ruleEngine/PriorityRuleApprovalsSection";
 import RateApprovalsSection from "@/pages/ruleEngine/RateApprovalsSection";
+import TransitAgentAccountAction from "@/components/transit-agents/TransitAgentAccountAction";
+import type { TransitAgent } from "@/services/transit-agents.service";
 import { YardDesksModal } from "@/pages/ruleEngine/YardDesksModal";
 import { nextPriorityRangeStart } from "@/pages/ruleEngine/priorityRuleRange";
 import RuleEngineCardGrid from "@/components/ruleEngine/RuleEngineCardGrid";
@@ -577,8 +579,9 @@ const RuleEngineResourcePage = () => {
     base.push({
       id: "actions",
       header: "Actions",
-      size: config.orderConfig ? 200 : 140,
-      minSize: config.orderConfig ? 180 : 120,
+      // Transit agents carry an extra Invite/Resend button in this cell.
+      size: config.orderConfig ? 200 : config.slug === "transit-agents" ? 200 : 140,
+      minSize: config.orderConfig ? 180 : config.slug === "transit-agents" ? 180 : 120,
       meta: {
         headerClassName,
         cellClassName: `${cellClassName} whitespace-nowrap`,
@@ -597,6 +600,12 @@ const RuleEngineResourcePage = () => {
                 </Button>
               </Tooltip>
             ) : null}
+            {config.slug === "transit-agents" ? (
+              <TransitAgentAccountAction
+                agent={row.original as unknown as TransitAgent}
+                disabled={!canUpdateControls}
+              />
+            ) : null}
             {config.orderConfig && canUpdateControls ? (
               <RuleEngineOrderControls
                 record={row.original}
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
index 273c535e8..62fecd600 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
@@ -11,13 +11,14 @@ export type ColumnFormat =
   | "activeBadge"
   | "rateStatus"
   | "validityBadge"
+  | "accountBadge"
   | "date"
   | "number"
   | "currency"
   | "entityLabel"
   | "rateLabel";
 
-export type FormFieldType = "text" | "number" | "boolean" | "date" | "email" | "select" | "multiselect" | "textarea" | "radio" | "tierList";
+export type FormFieldType = "text" | "number" | "boolean" | "date" | "email" | "phone" | "select" | "multiselect" | "textarea" | "radio" | "tierList";
 
 export interface ResourceColumn {
   id: string;
@@ -661,6 +662,8 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
     cardTitleKey: "name",
     columns: [
       { id: "name", header: "Name", accessorKey: "name" },
+      { id: "email", header: "Email", accessorKey: "email" },
+      { id: "phoneNumber", header: "Phone", accessorKey: "phoneNumber" },
       { id: "validFrom", header: "Valid from", accessorKey: "validFrom", format: "date" },
       { id: "validTo", header: "Valid to", accessorKey: "validTo", format: "date" },
       {
@@ -669,6 +672,12 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         accessorKey: "validityStatus",
         format: "validityBadge",
       },
+      {
+        id: "hasAccount",
+        header: "Portal account",
+        accessorKey: "hasAccount",
+        format: "accountBadge",
+      },
       activeColumn,
     ],
     formFields: [
@@ -681,6 +690,21 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         required: true,
         description: "Expired or not-yet-started agents can't be assigned — extend the dates or add a new one",
       },
+      {
+        name: "email",
+        label: "Email",
+        type: "email",
+        optional: true,
+        description:
+          "Filling this on create makes the portal account and emails the activation link. On an existing agent, use the Invite button instead — editing here only corrects the address.",
+      },
+      {
+        name: "phoneNumber",
+        label: "Phone number",
+        type: "phone",
+        optional: true,
+        description: "Ethiopian and Djiboutian mobiles also receive the link by SMS",
+      },
       { name: "isActive", label: "Active", type: "boolean", description: "Off suspends the officer regardless of the validity window" },
     ],
   },
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx
index 2b1961362..d9c7658f7 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx
@@ -641,6 +641,7 @@ export default function TrainScheduleTrackPage() {
         onClose={() => setYardModal(null)}
         scheduleId={scheduleId}
         station={yardModal?.station ?? null}
+        stations={track.stations}
         isFinal={yardModal?.isFinal ?? false}
         alreadyLogged={yardModal?.alreadyLogged ?? false}
       />
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
index 26d9d7f88..6265d6f2d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
@@ -1,6 +1,7 @@
 import {
   ActionIcon,
   Alert,
+  Anchor,
   Badge,
   Box,
   Button,
@@ -64,6 +65,11 @@ import { LegCapacityPanel } from "@/components/trainScheduling/LegCapacityPanel"
 import { ScheduleWagonYardPanel } from "@/components/trainScheduling/ScheduleWagonYardPanel";
 import { LegLoadBoardPanel } from "@/components/trainScheduling/LegLoadBoardPanel";
 import { LoadEmptyContainersModal } from "@/components/trainScheduling/LoadEmptyContainersModal";
+import {
+  PartiallyLoadedDecisionModal,
+  parsePartiallyLoaded,
+  type PartiallyLoadedPayload,
+} from "@/components/trainScheduling/PartiallyLoadedDecisionModal";
 import MergeScheduleTrainModal from "@/components/trainScheduling/MergeScheduleTrainModal";
 import ScheduleHistoryPanel from "@/components/trainScheduling/ScheduleHistoryPanel";
 import { StationWorkControls } from "@/components/trainScheduling/StationWorkControls";
@@ -135,10 +141,12 @@ export default function TrainScheduleV2DetailPage() {
   // Actual departure — staff often dispatch on paper first and record it later,
   // so the time is picked (defaults to now when the dialog opens).
   const [dispatchAt, setDispatchAt] = useState<Date | null>(null);
-  const openDispatchConfirm = () => {
-    setDispatchAt(new Date());
-    setDispatchConfirmOpen(true);
-  };
+  // Set when dispatch is rejected because a booking is part-loaded; drives the
+  // EDR-fault / customer-fault decision modal.
+  const [partialGate, setPartialGate] = useState<PartiallyLoadedPayload | null>(null);
+  // Log-pass / arrive confirmation for the dispatched leg of the workflow.
+  const [passConfirmOpen, setPassConfirmOpen] = useState(false);
+  const [passAt, setPassAt] = useState<Date | null>(null);
   const [switchTarget, setSwitchTarget] = useState<EligibleContainerBooking | null>(null);
   const [visualization3DOpen, setVisualization3DOpen] = useState(false);
   const [loadEmptiesOpen, setLoadEmptiesOpen] = useState(false);
@@ -155,6 +163,23 @@ export default function TrainScheduleV2DetailPage() {
       refetchInterval: 300_000,
     }),
   );
+  // Journey state for the dispatched leg of the workflow: the corridor stops,
+  // which one the train has reached, and each yard's loading/unloading windows.
+  // Only a rolling train has a journey, so it stays idle until then.
+  const trackQuery = useQuery(
+    api.trainScheduling.trainTrack.queryOptions({
+      input: { id: scheduleId ?? "" },
+      enabled: Boolean(scheduleId),
+    }),
+  );
+  // Which bookings board/alight at each yard — drives the loading gate on the
+  // log-pass button (a yard with cargo to load must finish its window first).
+  const yardWorkQuery = useQuery(
+    api.trainScheduling.yardWork.queryOptions({
+      input: { scheduleId: scheduleId ?? "" },
+      enabled: Boolean(scheduleId),
+    }),
+  );
   // One-row 60s heartbeat: refetch the (expensive) full detail only when the
   // schedule row actually changed — same freshness as polling the detail
   // itself, at a fraction of the server cost.
@@ -256,6 +281,9 @@ export default function TrainScheduleV2DetailPage() {
   const unassign = useMutation(api.trainScheduling.unassignBooking.mutationOptions());
   const switchGov = useMutation(api.trainScheduling.switchGovernmentBooking.mutationOptions());
   const dispatch = useMutation(api.trainScheduling.dispatchSchedule.mutationOptions());
+  const recordCheckpoint = useMutation(
+    api.trainScheduling.recordCheckpoint.mutationOptions(),
+  );
   const downloadMarshalling = useMutation({
     mutationFn: ({
       id,
@@ -497,12 +525,35 @@ export default function TrainScheduleV2DetailPage() {
       b.originYardId === originYardId &&
       !b.loadedAt &&
       (b.loadingStatus ?? "UNLOADED") !== "LOADED" &&
+      // Paid is read from the PAYMENT status only, never booking.status.
       (b.isGovernment
-        ? b.status === "APPROVED" || b.status === "PAID"
-        : b.status === "PAID" ||
+        ? b.status === "APPROVED" || b.paymentStatus === "PAID"
+        : b.paymentStatus === "PAID" ||
           // Shipping-line bookings ride from accept on the credit ledger.
           (Boolean(b.shippingLineCompanyId) && b.status === "FULLY_EXECUTED")),
   );
+  // A slot can carry several loads of the same booking, so count DISTINCT
+  // slots per booking — the operator is being told how much steel is freed.
+  const slotIdsByBookingId = new Map<string, Set<string>>();
+  for (const slot of schedule.trainSet?.wagons ?? []) {
+    for (const alloc of slot.allocations ?? []) {
+      if (!alloc.bookingId) continue;
+      const slots = slotIdsByBookingId.get(alloc.bookingId) ?? new Set<string>();
+      slots.add(slot.id);
+      slotIdsByBookingId.set(alloc.bookingId, slots);
+    }
+  }
+  const wagonsOf = (bookingId: string) => slotIdsByBookingId.get(bookingId)?.size ?? 0;
+
+  const openDispatchConfirm = () => {
+    setDispatchAt(new Date());
+    setDispatchConfirmOpen(true);
+  };
+  // Everything unloaded at the origin comes off the train on dispatch.
+  // Government bookings can never be shed: the server refuses to unassign them.
+  const leftBehind = pendingOriginBoarders.filter((b) => !b.isGovernment);
+  const leftBehindWagons = leftBehind.reduce((n, b) => n + wagonsOf(b.id), 0);
+
   // Origin loading time window: dispatch (which marks the boarders loaded)
   // is server-rejected until "Start loading" was clicked for the origin
   // yard, so the button mirrors that gate.
@@ -516,6 +567,89 @@ export default function TrainScheduleV2DetailPage() {
   // Same gate the server enforces.
   const dispatchBlockedByLoading = !originLoadingEnded;
 
+  // ── Journey leg: log pass / mark arrived ────────────────────────────────
+  // Once the train is rolling, the workflow's last step drives the corridor
+  // instead of dispatch. The stop being logged is the one AFTER the train's
+  // current position; the last stop on the route is the arrival.
+  const track = trackQuery.data;
+  const trackStations = track?.stations ?? [];
+  const isRolling = schedule.status === "DISPATCHED";
+  const nextStation = isRolling
+    ? trackStations.find((st) => st.sequenceNo === (track?.currentSequenceNo ?? 0) + 1)
+    : undefined;
+  const nextIsFinal =
+    Boolean(nextStation) &&
+    nextStation?.sequenceNo === trackStations[trackStations.length - 1]?.sequenceNo;
+  // Same permission the track page gates its checkpoint actions on.
+  const canLogPass =
+    isRolling && hasPermission(authUser, FREIGHT_PERMS.trainScheduling.update);
+  // Loading gate. Logging a pass means the train LEAVES the yard it is standing
+  // at, so cargo boarding there must have finished loading first — an open (or
+  // never-opened) loading window at a yard with boarders blocks the button.
+  // Unloading never blocks: cargo alighting here can be taken off after the
+  // pass is recorded, and the final arrival is what opens that window at all.
+  const currentStation = isRolling
+    ? trackStations.find((st) => st.sequenceNo === (track?.currentSequenceNo ?? 0))
+    : undefined;
+  const currentYardWork = currentStation
+    ? yardWorkQuery.data?.yards.find((y) => y.yardId === currentStation.yardId)
+    : undefined;
+  const boardersHere = (currentYardWork?.toLoad ?? []).filter((r) => !r.loadedAt);
+  const currentLoadingLog = currentStation
+    ? track?.stationWorkLogs?.[currentStation.yardId]?.loading
+    : undefined;
+  // Only a yard that actually has cargo to load can be blocked by its window.
+  const passBlockedByLoading =
+    boardersHere.length > 0 && !currentLoadingLog?.endedAt;
+  const passBlockReason = !passBlockedByLoading
+    ? null
+    : currentLoadingLog?.startedAt
+      ? `End the loading window at ${currentStation?.label ?? "this yard"} — the train cannot leave mid-loading.`
+      : `Start and end the loading window at ${currentStation?.label ?? "this yard"} — ${boardersHere.length} booking(s) board here.`;
+
+  const openPassConfirm = () => {
+    setPassAt(new Date());
+    setPassConfirmOpen(true);
+  };
+
+  const runLogPass = async () => {
+    if (!nextStation) return;
+    setPassConfirmOpen(false);
+    try {
+      await recordCheckpoint.mutateAsync({
+        id: scheduleId,
+        payload: {
+          sequenceNo: nextStation.sequenceNo,
+          ...(passAt ? { occurredAt: passAt.toISOString() } : {}),
+        },
+      });
+      toast({
+        title: nextIsFinal
+          ? `Train arrived at ${nextStation.label}`
+          : `Pass logged at ${nextStation.label}`,
+        description: nextIsFinal
+          ? "Remaining bookings are marked arrived and the assets are freed."
+          : "The train's position has moved to this yard.",
+      });
+      void trackQuery.refetch();
+      void yardWorkQuery.refetch();
+      void detailQuery.refetch();
+    } catch (err) {
+      // A part-loaded booking blocks the pass until its never-loaded wagons are
+      // cut — hand over the fault decision rather than a dead-end error.
+      const gate = parsePartiallyLoaded(err);
+      if (gate) {
+        setPartialGate(gate);
+        return;
+      }
+      toast({
+        title: nextIsFinal ? "Could not mark arrived" : "Could not log pass",
+        description: parseError(err, "Please try again"),
+        variant: "destructive",
+      });
+    }
+  };
+
   const finalizeStep = hasContainerStep ? 3 : 2;
   const canModifyBookings = canEditBookings && !["DISPATCHED", "ARRIVED"].includes(schedule.status);
   const canPrintMarshalling =
@@ -572,17 +706,34 @@ export default function TrainScheduleV2DetailPage() {
         id: scheduleId,
         payload: {
           ...(dispatchAt ? { actualDepartureAt: dispatchAt.toISOString() } : {}),
-          // No per-booking ticking in the dispatch dialog: every pending origin
-          // boarder rides — none are left behind at dispatch time.
-          loadedBookingIds: pendingOriginBoarders.map((b) => b.id),
+          // Dispatch never loads cargo — loading is recorded in the yard, per
+          // booking. Anything still unloaded when the train leaves did not make
+          // it aboard: the server unassigns it (wagons freed, booking back in
+          // the pool). Government bookings are exempt and ride regardless.
+          loadedBookingIds: pendingOriginBoarders
+            .filter((b) => b.isGovernment)
+            .map((b) => b.id),
         },
       });
+      if (leftBehind.length) {
+        toast({
+          title: `${leftBehind.length} booking${leftBehind.length === 1 ? "" : "s"} removed from the train`,
+          description: `Never loaded at the origin — ${leftBehindWagons} wagon${leftBehindWagons === 1 ? "" : "s"} freed. The bookings are back in the pool and can be allocated to another train or cancelled.`,
+        });
+      }
       await openMarshallingDocument({
         title: "Train dispatched",
         successDescription: "Marshalling document generated for the dispatched train.",
         errorTitle: "Train dispatched, but document could not open",
       });
     } catch (err) {
+      // A part-loaded booking blocks dispatch until its never-loaded wagons are
+      // cut — hand the operator the fault decision instead of a dead error.
+      const gate = parsePartiallyLoaded(err);
+      if (gate) {
+        setPartialGate(gate);
+        return;
+      }
       toast({
         title: "Dispatch failed",
         description: parseError(err, "Could not dispatch"),
@@ -705,8 +856,10 @@ export default function TrainScheduleV2DetailPage() {
     {
       key: "finalize",
       icon: CheckCircle2,
-      title: "Dispatch",
-      subtitle: "Review the consist & dispatch",
+      title: isRolling ? "Journey" : "Dispatch",
+      subtitle: isRolling
+        ? "Log each pass, then mark arrived"
+        : "Review the consist & dispatch",
       complete: finalizeComplete,
     },
   ];
@@ -958,14 +1111,51 @@ export default function TrainScheduleV2DetailPage() {
               <CheckCircle2 size={22} />
             </ThemeIcon>
             <Stack gap={2}>
-              <Text fw={600}>Ready to depart</Text>
+              <Text fw={600}>
+                {isRolling
+                  ? nextIsFinal
+                    ? "Final leg"
+                    : `In transit — at ${currentStation?.label ?? "the corridor"}`
+                  : "Ready to depart"}
+              </Text>
               <Text size="sm" c="dimmed">
-                Dispatch begins rail movement and notifies the yard.
+                {isRolling
+                  ? nextIsFinal
+                    ? "Marking arrived ends the journey and frees the locomotive and wagons."
+                    : "Logging the pass moves the train to the next yard and settles its cargo there."
+                  : "Dispatch begins rail movement and notifies the yard."}
               </Text>
             </Stack>
           </Group>
         </Paper>
-        {originYardId ? (
+        {/* Mid-route loading/unloading is recorded on the TRACKING page, per
+            yard — only the origin's window lives here (below), because dispatch
+            is the action this page owns. What stays is the read-only reason the
+            pass button is held, so the blocker is explainable without
+            duplicating the controls. */}
+        {isRolling && currentStation && passBlockedByLoading ? (
+          <Alert
+            color="orange"
+            variant="light"
+            radius="md"
+            icon={<AlertTriangle size={18} />}
+            title={`Loading is not finished at ${currentStation.label}`}
+          >
+            <Text size="xs">
+              {boardersHere.length} booking(s) board here, so the train cannot leave until
+              the loading window is closed. Start and end it on the{" "}
+              <Anchor
+                component={Link}
+                to={`/dashboard/operations/train-scheduling-v2/${scheduleId}/track`}
+                fw={600}
+              >
+                tracking page
+              </Anchor>
+              .
+            </Text>
+          </Alert>
+        ) : null}
+        {!isRolling && originYardId ? (
           <Paper p="md" radius="lg" withBorder>
             <Stack gap={6}>
               <Text fw={600} size="sm">
@@ -1000,7 +1190,35 @@ export default function TrainScheduleV2DetailPage() {
               Dispatch train
             </Button>
           ) : null}
-          {!canDispatch ? (
+          {/* The train is rolling: the same slot now drives the corridor. */}
+          {canLogPass && nextStation ? (
+            <Tooltip
+              label={passBlockReason ?? ""}
+              disabled={!passBlockedByLoading}
+              withArrow
+              multiline
+              w={280}
+            >
+              <div>
+                <Button
+                  color="edr-green"
+                  size="md"
+                  radius="md"
+                  leftSection={
+                    nextIsFinal ? <CheckCircle2 size={18} /> : <Navigation size={18} />
+                  }
+                  loading={recordCheckpoint.isPending}
+                  disabled={passBlockedByLoading}
+                  onClick={openPassConfirm}
+                >
+                  {nextIsFinal
+                    ? `Mark arrived at ${nextStation.label}`
+                    : `Log pass at ${nextStation.label}`}
+                </Button>
+              </div>
+            </Tooltip>
+          ) : null}
+          {!canDispatch && !(canLogPass && nextStation) ? (
             <Text size="sm" c="dimmed">
               No actions available for this schedule status.
             </Text>
@@ -1636,6 +1854,25 @@ export default function TrainScheduleV2DetailPage() {
             radius="md"
           />
 
+          {leftBehind.length > 0 ? (
+            <Alert
+              color="orange"
+              variant="light"
+              radius="md"
+              icon={<AlertTriangle size={18} />}
+              title={`${leftBehind.length} booking${leftBehind.length === 1 ? "" : "s"} will be removed from this train`}
+            >
+              <Text size="xs">
+                Never loaded at the origin, so {leftBehind.length === 1 ? "it is" : "they are"}{" "}
+                not aboard. Dispatch frees {leftBehindWagons} wagon
+                {leftBehindWagons === 1 ? "" : "s"} and returns{" "}
+                {leftBehind.length === 1 ? "the booking" : "them"} to the pool, ready to be
+                allocated to another train or cancelled. Load cargo from the yard workspace
+                before dispatching if it should ride.
+              </Text>
+            </Alert>
+          ) : null}
+
           {hasDispatchWarnings ? (
             <Alert
               color="orange"
@@ -1717,6 +1954,62 @@ export default function TrainScheduleV2DetailPage() {
           </Group>
         </Stack>
       </Modal>
+      {/* Log pass / arrival — confirmation only, with the recorded time. */}
+      <Modal
+        opened={passConfirmOpen}
+        onClose={() => setPassConfirmOpen(false)}
+        centered
+        radius="lg"
+        title={
+          <Group gap={8}>
+            {nextIsFinal ? <CheckCircle2 size={18} /> : <Navigation size={18} />}
+            <Text fw={700}>
+              {nextIsFinal ? "Mark the train arrived?" : "Log the pass?"}
+            </Text>
+          </Group>
+        }
+      >
+        <Stack gap="md">
+          <Text size="sm" c="dimmed">
+            {nextIsFinal
+              ? `Recording arrival at ${nextStation?.label ?? "the destination"} ends the journey: remaining bookings are marked arrived and the locomotive and wagons are freed.`
+              : `Recording the pass at ${nextStation?.label ?? "the next yard"} moves the train there. Cargo destined for that yard alights, and cargo boarding there becomes loadable.`}
+          </Text>
+
+          <DateTimePicker
+            label={nextIsFinal ? "Arrival time" : "Time at station"}
+            description="Defaults to now — pick an earlier time if you are recording after the fact."
+            value={passAt}
+            onChange={(v) => setPassAt(v ? new Date(v) : null)}
+            maxDate={new Date()}
+            valueFormat="DD MMM YYYY HH:mm"
+            clearable={false}
+            radius="md"
+          />
+
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" radius="md" onClick={() => setPassConfirmOpen(false)}>
+              Cancel
+            </Button>
+            <Button
+              color="edr-green"
+              radius="md"
+              loading={recordCheckpoint.isPending}
+              onClick={() => void runLogPass()}
+            >
+              {nextIsFinal ? "Mark arrived" : "Log pass"}
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+
+      {/* Part-loaded gate. Cutting the wagons does NOT dispatch — the operator
+          confirms dispatch again once the consist is clean. */}
+      <PartiallyLoadedDecisionModal
+        payload={partialGate}
+        onClose={() => setPartialGate(null)}
+        onResolved={() => void detailQuery.refetch()}
+      />
       {visualization3DOpen ? (
         <Train3DVisualization schedule={schedule} onClose={() => setVisualization3DOpen(false)} />
       ) : null}
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
index f9857fa5b..e59851feb 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
@@ -158,6 +158,11 @@ export default function TrainScheduleV2ListPage() {
   const [routeId, setRouteId] = useState("");
   const [scheduleDate, setScheduleDate] = useState("");
   const [trainId, setTrainId] = useState("");
+  // Voyage number for this departure — required. Auto-filled from the selected
+  // train's own voyage number (typed in the Train Builder) when a train is
+  // picked; legacy trains without one fall back to the direction-matched run
+  // number. Staff may edit.
+  const [voyageNumber, setVoyageNumber] = useState("");
   const [reverseWagonOrder, setReverseWagonOrder] = useState(false);
   // "" = a normal customer train; an id dedicates the departure to that
   // shipping line and hides it from every customer-facing view.
@@ -461,6 +466,13 @@ export default function TrainScheduleV2ListPage() {
       });
       return;
     }
+    if (!voyageNumber.trim()) {
+      toast({
+        title: "Voyage number is required",
+        variant: "destructive",
+      });
+      return;
+    }
     // Only build the window override when the toggle is on — off means "inherit
     // the global rules", which the API expresses as an absent windowRule.
     let windowRule: CreateScheduleWindowRulePayload | undefined;
@@ -483,6 +495,7 @@ export default function TrainScheduleV2ListPage() {
           routeId,
           scheduleDate: new Date(scheduleDate).toISOString(),
           trainId,
+          voyageNumber: voyageNumber.trim(),
           reverseWagonOrder,
           ...(shippingLineCompanyId ? { shippingLineCompanyId } : {}),
           ...(windowRule ? { windowRule } : {}),
@@ -490,6 +503,7 @@ export default function TrainScheduleV2ListPage() {
       });
       toast({ title: "Train schedule created" });
       showScheduleWarnings(created.warnings);
+      setVoyageNumber("");
       setReverseWagonOrder(false);
       setShippingLineCompanyId("");
       setConfigureWindow(false);
@@ -689,7 +703,20 @@ export default function TrainScheduleV2ListPage() {
               };
             })}
             value={trainId || null}
-            onChange={(v) => setTrainId(v ?? "")}
+            onChange={(v) => {
+              setTrainId(v ?? "");
+              // Default the voyage number to the picked train's own voyage
+              // number (the Train Builder stores it as `trainName`). The run
+              // number is a train number, not a voyage — only fall back to it
+              // for legacy trains that have no voyage number yet; staff can
+              // still override.
+              const picked = (trainsQuery.data ?? []).find((t) => t.id === v);
+              const runNumber =
+                selectedRoute?.direction === "IMPORT"
+                  ? picked?.importTrainNumber
+                  : picked?.exportTrainNumber;
+              setVoyageNumber(picked?.trainName?.trim() || runNumber || "");
+            }}
             searchable
             disabled={!routeId}
             nothingFoundMessage={
@@ -698,6 +725,15 @@ export default function TrainScheduleV2ListPage() {
                 : "Select a route first"
             }
           />
+          <TextInput
+            label="Voyage number"
+            description="Sailing/run number for this departure that yards and customs quote. Defaults to the selected train's voyage number — edit if needed."
+            placeholder={trainId ? "e.g. V-2026-0620" : "Select a train first"}
+            required
+            maxLength={20}
+            value={voyageNumber}
+            onChange={(e) => setVoyageNumber(e.currentTarget.value)}
+          />
           <Select
             label="Shipping line (optional)"
             description="Dedicate this departure to one shipping line. The train is then hidden from customers and shown only in that line's portal."
@@ -930,7 +966,12 @@ function TrainIdentityCell({ schedule }: { schedule: TrainScheduleListItem }) {
   let subtitle = "";
   if (schedule.train) {
     title = schedule.trainNumber ?? schedule.train.code;
-    subtitle = [schedule.trainNumber ? schedule.train.code : null, schedule.train.trainName]
+    // Show THIS departure's voyage number (the schedule's own), not the train's
+    // voyage/name — one train serves many departures, each with its own voyage.
+    subtitle = [
+      schedule.trainNumber ? schedule.train.code : null,
+      schedule.voyageNumber ? `Voyage ${schedule.voyageNumber}` : null,
+    ]
       .filter(Boolean)
       .join(" · ");
   } else if (locos.length) {
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
index c3896ca31..60b349437 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
@@ -27,7 +27,7 @@ import { DataTable, type ColumnDef } from "@edr/ui-common";
 import { PageContainer, PageHeader } from "@/components/page";
 import ListControls from "@/components/common/ListControls";
 import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
-import { extractDownloadErrorMessage } from "@/components/warehouses/options";
+import { extractDownloadErrorMessage, extractErrorMessage } from "@/components/warehouses/options";
 import { openPdfBlob } from "@/components/warehouses/pdf";
 import BulkContainerReturnModal from "@/components/warehouses/BulkContainerReturnModal";
 import { downloadContainerReturnTemplate } from "@/components/warehouses/container-return-excel";
@@ -40,10 +40,13 @@ import { useWarehouseYards, useWarehouseZones } from "@/hooks/useWarehouses";
 import { api } from "@/services/api";
 import { warehouseService } from "@/services/warehouse.service";
 import { importOperationsService } from "@/services/importOperations.service";
+import { emptyReturnRequestsService } from "@/services/emptyReturnRequests.service";
 import type {
   EmptyContainerReturn,
   EmptyContainerReturnStatus,
   EmptyContainerSize,
+  EmptyReturnBooking,
+  PlannedEmptyReturn,
 } from "@/types/importOperations";
 import type { TrainScheduleListItem } from "@/types/trainScheduling";
 import { formatDateTime, localNowForInput } from "@/lib/format";
@@ -77,6 +80,32 @@ const RETURNED_BY_SERIES = [
   { key: "customer", label: "Customer Self-Haul", color: "#b45309" },
 ];
 
+/**
+ * A scheduled request seen as the booking shape `BookingEmptyReturnModal`
+ * takes, so confirming an arrival runs through exactly the same recording
+ * path as any other empty return.
+ */
+const plannedAsBooking = (planned: PlannedEmptyReturn): EmptyReturnBooking => ({
+  bookingId: planned.bookingId,
+  bookingReference: planned.bookingReference ?? planned.bookingId,
+  bookingStatus: "SCHEDULED_RETURN",
+  equipmentReturn: "REQUESTED",
+  customerId: planned.companyId,
+  companyName: planned.companyName,
+  containers: planned.containers.map((container) => ({
+    key: `${planned.requestId}-${container.containerNumber}`,
+    unitId: `${planned.requestId}-${container.containerNumber}`,
+    containerNumber: container.containerNumber,
+    containerSize: null,
+    containerType: null,
+    returnId: container.returnId,
+    returnStatus: null,
+  })),
+  expectedCount: planned.containers.length,
+  recordedCount: planned.containers.filter((c) => c.returnId).length,
+  pendingCount: planned.containers.filter((c) => !c.returnId).length,
+});
+
 interface ContainerReturnRow {
   key: string;
   containerNumber: string;
@@ -111,6 +140,9 @@ export default function ContainerReturnsPage() {
   const [activeKey, setActiveKey] = useState<string | null>(null);
   const [historyRow, setHistoryRow] = useState<any | null>(null);
   const [allocateRow, setAllocateRow] = useState<EmptyContainerReturn | null>(null);
+  const [emptyReturnBooking, setEmptyReturnBooking] = useState<EmptyReturnBooking | null>(null);
+  const [expandedBooking, setExpandedBooking] = useState<string | null>(null);
+  const [arrivingReturn, setArrivingReturn] = useState<PlannedEmptyReturn | null>(null);
   const [documentBusyId, setDocumentBusyId] = useState<string | null>(null);
 
   const viewInterchangeDocument = async (ret: EmptyContainerReturn) => {
@@ -146,6 +178,24 @@ export default function ContainerReturnsPage() {
     },
   });
 
+  // Bookings that ship WITH empty-container return and still owe empties. This
+  // list stands on the booking's own return flags, so it does not wait for the
+  // box to reach a warehouse or for a last-mile truck to be assigned — the
+  // queue below still covers that path.
+  const emptyReturnBookingsQuery = useQuery({
+    queryKey: ["empty-return-bookings"],
+    queryFn: () => importOperationsService.listEmptyReturnBookings(),
+  });
+  const emptyReturnBookings = emptyReturnBookingsQuery.data ?? [];
+
+  // Requests the customer already paid for and booked a truck against — the
+  // warehouse confirms these on arrival, which is what records the containers.
+  const plannedReturnsQuery = useQuery({
+    queryKey: ["planned-empty-returns"],
+    queryFn: () => emptyReturnRequestsService.planned(),
+  });
+  const plannedReturns = plannedReturnsQuery.data ?? [];
+
   const bookingIds = unloadedQueue.map((item) => item.bookingId).filter(Boolean) as string[];
   const containerReturnsQuery = useQuery({
     queryKey: ["container-returns", bookingIds],
@@ -287,6 +337,10 @@ export default function ContainerReturnsPage() {
     searchKeys: ["bookingRef", "companyName"],
   });
 
+  const bookingReturnControls = useListControls(emptyReturnBookings, {
+    searchKeys: ["bookingReference", "companyName", "bookingStatus"],
+  });
+
   const createReturnsMutation = useMutation({
     mutationFn: async (payload: {
       trucks: Array<{
@@ -332,9 +386,13 @@ export default function ContainerReturnsPage() {
       toast({ title: "Container returns recorded" });
       qc.invalidateQueries({ queryKey: ["container-returns", bookingIds] });
       qc.invalidateQueries({ queryKey: ["empty-container-returns"] });
+      qc.invalidateQueries({ queryKey: ["empty-return-bookings"] });
+      qc.invalidateQueries({ queryKey: ["planned-empty-returns"] });
       setReturnModalOpen(false);
       setStandaloneModalOpen(false);
       setActiveKey(null);
+      setEmptyReturnBooking(null);
+      setArrivingReturn(null);
     },
     onError: (error: any) => {
       toast({
@@ -548,6 +606,240 @@ export default function ContainerReturnsPage() {
         </Group>
       </Group>
 
+      {plannedReturns.length > 0 && (
+        <Card withBorder radius="lg" p="md" mb="lg">
+          <Stack gap="md">
+            <Group justify="space-between" align="flex-start">
+              <div>
+                <Text fw={600}>Planned Empty Returns</Text>
+                <Text size="sm" c="dimmed">
+                  Customers who paid for an empty return and booked a truck. Confirm the arrival
+                  to record the containers.
+                </Text>
+              </div>
+              <Badge variant="light" size="lg" color="orange">
+                {plannedReturns.length} expected
+              </Badge>
+            </Group>
+
+            <Table.ScrollContainer minWidth={900}>
+              <Table highlightOnHover verticalSpacing="xs">
+                <Table.Thead>
+                  <Table.Tr>
+                    <Table.Th>Booking Ref</Table.Th>
+                    <Table.Th>Company</Table.Th>
+                    <Table.Th>Return Date</Table.Th>
+                    <Table.Th>Truck</Table.Th>
+                    <Table.Th>Containers</Table.Th>
+                    <Table.Th ta="right">Action</Table.Th>
+                  </Table.Tr>
+                </Table.Thead>
+                <Table.Tbody>
+                  {plannedReturns.map((planned) => {
+                    const outstanding = planned.containers.filter((c) => !c.returnId);
+                    return (
+                      <Table.Tr key={planned.requestId}>
+                        <Table.Td>
+                          <Text fw={600}>{planned.bookingReference ?? planned.bookingId}</Text>
+                        </Table.Td>
+                        <Table.Td>{planned.companyName ?? "—"}</Table.Td>
+                        <Table.Td>{planned.requestedReturnDate ?? "—"}</Table.Td>
+                        <Table.Td>
+                          <Stack gap={2}>
+                            <Text size="sm">{planned.truckPlateNumber ?? "—"}</Text>
+                            <Text size="xs" c="dimmed">
+                              {planned.truckDriverName ?? "—"}
+                              {planned.truckType ? ` · ${planned.truckType}` : ""}
+                            </Text>
+                          </Stack>
+                        </Table.Td>
+                        <Table.Td>
+                          <Stack gap={2}>
+                            <Badge color={outstanding.length ? "orange" : "edr-green"}>
+                              {outstanding.length} of {planned.containers.length} outstanding
+                            </Badge>
+                            <Text size="xs" c="dimmed" lineClamp={2}>
+                              {planned.containers.map((c) => c.containerNumber).join(", ")}
+                            </Text>
+                          </Stack>
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          <Button
+                            size="xs"
+                            variant="light"
+                            disabled={outstanding.length === 0}
+                            onClick={() => setArrivingReturn(planned)}
+                          >
+                            Confirm Arrival
+                          </Button>
+                        </Table.Td>
+                      </Table.Tr>
+                    );
+                  })}
+                </Table.Tbody>
+              </Table>
+            </Table.ScrollContainer>
+          </Stack>
+        </Card>
+      )}
+
+      <Card withBorder radius="lg" p="md" mb="lg">
+        <Stack gap="md">
+          <Group justify="space-between" align="flex-start">
+            <div>
+              <Text fw={600}>Bookings With Empty Container Return</Text>
+              <Text size="sm" c="dimmed">
+                Bookings that ship with equipment return and still owe empties. Open one to pick
+                the containers coming back, then record the return for that booking.
+              </Text>
+            </div>
+            <Badge variant="light" size="lg">
+              {emptyReturnBookings.length} booking{emptyReturnBookings.length !== 1 ? "s" : ""}
+            </Badge>
+          </Group>
+
+          <ListControls
+            search={bookingReturnControls.search}
+            onSearchChange={bookingReturnControls.setSearch}
+            searchPlaceholder="Search booking, company, status…"
+            dateFrom={bookingReturnControls.dateFrom}
+            onDateFromChange={bookingReturnControls.setDateFrom}
+            dateTo={bookingReturnControls.dateTo}
+            onDateToChange={bookingReturnControls.setDateTo}
+            showDateRange={false}
+            hasFilters={bookingReturnControls.hasFilters}
+            onReset={bookingReturnControls.reset}
+          />
+
+          {emptyReturnBookingsQuery.isLoading ? (
+            <Group justify="center" py="md">
+              <Loader size="sm" />
+            </Group>
+          ) : emptyReturnBookingsQuery.isError ? (
+            <Alert color="red">
+              Could not load bookings with empty container return.{" "}
+              {extractErrorMessage(emptyReturnBookingsQuery.error)}
+            </Alert>
+          ) : bookingReturnControls.pagedRows.length === 0 ? (
+            <Alert color="gray">
+              No booking is waiting on an empty container return.
+            </Alert>
+          ) : (
+            <>
+              <Table.ScrollContainer minWidth={900}>
+                <Table highlightOnHover verticalSpacing="xs">
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th w={40} />
+                      <Table.Th>Booking Ref</Table.Th>
+                      <Table.Th>Company</Table.Th>
+                      <Table.Th>Booking Status</Table.Th>
+                      <Table.Th>Containers To Return</Table.Th>
+                      <Table.Th ta="right">Action</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {bookingReturnControls.pagedRows.map((booking) => {
+                      const isOpen = expandedBooking === booking.bookingId;
+                      return (
+                        <Fragment key={booking.bookingId}>
+                          <Table.Tr>
+                            <Table.Td>
+                              <ActionIcon
+                                variant="subtle"
+                                color="gray"
+                                onClick={() =>
+                                  setExpandedBooking(isOpen ? null : booking.bookingId)
+                                }
+                                title={isOpen ? "Hide containers" : "Show containers"}
+                              >
+                                {isOpen ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
+                              </ActionIcon>
+                            </Table.Td>
+                            <Table.Td>
+                              <Text fw={600}>{booking.bookingReference}</Text>
+                            </Table.Td>
+                            <Table.Td>{booking.companyName ?? "—"}</Table.Td>
+                            <Table.Td>
+                              <Badge size="sm" variant="light">
+                                {booking.bookingStatus.replaceAll("_", " ")}
+                              </Badge>
+                            </Table.Td>
+                            <Table.Td>
+                              <Group gap="xs">
+                                <Badge color="orange">{booking.pendingCount} pending</Badge>
+                                {booking.recordedCount > 0 && (
+                                  <Badge color="edr-green" variant="light">
+                                    {booking.recordedCount} recorded
+                                  </Badge>
+                                )}
+                              </Group>
+                            </Table.Td>
+                            <Table.Td ta="right">
+                              <Button
+                                size="xs"
+                                variant="light"
+                                onClick={() => setEmptyReturnBooking(booking)}
+                              >
+                                Empty Container Return
+                              </Button>
+                            </Table.Td>
+                          </Table.Tr>
+                          {isOpen && (
+                            <Table.Tr>
+                              <Table.Td colSpan={6}>
+                                <Table striped>
+                                  <Table.Thead>
+                                    <Table.Tr>
+                                      <Table.Th>Container</Table.Th>
+                                      <Table.Th>Size</Table.Th>
+                                      <Table.Th>Type</Table.Th>
+                                      <Table.Th>Return Status</Table.Th>
+                                    </Table.Tr>
+                                  </Table.Thead>
+                                  <Table.Tbody>
+                                    {booking.containers.map((container) => (
+                                      <Table.Tr key={container.key}>
+                                        <Table.Td>{container.containerNumber}</Table.Td>
+                                        <Table.Td>{container.containerSize ?? "—"}</Table.Td>
+                                        <Table.Td>{container.containerType ?? "—"}</Table.Td>
+                                        <Table.Td>
+                                          {container.returnStatus ? (
+                                            <Badge size="sm" color="edr-green" variant="light">
+                                              {RETURN_STATUS_LABEL[container.returnStatus] ??
+                                                container.returnStatus}
+                                            </Badge>
+                                          ) : (
+                                            <Badge size="sm" color="orange" variant="light">
+                                              Awaiting return
+                                            </Badge>
+                                          )}
+                                        </Table.Td>
+                                      </Table.Tr>
+                                    ))}
+                                  </Table.Tbody>
+                                </Table>
+                              </Table.Td>
+                            </Table.Tr>
+                          )}
+                        </Fragment>
+                      );
+                    })}
+                  </Table.Tbody>
+                </Table>
+              </Table.ScrollContainer>
+              <RuleEngineListFooter
+                pagination={bookingReturnControls.pagination}
+                pageCount={bookingReturnControls.pageCount}
+                totalCount={bookingReturnControls.totalCount}
+                itemLabel="bookings"
+                onPaginationChange={bookingReturnControls.setPagination}
+              />
+            </>
+          )}
+        </Stack>
+      </Card>
+
       {returnedContainers.length > 0 && (
         <Card withBorder radius="lg" p="md" mb="lg">
           <Stack gap="md">
@@ -721,6 +1013,31 @@ export default function ContainerReturnsPage() {
         loading={createReturnsMutation.isPending}
       />
 
+      <BookingEmptyReturnModal
+        booking={emptyReturnBooking}
+        onClose={() => setEmptyReturnBooking(null)}
+        onSubmit={(payload) => createReturnsMutation.mutate(payload)}
+        loading={createReturnsMutation.isPending}
+      />
+
+      {/* A scheduled return arrives on the customer's own truck, so the modal
+          opens pre-set to self-haul with that truck already noted. */}
+      <BookingEmptyReturnModal
+        title="Confirm Empty Return Arrival"
+        booking={arrivingReturn ? plannedAsBooking(arrivingReturn) : null}
+        onClose={() => setArrivingReturn(null)}
+        onSubmit={(payload) => createReturnsMutation.mutate(payload)}
+        loading={createReturnsMutation.isPending}
+        defaultReturnedBy="CUSTOMER"
+        defaultHandoverNote={
+          arrivingReturn
+            ? `Scheduled empty return · truck ${arrivingReturn.truckPlateNumber ?? "—"}${
+                arrivingReturn.truckDriverName ? ` · driver ${arrivingReturn.truckDriverName}` : ""
+              }`
+            : undefined
+        }
+      />
+
       <BulkContainerReturnModal
         opened={bulkModalOpen}
         onClose={() => setBulkModalOpen(false)}
@@ -1028,6 +1345,305 @@ function ContainerReturnModal({ opened, onClose, group, onSubmit, loading }: Con
   );
 }
 
+
+interface BookingEmptyReturnModalProps {
+  booking: EmptyReturnBooking | null;
+  onClose: () => void;
+  onSubmit: (payload: any) => void;
+  loading: boolean;
+  /** Pre-set for a scheduled return, where the truck type is already known. */
+  defaultReturnedBy?: "EDR" | "CUSTOMER";
+  /** Pre-set for a scheduled return — the truck the customer told us about. */
+  defaultHandoverNote?: string;
+  title?: string;
+}
+
+/**
+ * Records the empty return for ONE booking: tick the containers coming back,
+ * say where they landed, and every tick becomes an empty container return on
+ * that booking. Containers whose return is already recorded stay visible but
+ * cannot be ticked again. A legacy booking that never captured container
+ * numbers shows numberless slots — the number is typed here instead.
+ */
+function BookingEmptyReturnModal({
+  booking,
+  onClose,
+  onSubmit,
+  loading,
+  defaultReturnedBy,
+  defaultHandoverNote,
+  title = "Empty Container Return",
+}: BookingEmptyReturnModalProps) {
+  const [selected, setSelected] = useState<string[]>([]);
+  const [returnedBy, setReturnedBy] = useState<"EDR" | "CUSTOMER" | null>(null);
+  const [returnDate, setReturnDate] = useState<string>(localNowForInput());
+  const [warehouse, setWarehouse] = useState<string | null>(null);
+  const [yardId, setYardId] = useState<string | null>(null);
+  const [zoneId, setZoneId] = useState<string | null>(null);
+  const [condition, setCondition] = useState<string>("");
+  const [handoverNote, setHandoverNote] = useState<string>("");
+
+  const bookingId = booking?.bookingId ?? null;
+
+  // A fresh booking starts from a clean form — never inherit the last one's
+  // ticks, typed numbers, or placement.
+  useEffect(() => {
+    setSelected([]);
+    setReturnedBy(defaultReturnedBy ?? null);
+    setReturnDate(localNowForInput());
+    setWarehouse(null);
+    setYardId(null);
+    setZoneId(null);
+    setCondition("");
+    setHandoverNote(defaultHandoverNote ?? "");
+  }, [bookingId, defaultReturnedBy, defaultHandoverNote]);
+
+  const { data: warehousesResponse } = useQuery({
+    queryKey: ["warehouses-list"],
+    queryFn: async () => {
+      return await warehouseService.list({});
+    },
+  });
+
+  const warehouses = (warehousesResponse as any)?.data ?? warehousesResponse ?? [];
+  const { data: yards } = useWarehouseYards(warehouse ?? undefined);
+  const { data: zones } = useWarehouseZones(yardId ?? undefined);
+
+  useEffect(() => {
+    setYardId(null);
+    setZoneId(null);
+  }, [warehouse]);
+
+  useEffect(() => {
+    setZoneId(null);
+  }, [yardId]);
+
+  const warehouseOptions = Array.isArray(warehouses)
+    ? warehouses.map((wh: any) => ({
+        value: wh.id,
+        label: `${wh.name} ${wh.code ? `(${wh.code})` : ""}`,
+      }))
+    : [];
+
+  const yardOptions = (yards ?? [])
+    .filter((y) => y.status === "ACTIVE")
+    .map((y) => ({ value: y.id, label: `${y.name} (${y.code})` }));
+
+  const zoneOptions = (zones ?? [])
+    .filter((z) => z.status === "ACTIVE")
+    .map((z) => ({ value: z.id, label: `${z.name} (${z.code})` }));
+
+  const pending = (booking?.containers ?? []).filter((container) => !container.returnId);
+
+  const toggle = (key: string, checked: boolean) =>
+    setSelected((current) => (checked ? [...current, key] : current.filter((k) => k !== key)));
+
+  const handleSubmit = () => {
+    if (!booking || !selected.length || !warehouse || !returnedBy) return;
+
+    const selectedWarehouse = Array.isArray(warehouses)
+      ? warehouses.find((wh: any) => wh.id === warehouse)
+      : null;
+    const selectedYard = yards?.find((y) => y.id === yardId);
+    const selectedZone = zones?.find((z) => z.id === zoneId);
+
+    const containers = pending
+      .filter((container) => selected.includes(container.key))
+      .map((container) => ({
+        containerNumber: container.containerNumber,
+        // The booking records "20ft"/"40ft"; the wagon rule only needs the number.
+        containerSize: container.containerSize?.includes("40")
+          ? ("40" as const)
+          : container.containerSize?.includes("20")
+            ? ("20" as const)
+            : undefined,
+        returnDate,
+        warehouse: selectedWarehouse?.name || warehouse,
+        yard: selectedYard?.name,
+        zone: selectedZone?.name,
+        condition: condition || undefined,
+        handoverNote: handoverNote || undefined,
+      }));
+
+    onSubmit({
+      trucks: [
+        {
+          bookingId: booking.bookingId,
+          customerId: booking.customerId,
+          companyName: booking.companyName ?? undefined,
+          returnType: returnedBy,
+          containers,
+        },
+      ],
+    });
+  };
+
+  return (
+    <Modal opened={!!booking} onClose={onClose} title={title} size="lg">
+      {booking && (
+        <Stack gap="md">
+          <Group gap="sm">
+            <Text fw={600}>{booking.bookingReference}</Text>
+            {booking.companyName && <Text c="dimmed">{booking.companyName}</Text>}
+            <Badge size="sm" variant="light">
+              {booking.bookingStatus.replaceAll("_", " ")}
+            </Badge>
+          </Group>
+
+          <div>
+            <Group justify="space-between" mb="xs">
+              <Text size="sm" fw={600}>
+                Containers to return
+              </Text>
+              <Button
+                size="compact-xs"
+                variant="subtle"
+                onClick={() =>
+                  setSelected(
+                    selected.length === pending.length ? [] : pending.map((c) => c.key),
+                  )
+                }
+              >
+                {selected.length === pending.length ? "Clear all" : "Select all"}
+              </Button>
+            </Group>
+
+            <Table>
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th w={40} />
+                  <Table.Th>Container</Table.Th>
+                  <Table.Th w={90}>Size</Table.Th>
+                  <Table.Th w={150}>Status</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {booking.containers.map((container) => {
+                  const recorded = Boolean(container.returnId);
+                  return (
+                    <Table.Tr key={container.key}>
+                      <Table.Td>
+                        <Checkbox
+                          checked={selected.includes(container.key)}
+                          disabled={recorded}
+                          onChange={(e) => toggle(container.key, e.currentTarget.checked)}
+                        />
+                      </Table.Td>
+                      <Table.Td>
+                        <Text size="sm">{container.containerNumber}</Text>
+                      </Table.Td>
+                      <Table.Td>{container.containerSize ?? "—"}</Table.Td>
+                      <Table.Td>
+                        {recorded ? (
+                          <Badge size="sm" color="edr-green" variant="light">
+                            {(container.returnStatus &&
+                              RETURN_STATUS_LABEL[container.returnStatus]) ??
+                              "Recorded"}
+                          </Badge>
+                        ) : (
+                          <Badge size="sm" color="orange" variant="light">
+                            Awaiting return
+                          </Badge>
+                        )}
+                      </Table.Td>
+                    </Table.Tr>
+                  );
+                })}
+              </Table.Tbody>
+            </Table>
+          </div>
+
+          <Select
+            label="Returned By"
+            placeholder="Select truck type"
+            value={returnedBy}
+            onChange={(val) => setReturnedBy(val as "EDR" | "CUSTOMER" | null)}
+            data={[
+              { value: "EDR", label: "EDR Last Mile" },
+              { value: "CUSTOMER", label: "Customer Self-Haul" },
+            ]}
+            required
+          />
+
+          <Select
+            label="Return Warehouse"
+            placeholder="Select warehouse for container return"
+            value={warehouse}
+            onChange={setWarehouse}
+            data={warehouseOptions}
+            required
+            searchable
+          />
+
+          <Select
+            label="Yard"
+            placeholder={warehouse ? "Select yard" : "Select warehouse first"}
+            value={yardId}
+            onChange={setYardId}
+            data={yardOptions}
+            disabled={!warehouse}
+            searchable
+          />
+
+          <Select
+            label="Zone"
+            placeholder={yardId ? "Select zone" : "Select yard first"}
+            value={zoneId}
+            onChange={setZoneId}
+            data={zoneOptions}
+            disabled={!yardId}
+            searchable
+          />
+
+          <Input.Wrapper label="Returned Date & Time" required>
+            <input
+              type="datetime-local"
+              value={returnDate}
+              onChange={(e) => setReturnDate(e.target.value)}
+              style={{
+                padding: "8px",
+                borderRadius: "4px",
+                border: "1px solid #ced4da",
+                width: "100%",
+              }}
+              required
+            />
+          </Input.Wrapper>
+
+          <Textarea
+            label="Condition"
+            placeholder="Damage, residue, or cleanliness notes"
+            value={condition}
+            onChange={(e) => setCondition(e.currentTarget.value)}
+            rows={3}
+          />
+
+          <Textarea
+            label="Handover Note"
+            placeholder="Consignee, trucker, or authorization notes"
+            value={handoverNote}
+            onChange={(e) => setHandoverNote(e.currentTarget.value)}
+            rows={3}
+          />
+
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" onClick={onClose} disabled={loading}>
+              Cancel
+            </Button>
+            <Button
+              onClick={handleSubmit}
+              disabled={!selected.length || !warehouse || !returnedBy}
+              loading={loading}
+            >
+              Record Empty Return ({selected.length})
+            </Button>
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}
+
 interface StandaloneReturnModalProps {
   opened: boolean;
   onClose: () => void;
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/EmptyReturnRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/EmptyReturnRequestsPage.tsx
new file mode 100644
index 000000000..3c2b487df
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/EmptyReturnRequestsPage.tsx
@@ -0,0 +1,497 @@
+import { useEffect, useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  Alert,
+  Badge,
+  Button,
+  Card,
+  Divider,
+  Group,
+  Loader,
+  Modal,
+  NumberInput,
+  Select,
+  SimpleGrid,
+  Stack,
+  Text,
+  Textarea,
+} from "@mantine/core";
+import { DataTable, type ColumnDef } from "@edr/ui-common";
+
+import { useAuth } from "@/auth/useAuth";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import { PageContainer, PageHeader } from "@/components/page";
+import ListControls from "@/components/common/ListControls";
+import { extractErrorMessage } from "@/components/warehouses/options";
+import { useListControls } from "@/hooks/useListControls";
+import { useToast } from "@/hooks/use-toast";
+import { emptyReturnRequestsService } from "@/services/emptyReturnRequests.service";
+import type {
+  EmptyReturnRequest,
+  EmptyReturnRequestStatus,
+} from "@/types/importOperations";
+import { formatDateTime } from "@/lib/format";
+
+const STATUS_META: Record<EmptyReturnRequestStatus, { label: string; color: string }> = {
+  SUBMITTED: { label: "Awaiting review", color: "orange" },
+  APPROVED: { label: "Awaiting payment", color: "yellow" },
+  REJECTED: { label: "Rejected", color: "red" },
+  PAID: { label: "Paid — awaiting date", color: "blue" },
+  SCHEDULED: { label: "Scheduled", color: "edr-green" },
+  COMPLETED: { label: "Returned", color: "gray" },
+  CANCELLED: { label: "Cancelled", color: "gray" },
+};
+
+const money = (amount: number | null | undefined, currency: string | null | undefined) =>
+  amount == null
+    ? "—"
+    : `${Number(amount).toLocaleString(undefined, { minimumFractionDigits: 2 })} ${currency ?? ""}`.trim();
+
+/**
+ * The queue for customer-initiated empty container returns: a booking sold
+ * WITHOUT the return service, whose customer now wants to send the empties
+ * back. Staff price and approve — which invoices the customer — or reject with
+ * a reason. Everything after payment (date, truck) happens in the portal, and
+ * the containers themselves are recorded on Container Returns.
+ */
+export default function EmptyReturnRequestsPage() {
+  const { toast } = useToast();
+  const qc = useQueryClient();
+  const { user } = useAuth();
+  // Anyone who runs container returns can watch the queue; pricing and
+  // approving is its own permission, so show the buttons disabled rather than
+  // letting them fire into a 403.
+  const canReview = hasPermission(user, FREIGHT_PERMS.emptyReturnRequests.review);
+  const [statusFilter, setStatusFilter] = useState<string | null>(null);
+  const [approving, setApproving] = useState<EmptyReturnRequest | null>(null);
+  const [rejecting, setRejecting] = useState<EmptyReturnRequest | null>(null);
+
+  const requestsQuery = useQuery({
+    queryKey: ["empty-return-requests"],
+    queryFn: () => emptyReturnRequestsService.list(),
+  });
+
+  const requests = useMemo(() => {
+    const rows = requestsQuery.data ?? [];
+    return statusFilter ? rows.filter((row) => row.status === statusFilter) : rows;
+  }, [requestsQuery.data, statusFilter]);
+
+  const controls = useListControls(requests, {
+    dateKey: "submittedAt",
+    searchValue: (row) =>
+      `${row.bookingReference ?? ""} ${row.companyName ?? ""} ${row.containerNumbers.join(" ")}`,
+  });
+
+  const invalidate = () => {
+    qc.invalidateQueries({ queryKey: ["empty-return-requests"] });
+    qc.invalidateQueries({ queryKey: ["planned-empty-returns"] });
+  };
+
+  const approveMutation = useMutation({
+    mutationFn: ({ id, unitAmount }: { id: string; unitAmount?: number }) =>
+      emptyReturnRequestsService.approve(id, { unitAmount }),
+    onSuccess: () => {
+      toast({ title: "Approved — invoice sent to the customer" });
+      invalidate();
+      setApproving(null);
+    },
+    onError: (error: unknown) => {
+      toast({
+        variant: "destructive",
+        title: "Could not approve the request",
+        description: extractErrorMessage(error),
+      });
+    },
+  });
+
+  const rejectMutation = useMutation({
+    mutationFn: ({ id, reason }: { id: string; reason: string }) =>
+      emptyReturnRequestsService.reject(id, reason),
+    onSuccess: () => {
+      toast({ title: "Request rejected" });
+      invalidate();
+      setRejecting(null);
+    },
+    onError: (error: unknown) => {
+      toast({
+        variant: "destructive",
+        title: "Could not reject the request",
+        description: extractErrorMessage(error),
+      });
+    },
+  });
+
+  const columns: ColumnDef<EmptyReturnRequest>[] = [
+    {
+      id: "booking",
+      header: "Booking",
+      cell: ({ row }) => (
+        <Stack gap={2}>
+          <Text fw={600} size="sm">
+            {row.original.bookingReference ?? row.original.bookingId}
+          </Text>
+          <Text size="xs" c="dimmed">
+            {row.original.companyName ?? "—"}
+          </Text>
+        </Stack>
+      ),
+    },
+    {
+      id: "containers",
+      header: "Containers",
+      cell: ({ row }) => (
+        <Stack gap={2}>
+          <Badge size="sm">{row.original.containerCount}</Badge>
+          <Text size="xs" c="dimmed" lineClamp={2}>
+            {row.original.containerNumbers.join(", ")}
+          </Text>
+        </Stack>
+      ),
+    },
+    {
+      id: "submittedAt",
+      header: "Requested",
+      cell: ({ row }) => formatDateTime(row.original.submittedAt),
+    },
+    {
+      id: "price",
+      header: "Price",
+      cell: ({ row }) =>
+        row.original.quotedTotalAmount == null ? (
+          "—"
+        ) : (
+          <Stack gap={2}>
+            <Text size="sm" fw={600}>
+              {money(row.original.quotedTotalAmount, row.original.currency)}
+            </Text>
+            <Text size="xs" c="dimmed">
+              {money(row.original.quotedUnitAmount, row.original.currency)} × {row.original.containerCount}
+            </Text>
+          </Stack>
+        ),
+    },
+    {
+      id: "return",
+      header: "Return",
+      cell: ({ row }) =>
+        row.original.requestedReturnDate ? (
+          <Stack gap={2}>
+            <Text size="sm">{row.original.requestedReturnDate}</Text>
+            <Text size="xs" c="dimmed">
+              {row.original.truckPlateNumber ?? "—"}
+              {row.original.truckDriverName ? ` · ${row.original.truckDriverName}` : ""}
+            </Text>
+          </Stack>
+        ) : (
+          "—"
+        ),
+    },
+    {
+      id: "status",
+      header: "Status",
+      cell: ({ row }) => {
+        const meta = STATUS_META[row.original.status];
+        return (
+          <Stack gap={2}>
+            <Badge size="sm" color={meta?.color ?? "gray"} variant="light">
+              {meta?.label ?? row.original.status}
+            </Badge>
+            {row.original.rejectionReason && (
+              <Text size="xs" c="dimmed" lineClamp={2}>
+                {row.original.rejectionReason}
+              </Text>
+            )}
+          </Stack>
+        );
+      },
+    },
+    {
+      id: "action",
+      header: "Action",
+      cell: ({ row }) =>
+        row.original.status === "SUBMITTED" ? (
+          <Group gap="xs" justify="flex-end" wrap="nowrap">
+            <Button
+              size="xs"
+              variant="subtle"
+              color="red"
+              disabled={!canReview}
+              title={canReview ? undefined : "You do not have permission to review these requests"}
+              onClick={() => setRejecting(row.original)}
+            >
+              Reject
+            </Button>
+            <Button
+              size="xs"
+              variant="light"
+              disabled={!canReview}
+              title={canReview ? undefined : "You do not have permission to review these requests"}
+              onClick={() => setApproving(row.original)}
+            >
+              Approve
+            </Button>
+          </Group>
+        ) : (
+          <Text size="xs" c="dimmed" ta="right">
+            {row.original.status === "APPROVED" ? "Awaiting customer payment" : "No action"}
+          </Text>
+        ),
+    },
+  ];
+
+  const pending = (requestsQuery.data ?? []).filter((row) => row.status === "SUBMITTED").length;
+
+  return (
+    <PageContainer>
+      <PageHeader
+        title="Empty Return Requests"
+        subtitle="Customers asking to send empty containers back on bookings sold without equipment return"
+      />
+
+      <Card withBorder radius="lg" p="md">
+        <Stack gap="md">
+          <Group justify="space-between">
+            <Text fw={600}>
+              Requests
+              {pending > 0 && (
+                <Badge ml="sm" color="orange" variant="light">
+                  {pending} awaiting review
+                </Badge>
+              )}
+            </Text>
+          </Group>
+
+          <ListControls
+            search={controls.search}
+            onSearchChange={controls.setSearch}
+            searchPlaceholder="Search booking, company, container…"
+            dateFrom={controls.dateFrom}
+            onDateFromChange={controls.setDateFrom}
+            dateTo={controls.dateTo}
+            onDateToChange={controls.setDateTo}
+            dateLabel="Requested"
+            hasFilters={controls.hasFilters || Boolean(statusFilter)}
+            onReset={() => {
+              controls.reset();
+              setStatusFilter(null);
+            }}
+          >
+            <Select
+              placeholder="Status"
+              value={statusFilter}
+              onChange={setStatusFilter}
+              data={Object.entries(STATUS_META).map(([value, meta]) => ({
+                value,
+                label: meta.label,
+              }))}
+              clearable
+              w={220}
+            />
+          </ListControls>
+
+          {requestsQuery.isLoading ? (
+            <Group justify="center" py="lg">
+              <Loader size="sm" />
+            </Group>
+          ) : requestsQuery.isError ? (
+            <Alert color="red">
+              Could not load empty return requests. {extractErrorMessage(requestsQuery.error)}
+            </Alert>
+          ) : controls.pagedRows.length === 0 ? (
+            <Alert color="gray">No empty return requests.</Alert>
+          ) : (
+            <DataTable
+              columns={columns}
+              data={controls.pagedRows}
+              containerClassName="border-0 shadow-none"
+              {...controls.tableProps}
+            />
+          )}
+        </Stack>
+      </Card>
+
+      <ApproveModal
+        request={approving}
+        onClose={() => setApproving(null)}
+        onApprove={(unitAmount) =>
+          approving && approveMutation.mutate({ id: approving.id, unitAmount })
+        }
+        loading={approveMutation.isPending}
+      />
+
+      <Modal
+        opened={!!rejecting}
+        onClose={() => setRejecting(null)}
+        title="Reject empty return request"
+        size="md"
+      >
+        {rejecting && (
+          <RejectForm
+            request={rejecting}
+            loading={rejectMutation.isPending}
+            onCancel={() => setRejecting(null)}
+            onReject={(reason) => rejectMutation.mutate({ id: rejecting.id, reason })}
+          />
+        )}
+      </Modal>
+    </PageContainer>
+  );
+}
+
+/**
+ * The pricing step. The per-container price is prefilled from the booking's
+ * route WITH_RETURN rate; the reviewer can override it before approving, and
+ * approving is what issues the customer's invoice.
+ */
+function ApproveModal({
+  request,
+  onClose,
+  onApprove,
+  loading,
+}: {
+  request: EmptyReturnRequest | null;
+  onClose: () => void;
+  onApprove: (unitAmount?: number) => void;
+  loading: boolean;
+}) {
+  const [unitAmount, setUnitAmount] = useState<number | "">("");
+
+  const quoteQuery = useQuery({
+    queryKey: ["empty-return-quote", request?.bookingId],
+    queryFn: () => emptyReturnRequestsService.quote(request!.bookingId),
+    enabled: Boolean(request),
+  });
+
+  // Prefill from the route rate as soon as it lands, and start clean whenever
+  // a different request is opened.
+  useEffect(() => {
+    setUnitAmount(quoteQuery.data?.unitAmount ?? "");
+  }, [quoteQuery.data?.unitAmount, request?.id]);
+
+  const count = request?.containerCount ?? 0;
+  const total = typeof unitAmount === "number" ? unitAmount * count : null;
+  const currency = quoteQuery.data?.currency ?? "ETB";
+
+  return (
+    <Modal opened={!!request} onClose={onClose} title="Approve empty return" size="md">
+      {request && (
+        <Stack gap="md">
+          <Group gap="sm">
+            <Text fw={600}>{request.bookingReference ?? request.bookingId}</Text>
+            <Text c="dimmed">{request.companyName ?? "—"}</Text>
+          </Group>
+
+          <div>
+            <Text size="sm" fw={600} mb={4}>
+              Containers coming back
+            </Text>
+            <Text size="sm" c="dimmed">
+              {request.containerNumbers.join(", ")}
+            </Text>
+          </div>
+
+          {quoteQuery.isLoading ? (
+            <Group justify="center" py="sm">
+              <Loader size="sm" />
+            </Group>
+          ) : (
+            <>
+              {quoteQuery.data?.unavailableReason && (
+                <Alert color="yellow">{quoteQuery.data.unavailableReason}</Alert>
+              )}
+
+              <NumberInput
+                label={`Price per container (${currency})`}
+                description={
+                  quoteQuery.data?.sourceRateUsd
+                    ? `Contract route rate: ${quoteQuery.data.sourceRateUsd} USD per container`
+                    : "No route rate found — enter the amount to bill."
+                }
+                value={unitAmount}
+                onChange={(value) =>
+                  setUnitAmount(typeof value === "number" ? value : value === "" ? "" : Number(value))
+                }
+                min={0}
+                decimalScale={2}
+                thousandSeparator=","
+                required
+              />
+
+              <Divider />
+
+              <SimpleGrid cols={2}>
+                <Text size="sm" c="dimmed">
+                  {count} container{count === 1 ? "" : "s"} ×{" "}
+                  {typeof unitAmount === "number" ? unitAmount.toLocaleString() : "—"}
+                </Text>
+                <Text size="lg" fw={700} ta="right">
+                  {total == null
+                    ? "—"
+                    : `${total.toLocaleString(undefined, { minimumFractionDigits: 2 })} ${currency}`}
+                </Text>
+              </SimpleGrid>
+
+              <Text size="xs" c="dimmed">
+                Approving issues this invoice to the customer. They pay it in the portal, then
+                choose the return date and give the truck details.
+              </Text>
+            </>
+          )}
+
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" onClick={onClose} disabled={loading}>
+              Cancel
+            </Button>
+            <Button
+              onClick={() => onApprove(typeof unitAmount === "number" ? unitAmount : undefined)}
+              disabled={typeof unitAmount !== "number" || unitAmount <= 0}
+              loading={loading}
+            >
+              Approve &amp; invoice
+            </Button>
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}
+
+function RejectForm({
+  request,
+  loading,
+  onCancel,
+  onReject,
+}: {
+  request: EmptyReturnRequest;
+  loading: boolean;
+  onCancel: () => void;
+  onReject: (reason: string) => void;
+}) {
+  const [reason, setReason] = useState("");
+
+  return (
+    <Stack gap="md">
+      <Text size="sm">
+        {request.bookingReference ?? request.bookingId} — {request.containerCount} container
+        {request.containerCount === 1 ? "" : "s"}
+      </Text>
+      <Textarea
+        label="Reason"
+        description="Shown to the customer."
+        placeholder="Why this return cannot be accepted"
+        value={reason}
+        onChange={(event) => setReason(event.currentTarget.value)}
+        rows={3}
+        required
+      />
+      <Group justify="flex-end" gap="sm">
+        <Button variant="default" onClick={onCancel} disabled={loading}>
+          Cancel
+        </Button>
+        <Button color="red" onClick={() => onReject(reason.trim())} disabled={reason.trim().length < 3} loading={loading}>
+          Reject request
+        </Button>
+      </Group>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/IntercityPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/IntercityPage.tsx
index f756af834..11981f707 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/IntercityPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/IntercityPage.tsx
@@ -205,7 +205,7 @@ function Rows({ rows }: { rows: IntercityRideAlongRow[] }) {
               <Table.Td>
                 <Group gap="xs" justify="flex-end" wrap="nowrap">
                   {/* Work the cargo right here while the train is at the yard. */}
-                  {r.trainScheduleId && atOrigin(r) && isWaiting(r) && r.status === "PAID" && (
+                  {r.trainScheduleId && atOrigin(r) && isWaiting(r) && r.paymentStatus === "PAID" && (
                     <Tooltip label={canLoad ? undefined : "You don't have permission to load cargo"} disabled={canLoad}>
                       <Button
                         size="compact-xs"
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadingQueuePage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadingQueuePage.tsx
index a03c7038e..1ef38a944 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadingQueuePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadingQueuePage.tsx
@@ -18,7 +18,9 @@ import { api } from '@/services/api';
 import { useToast } from '@/hooks/use-toast';
 import type { WarehouseInventoryItem } from '@/types/warehouse';
 
-const isPaid = (item: WarehouseInventoryItem) => item.booking?.status === 'PAID';
+// "Paid" is the booking's PAYMENT status only — never booking.status === 'PAID'.
+const isPaid = (item: WarehouseInventoryItem) =>
+  (item.booking?.paymentStatus ?? item.bookingPaymentStatus) === 'PAID';
 
 /**
  * Loading Queue — manage inventory through the loading workflow.
diff --git a/apps/edr-freight-web/backoffice/src/record-management/components/positionSelection.tsx b/apps/edr-freight-web/backoffice/src/record-management/components/positionSelection.tsx
index b014425e5..6e904066a 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/components/positionSelection.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/components/positionSelection.tsx
@@ -18,6 +18,10 @@ import {
   TooltipTrigger,
 } from "@/shared/common/ui/tooltip";
 import { PositionName } from "../dto/delegation/delegationDto";
+import {
+  getPositionCookie,
+  setPositionCookie,
+} from "@/shared/utils/positionCookie";
 interface BasePosition {
   id: string;
   employeePositionId: string;
@@ -55,7 +59,7 @@ export const PositionSelect = () => {
     ? unFilteredUserDetails.employee.flatMap((emp) => emp?.positions ?? [])
     : [];
   const selectablePositions = allPositions ?? [];
-  const currentPositionCookie = Cookies.get("current-position-id");
+  const currentPositionCookie = getPositionCookie();
   const delegatedPositionCookie = Cookies.get("delegatedPositionId");
   const activePositionId =
     selectedPositionId || currentPositionCookie || delegatedPositionCookie;
@@ -85,15 +89,18 @@ export const PositionSelect = () => {
     // (useAuthUser already self-heals this cookie for the same reason.)
     if (
       currentPosition.employeePositionId &&
-      Cookies.get("current-position-id") !== currentPosition.employeePositionId
+      getPositionCookie() !== currentPosition.employeePositionId
     ) {
-      Cookies.set("current-position-id", currentPosition.employeePositionId);
+      setPositionCookie(currentPosition.employeePositionId);
     }
 
     applyDelegationCookie(currentPosition);
   }, [currentPosition, isLoading, selectedPositionId, setSelectedPositionId]);
 
-  if (isLoading || selectablePositions.length === 0) return null;
+  // Below two desks there is nothing to switch between. This now sits in the
+  // main freight header, so a one-option dropdown would show for every
+  // single-desk staff member.
+  if (isLoading || selectablePositions.length < 2) return null;
 
   const handleChange = (value: string) => {
     const selected = selectablePositions.find((pos) => pos.id === value);
@@ -102,7 +109,7 @@ export const PositionSelect = () => {
     // dropdown's own value is position.id, which the API does not match on.
     setSelectedPositionId(selected?.employeePositionId ?? value);
     if (selected?.employeePositionId) {
-      Cookies.set("current-position-id", selected.employeePositionId);
+      setPositionCookie(selected.employeePositionId);
     }
     applyDelegationCookie(selected);
 
diff --git a/apps/edr-freight-web/backoffice/src/record-management/services/api/signatureAndTeeterService.ts b/apps/edr-freight-web/backoffice/src/record-management/services/api/signatureAndTeeterService.ts
index bb9d8b274..cefeb94ef 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/services/api/signatureAndTeeterService.ts
+++ b/apps/edr-freight-web/backoffice/src/record-management/services/api/signatureAndTeeterService.ts
@@ -12,9 +12,11 @@ import {
 } from "@/record-management/dto/userRecords/teetersAndSignatureDto";
 import Cookies from "js-cookie";
 
+import { getPositionCookie } from "@/shared/utils/positionCookie";
+
 export const withHeaders = (passPosId: boolean = false) => {
   const unitId = Cookies.get("unit-id");
-  const positionId = Cookies.get("current-position-id");
+  const positionId = getPositionCookie();
   const projectId = Cookies.get("current-project-id");
   const delegatedPositionId = Cookies.get("delegatedPositionId");
 
diff --git a/apps/edr-freight-web/backoffice/src/record-management/services/api/withHeaders.tsx b/apps/edr-freight-web/backoffice/src/record-management/services/api/withHeaders.tsx
index b735ce611..e00325c24 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/services/api/withHeaders.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/services/api/withHeaders.tsx
@@ -1,9 +1,11 @@
 import Cookies from "js-cookie";
 
+import { getPositionCookie } from "@/shared/utils/positionCookie";
+
 export const withHeaders = () => {
   const tenantKey = Cookies.get("tenant-key");
   const unitId = Cookies.get("unit-id");
-  const positionId = Cookies.get("current-position-id");
+  const positionId = getPositionCookie();
   const projectId = Cookies.get("current-project-id");
   const delegatedPositionId = Cookies.get("delegatedPositionId");
   const headers: Record<string, string> = {};
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 855b3805a..c130c12a5 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -272,6 +272,7 @@ import {
   type BulkFulfillResult,
   type TransferHistory,
   type TransferRequestListFilter,
+  type WagonHistoryParams,
 } from "./wagon.service";
 import { warehouseService } from "./warehouse.service";
 
@@ -295,6 +296,11 @@ const INVENTORY_INVALIDATIONS: ReadonlyArray<readonly unknown[]> = [
 const TRAIN_SCHEDULING_INVALIDATIONS: ReadonlyArray<readonly unknown[]> = [
   QUERY_KEYS.TRAIN_SCHEDULING.ROOT,
   QUERY_KEYS.BOOKINGS.ROOT,
+  // A station's loading window gates the warehouse loading queues too — they
+  // render the same Start/End controls, so they must refresh on the same click.
+  ["loadable-trains"],
+  ["train-loadable-items"],
+  ["warehouse-inventory"],
 ];
 
 /**
@@ -993,13 +999,25 @@ export const api = {
     ),
 
     cancelRemainingWagons: endpoint<
-      { bookingId: string; scheduleId: string; reason: string; edrFault?: boolean },
+      {
+        bookingId: string;
+        scheduleId: string;
+        reason: string;
+        edrFault?: boolean;
+        /** Cut only these never-loaded wagons; omit for the whole remainder. */
+        wagonAllocationIds?: string[];
+      },
       unknown
     >(
       "train-scheduling",
       "cancel-remaining-wagons",
-      ({ bookingId, scheduleId, reason, edrFault }) =>
-        trainSchedulingService.cancelRemainingWagons(bookingId, { scheduleId, reason, edrFault }),
+      ({ bookingId, scheduleId, reason, edrFault, wagonAllocationIds }) =>
+        trainSchedulingService.cancelRemainingWagons(bookingId, {
+          scheduleId,
+          reason,
+          edrFault,
+          wagonAllocationIds,
+        }),
       undefined,
       () => TRAIN_SCHEDULING_INVALIDATIONS,
     ),
@@ -2179,6 +2197,22 @@ export const api = {
       ({ id }) => wagonService.getStatusHistory(id).then((r) => r.data),
       ({ id }) => ["wagons", "status-history", id],
     ),
+
+    /** One keyset page of the unified wagon history; page with `cursor`. */
+    history: endpoint<{ id: string } & WagonHistoryParams, Freight.WagonHistoryPage>(
+      "wagons",
+      "history",
+      ({ id, ...params }) => wagonService.getHistory(id, params).then((r) => r.data),
+      ({ id, category, types, cursor, limit }) => [
+        "wagons",
+        "history",
+        id,
+        category ?? null,
+        types?.join(",") ?? null,
+        cursor ?? null,
+        limit ?? null,
+      ],
+    ),
   },
 
   wagonTransferRequests: {
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index 4f2feeea3..f6f97db3f 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -810,6 +810,14 @@ export const bookingsService = {
     return ensurePdfBlob(response.data as Blob);
   },
 
+  /** The Wagons tab's Excel export — customer name plus one row per wagon. */
+  downloadWagonsWorkbook: async (id: string): Promise<Blob> => {
+    const response = await client.get(B.WAGONS_EXPORT(id), {
+      responseType: "blob",
+    });
+    return response.data as Blob;
+  },
+
   getDjClearanceQueue: async (): Promise<BookingDetail[]> => {
     const response = await client.get(B.CLEARANCE_DJ_QUEUE);
     return (unwrap(response.data) ?? []) as BookingDetail[];
diff --git a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
index 3d9152d11..c06e280dd 100644
--- a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
@@ -288,6 +288,13 @@ export const contractsService = {
   reject: (id: string, reason: string) =>
     postContract<Freight.IContract>(C.STAFF_REJECT(id), { reason }),
 
+  /**
+   * Cancel a contract outright. Terminal — unlike {@link suspend} there is no
+   * way back; a new contract with the same details must be submitted instead.
+   */
+  cancelByStaff: (id: string, reason: string) =>
+    postContract<Freight.IContract>(C.STAFF_CANCEL(id), { reason }),
+
   /** Freeze a signed contract. Reversible — see {@link resume}. */
   suspend: (id: string, reason: string) =>
     postContract<Freight.IContract>(C.SUSPEND(id), { reason }),
diff --git a/apps/edr-freight-web/backoffice/src/services/emptyReturnRequests.service.ts b/apps/edr-freight-web/backoffice/src/services/emptyReturnRequests.service.ts
new file mode 100644
index 000000000..a326fe023
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/emptyReturnRequests.service.ts
@@ -0,0 +1,62 @@
+import { api as client } from '../auth/http';
+import { URL_CONSTANTS } from '@/constants/URLS';
+import { unwrap } from '@/utils/endpoint';
+import type {
+  EmptyReturnQuote,
+  EmptyReturnRequest,
+  EmptyReturnRequestStatus,
+  PlannedEmptyReturn,
+} from '@/types/importOperations';
+
+/**
+ * Empty container return requests — the customer-initiated path for a booking
+ * that was sold WITHOUT the return service. Staff price and approve them here;
+ * the customer pays and books the truck from the portal.
+ */
+export const emptyReturnRequestsService = {
+  list: async (params: {
+    status?: EmptyReturnRequestStatus;
+    bookingId?: string;
+  } = {}): Promise<EmptyReturnRequest[]> => {
+    const response = await client.get<EmptyReturnRequest[]>(
+      URL_CONSTANTS.EMPTY_RETURN_REQUESTS.BASE,
+      { params },
+    );
+    return unwrap(response.data);
+  },
+
+  /** Scheduled returns the warehouse is expecting, with date and truck. */
+  planned: async (): Promise<PlannedEmptyReturn[]> => {
+    const response = await client.get<PlannedEmptyReturn[]>(
+      URL_CONSTANTS.EMPTY_RETURN_REQUESTS.PLANNED,
+    );
+    return unwrap(response.data);
+  },
+
+  /** The route price staff see prefilled at approval. */
+  quote: async (bookingId: string): Promise<EmptyReturnQuote> => {
+    const response = await client.get<{ quote: EmptyReturnQuote }>(
+      URL_CONSTANTS.EMPTY_RETURN_REQUESTS.ELIGIBILITY(bookingId),
+    );
+    return unwrap(response.data).quote;
+  },
+
+  approve: async (
+    id: string,
+    payload: { unitAmount?: number; currency?: string } = {},
+  ): Promise<EmptyReturnRequest> => {
+    const response = await client.post<EmptyReturnRequest>(
+      URL_CONSTANTS.EMPTY_RETURN_REQUESTS.APPROVE(id),
+      payload,
+    );
+    return unwrap(response.data);
+  },
+
+  reject: async (id: string, reason: string): Promise<EmptyReturnRequest> => {
+    const response = await client.post<EmptyReturnRequest>(
+      URL_CONSTANTS.EMPTY_RETURN_REQUESTS.REJECT(id),
+      { reason },
+    );
+    return unwrap(response.data);
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts b/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts
index 5911407d5..a2f13897b 100644
--- a/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts
@@ -8,6 +8,7 @@ import type {
   LoadEmptyContainersOnTrainPayload,
   DjiboutiIncident,
   EmptyContainerReturn,
+  EmptyReturnBooking,
   ImportCustomsFinalization,
   ImportOperationActionPayload,
   RecordDeclarationPayload,
@@ -114,6 +115,14 @@ export const importOperationsService = {
     return unwrap(response.data);
   },
 
+  /** Bookings that ship with empty-container return and still owe empties back. */
+  listEmptyReturnBookings: async (): Promise<EmptyReturnBooking[]> => {
+    const response = await client.get<EmptyReturnBooking[]>(
+      URL_CONSTANTS.IMPORT_OPERATIONS.EMPTY_RETURN_BOOKINGS,
+    );
+    return unwrap(response.data);
+  },
+
   createEmptyReturn: async (
     payload: CreateEmptyContainerReturnPayload,
   ): Promise<EmptyContainerReturn> => {
diff --git a/apps/edr-freight-web/backoffice/src/services/last-mile.service.ts b/apps/edr-freight-web/backoffice/src/services/last-mile.service.ts
index 4f7f2904a..7cd93f572 100644
--- a/apps/edr-freight-web/backoffice/src/services/last-mile.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/last-mile.service.ts
@@ -84,6 +84,12 @@ export interface LastMileRecord {
   }>;
   /** Present only when an invoice has actually been generated (not on distance). */
   invoice?: { id: string; number: string; status: string } | null;
+  /**
+   * The approved last-mile advance has not been paid yet. While true the API
+   * refuses to make this leg dispatchable or move it, so the UI must not offer
+   * those transitions.
+   */
+  advanceOutstanding?: boolean;
   /** Truck-detention clock: vehicle arrival + delivery/return times. */
   arrivedAt?: string | null;
   deliveredAt?: string | null;
diff --git a/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts b/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
index f983baf15..c14569d5a 100644
--- a/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
@@ -546,7 +546,12 @@ export const trainSchedulingService = {
 
   cancelRemainingWagons: async (
     bookingId: string,
-    payload: { scheduleId: string; reason: string; edrFault?: boolean },
+    payload: {
+      scheduleId: string;
+      reason: string;
+      edrFault?: boolean;
+      wagonAllocationIds?: string[];
+    },
   ): Promise<unknown> => {
     const response = await client.post(
       URL_CONSTANTS.TRAIN_SCHEDULING.CANCEL_REMAINING_WAGONS(bookingId),
diff --git a/apps/edr-freight-web/backoffice/src/services/transit-agents.service.ts b/apps/edr-freight-web/backoffice/src/services/transit-agents.service.ts
index bee743920..96687dc67 100644
--- a/apps/edr-freight-web/backoffice/src/services/transit-agents.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/transit-agents.service.ts
@@ -1,5 +1,6 @@
-import { api } from "../auth/http";
+import { api as apiClient } from "../auth/http";
 import { URL_CONSTANTS } from "../constants/URLS";
+import type { ResetChannel } from "../types/shippingLineCompany";
 
 export interface TransitAgent {
   id: string;
@@ -7,14 +8,53 @@ export interface TransitAgent {
   validFrom: string;
   validTo: string;
   isActive: boolean;
+  /** Null on every agent that exists only as a GL-assignable roster entry. */
+  email?: string | null;
+  phoneNumber?: string | null;
+  /** True once an IAM account backs the agent — i.e. it can sign in. */
+  hasAccount?: boolean;
+}
+
+export interface InviteTransitAgentDto {
+  email: string;
+  phoneNumber?: string;
+  username?: string;
+}
+
+/** What the API reports back about an activation send. */
+export interface ActivationSendResult {
+  maskedTarget: string;
+  channel: string;
+  expiresAt: string;
 }
 
 export const transitAgentsService = {
   /** Active + currently inside its validity window — the assignment dropdown. */
   async listAssignable() {
-    const response = await api.get<TransitAgent[]>(
+    const response = await apiClient.get<TransitAgent[]>(
       URL_CONSTANTS.RULE_ENGINE.TRANSIT_AGENTS_ASSIGNABLE,
     );
     return response.data;
   },
+
+  /**
+   * Create the portal account for an agent that has none and send its
+   * activation link. Separate from the rule-engine CRUD update because it mints
+   * an IAM user, which a field edit must never do implicitly.
+   */
+  async invite(id: string, dto: InviteTransitAgentDto) {
+    const response = await apiClient.post<{
+      agent: TransitAgent;
+      activationSentTo: string | null;
+    }>(URL_CONSTANTS.RULE_ENGINE.TRANSIT_AGENT_INVITE(id), dto);
+    return response.data;
+  },
+
+  async resendActivation(id: string, channel: ResetChannel) {
+    const response = await apiClient.post<ActivationSendResult>(
+      URL_CONSTANTS.RULE_ENGINE.TRANSIT_AGENT_RESEND_ACTIVATION(id),
+      { channel },
+    );
+    return response.data;
+  },
 };
diff --git a/apps/edr-freight-web/backoffice/src/services/wagon.service.ts b/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
index e484632e6..4dd17aca1 100644
--- a/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
@@ -154,8 +154,29 @@ export const wagonService = {
   /** Status audit trail for one wagon, newest first. */
   getStatusHistory: (id: string) =>
     apiClient.get<WagonStatusLog[]>(`/wagons/${id}/status-history`),
+  /**
+   * Unified history (yard moves, coupling, schedule pins/dispatch, status,
+   * cargo, lifecycle) — one keyset page, newest first. Pass the previous
+   * page's `nextCursor` to continue.
+   */
+  getHistory: (id: string, params: WagonHistoryParams = {}) => {
+    const qs = new URLSearchParams();
+    if (params.category) qs.set('category', params.category);
+    if (params.types?.length) qs.set('types', params.types.join(','));
+    if (params.cursor) qs.set('cursor', params.cursor);
+    if (params.limit) qs.set('limit', String(params.limit));
+    const q = qs.toString();
+    return apiClient.get<Freight.WagonHistoryPage>(`/wagons/${id}/history${q ? `?${q}` : ''}`);
+  },
 };
 
+export interface WagonHistoryParams {
+  category?: Freight.WagonEventCategory;
+  types?: Freight.WagonEventType[];
+  cursor?: string;
+  limit?: number;
+}
+
 /**
  * A two-person wagon-transfer request: a requester asks for N wagons of a type
  * to move between yards (count only); OCC hand-picks the wagons and fulfils it.
diff --git a/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts b/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts
index ad66776c3..98a8d59e4 100644
--- a/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/warehouse.service.ts
@@ -82,6 +82,7 @@ import type {
   WarehouseZone,
   ZoneContentItem,
 } from '@/types/warehouse';
+import type { StationWorkLog } from '@/types/trainScheduling';
 
 export type ContainerItemStage = 'PENDING' | 'RECEIVED' | 'GRN' | 'ASSIGNED' | 'LOADED' | 'LEFT' | 'DELIVERED';
 
@@ -115,6 +116,10 @@ export interface LoadableTrain {
   departureTime: string | null;
   readyCount: number;
   loadedCount: number;
+  /** freight.yards.id the train departs from. */
+  originStationId: string | null;
+  /** The schedule's per-yard loading/unloading windows — same store the train schedule page writes. */
+  stationWorkLogs: Record<string, StationWorkLog> | null;
 }
 
 /** A container/cargo inventory item assigned to a train, with its allocated wagon. */
@@ -132,6 +137,11 @@ export interface TrainLoadableItem {
   wagonId: string | null;
   wagonNumber: string | null;
   sequenceNo: number | null;
+  /** The booking's boarding yard — the yard whose loading window gates this item. */
+  originYardId: string | null;
+  originYardLabel: string | null;
+  /** True once "Start loading" was clicked for this item's boarding yard on this train. */
+  loadingWindowStarted: boolean;
   loadable: boolean;
 }
 
@@ -196,7 +206,7 @@ export const warehouseService = {
   /** A booking's containers with VGM cargo weight (tonnes) for exit weighing. */
   getContainerWeights: async (
     bookingId: string,
-  ): Promise<Array<{ containerNumber: string; weightTons: number }>> => {
+  ): Promise<Array<{ containerNumber: string; weightTons: number; containerSize: string | null }>> => {
     const { data } = await apiClient.get(
       `/warehouse-inventory/bookings/${bookingId}/container-weights`,
     );
@@ -225,9 +235,15 @@ export const warehouseService = {
   },
 
   // ── Load to Train ─────────────────────────────────────────────────────────
-  /** Pre-dispatch EXPORT trains with inventory waiting to be loaded. */
-  getLoadableTrains: async (): Promise<LoadableTrain[]> => {
-    const { data } = await apiClient.get('/warehouse-inventory/loadable-trains');
+  /**
+   * EXPORT trains with inventory waiting to be loaded. Pre-dispatch only by
+   * default; `includeDispatched` adds rolling trains still boarding cargo at
+   * corridor yards (what the train-centric loading workspace lists).
+   */
+  getLoadableTrains: async (opts: { includeDispatched?: boolean } = {}): Promise<LoadableTrain[]> => {
+    const { data } = await apiClient.get('/warehouse-inventory/loadable-trains', {
+      params: opts.includeDispatched ? { includeDispatched: 'true' } : undefined,
+    });
     return data?.data ?? data ?? [];
   },
 
diff --git a/apps/edr-freight-web/backoffice/src/shared/hooks/useAuthUser.ts b/apps/edr-freight-web/backoffice/src/shared/hooks/useAuthUser.ts
index af41dc2b7..bd589d51b 100644
--- a/apps/edr-freight-web/backoffice/src/shared/hooks/useAuthUser.ts
+++ b/apps/edr-freight-web/backoffice/src/shared/hooks/useAuthUser.ts
@@ -30,6 +30,10 @@ import {
   persistRememberMePreference,
   setAuthCookies,
 } from "@/shared/utils/authPersistence";
+import {
+  getPositionCookie,
+  setPositionCookie,
+} from "@/shared/utils/positionCookie";
 import { clearComplaintVerification } from "@/complaints/utils/complaintVerificationStorage";
 
 interface LoginPayload {
@@ -46,7 +50,7 @@ export const useAuthUser = () => {
   const { t } = useTranslation();
   const { handleError } = useErrorHandler(t);
   const delegatedPositionId = Cookies.get("delegatedPositionId");
-  const currentPositionId = Cookies.get("current-position-id");
+  const currentPositionId = getPositionCookie();
 
   const {
     setUser,
@@ -96,7 +100,7 @@ export const useAuthUser = () => {
         userDetails.employee?.[0]?.positions?.[0]?.employeePositionId;
       if (firstPositionId) {
         setSelectedPositionId(firstPositionId);
-        Cookies.set("current-position-id", firstPositionId, cookieOptions);
+        setPositionCookie(firstPositionId, cookieOptions);
       }
     }
 
@@ -141,7 +145,7 @@ export const useAuthUser = () => {
 
         if (fallbackId) {
           setSelectedPositionId(fallbackId);
-          Cookies.set("current-position-id", fallbackId);
+          setPositionCookie(fallbackId);
         }
       } else if (selectedPositionId) {
         // Self-heal stale cookies that were set to position.id instead of
@@ -157,10 +161,7 @@ export const useAuthUser = () => {
 
           if (matchingPosition?.employeePositionId) {
             setSelectedPositionId(matchingPosition.employeePositionId);
-            Cookies.set(
-              "current-position-id",
-              matchingPosition.employeePositionId,
-            );
+            setPositionCookie(matchingPosition.employeePositionId);
           }
         }
       }
diff --git a/apps/edr-freight-web/backoffice/src/shared/utils/faydaAuthSession.ts b/apps/edr-freight-web/backoffice/src/shared/utils/faydaAuthSession.ts
index 8200f6aba..8dce901b3 100644
--- a/apps/edr-freight-web/backoffice/src/shared/utils/faydaAuthSession.ts
+++ b/apps/edr-freight-web/backoffice/src/shared/utils/faydaAuthSession.ts
@@ -8,6 +8,7 @@ import {
   getAuthCookieOptions,
   setAuthCookies,
 } from "@/shared/utils/authPersistence";
+import { setPositionCookie } from "@/shared/utils/positionCookie";
 import type { VerifiedCitizen } from "@/complaints/types/complaint.types";
 
 function unwrapApiData<T>(payload: T | { data?: T }): T {
@@ -138,7 +139,7 @@ export async function persistFaydaRegistrationAuth(
     const firstPositionId =
       userDetails.employee?.[0]?.positions?.[0]?.employeePositionId;
     if (firstPositionId) {
-      Cookies.set("current-position-id", firstPositionId, cookieOptions);
+      setPositionCookie(firstPositionId, cookieOptions);
     }
 
     return userDetails;
diff --git a/apps/edr-freight-web/backoffice/src/shared/utils/positionCookie.ts b/apps/edr-freight-web/backoffice/src/shared/utils/positionCookie.ts
new file mode 100644
index 000000000..60c97c6ae
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/shared/utils/positionCookie.ts
@@ -0,0 +1,39 @@
+import Cookies from "js-cookie";
+
+type CookieOptions = NonNullable<Parameters<typeof Cookies.set>[2]>;
+
+/**
+ * Freight's own active-position cookie.
+ *
+ * Smart Office is a separate app on the same IAM and it also writes a cookie
+ * named `current-position-id` — but it stores `position.id` where freight
+ * stores `employeePositionId`. The two are not interchangeable, so on a shared
+ * domain each app's login silently overwrote the other's desk selection and the
+ * loser fell back to `positions[0]`. Freight keeps its own cookie name so both
+ * can hold a selection at once.
+ */
+export const POSITION_COOKIE = "freight-current-position-id";
+
+/**
+ * The pre-rename, shared-with-Smart-Office name. Still read so a session that
+ * is live across the deploy keeps its desk, and cleared on every write so the
+ * colliding cookie does not linger.
+ */
+const LEGACY_POSITION_COOKIE = "current-position-id";
+
+/** The active `employeePositionId`, or undefined when no desk is selected. */
+export const getPositionCookie = (): string | undefined =>
+  Cookies.get(POSITION_COOKIE) ?? Cookies.get(LEGACY_POSITION_COOKIE);
+
+export const setPositionCookie = (
+  value: string,
+  options?: CookieOptions,
+): void => {
+  Cookies.set(POSITION_COOKIE, value, options);
+  Cookies.remove(LEGACY_POSITION_COOKIE);
+};
+
+export const clearPositionCookie = (): void => {
+  Cookies.remove(POSITION_COOKIE);
+  Cookies.remove(LEGACY_POSITION_COOKIE);
+};
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index 287b41c83..d536734ef 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -201,6 +201,10 @@ export interface BookingDetail {
   cargoTotalWeightVgm: number;
   /** Break-bulk (PER_ITEM) only: real total tons — cargoTotalWeightVgm then holds the item count. */
   bulkTotalWeightTons?: number | null;
+  /** NUMBER_OF_WAGONS bulk only: the wagon count the customer booked. */
+  bulkRequestedWagons?: number | null;
+  /** NUMBER_OF_WAGONS bulk only: informational item count entered with the weight. */
+  bulkItemCount?: number | null;
   isHazardous: boolean;
   isReefer?: boolean;
   consolidationPartnerId?: string | null;
@@ -212,6 +216,14 @@ export interface BookingDetail {
   wagonsRequired?: number | null;
   scheduledAt?: string | null;
   trainScheduleId?: string | null;
+  /**
+   * The allocated train's departure date, attached by the LIST endpoint (the
+   * detail endpoint carries the fuller `trainScheduleSummary` instead). This is
+   * the operational date, as opposed to the customer-requested `scheduledDate`.
+   */
+  trainScheduleDepartureDate?: string | null;
+  /** The allocated train's reference (S-YYYY-NNNNN) or train number. */
+  trainScheduleReference?: string | null;
   /** Operational status of the allocated train (null until scheduled). */
   trainScheduleStatus?: string | null;
   /** The allocated train's identity + clock, attached by the detail endpoint. */
@@ -240,6 +252,12 @@ export interface BookingDetail {
   allDocsApproved?: boolean;
   /** ET clearance queue: a customer document is PENDING or QUERIED. */
   hasDocumentsAwaitingReview?: boolean;
+  /**
+   * ET clearance queue: id of an unspent wagon-cancellation credit on this
+   * booking (CREDIT_AVAILABLE, worth > 0, not yet rebooked). Null when there is
+   * none — GL rebooks the credit straight from the queue row.
+   */
+  rebookableCancellationId?: string | null;
   contractKind?: "ONE_TIME" | "GENERAL" | null;
   contractId?: string | null;
   /** Reference of the contract this booking was created under (list column + search). */
@@ -264,7 +282,9 @@ export interface BookingDetail {
   originYard?: BookingNamedRef;
   destinationYard?: BookingNamedRef;
   serviceType?: BookingNamedRef & { code?: string; includesCustoms?: boolean; includesFirstMile?: boolean; includesLastMile?: boolean };
-  cargoType?: BookingNamedRef;
+  cargoType?: BookingNamedRef & {
+    unitOfMeasure?: "PER_TON" | "PER_ITEM" | "NUMBER_OF_WAGONS" | null;
+  };
   shippingLine?: BookingNamedRef;
   bookingContainers?: BookingContainerLine[];
   reviewNotes?: BookingReviewNote[];
@@ -298,6 +318,10 @@ export interface BookingListRow {
   schedulingStatus?: string;
   serviceTypeLabel?: string;
   trainScheduleId?: string | null;
+  /** Departure date of the train this booking is allocated to; null until scheduled. */
+  trainScheduleDepartureDate?: string | null;
+  /** Reference of the train this booking is allocated to. */
+  trainScheduleReference?: string | null;
   isGovernment?: boolean;
   governmentInstitution?: string | null;
   consolidationPartnerId?: string | null;
diff --git a/apps/edr-freight-web/backoffice/src/types/importOperations.ts b/apps/edr-freight-web/backoffice/src/types/importOperations.ts
index b4a034bfb..42238d157 100644
--- a/apps/edr-freight-web/backoffice/src/types/importOperations.ts
+++ b/apps/edr-freight-web/backoffice/src/types/importOperations.ts
@@ -121,6 +121,33 @@ export interface EmptyContainerReturn {
 
 export type EmptyContainerSize = '20' | '40';
 
+/** One container a with-return booking owes back empty. */
+export interface EmptyReturnBookingContainer {
+  /** Stable row key — the booking container unit id. */
+  key: string;
+  unitId: string;
+  containerNumber: string;
+  containerSize: string | null;
+  containerType: string | null;
+  /** Set once this container's empty return has been recorded. */
+  returnId: string | null;
+  returnStatus: EmptyContainerReturnStatus | null;
+}
+
+/** A booking that ships with empty-container return and still owes empties. */
+export interface EmptyReturnBooking {
+  bookingId: string;
+  bookingReference: string;
+  bookingStatus: string;
+  equipmentReturn: string;
+  customerId: string | null;
+  companyName: string | null;
+  containers: EmptyReturnBookingContainer[];
+  expectedCount: number;
+  recordedCount: number;
+  pendingCount: number;
+}
+
 export interface CreateEmptyContainerReturnPayload {
   containerNumber: string;
   containerSize?: EmptyContainerSize;
@@ -152,3 +179,60 @@ export interface UpdateEmptyContainerReturnStatusPayload extends ImportOperation
   wagonAllocationReference?: string;
   handoverNote?: string;
 }
+
+export type EmptyReturnRequestStatus =
+  | 'SUBMITTED'
+  | 'APPROVED'
+  | 'REJECTED'
+  | 'PAID'
+  | 'SCHEDULED'
+  | 'COMPLETED'
+  | 'CANCELLED';
+
+/** A customer's request to send empties back on a booking sold without return. */
+export interface EmptyReturnRequest {
+  id: string;
+  bookingId: string;
+  bookingReference: string | null;
+  companyId: string | null;
+  companyName: string | null;
+  status: EmptyReturnRequestStatus;
+  containerNumbers: string[];
+  containerCount: number;
+  quotedUnitAmount: number | null;
+  quotedTotalAmount: number | null;
+  currency: string | null;
+  invoiceId: string | null;
+  paidAt: string | null;
+  requestedReturnDate: string | null;
+  truckPlateNumber: string | null;
+  truckDriverName: string | null;
+  truckType: string | null;
+  scheduledAt: string | null;
+  submittedAt: string;
+  reviewedAt: string | null;
+  rejectionReason: string | null;
+  completedAt: string | null;
+}
+
+/** Per-container price for an empty return, off the route's WITH_RETURN rate. */
+export interface EmptyReturnQuote {
+  unitAmount: number | null;
+  currency: string;
+  sourceRateUsd: number | null;
+  unavailableReason: string | null;
+}
+
+/** A scheduled empty return the warehouse is waiting on. */
+export interface PlannedEmptyReturn {
+  requestId: string;
+  bookingId: string;
+  bookingReference: string | null;
+  companyName: string | null;
+  companyId: string | null;
+  requestedReturnDate: string | null;
+  truckPlateNumber: string | null;
+  truckDriverName: string | null;
+  truckType: string | null;
+  containers: Array<{ containerNumber: string; returnId: string | null }>;
+}
diff --git a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
index 3536cddf9..3f5a0d0fe 100644
--- a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
+++ b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
@@ -192,6 +192,8 @@ export interface TrainScheduleListItem {
   createdAt?: string | null;
   scheduleDate: string;
   trainNumber?: string | null;
+  /** Voyage (sailing) number for THIS departure — the schedule's own, not the train's. */
+  voyageNumber?: string | null;
   /** Trade direction of this departure (IMPORT / EXPORT), when known. */
   direction?: string | null;
   routeName?: string | null;
@@ -766,6 +768,8 @@ export interface TrainScheduleDetail {
     /** Cargo only (VGM/bulk tons) — the booked weight without wagon tare. */
     cargoWeightTons?: number;
     status: string | null;
+    /** Payment status — the only signal that decides whether cargo may load. */
+    paymentStatus?: string | null;
     schedulingStatus?: SchedulingStatus | null;
     freightType?: FreightType | string | null;
     /** DOMESTIC = intercity ride-along; rides only its own leg below. */
@@ -1034,6 +1038,12 @@ export interface ReschedulePlan {
 export interface CreateTrainSchedulePayload {
   routeId: string;
   scheduleDate: string;
+  /**
+   * Voyage (sailing) number for this departure — required. The create dialog
+   * pre-fills it with the selected train's direction-matched run number; staff
+   * may override before submitting.
+   */
+  voyageNumber: string;
   /** Built train (Train Builder) to run this departure — its locomotives are used. */
   trainId?: string;
   /** Hand-picked locomotives (minimum 2 — front and back). Ignored when trainId is set. */
@@ -1145,6 +1155,8 @@ export interface IntercityBookingRow {
   id: string;
   reference: string | null;
   status: string;
+  /** Payment status — the only signal that decides whether cargo may load. */
+  paymentStatus?: string | null;
   freightType: FreightType | null;
   isGovernment: boolean;
   customer: string;
@@ -1246,10 +1258,24 @@ export interface BookingWagonRow {
   allocatedWeightTons: number | string | null;
   loadType: string | null;
   status: string;
+  /** Numeric columns arrive as strings from pg — parse before arithmetic. */
+  tareWeightTons?: number | string | null;
+  capacityTons?: number | string | null;
+  lengthMeters?: number | string | null;
+  /** The train this wagon rides on, and where it runs. */
+  trainNumber?: string | null;
+  departureAt?: string | null;
+  originStation?: string | null;
+  destinationStation?: string | null;
+  /** Set only when the wagon carries bulk rather than containers. */
+  bulkCargoDescription?: string | null;
+  bulkQuantity?: number | string | null;
   containers: Array<{
     containerNumber: string | null;
     sizeFt: number | null;
     grossWeightTons: number | string | null;
+    sealNumber?: string | null;
+    positionOnWagon?: number | null;
   }>;
 }
 
@@ -1265,6 +1291,8 @@ export interface IntercityRideAlongRow {
   bookingId: string;
   reference: string | null;
   status: string;
+  /** Payment status — the only signal that decides whether cargo may load. */
+  paymentStatus?: string | null;
   freightType: string | null;
   weightTons: number | null;
   loadedAt: string | null;
diff --git a/apps/edr-freight-web/backoffice/src/types/warehouse.ts b/apps/edr-freight-web/backoffice/src/types/warehouse.ts
index b17b728a9..47107ff9a 100644
--- a/apps/edr-freight-web/backoffice/src/types/warehouse.ts
+++ b/apps/edr-freight-web/backoffice/src/types/warehouse.ts
@@ -361,6 +361,8 @@ export interface WarehouseInventoryItem {
   /** Flat booking summary fields attached by the inventory list (attachBookingSummaries). */
   bookingReference?: string | null;
   bookingStatus?: string | null;
+  /** Payment status of the booking — the only signal that decides "paid". */
+  bookingPaymentStatus?: string | null;
   customerName?: string | null;
 }
 
@@ -575,6 +577,15 @@ export interface EligibleBooking {
   customerTruckType: string | null;
   customerTruckContainerNumber: string | null;
   customerTruckAssignedAt: string | null;
+  containerUnits: Array<{
+    containerNumber: string;
+    containerSize: string | null;
+    weightTons: number;
+    received: boolean;
+    grnNumber: string | null;
+  }>;
+  receivedContainerCount: number;
+  remainingContainerCount: number;
 }
 
 export interface BulkReceivePayload {
@@ -583,13 +594,23 @@ export interface BulkReceivePayload {
   yardId: string;
   zoneId: string;
   bookingIds: string[];
+  containerNumbers?: string[];
   truckEntrance?: TruckEntrancePayload;
 }
 
 export interface BulkReceiveResult {
   receivedCount: number;
   skippedCount: number;
-  results: { bookingId: string; status: string; inventoryId?: string; grnNumber?: string; reason?: string }[];
+  results: {
+    bookingId: string;
+    status: string;
+    inventoryId?: string;
+    inventoryIds?: string[];
+    grnNumber?: string;
+    receivedContainers?: number;
+    remainingContainers?: number;
+    reason?: string;
+  }[];
 }
 
 export interface TruckEntrancePayload {
diff --git a/apps/edr-freight-web/portal/src/App.tsx b/apps/edr-freight-web/portal/src/App.tsx
index 8ab2f60d1..5391fa150 100644
--- a/apps/edr-freight-web/portal/src/App.tsx
+++ b/apps/edr-freight-web/portal/src/App.tsx
@@ -3,6 +3,7 @@ import { useDisclosure } from "@mantine/hooks";
 import {
   Home,
   Layers,
+  LayoutDashboard,
   LifeBuoy,
   Loader2,
   // MapPin,
@@ -68,6 +69,11 @@ import {
   ShippingLineInvoicesPage,
   ShippingLineSettingsPage,
 } from "./pages/shipping-line";
+import {
+  TransitAgentBookingsPage,
+  TransitAgentBookingDetailPage,
+  TransitAgentOverviewPage,
+} from "./pages/transit-agent";
 import FaqPage from "./pages/support/FaqPage";
 import HelpPage from "./pages/support/HelpPage";
 import PrivacyPolicyPage from "./pages/support/PrivacyPolicyPage";
@@ -143,15 +149,15 @@ function isOnboardingAllowedPath(pathname: string): boolean {
  * captured, so there is nothing for them to onboard — they go straight to home.
  */
 function OnboardingGate() {
-  const { company, onboardingCompleted, isShippingLine } = useAuth();
+  const { company, onboardingCompleted, isShippingLine, isTransitAgent } =
+    useAuth();
   const location = useLocation();
 
-  // Keyed off a positive shipping-line identification, never off "no company":
-  // that is also true mid-fetch and on error, which would let customers slip
-  // past onboarding whenever the request failed.
-  const needsOnboarding = isShippingLine
-    ? false
-    : !company || !onboardingCompleted;
+  // Keyed off a positive shipping-line / transit-agent identification, never
+  // off "no company": that is also true mid-fetch and on error, which would let
+  // customers slip past onboarding whenever the request failed.
+  const needsOnboarding =
+    isShippingLine || isTransitAgent ? false : !company || !onboardingCompleted;
   const allowedHere = isOnboardingAllowedPath(location.pathname);
 
   // Open by default while onboarding is pending (covers the login case).
@@ -199,13 +205,14 @@ function OnboardingGate() {
  * contract/company-shaped page that has no meaning for it.
  */
 function RequireCustomer() {
-  const { isShippingLine, customerQuery } = useAuth();
+  const { isShippingLine, isTransitAgent, customerQuery } = useAuth();
 
   // RequireCompany already awaits this query, but guard anyway: a refetch can
   // flip `isPending` back on, and redirecting on a half-loaded account would
   // throw the user into the wrong app.
   if (customerQuery.isPending) return <FullScreenSpinner />;
   if (isShippingLine) return <Navigate to="/shipping-line" replace />;
+  if (isTransitAgent) return <Navigate to="/transit-agent" replace />;
   return <Outlet />;
 }
 
@@ -218,6 +225,15 @@ function RequireShippingLine() {
   return <Outlet />;
 }
 
+/** Transit-agent routes, closed to every other account kind. */
+function RequireTransitAgent() {
+  const { isTransitAgent, customerQuery } = useAuth();
+
+  if (customerQuery.isPending) return <FullScreenSpinner />;
+  if (!isTransitAgent) return <Navigate to="/portal" replace />;
+  return <Outlet />;
+}
+
 /**
  * Where a signed-in account belongs. Shipping lines and customers have separate
  * apps, so every "you're already logged in" redirect has to pick between them.
@@ -225,11 +241,15 @@ function RequireShippingLine() {
  * still in flight, which would land a shipping line on the customer home first.
  */
 function useHomeRoute(): { ready: boolean; href: string } {
-  const { isShippingLine, customerQuery } = useAuth();
+  const { isShippingLine, isTransitAgent, customerQuery } = useAuth();
 
   return {
     ready: !customerQuery.isPending,
-    href: isShippingLine ? "/shipping-line" : "/portal",
+    href: isShippingLine
+      ? "/shipping-line"
+      : isTransitAgent
+        ? "/transit-agent"
+        : "/portal",
   };
 }
 
@@ -326,6 +346,24 @@ const shippingLineSidebarItems: SidebarItem[] = [
   },
 ];
 
+/**
+ * Sidebar for transit agents. Two entries only — the rest of the portal
+ * (contracts, invoices, settings, support) is company-scoped and has no meaning
+ * for an agent, so nothing is filtered in from the other lists.
+ */
+const transitAgentSidebarItems: SidebarItem[] = [
+  {
+    label: "Overview",
+    href: "/transit-agent",
+    icon: <LayoutDashboard size={18} />,
+  },
+  {
+    label: "Bookings",
+    href: "/transit-agent/bookings",
+    icon: <Package size={18} />,
+  },
+];
+
 const App = () => {
   const navigate = useNavigate();
   const location = useLocation();
@@ -337,6 +375,7 @@ const App = () => {
     reapplyProfile,
     isAuthenticated,
     isShippingLine,
+    isTransitAgent,
   } = useAuth();
 
   // Attribute replays and exceptions to the signed-in user (id/org only).
@@ -478,6 +517,43 @@ const App = () => {
               </Route>
             )}
 
+            {/* Transit-agent app. Two pages, both empty for now, behind their
+              own layout — there is no support widget because the chat is
+              company-scoped and an agent has no company, exactly as for a
+              shipping line. */}
+            {isTransitAgent && (
+              <Route element={<RequireTransitAgent />}>
+                <Route
+                  element={
+                    <AppLayout
+                      title="EDR Freight"
+                      sidebarItems={transitAgentSidebarItems}
+                      activeHref={location.pathname}
+                      onNavigate={navigate}
+                      userName={displayName}
+                      userEmail={userEmail}
+                      showSupportWidget={false}
+                    >
+                      <Outlet />
+                    </AppLayout>
+                  }
+                >
+                  <Route
+                    path="/transit-agent"
+                    element={<TransitAgentOverviewPage />}
+                  />
+                  <Route
+                    path="/transit-agent/bookings"
+                    element={<TransitAgentBookingsPage />}
+                  />
+                  <Route
+                    path="/transit-agent/bookings/:id"
+                    element={<TransitAgentBookingDetailPage />}
+                  />
+                </Route>
+              </Route>
+            )}
+
             {/* Customer app — unchanged. */}
             <Route element={<RequireCustomer />}>
               <Route
diff --git a/apps/edr-freight-web/portal/src/components/contracts/PortalMultiFileDropzone.tsx b/apps/edr-freight-web/portal/src/components/contracts/PortalMultiFileDropzone.tsx
new file mode 100644
index 000000000..060b85e75
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/components/contracts/PortalMultiFileDropzone.tsx
@@ -0,0 +1,248 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  ActionIcon,
+  Box,
+  Group,
+  Stack,
+  Text,
+  ThemeIcon,
+  UnstyledButton,
+} from "@mantine/core";
+import { FileText, Plus, Trash2, UploadCloud } from "lucide-react";
+
+import { BORDER, GREEN, INK } from "@/pages/contracts/contract-ui";
+
+export interface PortalMultiFileDropzoneProps {
+  label: string;
+  description?: string;
+  files: File[];
+  onChange: (next: File[]) => void;
+  accept?: string;
+  disabled?: boolean;
+  /** Hint under the drop area, e.g. "PDF or image". */
+  acceptHint?: string;
+}
+
+export function formatBytes(bytes: number | null | undefined): string {
+  if (!bytes) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), sizes.length - 1);
+  return `${parseFloat((bytes / k ** i).toFixed(1))} ${sizes[i]}`;
+}
+
+function isImageFile(file: File): boolean {
+  if (file.type.startsWith("image/")) return true;
+  const ext = file.name.split(".").pop()?.toLowerCase() ?? "";
+  return ["png", "jpg", "jpeg", "webp", "gif", "bmp", "svg"].includes(ext);
+}
+
+/** Stable identity for a staged file — two picks of the same file dedupe. */
+const fileKey = (f: File) => `${f.name}:${f.size}:${f.lastModified}`;
+
+/**
+ * Multi-file counterpart of `PortalFileDropzone`: the same drop area, but the
+ * picker keeps a list. Picking again APPENDS (deduplicated by name+size+mtime),
+ * so an officer can gather documents across several picks before uploading.
+ */
+export function PortalMultiFileDropzone({
+  label,
+  description,
+  files,
+  onChange,
+  accept = "application/pdf,image/*",
+  disabled = false,
+  acceptHint = "PDF or image",
+}: PortalMultiFileDropzoneProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [dragOver, setDragOver] = useState(false);
+
+  // One object URL per staged image, revoked when the list changes.
+  const thumbs = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const f of files) {
+      if (isImageFile(f)) map.set(fileKey(f), URL.createObjectURL(f));
+    }
+    return map;
+  }, [files]);
+
+  useEffect(() => {
+    return () => {
+      for (const url of thumbs.values()) URL.revokeObjectURL(url);
+    };
+  }, [thumbs]);
+
+  const add = (incoming: File[]) => {
+    if (disabled || incoming.length === 0) return;
+    const seen = new Set(files.map(fileKey));
+    const next = [...files];
+    for (const f of incoming) {
+      const key = fileKey(f);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      next.push(f);
+    }
+    onChange(next);
+  };
+
+  const remove = (target: File) =>
+    onChange(files.filter((f) => fileKey(f) !== fileKey(target)));
+
+  const openPicker = () => {
+    if (disabled) return;
+    // Reset so re-picking the same file after removal still fires onChange.
+    if (inputRef.current) inputRef.current.value = "";
+    inputRef.current?.click();
+  };
+
+  const hasFiles = files.length > 0;
+
+  return (
+    <Stack gap={8}>
+      <Box>
+        <Text fz={13} fw={700} style={{ color: INK }}>
+          {label}
+        </Text>
+        {description ? (
+          <Text fz={12} c="dimmed" mt={2}>
+            {description}
+          </Text>
+        ) : null}
+      </Box>
+
+      <input
+        ref={inputRef}
+        type="file"
+        multiple
+        accept={accept}
+        hidden
+        disabled={disabled}
+        onChange={(e) => add(Array.from(e.target.files ?? []))}
+      />
+
+      <Box
+        onDragOver={(e) => {
+          e.preventDefault();
+          if (!disabled) setDragOver(true);
+        }}
+        onDragLeave={() => setDragOver(false)}
+        onDrop={(e) => {
+          e.preventDefault();
+          setDragOver(false);
+          add(Array.from(e.dataTransfer.files ?? []));
+        }}
+        onClick={openPicker}
+        style={{
+          borderRadius: 14,
+          border: `2px dashed ${dragOver ? GREEN : BORDER}`,
+          background: dragOver ? "#F2FBF6" : "#FAFCFE",
+          padding: hasFiles ? "16px 20px" : "28px 20px",
+          textAlign: "center",
+          cursor: disabled ? "not-allowed" : "pointer",
+          opacity: disabled ? 0.6 : 1,
+          transition: "border-color 120ms ease, background 120ms ease, padding 120ms ease",
+        }}
+      >
+        <Stack gap={8} align="center">
+          <ThemeIcon
+            variant="light"
+            color={dragOver ? "edr-green" : hasFiles ? "edr-green" : "gray"}
+            radius="xl"
+            size={hasFiles ? 40 : 48}
+          >
+            {hasFiles ? <Plus size={20} /> : <UploadCloud size={24} />}
+          </ThemeIcon>
+          <Box>
+            <Text fz={13} fw={600} style={{ color: INK }}>
+              {dragOver
+                ? "Drop to add"
+                : hasFiles
+                  ? "Add more files"
+                  : "Drag & drop your files here"}
+            </Text>
+            <Text fz={12} c="dimmed" mt={4}>
+              or <span style={{ color: GREEN, fontWeight: 700 }}>browse</span> —{" "}
+              {acceptHint}. Add as many as you need.
+            </Text>
+          </Box>
+        </Stack>
+      </Box>
+
+      {hasFiles ? (
+        <Stack gap={6}>
+          <Group justify="space-between" px={2}>
+            <Text fz={11} fw={700} c="edr-green" tt="uppercase">
+              {files.length} file{files.length === 1 ? "" : "s"} ready to upload
+            </Text>
+            <UnstyledButton
+              onClick={() => onChange([])}
+              disabled={disabled}
+              style={{ fontSize: 11.5, color: "#6B7C8E", fontWeight: 600 }}
+            >
+              Clear all
+            </UnstyledButton>
+          </Group>
+          {files.map((f) => {
+            const key = fileKey(f);
+            const thumb = thumbs.get(key);
+            return (
+              <Group
+                key={key}
+                gap={12}
+                wrap="nowrap"
+                p="xs"
+                style={{
+                  borderRadius: 12,
+                  border: `1px solid ${GREEN}`,
+                  background: "linear-gradient(135deg, #F2FBF6 0%, #fff 75%)",
+                  minWidth: 0,
+                }}
+              >
+                {thumb ? (
+                  <Box
+                    style={{
+                      width: 40,
+                      height: 40,
+                      flexShrink: 0,
+                      borderRadius: 8,
+                      overflow: "hidden",
+                      border: `1px solid ${BORDER}`,
+                    }}
+                  >
+                    <img
+                      src={thumb}
+                      alt=""
+                      style={{ width: "100%", height: "100%", objectFit: "cover" }}
+                    />
+                  </Box>
+                ) : (
+                  <ThemeIcon variant="light" color="edr-green" radius="md" size={40}>
+                    <FileText size={18} />
+                  </ThemeIcon>
+                )}
+                <Box style={{ minWidth: 0, flex: 1 }}>
+                  <Text fz={13} fw={600} style={{ color: INK }} truncate>
+                    {f.name}
+                  </Text>
+                  <Text fz={11} c="dimmed">
+                    {formatBytes(f.size)}
+                  </Text>
+                </Box>
+                <ActionIcon
+                  variant="subtle"
+                  color="red"
+                  radius="md"
+                  aria-label={`Remove ${f.name}`}
+                  onClick={() => remove(f)}
+                  disabled={disabled}
+                >
+                  <Trash2 size={15} />
+                </ActionIcon>
+              </Group>
+            );
+          })}
+        </Stack>
+      ) : null}
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/constants/URLS.ts b/apps/edr-freight-web/portal/src/constants/URLS.ts
index 6b6f701bb..28452704a 100644
--- a/apps/edr-freight-web/portal/src/constants/URLS.ts
+++ b/apps/edr-freight-web/portal/src/constants/URLS.ts
@@ -229,6 +229,13 @@ export const URL_CONSTANTS = {
     PUBLIC: "/api/support-content",
   },
 
+  EMPTY_RETURN_REQUESTS: {
+    BASE: "/api/empty-return-requests",
+    ELIGIBILITY: (bookingId: string) => `/api/empty-return-requests/eligibility/${bookingId}`,
+    BY_BOOKING: (bookingId: string) => `/api/empty-return-requests/by-booking/${bookingId}`,
+    SCHEDULE: (id: string) => `/api/empty-return-requests/${id}/schedule`,
+  },
+
   LAST_MILE_REQUESTS: {
     BY_BOOKING: (bookingId: string) => `/api/last-mile-requests/by-booking/${bookingId}`,
     BY_ID: (id: string) => `/api/last-mile-requests/${id}`,
diff --git a/apps/edr-freight-web/portal/src/hooks/useAuth.ts b/apps/edr-freight-web/portal/src/hooks/useAuth.ts
index 518d9dd35..e9ad1753c 100644
--- a/apps/edr-freight-web/portal/src/hooks/useAuth.ts
+++ b/apps/edr-freight-web/portal/src/hooks/useAuth.ts
@@ -6,6 +6,7 @@ import type {
 import {
   companiesService,
   isShippingLineAccount,
+  isTransitAgentAccount,
 } from "@/services/companies.service";
 import type {
   LoginPayload,
@@ -184,10 +185,21 @@ const useAuth = () => {
   const isShippingLine = isShippingLineAccount(accountInfo);
   const shippingLine = isShippingLine ? accountInfo : null;
 
-  // Every customer-shaped field below is null/empty for a shipping line.
-  const companyInfo = isShippingLine
-    ? null
-    : (accountInfo as CompanyInfoResponse | null);
+  /**
+   * Transit agents share the portal with customers and shipping lines but have
+   * no company, no external profile and no onboarding. Identified positively
+   * from the backend's discriminator, for the same reason as the shipping line
+   * above — never from "company is missing".
+   */
+  const isTransitAgent = isTransitAgentAccount(accountInfo);
+  const transitAgent = isTransitAgent ? accountInfo : null;
+
+  // Every customer-shaped field below is null/empty for a shipping line and for
+  // a transit agent alike.
+  const companyInfo =
+    isShippingLine || isTransitAgent
+      ? null
+      : (accountInfo as CompanyInfoResponse | null);
   const companyType = companyInfo?.company?.type ?? null;
   const companyStatus = companyInfo?.company?.status ?? null;
   // A company can create bookings only once an admin has approved it (active).
@@ -314,6 +326,8 @@ const useAuth = () => {
     onboardingStep,
     isShippingLine,
     shippingLine,
+    isTransitAgent,
+    transitAgent,
     createProfile,
     reapplyProfile,
     login,
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
index d6e07399f..44a09450c 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
@@ -17,6 +17,7 @@ import { useNavigate, useSearchParams } from "react-router-dom";
 
 import { useFileViewer } from "@/hooks/useFileViewer";
 import { bookingsService } from "@/services/bookings.service";
+import { lastMileRequestsService } from "@/services/last-mile-requests.service";
 import type { Freight } from "@edr/types";
 
 import { ApproveDeliveryButton } from "../delivery/ApproveDeliveryButton";
@@ -41,6 +42,7 @@ import {
 } from "./components/Notices";
 import { BookingPaymentPanel } from "./components/BookingPaymentPanel";
 import { AdditionalChargesPanel } from "./components/AdditionalChargesPanel";
+import { EmptyReturnRequestPanel } from "./components/EmptyReturnRequestPanel";
 import { HeaderButton, PageHeader } from "./components/PageHeader";
 import { PaymentMethodModal } from "./components/PaymentMethodModal";
 import { ScheduleCard } from "./components/ScheduleCard";
@@ -181,23 +183,70 @@ export function ReadonlyBookingView({
   // backend flag counts only unsigned SELF_HAUL handovers, so no status
   // heuristics are needed here.
   const canApproveDelivery = Boolean(booking.handoverAwaitingSignature);
+  // Delivery chosen on the contract only opens a last-mile request; EDR is
+  // committed to that leg once the request is approved (or a leg record
+  // exists). Until then the customer may still bring their own truck. Same
+  // rule as the API's `edrHaulsThisBooking`. Collection (the export leg) has
+  // no approval step, so the address alone decides it.
+  const hasLastMileChoice =
+    booking.tradeDirection !== "EXPORT" && !!booking.lastMileDeliveryAddress;
+  const lastMileRequests = useQuery({
+    queryKey: ["booking-last-mile-requests", booking.id],
+    queryFn: () => lastMileRequestsService.listForBooking(booking.id),
+    enabled: hasLastMileChoice,
+  });
+  const mileSummary = useQuery({
+    queryKey: ["booking-mile-summary", booking.id],
+    queryFn: () => bookingsService.mileSummary(booking.id),
+    enabled: hasLastMileChoice,
+  });
+  const lastMileCommitted =
+    hasLastMileChoice &&
+    ((lastMileRequests.data ?? []).some((r) => r.status === "APPROVED") ||
+      !!mileSummary.data?.lastMile);
+  const lastMileCheckPending =
+    hasLastMileChoice && (lastMileRequests.isPending || mileSummary.isPending);
   const usesCustomerTruck =
     booking.tradeDirection === "IMPORT"
-      ? !booking.lastMileDeliveryAddress
+      ? !lastMileCommitted
       : booking.tradeDirection === "EXPORT"
         ? !booking.firstMilePickupAddress
-        : !booking.firstMilePickupAddress && !booking.lastMileDeliveryAddress;
-  const canAssignCustomerTruck =
-    booking.paymentStatus === "PAID" &&
-    usesCustomerTruck &&
-    (booking.tradeDirection === "IMPORT"
-      ? // Import self-haul: pickup trucks are assigned only after the train has
-        // arrived at the destination.
-        status === "ARRIVED"
-      : // Export / domestic self-haul: delivery trucks are assigned only before
-        // the cargo is loaded onto the train (PAID / TRUCK_ASSIGNED). Once loaded
-        // (IN_TRANSIT and beyond) assignment is closed.
-        ["PAID", "TRUCK_ASSIGNED"].includes(status));
+        : !booking.firstMilePickupAddress && !lastMileCommitted;
+  // Why truck assignment is closed, or null when it is open. The card renders
+  // either way — a customer who opens Logistics and finds nothing there cannot
+  // tell a missing feature from a stage they have not reached yet.
+  const truckBlockedReason = (() => {
+    if (lastMileCheckPending) {
+      return "Checking whether EDR last-mile delivery has been approved for this booking…";
+    }
+    if (!usesCustomerTruck) {
+      return booking.tradeDirection !== "EXPORT" && lastMileCommitted
+        ? "EDR last-mile delivery for this booking has been approved, so no customer truck is needed."
+        : "EDR is handling first-mile pickup for this booking, so no customer truck is needed.";
+    }
+    if (booking.paymentStatus !== "PAID") {
+      return "Truck assignment opens once payment for this booking is confirmed.";
+    }
+    if (booking.tradeDirection === "IMPORT") {
+      // Import self-haul: pickup trucks are assigned only after the train has
+      // arrived at the destination.
+      return status === "ARRIVED" || booking.trainScheduleStatus === "ARRIVED"
+        ? null
+        : "Pickup trucks can be assigned once the train arrives at the destination.";
+    }
+    // Export / domestic self-haul: delivery trucks are assigned only before the
+    // cargo is loaded onto the train (PAID / TRUCK_ASSIGNED). Once loaded
+    // (IN_TRANSIT and beyond) assignment is closed.
+    return ["PAID", "TRUCK_ASSIGNED"].includes(status)
+      ? null
+      : "The cargo is already loaded onto the train — truck assignment is closed.";
+  })();
+  // The customer asked for EDR delivery and can still self-haul instead — say
+  // so, because assigning a truck here makes that pending request unapprovable.
+  const truckNotice =
+    !truckBlockedReason && hasLastMileChoice && !lastMileCommitted
+      ? "You requested EDR last-mile delivery for this booking, and it has not been approved yet. Assigning your own truck here replaces that request — it can no longer be approved once a truck is on the booking."
+      : null;
   const showCountdown = canPay && !!booking.paymentDeadline;
   const isExpired = status === "EXPIRED";
   // Customs (Path B) bookings are created AND rebooked by Global Logistics, not
@@ -415,6 +464,7 @@ export function ReadonlyBookingView({
                     showCountdown={showCountdown}
                   />
                   <AdditionalChargesPanel bookingId={booking.id} />
+                  <EmptyReturnRequestPanel bookingId={booking.id} />
                   <ScheduleCard
                     booking={booking}
                     title="Consignment & Schedule"
@@ -462,14 +512,16 @@ export function ReadonlyBookingView({
             <BodyGrid
               left={
                 <>
-                  <WarehouseLocationCard bookingId={booking.id} />
+                  {/* Truck assignment leads; where the cargo currently sits is
+                      supporting detail beneath it. */}
+                  <CustomerTruckAssignmentCard
+                    booking={booking}
+                    blockedReason={truckBlockedReason}
+                    notice={truckNotice}
+                    onAssigned={onBookingUpdated ?? (() => {})}
+                  />
 
-                  {canAssignCustomerTruck && (
-                    <CustomerTruckAssignmentCard
-                      booking={booking}
-                      onAssigned={onBookingUpdated ?? (() => {})}
-                    />
-                  )}
+                  <WarehouseLocationCard bookingId={booking.id} />
 
                   <MileSummaryCard booking={booking} />
                 </>
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/booking-detail-types.ts b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/booking-detail-types.ts
index 95bc57640..bbb3d8dbf 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/booking-detail-types.ts
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/booking-detail-types.ts
@@ -80,6 +80,8 @@ export type BookingDetail = Freight.IBooking & {
   /** The allocated train, present once the booking is placed on a schedule. */
   trainSchedule?: {
     trainNumber: string | null;
+    /** The schedule's own voyage (sailing) number for this departure. */
+    voyageNumber: string | null;
     reference: string | null;
     scheduledDepartureDate: string | null;
   } | null;
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BulkTruckUploadModal.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BulkTruckUploadModal.tsx
index eec8183af..4fa315fdf 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BulkTruckUploadModal.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BulkTruckUploadModal.tsx
@@ -1,131 +1,237 @@
-import { useState } from "react";
-import { Alert, Button, Group, Modal, Stack, Table, Text, FileInput, Badge } from "@mantine/core";
-import { Upload, Download, AlertCircle, CheckCircle, AlertTriangle } from "lucide-react";
-import { useMutation } from "@tanstack/react-query";
+import { useMemo, useRef, useState } from "react";
+import {
+  Alert,
+  Badge,
+  Button,
+  FileButton,
+  Group,
+  List,
+  Modal,
+  Stack,
+  Table,
+  Text,
+} from "@mantine/core";
+import { AlertCircle, AlertTriangle, CheckCircle, Download, Upload } from "lucide-react";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type { Freight } from "@edr/types";
 
 import { client } from "@/utils/api";
 import { URL_CONSTANTS } from "@/constants/URLS";
-import { generateTruckAssignmentTemplate, parseTruckAssignmentFile } from "@/utils/truck-assignment-template";
+import {
+  downloadTruckAssignmentTemplate,
+  parseTruckAssignmentFile,
+  truckTemplateContext,
+  type ParsedTruckFile,
+} from "@/utils/truck-assignment-template";
+
+import type { BookingDetail } from "../booking-detail-types";
+
+interface BulkTruckUploadResponse {
+  success: number;
+  failed: number;
+  errors: Array<{ index: number; row: number; truck: string; reason: string }>;
+}
 
 interface BulkTruckUploadModalProps {
   opened: boolean;
   onClose: () => void;
-  bookingId: string;
+  booking: BookingDetail;
+  trucks: Freight.ICustomerTruck[];
   onSuccess?: () => void;
 }
 
+/** Long error lists are unreadable in a modal — show the first few and count the rest. */
+const MAX_LISTED_ERRORS = 8;
+
 export function BulkTruckUploadModal({
   opened,
   onClose,
-  bookingId,
+  booking,
+  trucks,
   onSuccess,
 }: BulkTruckUploadModalProps) {
-  const [file, setFile] = useState<File | null>(null);
-  const [parsed, setParsed] = useState<
-    Array<{
-      truckPlateNumber: string;
-      driverName: string;
-      truckType: string;
-      containerNumbers?: string[];
-    }>
-  >([]);
-  const [parseError, setParseError] = useState<string | null>(null);
+  const queryClient = useQueryClient();
+  // `resetRef` lets the customer re-pick a corrected file with the same name —
+  // without it the input's onChange never fires the second time.
+  const resetFile = useRef<() => void>(null);
+
+  const [fileName, setFileName] = useState<string | null>(null);
+  const [parsed, setParsed] = useState<ParsedTruckFile>({ rows: [], errors: [], rowNumbers: [] });
+  const [result, setResult] = useState<BulkTruckUploadResponse | null>(null);
+
+  const ctx = useMemo(() => truckTemplateContext(booking, trucks), [booking, trucks]);
+
+  const reset = () => {
+    resetFile.current?.();
+    setFileName(null);
+    setParsed({ rows: [], errors: [], rowNumbers: [] });
+    setResult(null);
+  };
 
   const uploadMutation = useMutation({
     mutationFn: async () => {
-      const { data } = await client.post(URL_CONSTANTS.BOOKINGS.CUSTOMER_TRUCKS_BULK(bookingId), {
-        trucks: parsed,
-      });
-      return data;
+      const { data } = await client.post<BulkTruckUploadResponse | { data: BulkTruckUploadResponse }>(
+        URL_CONSTANTS.BOOKINGS.CUSTOMER_TRUCKS_BULK(booking.id),
+        { trucks: parsed.rows },
+      );
+      return ("data" in data ? data.data : data) as BulkTruckUploadResponse;
     },
-    onSuccess: () => {
+    onSuccess: (response) => {
+      void queryClient.invalidateQueries({ queryKey: ["customer-trucks", booking.id] });
       onSuccess?.();
-      setFile(null);
-      setParsed([]);
-      onClose();
+      // Only a clean run closes. A partial failure has to be shown, or the
+      // customer walks away believing all their trucks were created.
+      if (response.failed === 0) {
+        reset();
+        onClose();
+        return;
+      }
+      setResult(response);
     },
   });
 
-  const handleFileSelect = async (selectedFile: File | null) => {
-    if (!selectedFile) {
-      setFile(null);
-      setParsed([]);
-      setParseError(null);
+  const handleFile = async (selected: File | null) => {
+    setResult(null);
+    if (!selected) {
+      reset();
       return;
     }
-
+    setFileName(selected.name);
     try {
-      setParseError(null);
-      const trucks = await parseTruckAssignmentFile(selectedFile);
-      setFile(selectedFile);
-      setParsed(trucks);
-    } catch (err: any) {
-      setParseError(err.message || "Failed to parse Excel file");
-      setFile(null);
-      setParsed([]);
+      setParsed(await parseTruckAssignmentFile(selected, ctx));
+    } catch (err) {
+      setParsed({
+        rows: [],
+        errors: [err instanceof Error ? err.message : "Could not read the file."],
+        rowNumbers: [],
+      });
     }
   };
 
-  const handleDownloadTemplate = () => {
-    generateTruckAssignmentTemplate("truck-assignments.xlsx");
-  };
+  const { rows, errors, rowNumbers } = parsed;
+  const listedErrors = errors.slice(0, MAX_LISTED_ERRORS);
+  const hiddenErrors = errors.length - listedErrors.length;
+
+  /** Map a server error back to the spreadsheet row the customer actually sees. */
+  const excelRowFor = (index: number, fallback: number) => rowNumbers[index] ?? fallback;
+
+  const columnLabel =
+    ctx.shape === "CONTAINER"
+      ? "Containers"
+      : ctx.shape === "PER_ITEM"
+        ? `Quantity (${ctx.itemNoun})`
+        : "Planned tons";
 
   return (
     <Modal
       opened={opened}
-      onClose={onClose}
-      title="Bulk Upload Truck Assignments"
+      onClose={() => {
+        reset();
+        onClose();
+      }}
+      title="Bulk upload truck assignments"
       size="lg"
       centered
     >
       <Stack gap="lg">
         <Alert icon={<AlertCircle size={16} />} color="blue">
-          Download template, fill with truck data, upload Excel file to bulk-create truck assignments.
+          Download the template for this booking, fill in one row per truck, then upload it.
+          {ctx.shape === "CONTAINER"
+            ? " It lists this booking's containers and their sizes."
+            : ctx.remainingTons != null
+              ? ` ${ctx.remainingTons} t are still to be hauled.`
+              : ""}
         </Alert>
 
         <Group>
           <Button
             leftSection={<Download size={16} />}
             variant="light"
-            onClick={handleDownloadTemplate}
+            onClick={() => downloadTruckAssignmentTemplate(ctx)}
           >
-            Download Template
+            Download template
           </Button>
+          <FileButton resetRef={resetFile} accept=".xlsx,.xls" onChange={handleFile}>
+            {(props) => (
+              <Button {...props} variant="default" leftSection={<Upload size={16} />}>
+                {fileName ?? "Choose Excel file"}
+              </Button>
+            )}
+          </FileButton>
         </Group>
 
-        <FileInput
-          label="Select Excel File"
-          placeholder="Choose .xlsx file"
-          accept=".xlsx,.xls"
-          value={file}
-          onChange={handleFileSelect}
-          leftSection={<Upload size={14} />}
-        />
-
-        {parseError && (
-          <Alert icon={<AlertTriangle size={16} />} color="red" title="Parse Error">
-            {parseError}
+        {errors.length > 0 && (
+          <Alert
+            icon={<AlertTriangle size={16} />}
+            color="red"
+            title="Import failed — fix the file and upload it again"
+          >
+            <List size="sm" spacing={4}>
+              {listedErrors.map((message) => (
+                <List.Item key={message}>{message}</List.Item>
+              ))}
+            </List>
+            {hiddenErrors > 0 && (
+              <Text size="sm" mt={6}>
+                …and {hiddenErrors} more.
+              </Text>
+            )}
           </Alert>
         )}
 
-        {parsed.length > 0 && (
+        {result && result.failed > 0 && (
+          <Alert
+            icon={<AlertTriangle size={16} />}
+            color="orange"
+            title={`${result.success} truck(s) added, ${result.failed} rejected`}
+          >
+            <Table verticalSpacing="xs" mt="xs">
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th>Row</Table.Th>
+                  <Table.Th>Plate</Table.Th>
+                  <Table.Th>Reason</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {result.errors.map((e) => (
+                  <Table.Tr key={`${e.index}-${e.truck}`}>
+                    <Table.Td>{excelRowFor(e.index, e.row)}</Table.Td>
+                    <Table.Td>{e.truck}</Table.Td>
+                    <Table.Td>
+                      <Text size="sm">{e.reason}</Text>
+                    </Table.Td>
+                  </Table.Tr>
+                ))}
+              </Table.Tbody>
+            </Table>
+          </Alert>
+        )}
+
+        {rows.length > 0 && (
           <>
             <div>
               <Text fw={600} mb="xs">
-                Preview ({parsed.length} trucks)
+                Preview ({rows.length} truck{rows.length !== 1 ? "s" : ""})
               </Text>
               <Table striped highlightOnHover verticalSpacing="xs">
                 <Table.Thead>
                   <Table.Tr>
-                    <Table.Th>Plate Number</Table.Th>
-                    <Table.Th>Driver Name</Table.Th>
-                    <Table.Th>Truck Type</Table.Th>
-                    <Table.Th>Containers</Table.Th>
+                    <Table.Th>Row</Table.Th>
+                    <Table.Th>Plate number</Table.Th>
+                    <Table.Th>Driver</Table.Th>
+                    <Table.Th>Truck type</Table.Th>
+                    <Table.Th>{columnLabel}</Table.Th>
                   </Table.Tr>
                 </Table.Thead>
                 <Table.Tbody>
-                  {parsed.map((truck, idx) => (
-                    <Table.Tr key={idx}>
+                  {rows.map((truck, idx) => (
+                    <Table.Tr key={`${truck.truckPlateNumber}-${idx}`}>
+                      <Table.Td>
+                        <Text size="sm" c="dimmed">
+                          {rowNumbers[idx]}
+                        </Text>
+                      </Table.Td>
                       <Table.Td>
                         <Text size="sm">{truck.truckPlateNumber}</Text>
                       </Table.Td>
@@ -136,18 +242,21 @@ export function BulkTruckUploadModal({
                         <Text size="sm">{truck.truckType}</Text>
                       </Table.Td>
                       <Table.Td>
-                        {truck.containerNumbers?.length ? (
+                        {ctx.shape === "CONTAINER" ? (
                           <Group gap="xs">
-                            {truck.containerNumbers.map((c) => (
+                            {(truck.containerNumbers ?? []).map((c) => (
                               <Badge key={c} size="sm">
                                 {c}
                               </Badge>
                             ))}
                           </Group>
-                        ) : (
-                          <Text size="sm" c="dimmed">
-                            —
+                        ) : ctx.shape === "PER_ITEM" ? (
+                          <Text size="sm">
+                            {truck.plannedQuantity}
+                            {truck.plannedTons ? ` · ${truck.plannedTons} t` : ""}
                           </Text>
+                        ) : (
+                          <Text size="sm">{truck.plannedTons} t</Text>
                         )}
                       </Table.Td>
                     </Table.Tr>
@@ -158,14 +267,14 @@ export function BulkTruckUploadModal({
 
             <Group justify="space-between">
               <Text size="sm" c="dimmed">
-                Ready to upload {parsed.length} truck(s)
+                Ready to upload {rows.length} truck{rows.length !== 1 ? "s" : ""}
               </Text>
               <Button
                 loading={uploadMutation.isPending}
                 onClick={() => uploadMutation.mutate()}
                 leftSection={<CheckCircle size={16} />}
               >
-                Upload Trucks
+                Upload trucks
               </Button>
             </Group>
           </>
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/CustomerTruckAssignmentCard.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/CustomerTruckAssignmentCard.tsx
index 7ec73c848..839b537dd 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/CustomerTruckAssignmentCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/CustomerTruckAssignmentCard.tsx
@@ -16,9 +16,20 @@ import {
   TextInput,
 } from "@mantine/core";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import type { Freight } from "@edr/types";
-import { CheckCircle2, Clock, Download, Pencil, Plus, Trash2, Truck, Upload } from "lucide-react";
-import { useState } from "react";
+import { CUSTOMER_TRUCK_TYPES, type Freight } from "@edr/types";
+import {
+  AlertTriangle,
+  CheckCircle2,
+  Clock,
+  Download,
+  Lock,
+  Pencil,
+  Plus,
+  Trash2,
+  Truck,
+  Upload,
+} from "lucide-react";
+import { useMemo, useState } from "react";
 import toast from "react-hot-toast";
 
 import { api } from "@/services/api";
@@ -26,9 +37,14 @@ import { customerTrucksService } from "@/services/customer-trucks.service";
 
 import { CardTitle, SectionCard } from "./layout";
 import { BulkTruckUploadModal } from "./BulkTruckUploadModal";
-import { generateTruckAssignmentTemplate } from "@/utils/truck-assignment-template";
+import type { BookingDetail } from "../booking-detail-types";
+import {
+  downloadTruckAssignmentTemplate,
+  isTwentyFoot,
+  truckTemplateContext,
+} from "@/utils/truck-assignment-template";
 
-const TRUCK_TYPES = ["Flatbed", "Container Chassis", "Lowboy", "Box Truck", "Tipper"];
+const TRUCK_TYPES = [...CUSTOMER_TRUCK_TYPES];
 
 // Waybill-style selectable copies (indexes 1-8 in the API catalog). The 2 gate
 // copies (Port Operations, Gate Security & Carrier) are always printed.
@@ -64,9 +80,19 @@ const errorMessage = (error: unknown, fallback: string) => {
 export function CustomerTruckAssignmentCard({
   booking,
   onAssigned,
+  blockedReason,
+  notice,
 }: {
-  booking: Freight.IBooking;
+  booking: BookingDetail;
   onAssigned: () => void;
+  /**
+   * Why assignment is closed right now, if it is. The card still renders — and
+   * still lists any trucks already assigned — with this shown in place of the
+   * form, rather than the whole card vanishing from the Logistics tab.
+   */
+  blockedReason?: string | null;
+  /** Something the customer should know before assigning — shown above the form when it is open. */
+  notice?: string | null;
 }) {
   const queryClient = useQueryClient();
   const trucksKey = ["customer-trucks", booking.id];
@@ -86,6 +112,12 @@ export function CustomerTruckAssignmentCard({
   const [error, setError] = useState<string | null>(null);
   const [bulkModalOpen, setBulkModalOpen] = useState(false);
 
+  // What this booking hauls: containers, loose tonnage (PER_TON), or counted
+  // items (PER_ITEM — machinery, RoRo vehicles). Drives the form, the Excel
+  // template and its parser from one place.
+  const ctx = useMemo(() => truckTemplateContext(booking, trucks), [booking, trucks]);
+  const isPerItem = ctx.shape === "PER_ITEM";
+
   // Container numbers on the booking that aren't already loaded onto a truck.
   const assignedNumbers = new Set(
     trucks.flatMap((t) => (t.containers ?? []).map((c) => c.containerNumber)),
@@ -94,9 +126,20 @@ export function CustomerTruckAssignmentCard({
   const editingOwn = new Set(
     (trucks.find((t) => t.id === editingId)?.containers ?? []).map((c) => c.containerNumber),
   );
-  const availableContainers = (booking.containerNumbers ?? []).filter(
+  const containerSizes = new Map(ctx.containers.map((c) => [c.number, c.size]));
+  const unassignedContainers = (booking.containerNumbers ?? []).filter(
     (n) => !assignedNumbers.has(n) || editingOwn.has(n),
   );
+  // A 40ft fills the truck. Once one is picked, or two 20ft are, nothing more
+  // may be added — the API rejects it either way, so don't offer the choice.
+  const pickedHas40ft = containers.some((n) => !isTwentyFoot(containerSizes.get(n) ?? ""));
+  const availableContainers = unassignedContainers.filter((n) => {
+    if (containers.includes(n)) return true;
+    if (pickedHas40ft) return false;
+    // Something is already picked and it's 20ft — only another 20ft may join it.
+    if (containers.length > 0) return isTwentyFoot(containerSizes.get(n) ?? "");
+    return true;
+  });
   // Containers on the booking not yet assigned to any truck (independent of edit).
   const pendingAssignmentCount = (booking.containerNumbers ?? []).filter(
     (n) => !assignedNumbers.has(n),
@@ -115,16 +158,12 @@ export function CustomerTruckAssignmentCard({
   };
 
   const startEdit = (t: Freight.ICustomerTruck) => {
-    const planned = t as Freight.ICustomerTruck & {
-      plannedTons?: number | string | null;
-      plannedQuantity?: number | null;
-    };
     setPlateNumber(t.plateNumber ?? "");
     setDriverName(t.driverName ?? "");
     setTruckType(t.truckType ?? "");
     setContainers((t.containers ?? []).map((c) => c.containerNumber));
-    setPlannedTons(planned.plannedTons != null ? Number(planned.plannedTons) : "");
-    setPlannedQty(planned.plannedQuantity != null ? Number(planned.plannedQuantity) : "");
+    setPlannedTons(t.plannedTons != null ? Number(t.plannedTons) : "");
+    setPlannedQty(t.plannedQuantity != null ? Number(t.plannedQuantity) : "");
     setEditingId(t.id);
     setError(null);
   };
@@ -187,7 +226,13 @@ export function CustomerTruckAssignmentCard({
       setError("Select 1 or 2 container numbers for this truck.");
       return;
     }
-    if (isBulk && plannedTons === "") {
+    // Counted cargo (machinery, RoRo vehicles) is committed by item count —
+    // tonnage is often unknown until the weighbridge, so it stays optional.
+    if (isBulk && isPerItem && plannedQty === "") {
+      setError(`Enter how many ${ctx.itemNoun} this truck will carry.`);
+      return;
+    }
+    if (isBulk && !isPerItem && plannedTons === "") {
       setError("Enter the tonnes this truck will haul.");
       return;
     }
@@ -204,25 +249,27 @@ export function CustomerTruckAssignmentCard({
             <CardTitle>External Truck Assignment</CardTitle>
           </Group>
           <Group gap={12}>
-            <Group gap="sm">
-              <Button
-                size="xs"
-                variant="default"
-                leftSection={<Download size={14} />}
-                onClick={() => generateTruckAssignmentTemplate("truck-assignments.xlsx")}
-              >
-                Download Template
-              </Button>
-              <Button
-                size="xs"
-                variant="light"
-                leftSection={<Upload size={14} />}
-                onClick={() => setBulkModalOpen(true)}
-              >
-                Bulk Upload
-              </Button>
-            </Group>
-            {pendingAssignmentCount > 0 && (
+            {!blockedReason && (
+              <Group gap="sm">
+                <Button
+                  size="xs"
+                  variant="default"
+                  leftSection={<Download size={14} />}
+                  onClick={() => downloadTruckAssignmentTemplate(ctx)}
+                >
+                  Download Template
+                </Button>
+                <Button
+                  size="xs"
+                  variant="light"
+                  leftSection={<Upload size={14} />}
+                  onClick={() => setBulkModalOpen(true)}
+                >
+                  Bulk Upload
+                </Button>
+              </Group>
+            )}
+            {!blockedReason && pendingAssignmentCount > 0 && (
               <Text size="sm" fw={600} c="#b45309">
                 {pendingAssignmentCount} container{pendingAssignmentCount !== 1 ? "s" : ""} pending assignment
               </Text>
@@ -306,6 +353,26 @@ export function CustomerTruckAssignmentCard({
           </Alert>
         )}
 
+        {/* Assignment is closed for now — say why, and keep the trucks above
+            visible rather than hiding the whole card. */}
+        {blockedReason ? (
+          <Alert color="gray" variant="light" icon={<Lock size={16} />}>
+            {blockedReason}
+          </Alert>
+        ) : (
+          <>
+        {notice && (
+          <Alert color="yellow" variant="light" icon={<AlertTriangle size={16} />}>
+            {notice}
+          </Alert>
+        )}
+        {!isBulk && (
+          <Alert color="blue" variant="light">
+            Truck capacity: assign either <b>1 x 40ft container</b> or up to{' '}
+            <b>2 x 20ft containers</b>. A 40ft container must travel alone.
+          </Alert>
+        )}
+
         {/* Add-truck form. Container bookings assign 1–2 containers per truck;
             bulk bookings just register the truck (no container picker). */}
         {isBulk || availableContainers.length > 0 ? (
@@ -337,34 +404,39 @@ export function CustomerTruckAssignmentCard({
                   description="20ft: up to 2 per truck · 40ft: 1 per truck"
                   required
                   placeholder="Select container numbers"
-                  data={availableContainers}
+                  data={availableContainers.map((n) => {
+                    const size = containerSizes.get(n);
+                    return { value: n, label: size ? `${n} · ${size}` : n };
+                  })}
                   value={containers}
                   onChange={setContainers}
-                  maxValues={2}
+                  maxValues={pickedHas40ft ? 1 : 2}
                   searchable
                   nothingFoundMessage="No unassigned containers"
                 />
               )}
               {isBulk && (
                 <NumberInput
-                  label="Tonnes to load"
+                  label={isPerItem ? "Tonnes to load (optional)" : "Tonnes to load"}
                   description={(() => {
                     const total = Number(booking.cargoTotalWeightVgm) || 0;
                     const assigned = trucks
                       .filter((t) => t.id !== editingId)
-                      .reduce((s, t) => {
-                        const x = t as Freight.ICustomerTruck & {
-                          netWeightTons?: number | string | null;
-                          plannedTons?: number | string | null;
-                        };
-                        return s + (Number(x.netWeightTons ?? x.plannedTons) || 0);
-                      }, 0);
+                      .reduce(
+                        (s, t) =>
+                          s +
+                          (Number(
+                            (t as Freight.ICustomerTruck & { netWeightTons?: number | string | null })
+                              .netWeightTons ?? t.plannedTons,
+                          ) || 0),
+                        0,
+                      );
                     const remaining = Math.max(0, Math.round((total - assigned) * 1000) / 1000);
                     return total > 0
                       ? `${assigned} t of ${total} t already on trucks · ${remaining} t remaining`
                       : "Tonnage this truck hauls";
                   })()}
-                  required
+                  required={!isPerItem}
                   min={0}
                   value={plannedTons}
                   onChange={(v) => setPlannedTons(v === "" ? "" : Number(v))}
@@ -372,9 +444,17 @@ export function CustomerTruckAssignmentCard({
               )}
               {isBulk && (
                 <NumberInput
-                  label="Items quantity (pcs)"
-                  description="Optional piece count on this truck"
+                  // Counted cargo commits by piece count; loose bulk records it
+                  // only as a note alongside the tonnage that actually bills.
+                  label={isPerItem ? `Number of ${ctx.itemNoun}` : "Items quantity (pcs)"}
+                  description={
+                    isPerItem
+                      ? `How many ${ctx.itemNoun} ride this truck`
+                      : "Optional piece count on this truck"
+                  }
+                  required={isPerItem}
                   min={0}
+                  allowDecimal={false}
                   value={plannedQty}
                   onChange={(v) => setPlannedQty(v === "" ? "" : Number(v))}
                 />
@@ -403,6 +483,8 @@ export function CustomerTruckAssignmentCard({
             </Text>
           )
         )}
+          </>
+        )}
 
         {trucks.length > 0 && (
           <Stack gap="xs">
@@ -457,7 +539,8 @@ export function CustomerTruckAssignmentCard({
       <BulkTruckUploadModal
         opened={bulkModalOpen}
         onClose={() => setBulkModalOpen(false)}
-        bookingId={booking.id}
+        booking={booking}
+        trucks={trucks}
         onSuccess={() => {
           queryClient.invalidateQueries({ queryKey: trucksKey });
           onAssigned();
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
index 46c19ea7a..25f601628 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
@@ -27,6 +27,25 @@ import { ClearanceUploadedDocumentsPanel } from "@/components/contracts/Clearanc
 
 import toast from "react-hot-toast";
 
+/**
+ * A `responseType: "blob"` request delivers its JSON error body as a Blob, so
+ * reading `error.message` gives "Request failed with status code 400" instead
+ * of the reason. Read the blob back before falling back.
+ */
+async function downloadErrorMessage(error: unknown, fallback: string): Promise<string> {
+  const data = (error as { response?: { data?: unknown } })?.response?.data;
+  if (data instanceof Blob) {
+    try {
+      const parsed = JSON.parse(await data.text()) as { message?: unknown };
+      if (parsed?.message) return String(parsed.message);
+    } catch {
+      /* not JSON — fall through */
+    }
+  }
+  return error instanceof Error ? error.message : fallback;
+}
+
+
 import { bookingsService } from "@/services/bookings.service";
 import type { EmptyContainerReturn } from "@/services/bookings.service";
 import { saveBlob } from "@/utils/download";
@@ -308,6 +327,25 @@ export function DocumentsTab({ booking }: { booking: Freight.IBooking }) {
 
   // One-click warehouse-document bundle: GRN + gate clearance + handover.
   const [bundleBusy, setBundleBusy] = useState(false);
+
+  // The carriage acceptance sheet is its own document, not warehouse paperwork:
+  // direct truck-to-train cargo never sees a warehouse, and this sheet IS its
+  // handover record. Hiding it inside the warehouse bundle made it unfindable.
+  const [casBusy, setCasBusy] = useState(false);
+  const downloadCarriageAcceptance = async () => {
+    setCasBusy(true);
+    const ref = booking.reference ?? booking.id;
+    try {
+      const blob = await bookingsService.downloadCarriageAcceptanceSheet(booking.id);
+      saveBlob(blob, `carriage-acceptance-${ref}.pdf`);
+    } catch (error) {
+      toast.error(
+        await downloadErrorMessage(error, "Carriage acceptance sheet is not available yet."),
+      );
+    } finally {
+      setCasBusy(false);
+    }
+  };
   const downloadWarehouseDocuments = async () => {
     setBundleBusy(true);
     const ref = booking.reference ?? booking.id;
@@ -654,6 +692,24 @@ export function DocumentsTab({ booking }: { booking: Freight.IBooking }) {
         </SectionCard>
       )}
 
+      {/* ── Carriage acceptance sheet (its own document) ────────────────── */}
+      <SectionCard>
+        <CardTitle>Carriage acceptance sheet</CardTitle>
+        <Text fz="12.5px" c="dimmed" mt={4} mb="sm">
+          The record of the cargo EDR has accepted for carriage, listing each wagon and the
+          containers on it, and marking which have been loaded.
+        </Text>
+        <Button
+          leftSection={<Download size={16} />}
+          color="edr-green"
+          variant="light"
+          loading={casBusy}
+          onClick={downloadCarriageAcceptance}
+        >
+          Download sheet
+        </Button>
+      </SectionCard>
+
       {/* ── Warehouse documents (one-click bundle) ──────────────────────── */}
       <SectionCard>
         <CardTitle>Warehouse documents</CardTitle>
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/EmptyReturnRequestPanel.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/EmptyReturnRequestPanel.tsx
new file mode 100644
index 000000000..e7d15af8f
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/EmptyReturnRequestPanel.tsx
@@ -0,0 +1,446 @@
+import { useState } from "react";
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Checkbox,
+  Group,
+  Select,
+  Stack,
+  Text,
+  TextInput,
+} from "@mantine/core";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Container as ContainerIcon, CreditCard } from "lucide-react";
+import toast from "react-hot-toast";
+
+import { useInvoicePayment } from "@/hooks/useInvoicePayment";
+import { ModalSafeWrapper } from "@/components/customer-actions/ModalSafeWrapper";
+import {
+  emptyReturnRequestsService,
+  type EmptyReturnRequest,
+  type EmptyReturnRequestStatus,
+} from "@/services/empty-return-requests.service";
+
+import { PaymentMethodModal } from "./PaymentMethodModal";
+import { CardTitle, SectionCard } from "./layout";
+
+const TRUCK_TYPES = ["Flatbed", "Container Chassis", "Lowboy", "Box Truck", "Tipper"];
+
+const STATUS_META: Record<EmptyReturnRequestStatus, { label: string; color: string }> = {
+  SUBMITTED: { label: "Awaiting EDR review", color: "#B07D14" },
+  APPROVED: { label: "Awaiting payment", color: "#B07D14" },
+  REJECTED: { label: "Rejected", color: "red" },
+  PAID: { label: "Paid — choose your date", color: "#1F6FEB" },
+  SCHEDULED: { label: "Scheduled", color: "#0A6F4D" },
+  COMPLETED: { label: "Returned", color: "#0A6F4D" },
+  CANCELLED: { label: "Cancelled", color: "#9AA8B5" },
+};
+
+const money = (amount: number | null, currency: string | null) =>
+  amount == null
+    ? "—"
+    : `${amount.toLocaleString(undefined, { minimumFractionDigits: 2 })} ${currency ?? "ETB"}`;
+
+const errorMessage = (error: unknown, fallback: string) => {
+  const data = (error as { response?: { data?: { message?: string | string[] } } })?.response?.data;
+  if (Array.isArray(data?.message)) return data.message.join(", ");
+  return data?.message ?? fallback;
+};
+
+/**
+ * Returning empties on a booking that did NOT buy the return service up front.
+ * The customer picks the containers off this booking; EDR prices and approves
+ * it; the customer pays here and then books the date and the truck that brings
+ * them in.
+ */
+export function EmptyReturnRequestPanel({ bookingId }: { bookingId: string }) {
+  const qc = useQueryClient();
+
+  const eligibilityQuery = useQuery({
+    queryKey: ["empty-return-eligibility", bookingId],
+    queryFn: () => emptyReturnRequestsService.eligibility(bookingId),
+  });
+
+  const requestsQuery = useQuery({
+    queryKey: ["empty-return-requests", bookingId],
+    queryFn: () => emptyReturnRequestsService.listForBooking(bookingId),
+  });
+
+  const requests = requestsQuery.data ?? [];
+  const live = requests.filter((r) => r.status !== "REJECTED" && r.status !== "CANCELLED");
+  const eligibility = eligibilityQuery.data;
+
+  const refresh = () => {
+    qc.invalidateQueries({ queryKey: ["empty-return-requests", bookingId] });
+    qc.invalidateQueries({ queryKey: ["empty-return-eligibility", bookingId] });
+  };
+
+  // Nothing to offer and nothing to show — stay out of the way entirely.
+  if (!eligibility?.eligible && requests.length === 0) return null;
+
+  return (
+    <SectionCard p={22}>
+      <CardTitle>Empty container return</CardTitle>
+
+      <Stack gap={14} mt={12}>
+        {live.map((request) => (
+          <RequestRow key={request.id} request={request} onChanged={refresh} />
+        ))}
+
+        {requests
+          .filter((r) => r.status === "REJECTED")
+          .map((request) => (
+            <Box key={request.id} p={12} style={{ borderRadius: 10, border: "1px solid #FDE2E1" }}>
+              <Group justify="space-between">
+                <Text fz="13px" fw={600} c="#10202F">
+                  {request.containerCount} container{request.containerCount === 1 ? "" : "s"}
+                </Text>
+                <Badge radius="sm" variant="light" color="red">
+                  Rejected
+                </Badge>
+              </Group>
+              {request.rejectionReason && (
+                <Text fz="12px" c="#9AA8B5" mt={4}>
+                  {request.rejectionReason}
+                </Text>
+              )}
+            </Box>
+          ))}
+
+        {eligibility?.eligible ? (
+          <NewRequestForm
+            bookingId={bookingId}
+            availableNumbers={eligibility.availableContainerNumbers}
+            unitAmount={eligibility.quote.unitAmount}
+            currency={eligibility.quote.currency}
+            onCreated={refresh}
+          />
+        ) : (
+          eligibility?.reason &&
+          live.length === 0 && (
+            <Text fz="12px" c="#9AA8B5">
+              {eligibility.reason}
+            </Text>
+          )
+        )}
+      </Stack>
+    </SectionCard>
+  );
+}
+
+/** One live request: what it costs, what it is waiting on, and the next step. */
+function RequestRow({
+  request,
+  onChanged,
+}: {
+  request: EmptyReturnRequest;
+  onChanged: () => void;
+}) {
+  const meta = STATUS_META[request.status];
+
+  return (
+    <Box p={14} style={{ borderRadius: 10, border: "1px solid #EEF2F6" }}>
+      <Group justify="space-between" align="flex-start" wrap="nowrap">
+        <Box style={{ minWidth: 0 }}>
+          <Group gap={6}>
+            <ContainerIcon size={13} color="#9AA8B5" />
+            <Text fz="13.5px" fw={700} c="#10202F">
+              {request.containerCount} empty container{request.containerCount === 1 ? "" : "s"}
+            </Text>
+          </Group>
+          <Text fz="12px" c="#9AA8B5" mt={2}>
+            {request.containerNumbers.join(", ")}
+          </Text>
+          {request.quotedTotalAmount != null && (
+            <Text fz="12px" c="#9AA8B5" mt={2}>
+              {money(request.quotedTotalAmount, request.currency)}
+              {request.quotedUnitAmount != null &&
+                ` · ${money(request.quotedUnitAmount, request.currency)} per container`}
+            </Text>
+          )}
+          {request.requestedReturnDate && (
+            <Text fz="12px" c="#9AA8B5" mt={2}>
+              Returning {request.requestedReturnDate} · truck {request.truckPlateNumber}
+            </Text>
+          )}
+        </Box>
+        <Badge
+          radius="sm"
+          variant="light"
+          styles={{ root: { backgroundColor: `${meta.color}22`, color: meta.color } }}
+        >
+          {meta.label}
+        </Badge>
+      </Group>
+
+      {request.status === "APPROVED" && request.invoiceId && (
+        <PayButton
+          invoiceId={request.invoiceId}
+          amount={request.quotedTotalAmount ?? 0}
+          currency={request.currency ?? "ETB"}
+        />
+      )}
+
+      {request.status === "PAID" && <ScheduleForm request={request} onScheduled={onChanged} />}
+    </Box>
+  );
+}
+
+function PayButton({
+  invoiceId,
+  amount,
+  currency,
+}: {
+  invoiceId: string;
+  amount: number;
+  currency: string;
+}) {
+  const [modalOpen, setModalOpen] = useState(false);
+  const flow = useInvoicePayment();
+
+  const close = () => {
+    if (!flow.processing) {
+      setModalOpen(false);
+      flow.reset();
+    }
+  };
+
+  return (
+    <ModalSafeWrapper>
+      <Button
+        mt={10}
+        size="xs"
+        radius="md"
+        fw={700}
+        color="edr-green"
+        leftSection={<CreditCard size={14} />}
+        onClick={(event) => {
+          event.stopPropagation();
+          setModalOpen(true);
+        }}
+      >
+        Pay now
+      </Button>
+      <PaymentMethodModal
+        opened={modalOpen}
+        onClose={close}
+        amountLabel={`${amount.toLocaleString(undefined, { minimumFractionDigits: 2 })} ${currency}`}
+        currency={currency}
+        processing={flow.processing}
+        error={flow.error}
+        otp={flow.otp}
+        bill={flow.bill}
+        onConfirm={(method, payerAccount) => flow.pay(invoiceId, method, payerAccount)}
+      />
+    </ModalSafeWrapper>
+  );
+}
+
+/** After payment: when the empties come back, and on whose truck. */
+function ScheduleForm({
+  request,
+  onScheduled,
+}: {
+  request: EmptyReturnRequest;
+  onScheduled: () => void;
+}) {
+  const [returnDate, setReturnDate] = useState("");
+  const [plate, setPlate] = useState("");
+  const [driver, setDriver] = useState("");
+  const [truckType, setTruckType] = useState<string | null>(null);
+
+  const mutation = useMutation({
+    mutationFn: () =>
+      emptyReturnRequestsService.schedule(request.id, {
+        returnDate,
+        truckPlateNumber: plate.trim(),
+        truckDriverName: driver.trim(),
+        truckType: truckType ?? undefined,
+      }),
+    onSuccess: () => {
+      toast.success("Return date and truck saved");
+      onScheduled();
+    },
+    onError: (error: unknown) => {
+      toast.error(errorMessage(error, "Could not save the return details"));
+    },
+  });
+
+  const ready = Boolean(returnDate && plate.trim() && driver.trim());
+
+  return (
+    <Stack gap={10} mt={12}>
+      <Text fz="12px" fw={600} c="#10202F">
+        Tell us when the containers are coming back
+      </Text>
+
+      <TextInput
+        size="xs"
+        type="date"
+        label="Return date"
+        value={returnDate}
+        onChange={(event) => setReturnDate(event.currentTarget.value)}
+        required
+      />
+      <TextInput
+        size="xs"
+        label="Truck plate"
+        placeholder="3-A12345"
+        value={plate}
+        onChange={(event) => setPlate(event.currentTarget.value.toUpperCase())}
+        required
+      />
+      <TextInput
+        size="xs"
+        label="Driver name"
+        value={driver}
+        onChange={(event) => setDriver(event.currentTarget.value)}
+        required
+      />
+      <Select
+        size="xs"
+        label="Truck type"
+        placeholder="Select"
+        data={TRUCK_TYPES}
+        value={truckType}
+        onChange={setTruckType}
+        clearable
+      />
+
+      <Button
+        size="xs"
+        radius="md"
+        fw={700}
+        color="edr-green"
+        disabled={!ready}
+        loading={mutation.isPending}
+        onClick={() => mutation.mutate()}
+      >
+        Confirm return details
+      </Button>
+    </Stack>
+  );
+}
+
+/**
+ * The booking's own containers, ticked. Only a container that came in on this
+ * booking can go back on it, so the customer picks from that list rather than
+ * typing numbers, and the count follows the ticks.
+ */
+function NewRequestForm({
+  bookingId,
+  availableNumbers,
+  unitAmount,
+  currency,
+  onCreated,
+}: {
+  bookingId: string;
+  availableNumbers: string[];
+  unitAmount: number | null;
+  currency: string;
+  onCreated: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [selected, setSelected] = useState<string[]>([]);
+
+  const mutation = useMutation({
+    mutationFn: () => emptyReturnRequestsService.create(bookingId, selected),
+    onSuccess: () => {
+      toast.success("Empty return requested — EDR will review and price it");
+      setOpen(false);
+      setSelected([]);
+      onCreated();
+    },
+    onError: (error: unknown) => {
+      toast.error(errorMessage(error, "Could not submit the request"));
+    },
+  });
+
+  if (!open) {
+    return (
+      <Stack gap={6}>
+        <Button
+          size="xs"
+          radius="md"
+          fw={700}
+          variant="light"
+          color="edr-green"
+          onClick={() => setOpen(true)}
+        >
+          Request empty return
+        </Button>
+        {unitAmount != null && (
+          <Text fz="11.5px" c="#9AA8B5">
+            {money(unitAmount, currency)} per container, payable after EDR approves.
+          </Text>
+        )}
+      </Stack>
+    );
+  }
+
+  return (
+    <Stack gap={10}>
+      <Group justify="space-between" align="center">
+        <Text fz="12px" fw={600} c="#10202F">
+          Select the containers you are returning
+        </Text>
+        <Button
+          size="compact-xs"
+          variant="subtle"
+          color="edr-green"
+          onClick={() =>
+            setSelected(selected.length === availableNumbers.length ? [] : [...availableNumbers])
+          }
+        >
+          {selected.length === availableNumbers.length ? "Clear all" : "Select all"}
+        </Button>
+      </Group>
+
+      <Stack gap={6}>
+        {availableNumbers.map((number) => (
+          <Checkbox
+            key={number}
+            size="xs"
+            label={number}
+            checked={selected.includes(number)}
+            onChange={(event) =>
+              setSelected((current) =>
+                event.currentTarget.checked
+                  ? [...current, number]
+                  : current.filter((value) => value !== number),
+              )
+            }
+          />
+        ))}
+      </Stack>
+
+      {unitAmount != null && selected.length > 0 && (
+        <Alert color="gray" p={10}>
+          <Text fz="12px">
+            Estimated {money(unitAmount * selected.length, currency)} for {selected.length} container
+            {selected.length === 1 ? "" : "s"}. EDR confirms the price when it approves your request.
+          </Text>
+        </Alert>
+      )}
+
+      <Group gap={8}>
+        <Button size="xs" variant="default" radius="md" onClick={() => setOpen(false)}>
+          Cancel
+        </Button>
+        <Button
+          size="xs"
+          radius="md"
+          fw={700}
+          color="edr-green"
+          disabled={selected.length === 0}
+          loading={mutation.isPending}
+          onClick={() => mutation.mutate()}
+        >
+          Submit request{selected.length > 0 ? ` (${selected.length})` : ""}
+        </Button>
+      </Group>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/ScheduleCard.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/ScheduleCard.tsx
index 0d8df5cee..2bbb34baf 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/ScheduleCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/ScheduleCard.tsx
@@ -106,12 +106,19 @@ export function ScheduleCard({
     value: <StatusPill status={booking.status as string} />,
   };
 
+  // The schedule's own voyage (sailing) number — shown once the booking has an
+  // assigned train that carries one.
+  const voyageRows: Row[] = schedule?.voyageNumber
+    ? [{ label: "Voyage number", value: schedule.voyageNumber }]
+    : [];
+
   const rows: Row[] = consignment
     ? [
         { label: "Consignment ID", value: booking.reference },
         { label: "Service", value: service },
         { label: "Equipment return", value: equipmentReturn },
         assignedTrain,
+        ...voyageRows,
         { label: "Scheduled", value: fmtDate(booking.scheduledDate) },
       ]
     : [
@@ -120,6 +127,7 @@ export function ScheduleCard({
         { label: "Equipment return", value: equipmentReturn },
         { label: "Proposed date", value: fmtDate(booking.scheduledDate) },
         assignedTrain,
+        ...voyageRows,
       ];
 
   return (
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
index 85c8dd615..56a4f3972 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
@@ -139,8 +139,17 @@ export function WagonCancellationCard({
   // rows this booking opened itself can be paid/withdrawn/rebooked from here.
   const rows = data?.items ?? [];
   const ownRows = rows.filter((r) => r.bookingId === booking.id);
-  const openRow = ownRows.find((r) => r.status === "FEE_PENDING");
-  const creditRow = ownRows.find((r) => r.status === "CREDIT_AVAILABLE");
+  // A cancellation owes its fee whenever a customer-fault fee is still
+  // unsettled. FEE_PENDING is the customer-requested flow (cut applies at
+  // payment); an AT-LOADING cut applies immediately and jumps straight to
+  // CREDIT_AVAILABLE with its invoice left open — so status alone would hide
+  // the fee and offer a "no further payment needed" rebook on money still owed.
+  const owesFee = (r: (typeof ownRows)[number]) =>
+    r.fault === "CUSTOMER" && Number(r.feeAmount ?? 0) > 0 && !r.feePaidAt;
+  const openRow = ownRows.find((r) => r.status === "FEE_PENDING" || owesFee(r));
+  const creditRow = ownRows.find(
+    (r) => r.status === "CREDIT_AVAILABLE" && !owesFee(r),
+  );
 
   const feePay = useFeeInvoicePayment(booking.id);
 
@@ -237,7 +246,14 @@ export function WagonCancellationCard({
       toast.error(apiErrorMessage(e, "Could not rebook the wagons. Please try again.")),
   });
 
-  if (!eligible) return null;
+  // Showing the card is NOT the same as allowing a new cut. A partial cancel at
+  // loading leaves the kept wagons to ride, so the booking moves on to
+  // IN_TRANSIT/ARRIVED/COMPLETED while its cancellation still owes a fee and
+  // holds a rebookable credit. Gating on PAID/CANCELLED hid exactly that case —
+  // the customer saw neither the cancelled wagons nor the fee they owe. Any
+  // booking that HAS cancellation rows keeps the card, whatever its status;
+  // `canRequest` still limits NEW cuts to a live PAID booking.
+  if (!eligible && !ownRows.length) return null;
   if (!canRequest && !ownRows.length) return null;
 
   return (
@@ -265,8 +281,10 @@ export function WagonCancellationCard({
               {fmtMoney(openRow.feeAmount, openRow.feeCurrency)}
             </Text>
             . The cancelled wagons have left the train. Pay the fee to unlock
-            the rebooking credit. The request cannot be withdrawn from here —
-            if it was a mistake, contact EDR staff.
+            the rebooking credit — the {Number(openRow.wagonsCancelled)} cancelled
+            wagon(s) can then be rebooked on a coming train day. The request
+            cannot be withdrawn from here — if it was a mistake, contact EDR
+            staff.
           </Alert>
           <Group gap={8}>
             <Button
@@ -293,7 +311,7 @@ export function WagonCancellationCard({
           {isCustoms || oddFt20Credit ? (
             <Text fz={13} c="#475569">
               {isCustoms
-                ? "This is a customs-cleared booking — Global Logistics will rebook the credit for you."
+                ? "This is a customs-cleared booking — Global Logistics (EDR staff) will rebook the credit for you on a coming train day. Contact them if you have a preferred date."
                 : "Your credit includes an odd 20ft container that must share a wagon with another booking — Global Logistics will rebook it for you and pair the wagon. Please contact EDR staff."}
             </Text>
           ) : (
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx
index 345028ad0..2dd880c7b 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx
@@ -235,9 +235,9 @@ function ConsistStrip({ wagons }: { wagons: BookingWagonAllocation[] }) {
             LOCO
           </Text>
         </Box>
-        {wagons.map((w) => (
+        {wagons.map((w, i) => (
           <Tooltip
-            key={w.sequenceNo}
+            key={w.allocationId ?? w.sequenceNo}
             label={`${w.wagonNumber ?? "Unassigned"} · ${w.wagonType ?? "—"} · ${
               STATUS_TONES[w.status]?.label ?? w.status
             }`}
@@ -257,7 +257,7 @@ function ConsistStrip({ wagons }: { wagons: BookingWagonAllocation[] }) {
               }}
             >
               <Text fz={10} fw={700} c="#6B7C8E">
-                W{w.sequenceNo}
+                W{i + 1}
               </Text>
               <Text fz={11.5} fw={800} c="#10202F" style={{ fontFamily: "monospace" }}>
                 {w.wagonNumber ?? "—"}
@@ -302,12 +302,21 @@ const th = { color: "#9AA8B5", fontSize: 11 } as const;
 
 function WagonCard({
   wagon,
+  displayNo,
   selectable,
   selected,
   shared,
   onToggle,
 }: {
   wagon: BookingWagonAllocation;
+  /**
+   * 1-based position in THIS booking's wagon list — what the customer sees.
+   * Deliberately not `sequenceNo`, which is the wagon's slot in the shared
+   * train set and so starts wherever the previous booking left off (and
+   * leaves holes when wagons are cancelled). Cancellation keys off
+   * `allocationId`, so this number is display-only.
+   */
+  displayNo: number;
   selectable?: boolean;
   selected?: boolean;
   /** Shared consolidation wagon — not selectable for cancellation. */
@@ -333,7 +342,7 @@ function WagonCard({
               checked={!!selected}
               onChange={onToggle}
               color="orange"
-              aria-label={`Select wagon ${wagon.sequenceNo} for cancellation`}
+              aria-label={`Select wagon ${displayNo} for cancellation`}
             />
           )}
           <Box
@@ -354,7 +363,7 @@ function WagonCard({
               WAGON
             </Text>
             <Text fz={15} fw={800} lh={1.2}>
-              {wagon.sequenceNo}
+              {displayNo}
             </Text>
           </Box>
           <Box>
@@ -727,7 +736,7 @@ export function WagonsTab({
       <CancelledWagonsSection rows={ownCancellations} />
 
       <SimpleGrid cols={{ base: 1, md: 2 }} spacing={24}>
-        {wagons.map((w) => {
+        {wagons.map((w, i) => {
           // The shared consolidation wagon carries this booking's lone 20ft —
           // its other half belongs to the partner booking, so it can never be
           // cancelled on its own (the server rejects it too).
@@ -740,6 +749,7 @@ export function WagonsTab({
             <WagonCard
               key={w.allocationId ?? w.sequenceNo}
               wagon={w}
+              displayNo={i + 1}
               shared={isSharedWagon}
               selectable={
                 canSelect &&
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
index e4c02608f..d892119a3 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
@@ -459,7 +459,15 @@ export default function BookingsListPage() {
   const creditByBooking = useMemo(() => {
     const m = new Map<string, WagonCancellation>();
     for (const r of myCancellations?.items ?? []) {
-      if (r.status === "CREDIT_AVAILABLE" && !m.has(r.bookingId)) m.set(r.bookingId, r);
+      // A customer-fault cut invoices a fee. An at-loading cut applies at once
+      // and opens the credit with that invoice still OPEN, so CREDIT_AVAILABLE
+      // alone never means the fee was settled — offering "Rebook" here would
+      // let the customer redeem the wagons without ever paying. Those rows fall
+      // through to the row's Pay button instead (the fee is on my-payables).
+      const owesFee =
+        r.fault === "CUSTOMER" && Number(r.feeAmount ?? 0) > 0 && !r.feePaidAt;
+      if (r.status === "CREDIT_AVAILABLE" && !owesFee && !m.has(r.bookingId))
+        m.set(r.bookingId, r);
     }
     return m;
   }, [myCancellations]);
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentPage.tsx
index 61d162035..9ce8d1cd3 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentPage.tsx
@@ -660,6 +660,21 @@ function NewShipmentBookingForm({
   // summary alert next to the submit button so the click never looks inert.
   const showValidationSummary =
     form.formState.isSubmitted && !form.formState.isValid;
+  // Export completion must lock onto a train. The button stays enabled (a
+  // disabled button with no explanation looks broken) — instead, once the
+  // customer tries to review, name the missing pick here in the always-visible
+  // footer, because the train picker itself is usually scrolled off-screen.
+  const requiresTrainPick =
+    contract.tradeDirection === "EXPORT" && Boolean(completeBookingId);
+  const watchedScheduledDate = form.watch("scheduledDate");
+  const watchedTrainId = form.watch("trainScheduleId");
+  const validationSummaryText = !requiresTrainPick
+    ? "Fix the highlighted fields to review the price."
+    : !watchedScheduledDate?.trim()
+      ? "Select a shipment day and a train to review the price."
+      : !watchedTrainId?.trim()
+        ? "Select a train for your shipment day to review the price."
+        : "Fix the highlighted fields to review the price.";
 
   const handleConfirm = () => {
     if (!pendingValues) return;
@@ -838,7 +853,7 @@ function NewShipmentBookingForm({
                       style={{ flexShrink: 0 }}
                     />
                     <Text fz={13} fw={500} c="#C0392B">
-                      Fix the highlighted fields to review the price.
+                      {validationSummaryText}
                     </Text>
                   </>
                 )}
@@ -2358,7 +2373,7 @@ function ContainerLineEditor({
                 render={({ field, fieldState }) => (
                   <TextInput
                     {...field}
-                    placeholder="e.g. SL-0099231"
+                    placeholder="e.g. SL0123456"
                     error={fieldState.error?.message}
                     radius={10}
                     styles={fieldStyles}
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/new-shipment-form/schema.ts b/apps/edr-freight-web/portal/src/pages/contracts/new-shipment-form/schema.ts
index 121346d06..9bd1afc2a 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/new-shipment-form/schema.ts
+++ b/apps/edr-freight-web/portal/src/pages/contracts/new-shipment-form/schema.ts
@@ -61,8 +61,11 @@ const containerUnitSchema = z.object({
       (v) => ISO_CONTAINER_NUMBER_REGEX.test(v.trim().toUpperCase()),
       "Enter a valid ISO container number (e.g. ABCD1234567).",
     ),
+  // Every physical container is sealed before it ships; the yard checks the
+  // seal against the booking, so it is required alongside number and VGM.
   sealNumber: z
     .string()
+    .default("")
     .refine((v) => v.trim().length > 0, "Seal number is required."),
   vgmTons: z
     .string()
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/new-shipment-form/seal-required.test.ts b/apps/edr-freight-web/portal/src/pages/contracts/new-shipment-form/seal-required.test.ts
new file mode 100644
index 000000000..b13cfebe2
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/contracts/new-shipment-form/seal-required.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { createShipmentFormSchema } from "./schema";
+
+const schema = createShipmentFormSchema({
+  isContainer: true,
+  isHazardous: false,
+  isReefer: false,
+  withReturnService: false,
+  requiresDate: true,
+});
+
+const unit = (overrides: Partial<{ sealNumber: string }> = {}) => ({
+  containerNumber: "MSCU1234567",
+  sealNumber: "SL0123456",
+  vgmTons: "24.5",
+  isHazardous: false,
+  isReefer: false,
+  isReturn: false,
+  ...overrides,
+});
+
+const values = (sealNumber: string) => ({
+  contractRouteId: "route-1",
+  scheduledDate: "2026-09-10",
+  paymentCurrency: "USD" as const,
+  containers: [
+    {
+      containerSize: "40ft" as const,
+      quantity: "1",
+      units: [unit({ sealNumber })],
+    },
+  ],
+});
+
+const sealIssue = (v: ReturnType<typeof values>) => {
+  const result = schema.safeParse(v);
+  return result.success
+    ? undefined
+    : result.error.issues.find((i) => i.path.at(-1) === "sealNumber");
+};
+
+describe("container unit seal number", () => {
+  it("rejects a missing seal number", () => {
+    expect(sealIssue(values(""))?.message).toBe("Seal number is required.");
+  });
+
+  it("rejects a whitespace-only seal number", () => {
+    expect(sealIssue(values("   "))?.message).toBe("Seal number is required.");
+  });
+
+  it("accepts a filled seal number", () => {
+    expect(sealIssue(values("SL0123456"))).toBeUndefined();
+  });
+});
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/ClearanceWorkflowFilesPanel.tsx b/apps/edr-freight-web/portal/src/pages/transit-agent/ClearanceWorkflowFilesPanel.tsx
new file mode 100644
index 000000000..a0e34a6ad
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/ClearanceWorkflowFilesPanel.tsx
@@ -0,0 +1,166 @@
+import {
+  Badge,
+  Box,
+  Button,
+  Card,
+  Group,
+  Paper,
+  Stack,
+  Text,
+  ThemeIcon,
+  Tooltip,
+} from "@mantine/core";
+import { Download, Eye, FileText } from "lucide-react";
+import type { Freight } from "@edr/types";
+import { isViewable } from "@edr/ui-common";
+
+import { fetchViewableFile } from "@/services/files.service";
+
+const CATEGORY_LABELS: Record<
+  Freight.ClearanceWorkflowFileCategory,
+  string
+> = {
+  declaration: "Declaration",
+  draft_declaration: "Draft declaration",
+  duty: "Duty & taxes",
+  transit: "Transit",
+  djibouti: "Djibouti",
+};
+
+const CATEGORY_ORDER: Freight.ClearanceWorkflowFileCategory[] = [
+  "draft_declaration",
+  "declaration",
+  "duty",
+  "transit",
+  "djibouti",
+];
+
+const OWNER_LABELS: Record<Freight.ClearanceWorkflowFileOwner, string> = {
+  customer: "Customer",
+  gl_et: "GL Ethiopia",
+  gl_dj: "GL Djibouti",
+};
+
+export interface ClearanceWorkflowFilesPanelProps {
+  files: Freight.ClearanceWorkflowFile[];
+  onView: (file: { name: string; url: string }) => void;
+  onDownload?: (file: { id: string; name: string }) => void;
+  title?: string;
+}
+
+export function ClearanceWorkflowFilesPanel({
+  files,
+  onView,
+  onDownload,
+  title = "Customs workflow documents",
+}: ClearanceWorkflowFilesPanelProps) {
+  if (files.length === 0) return null;
+
+  const grouped = CATEGORY_ORDER.map((category) => ({
+    category,
+    label: CATEGORY_LABELS[category],
+    items: files.filter((f) => f.category === category),
+  })).filter((g) => g.items.length > 0);
+
+  return (
+    <Card withBorder radius="md" p="md">
+      <Group gap={10} mb="sm" wrap="nowrap">
+        <ThemeIcon variant="light" color="edr-green" radius="md" size={32}>
+          <FileText size={16} />
+        </ThemeIcon>
+        <Text fw={600} fz={15}>
+          {title}
+        </Text>
+      </Group>
+      <Stack gap="md">
+        {grouped.map((group) => (
+          <Box key={group.category}>
+            <Text size="xs" fw={700} c="dimmed" tt="uppercase" mb={8}>
+              {group.label}
+            </Text>
+            <Stack gap={8}>
+              {group.items.map((item) => (
+                <WorkflowFileRow
+                  key={item.code}
+                  item={item}
+                  onView={onView}
+                  onDownload={onDownload}
+                />
+              ))}
+            </Stack>
+          </Box>
+        ))}
+      </Stack>
+    </Card>
+  );
+}
+
+function WorkflowFileRow({
+  item,
+  onView,
+  onDownload,
+}: {
+  item: Freight.ClearanceWorkflowFile;
+  onView: (file: { name: string; url: string }) => void;
+  onDownload?: (file: { id: string; name: string }) => void;
+}) {
+  const file = item.file;
+  if (!file) return null;
+
+  const canPreview = isViewable({ name: file.name, url: "" });
+
+  return (
+    <Paper withBorder radius="md" p="sm">
+      <Group justify="space-between" wrap="nowrap" align="center">
+        <Group gap={10} wrap="nowrap" style={{ minWidth: 0 }}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={36}>
+            <FileText size={17} />
+          </ThemeIcon>
+          <Box style={{ minWidth: 0 }}>
+            <Text size="sm" fw={600} truncate>
+              {item.label}
+            </Text>
+            <Group gap={6} wrap="nowrap" mt={2}>
+              <Badge size="xs" variant="light" color="gray" radius="sm" tt="none">
+                {OWNER_LABELS[item.uploadedBy]}
+              </Badge>
+              <Text size="xs" c="dimmed" truncate>
+                {file.name}
+              </Text>
+            </Group>
+          </Box>
+        </Group>
+        <Group gap={6} wrap="nowrap">
+          {canPreview ? (
+            <Tooltip label="Preview">
+              <Button
+                size="compact-xs"
+                variant="default"
+                radius="md"
+                leftSection={<Eye size={13} />}
+                onClick={() =>
+                  void fetchViewableFile(file.id, file.name).then(onView)
+                }
+              >
+                View
+              </Button>
+            </Tooltip>
+          ) : null}
+          {onDownload ? (
+            <Tooltip label="Download">
+              <Button
+                size="compact-xs"
+                variant="light"
+                radius="md"
+                leftSection={<Download size={13} />}
+                onClick={() => onDownload({ id: file.id, name: file.name })}
+              >
+                Download
+              </Button>
+            </Tooltip>
+          ) : null}
+        </Group>
+      </Group>
+    </Paper>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentBookingDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentBookingDetailPage.tsx
new file mode 100644
index 000000000..0808814cc
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentBookingDetailPage.tsx
@@ -0,0 +1,1188 @@
+import {
+  Alert,
+  Anchor,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Checkbox,
+  Grid,
+  Group,
+  Loader,
+  Modal,
+  Paper,
+  Stack,
+  Tabs,
+  Text,
+  TextInput,
+  ThemeIcon,
+  Timeline,
+  Title,
+  Tooltip,
+} from "@mantine/core";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  AlertCircle,
+  AlertTriangle,
+  ArrowLeft,
+  Building2,
+  CheckCircle2,
+  CircleDot,
+  ClipboardList,
+  Download,
+  Eye,
+  EyeOff,
+  FileText,
+  History,
+  MessageSquareWarning,
+  Send,
+  Ship,
+  Receipt,
+  Share2,
+  Train,
+  Upload,
+  UserCheck,
+} from "lucide-react";
+import { useNavigate, useParams } from "react-router-dom";
+import type { Freight } from "@edr/types";
+
+import { isViewable } from "@edr/ui-common";
+
+import { useFileViewer } from "@/hooks/useFileViewer";
+import {
+  downloadStoredFile,
+  fetchViewableFile,
+} from "@/services/files.service";
+import { ClearanceWorkflowFilesPanel } from "@/pages/transit-agent/ClearanceWorkflowFilesPanel";
+import { TransitClearanceActionPanel } from "@/pages/transit-agent/TransitClearanceActionPanel";
+import {
+  TransitExportDocumentsPanel,
+  TransitImportDocumentsPanel,
+} from "@/pages/transit-agent/TransitDocumentsPanel";
+import { transitAssignmentsService } from "@/services/transit-assignments.service";
+import { bookingsService } from "@/services/bookings.service";
+import { useState } from "react";
+import toast from "react-hot-toast";
+
+const BACK_TO = "/transit-agent/bookings";
+
+const prettyStatus = (s?: string | null) =>
+  (s ?? "")
+    .toLowerCase()
+    .replace(/_/g, " ")
+    .replace(/^\w/, (c) => c.toUpperCase());
+
+const formatDate = (value?: string | null): string =>
+  value ? new Date(value).toLocaleString() : "—";
+
+/** Minutes as "5h 30m" — the raw integer is unreadable in a grid. */
+function formatMinutes(minutes: number | null | undefined): string {
+  if (minutes == null) return "—";
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return hours ? `${hours}h ${rest}m` : `${rest}m`;
+}
+
+const STATUS_COLOR: Record<string, string> = {
+  NOT_STARTED: "gray",
+  IN_PROGRESS: "blue",
+  FINISHED: "edr-green",
+};
+
+/** Icon + color per action family; unknown actions fall back to a neutral dot. */
+function eventMeta(action: string): { icon: typeof Upload; color: string } {
+  if (
+    action === "DOC_APPROVED" ||
+    action.endsWith("_ACCEPTED") ||
+    action.endsWith("_FINALIZED") ||
+    action.endsWith("_CONFIRMED")
+  )
+    return { icon: CheckCircle2, color: "edr-green" };
+  if (
+    action === "DOC_QUERIED" ||
+    action.includes("CHANGE_REQUESTED") ||
+    action.includes("AMENDMENT")
+  )
+    return { icon: MessageSquareWarning, color: "red" };
+  if (action.startsWith("CHARGE_"))
+    return {
+      icon: Receipt,
+      color: action === "CHARGE_PAID" ? "edr-green" : "orange",
+    };
+  if (action.includes("TRANSIT_ASSIGNEE")) return { icon: UserCheck, color: "blue" };
+  if (action.includes("ORDER")) return { icon: Ship, color: "blue" };
+  if (action.includes("SENT")) return { icon: Send, color: "blue" };
+  if (action.includes("UPLOAD") || action.includes("SUBMITTED"))
+    return { icon: Upload, color: "blue" };
+  if (action.includes("DOC")) return { icon: FileText, color: "gray" };
+  return { icon: CircleDot, color: "gray" };
+}
+
+const ACTOR_BADGE: Record<
+  Freight.ClearanceHistoryEvent["actorType"],
+  { label: string; color: string }
+> = {
+  STAFF: { label: "Staff", color: "blue" },
+  CUSTOMER: { label: "Customer", color: "grape" },
+  SYSTEM: { label: "System", color: "gray" },
+};
+
+const SIDES: Record<
+  Freight.GlExchangeDocument["side"],
+  { label: string; color: string }
+> = {
+  ET: { label: "GL Ethiopia", color: "edr-green" },
+  DJ: { label: "GL Djibouti", color: "blue" },
+  TRANSIT: { label: "Transit agent", color: "grape" },
+};
+
+function formatBytes(bytes: number): string {
+  if (!bytes) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${parseFloat((bytes / 1024 ** i).toFixed(1))} ${units[i]}`;
+}
+
+const formatDateTime = (value?: string | null): string =>
+  value
+    ? new Date(value).toLocaleString("en-GB", {
+        day: "numeric",
+        month: "short",
+        year: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+      })
+    : "—";
+
+/** Review state → badge, matching the GL review section's scale. */
+const REVIEW_META: Record<string, { label: string; color: string }> = {
+  APPROVED: { label: "Approved", color: "edr-green" },
+  QUERIED: { label: "Queried", color: "red" },
+  PENDING: { label: "Pending review", color: "yellow" },
+};
+
+/**
+ * The customer's clearance documents — what the shipment was cleared on.
+ *
+ * Read-only here: approving and querying are GL Ethiopia's, and the agent's
+ * token would be refused. Every attached file is viewable and downloadable,
+ * which is the point of the panel for the officer handling the shipment.
+ */
+function CustomerDocumentsCard({
+  documents,
+  loading,
+  onView,
+}: {
+  documents: Freight.ClearanceDocument[];
+  loading: boolean;
+  onView: (file: { name: string; url: string }) => void;
+}) {
+  const attached = documents.filter((d) => d.file);
+
+  return (
+    <Card withBorder radius="md" p="md">
+      <Group gap={10} mb="sm" wrap="nowrap" justify="space-between">
+        <Group gap={10} wrap="nowrap">
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={32}>
+            <FileText size={16} />
+          </ThemeIcon>
+          <Text fw={600} fz={15}>
+            Customer documents
+          </Text>
+        </Group>
+        {attached.length > 0 ? (
+          <Badge size="sm" variant="light" color="gray" radius="sm">
+            {attached.length}
+          </Badge>
+        ) : null}
+      </Group>
+
+      {loading ? (
+        <Group py="lg" justify="center">
+          <Loader size="sm" color="edr-green" />
+        </Group>
+      ) : documents.length === 0 ? (
+        <Text fz={13} c="dimmed">
+          No customer documents on this shipment.
+        </Text>
+      ) : (
+        <Stack gap={8}>
+          {documents.map((doc) => {
+            const meta = doc.reviewStatus
+              ? REVIEW_META[doc.reviewStatus]
+              : null;
+            return (
+              <Paper key={`${doc.settingCode}:${doc.fileKey}`} withBorder radius="md" p="sm">
+                <Group justify="space-between" wrap="nowrap" align="flex-start" gap="sm">
+                  <Group gap={10} wrap="nowrap" align="flex-start" style={{ minWidth: 0 }}>
+                    <ThemeIcon
+                      variant="light"
+                      color={doc.file ? "edr-green" : "gray"}
+                      radius="md"
+                      size={36}
+                    >
+                      <FileText size={16} />
+                    </ThemeIcon>
+                    <Box style={{ minWidth: 0 }}>
+                      <Group gap={6} wrap="nowrap">
+                        <Text size="sm" fw={600} truncate>
+                          {doc.label}
+                        </Text>
+                        {doc.required ? (
+                          <Badge size="xs" variant="light" color="gray" radius="sm" tt="none">
+                            Required
+                          </Badge>
+                        ) : null}
+                        {meta ? (
+                          <Badge size="xs" variant="light" color={meta.color} radius="sm" tt="none">
+                            {meta.label}
+                          </Badge>
+                        ) : null}
+                      </Group>
+                      {doc.file ? (
+                        <Text size="xs" c="dimmed" mt={3} truncate>
+                          {doc.file.name}
+                          {doc.uploadedAt ? ` · ${formatDateTime(doc.uploadedAt)}` : ""}
+                        </Text>
+                      ) : (
+                        <Text size="xs" c="dimmed" mt={3}>
+                          Not uploaded yet
+                        </Text>
+                      )}
+                      {/* GL's query reason — the officer needs to know why a
+                          document was sent back, not just that it was. */}
+                      {doc.reviewStatus === "QUERIED" && doc.note ? (
+                        <Text fz="12px" c="red.8" mt={3}>
+                          {doc.note}
+                        </Text>
+                      ) : null}
+                    </Box>
+                  </Group>
+
+                  {doc.file ? (
+                    <Group gap={6} wrap="nowrap">
+                      {isViewable({ name: doc.file.name, url: "" }) ? (
+                        <Tooltip label="Preview">
+                          <Button
+                            size="compact-xs"
+                            variant="default"
+                            radius="md"
+                            leftSection={<Eye size={13} />}
+                            onClick={() =>
+                              void fetchViewableFile(
+                                doc.file!.id,
+                                doc.file!.name,
+                              ).then(onView)
+                            }
+                          >
+                            View
+                          </Button>
+                        </Tooltip>
+                      ) : null}
+                      <Tooltip label="Download">
+                        <Button
+                          size="compact-xs"
+                          variant="light"
+                          radius="md"
+                          leftSection={<Download size={13} />}
+                          onClick={() =>
+                            void downloadStoredFile(doc.file!.id, doc.file!.name)
+                          }
+                        >
+                          Download
+                        </Button>
+                      </Tooltip>
+                    </Group>
+                  ) : null}
+                </Group>
+              </Paper>
+            );
+          })}
+        </Stack>
+      )}
+    </Card>
+  );
+}
+
+/**
+ * Share a document into the GL Ethiopia ↔ GL Djibouti exchange.
+ *
+ * The API stamps the post as the TRANSIT side from the session, so the agent
+ * cannot post as either desk. `visibleToCustomer` additionally surfaces the
+ * document in the customer's own portal — off by default, since most transit
+ * paperwork is between the desks.
+ */
+function ShareExchangeModal({
+  opened,
+  bookingId,
+  onClose,
+  onShared,
+}: {
+  opened: boolean;
+  bookingId: string;
+  onClose: () => void;
+  onShared: () => void;
+}) {
+  const [file, setFile] = useState<File | null>(null);
+  const [title, setTitle] = useState("");
+  const [visibleToCustomer, setVisibleToCustomer] = useState(false);
+
+  const close = () => {
+    setFile(null);
+    setTitle("");
+    setVisibleToCustomer(false);
+    onClose();
+  };
+
+  const submit = useMutation({
+    mutationFn: () =>
+      transitAssignmentsService.shareExchangeDocument(bookingId, {
+        file: file!,
+        title,
+        visibleToCustomer,
+      }),
+    onSuccess: () => {
+      toast.success("Document shared with both GL desks");
+      onShared();
+      close();
+    },
+    onError: (e: unknown) =>
+      toast.error(e instanceof Error ? e.message : "Could not share document"),
+  });
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={close}
+      radius="md"
+      size="md"
+      title={
+        <Group gap={8}>
+          <Share2 size={18} />
+          <Text fw={700}>Share a document</Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          Both Global Logistics desks see this immediately. Only you can edit or
+          remove what you post.
+        </Text>
+
+        <TextInput
+          label="Title"
+          placeholder="What is this document?"
+          value={title}
+          onChange={(e) => setTitle(e.currentTarget.value)}
+          required
+          withAsterisk
+        />
+
+        <Stack gap={6}>
+          <Text fz={13} fw={600}>
+            File
+          </Text>
+          <input
+            type="file"
+            onChange={(e) => setFile(e.currentTarget.files?.[0] ?? null)}
+            style={{
+              border: "1px dashed var(--mantine-color-gray-4)",
+              borderRadius: 8,
+              padding: 10,
+              fontSize: 12.5,
+              background: "var(--mantine-color-gray-0)",
+            }}
+          />
+          {file ? (
+            <Text fz={11.5} c="dimmed">
+              {file.name} · {formatBytes(file.size)}
+            </Text>
+          ) : null}
+        </Stack>
+
+        <Checkbox
+          label="Also make this visible to the customer"
+          description="Off by default — transit paperwork usually stays between the desks."
+          checked={visibleToCustomer}
+          onChange={(e) => setVisibleToCustomer(e.currentTarget.checked)}
+        />
+
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" onClick={close} disabled={submit.isPending}>
+            Cancel
+          </Button>
+          <Button
+            color="edr-green"
+            loading={submit.isPending}
+            disabled={!file || title.trim().length === 0}
+            leftSection={<Upload size={16} />}
+            onClick={() => submit.mutate()}
+          >
+            Share
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
+/** Empty-state block, matching the GL detail page's dashed panel. */
+function EmptyPanel({ icon: Icon, children }: { icon: typeof FileText; children: React.ReactNode }) {
+  return (
+    <Box
+      py={48}
+      style={{
+        borderRadius: 12,
+        border: "1px dashed var(--mantine-color-gray-4)",
+        background: "var(--mantine-color-gray-0)",
+        textAlign: "center",
+      }}
+    >
+      <Stack gap={8} align="center">
+        <ThemeIcon variant="light" color="gray" radius="xl" size={48}>
+          <Icon size={22} />
+        </ThemeIcon>
+        <Text size="sm" c="dimmed" maw={380}>
+          {children}
+        </Text>
+      </Stack>
+    </Box>
+  );
+}
+
+/** Bordered section with an icon header — the portal's SectionCard equivalent. */
+function SectionCard({
+  icon: Icon,
+  title,
+  children,
+}: {
+  icon: typeof FileText;
+  title: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card withBorder radius="md" p="md">
+      <Group gap={10} mb="sm" wrap="nowrap">
+        <ThemeIcon variant="light" color="edr-green" radius="md" size={32}>
+          <Icon size={16} />
+        </ThemeIcon>
+        <Text fw={600} fz={15}>
+          {title}
+        </Text>
+      </Group>
+      {children}
+    </Card>
+  );
+}
+
+function FieldRow({ label, value }: { label: string; value: React.ReactNode }) {
+  return (
+    <Group justify="space-between" wrap="nowrap" align="flex-start" gap="md">
+      <Text fz={12.5} c="edr-muted" style={{ flexShrink: 0 }}>
+        {label}
+      </Text>
+      <Box style={{ textAlign: "right", minWidth: 0 }}>{value}</Box>
+    </Group>
+  );
+}
+
+/**
+ * A transit agent's view of one assigned shipment, mirroring the backoffice's
+ * GL Djibouti clearance detail page tab for tab.
+ *
+ * Every tab here is READ-ONLY except the agent's own documents and progress.
+ * The clearance reads are authorized server-side by the assignment itself (see
+ * `assertTransitAgentScope` in the API) — this page never re-derives that rule,
+ * so a tab cannot show something the API would refuse.
+ */
+export default function TransitAgentBookingDetailPage() {
+  const { id } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const { view, viewer } = useFileViewer();
+  const [shareOpen, setShareOpen] = useState(false);
+
+  const assignmentQuery = useQuery({
+    queryKey: ["transit-assignment", id],
+    queryFn: () => transitAssignmentsService.getById(id!),
+    enabled: Boolean(id),
+  });
+
+  const assignment = assignmentQuery.data;
+  const bookingId = assignment?.bookingId;
+
+  // The clearance grid drives both the workflow and documents tabs.
+  const clearanceQuery = useQuery({
+    queryKey: ["transit-clearance", bookingId],
+    queryFn: () => bookingsService.getClearance(bookingId!),
+    enabled: Boolean(bookingId),
+  });
+
+  const historyQuery = useQuery({
+    queryKey: ["transit-clearance-history", bookingId],
+    queryFn: () => transitAssignmentsService.clearanceHistory(bookingId!),
+    enabled: Boolean(bookingId),
+  });
+
+  const exchangeQuery = useQuery({
+    queryKey: ["transit-gl-exchange", bookingId],
+    queryFn: () => transitAssignmentsService.glExchange(bookingId!),
+    enabled: Boolean(bookingId),
+  });
+
+  const incidentsQuery = useQuery({
+    queryKey: ["transit-incidents", bookingId],
+    queryFn: () => transitAssignmentsService.incidents(bookingId!),
+    enabled: Boolean(bookingId),
+  });
+
+  if (assignmentQuery.isPending) {
+    return (
+      <Box px="lg" py="lg" mx="auto" w="100%" maw={1600}>
+        <Stack align="center" py={80}>
+          <Loader color="edr-green" />
+          <Text c="dimmed">Loading shipment…</Text>
+        </Stack>
+      </Box>
+    );
+  }
+
+  if (assignmentQuery.isError || !assignment) {
+    return (
+      <Box px="lg" py="lg" mx="auto" w="100%" maw={1600}>
+        <Alert color="red" icon={<AlertCircle size={16} />}>
+          Could not load this shipment. It may no longer be assigned to you.
+        </Alert>
+      </Box>
+    );
+  }
+
+  const booking = assignment.booking;
+  const clearance = clearanceQuery.data;
+  const workflowFiles = clearance?.workflowFiles ?? [];
+  const workflowFileCount = workflowFiles.filter((f) => f.file).length;
+  const docCount = assignment.files?.length ?? 0;
+  const isImport = booking?.tradeDirection === "IMPORT";
+
+  // What the customer supplied, as the GL review section scopes it — the GL
+  // side of the grid is staff paperwork the officer does not action.
+  const customerDocuments = (clearance?.documents ?? []).filter(
+    (d) => d.uploadedBy === "customer",
+  );
+  const exchangeDocs = exchangeQuery.data ?? [];
+  const exchangeStats = {
+    et: exchangeDocs.filter((d) => d.side === "ET").length,
+    dj: exchangeDocs.filter((d) => d.side === "DJ").length,
+    transit: exchangeDocs.filter((d) => d.side === "TRANSIT").length,
+    shared: exchangeDocs.filter((d) => d.visibleToCustomer).length,
+  };
+  const historyEvents = historyQuery.data ?? [];
+
+  return (
+    <Box px="lg" py="lg" mx="auto" w="100%" maw={1600}>
+      <Stack gap="lg">
+        {/* ── Header ───────────────────────────────────────────────── */}
+        <Stack gap="sm">
+          <Group gap={6}>
+            <Anchor
+              fz={12.5}
+              c="edr-muted"
+              onClick={() => navigate(BACK_TO)}
+              style={{ cursor: "pointer" }}
+            >
+              My bookings
+            </Anchor>
+            <Text fz={12.5} c="edr-muted">
+              /
+            </Text>
+            <Text fz={12.5} c="edr-text">
+              {booking?.reference ?? "—"}
+            </Text>
+          </Group>
+
+          <Group justify="space-between" align="flex-start" gap="md">
+            <Group gap="sm" align="center" wrap="nowrap" style={{ minWidth: 0 }}>
+              <Button
+                variant="subtle"
+                color="gray"
+                px={8}
+                onClick={() => navigate(BACK_TO)}
+                aria-label="Go back"
+              >
+                <ArrowLeft size={18} />
+              </Button>
+              <div style={{ minWidth: 0, maxWidth: 640 }}>
+                <Group gap="sm" align="center" wrap="nowrap">
+                  <Title order={2} className="truncate" style={{ minWidth: 0 }}>
+                    {booking?.reference ?? "Shipment"}
+                  </Title>
+                  {booking?.tradeDirection ? (
+                    <Badge
+                      variant="light"
+                      color={isImport ? "edr-green" : "gray"}
+                      radius="sm"
+                    >
+                      {prettyStatus(booking.tradeDirection)}
+                    </Badge>
+                  ) : null}
+                  <Badge
+                    variant="light"
+                    radius="sm"
+                    color={STATUS_COLOR[assignment.status] ?? "gray"}
+                  >
+                    {prettyStatus(assignment.status)}
+                  </Badge>
+                </Group>
+                <Group gap={5} wrap="nowrap" mt={4}>
+                  <Building2 size={12} className="shrink-0 text-edr-muted" />
+                  <Text c="dimmed" size="sm" className="truncate">
+                    {assignment.customerName ?? "—"}
+                  </Text>
+                </Group>
+              </div>
+            </Group>
+
+          </Group>
+        </Stack>
+
+        <Tabs defaultValue="workflow" keepMounted={false}>
+          <Tabs.List mb="md">
+            <Tabs.Tab value="workflow" leftSection={<ClipboardList size={14} />}>
+              Clearance workflow
+            </Tabs.Tab>
+            <Tabs.Tab
+              value="documents"
+              leftSection={<FileText size={14} />}
+              rightSection={
+                workflowFileCount > 0 ? (
+                  <Badge size="xs" variant="light" color="edr-green" circle>
+                    {workflowFileCount}
+                  </Badge>
+                ) : undefined
+              }
+            >
+              Customs documents (all steps)
+            </Tabs.Tab>
+            <Tabs.Tab value="exchange" leftSection={<Share2 size={14} />}>
+              Document exchange
+            </Tabs.Tab>
+            <Tabs.Tab value="history" leftSection={<History size={14} />}>
+              History
+            </Tabs.Tab>
+            <Tabs.Tab value="incidents" leftSection={<AlertTriangle size={14} />}>
+              Incidents
+            </Tabs.Tab>
+          </Tabs.List>
+
+          {/* ── Clearance workflow ─────────────────────────────────── */}
+          <Tabs.Panel value="workflow">
+            {/* The officer's own uploads with their timings, ahead of the
+                read-only grid: RO / gate pass / Djibouti T1 for exports,
+                DO / T1 for imports. */}
+            {clearance && bookingId && booking?.tradeDirection ? (
+              <Box mb="md">
+                {booking.tradeDirection === "IMPORT" ? (
+                  <TransitImportDocumentsPanel
+                    bookingId={bookingId}
+                    clearance={clearance}
+                    history={historyEvents}
+                    onView={view}
+                    onChanged={() => void assignmentQuery.refetch()}
+                  />
+                ) : (
+                  <TransitExportDocumentsPanel
+                    bookingId={bookingId}
+                    clearance={clearance}
+                    history={historyEvents}
+                    onView={view}
+                    onChanged={() => void assignmentQuery.refetch()}
+                  />
+                )}
+              </Box>
+            ) : null}
+            <Grid>
+              <Grid.Col span={{ base: 12, lg: 7 }}>
+                <SectionCard icon={ClipboardList} title="Clearance status">
+                  {clearanceQuery.isPending ? (
+                    <Group py="lg" justify="center">
+                      <Loader size="sm" color="edr-green" />
+                    </Group>
+                  ) : clearanceQuery.isError ? (
+                    <Alert color="red" variant="light" icon={<AlertCircle size={16} />}>
+                      Clearance details are not available for this shipment.
+                    </Alert>
+                  ) : (
+                    <Stack gap={10}>
+                      <FieldRow
+                        label="Clearance phase"
+                        value={
+                          <Text fz={13} fw={500}>
+                            {prettyStatus(clearance?.phase) || "—"}
+                          </Text>
+                        }
+                      />
+                      <FieldRow
+                        label="Booking status"
+                        value={
+                          <Badge size="sm" variant="light" radius="sm">
+                            {prettyStatus(booking?.status) || "—"}
+                          </Badge>
+                        }
+                      />
+                      <FieldRow
+                        label="Shipment"
+                        value={
+                          <Badge
+                            size="sm"
+                            variant="light"
+                            radius="sm"
+                            color={
+                              booking?.schedulingStatus === "DISPATCHED"
+                                ? "teal"
+                                : "blue"
+                            }
+                          >
+                            {prettyStatus(booking?.schedulingStatus) || "—"}
+                          </Badge>
+                        }
+                      />
+                      <FieldRow
+                        label="Vessel arrival"
+                        value={
+                          <Text fz={13}>
+                            {formatDate(clearance?.vesselArrivalDate)}
+                          </Text>
+                        }
+                      />
+                      <FieldRow
+                        label="DO collected"
+                        value={
+                          <Text fz={13}>
+                            {formatDate(clearance?.doCollectedDate)}
+                          </Text>
+                        }
+                      />
+                    </Stack>
+                  )}
+                </SectionCard>
+
+                <Box mt="md">
+                  <CustomerDocumentsCard
+                    documents={customerDocuments}
+                    loading={clearanceQuery.isPending}
+                    onView={view}
+                  />
+                </Box>
+              </Grid.Col>
+
+              <Grid.Col span={{ base: 12, lg: 5 }}>
+                <Stack gap="md">
+                  <SectionCard icon={Train} title="My assignment">
+                    <Stack gap={10}>
+                      <FieldRow
+                        label="My status"
+                        value={
+                          <Badge
+                            size="sm"
+                            variant="light"
+                            radius="sm"
+                            color={STATUS_COLOR[assignment.status] ?? "gray"}
+                          >
+                            {prettyStatus(assignment.status)}
+                          </Badge>
+                        }
+                      />
+                      <FieldRow
+                        label="Assigned"
+                        value={<Text fz={13}>{formatDate(assignment.assignedAt)}</Text>}
+                      />
+                      <FieldRow
+                        label="Started"
+                        value={<Text fz={13}>{formatDate(assignment.startedAt)}</Text>}
+                      />
+                      <FieldRow
+                        label="Finished"
+                        value={<Text fz={13}>{formatDate(assignment.finishedAt)}</Text>}
+                      />
+                      <FieldRow
+                        label="Time after arrival"
+                        value={
+                          <Text fz={13}>
+                            {formatMinutes(assignment.timeAfterTrainArrives)}
+                          </Text>
+                        }
+                      />
+                      <FieldRow
+                        label="My documents"
+                        value={<Text fz={13}>{docCount || "—"}</Text>}
+                      />
+                      {assignment.note ? (
+                        <FieldRow
+                          label="My note"
+                          value={<Text fz={13}>{assignment.note}</Text>}
+                        />
+                      ) : null}
+                    </Stack>
+                  </SectionCard>
+
+                  <TransitClearanceActionPanel
+                    bookingId={bookingId!}
+                    clearance={clearance}
+                    tradeDirection={booking?.tradeDirection}
+                    onChanged={() => void assignmentQuery.refetch()}
+                  />
+
+                  <SectionCard icon={Building2} title="Customer">
+                    <Text fz={13}>{assignment.customerName ?? "—"}</Text>
+                  </SectionCard>
+                </Stack>
+              </Grid.Col>
+            </Grid>
+          </Tabs.Panel>
+
+          {/* ── Customs documents (all steps) ──────────────────────── */}
+          {/* ── Customs documents (all steps) ──────────────────────── */}
+          <Tabs.Panel value="documents">
+            {clearanceQuery.isPending ? (
+              <Group justify="center" py="xl" gap={10}>
+                <Loader size="sm" color="edr-green" />
+                <Text c="dimmed">Loading documents…</Text>
+              </Group>
+            ) : workflowFileCount > 0 ? (
+              <ClearanceWorkflowFilesPanel
+                files={workflowFiles}
+                title="Customs documents (all steps)"
+                onView={view}
+                onDownload={(f) => void downloadStoredFile(f.id, f.name)}
+              />
+            ) : (
+              <EmptyPanel icon={FileText}>
+                No customs workflow documents uploaded yet. Files from
+                Ethiopia-side clearance and the Djibouti desk's DO/RO uploads
+                will appear here.
+              </EmptyPanel>
+            )}
+          </Tabs.Panel>
+
+          {/* ── Document exchange ──────────────────────────────────── */}
+          <Tabs.Panel value="exchange">
+            <Stack gap="md">
+              <Paper withBorder radius="md" p="md">
+                <Group justify="space-between" wrap="nowrap" gap="sm">
+                <Group gap={12} wrap="nowrap" style={{ minWidth: 0 }}>
+                  <ThemeIcon variant="light" color="edr-green" radius="md" size={44}>
+                    <Share2 size={20} />
+                  </ThemeIcon>
+                  <Box style={{ minWidth: 0 }}>
+                    <Text fw={700} fz={16}>
+                      Document exchange
+                    </Text>
+                    <Text size="xs" c="dimmed">
+                      Documents shared with both Global Logistics desks for
+                      this shipment. Anything you share here is visible to GL
+                      Ethiopia and GL Djibouti immediately.
+                    </Text>
+                  </Box>
+                </Group>
+                  <Button
+                    color="edr-green"
+                    radius="md"
+                    leftSection={<Upload size={16} />}
+                    onClick={() => setShareOpen(true)}
+                  >
+                    Share document
+                  </Button>
+                </Group>
+
+                {exchangeDocs.length > 0 ? (
+                  <Group gap={8} mt="md">
+                    <Badge variant="light" color="edr-green" radius="sm" tt="none">
+                      {exchangeStats.et} from GL Ethiopia
+                    </Badge>
+                    <Badge variant="light" color="blue" radius="sm" tt="none">
+                      {exchangeStats.dj} from GL Djibouti
+                    </Badge>
+                    <Badge variant="light" color="grape" radius="sm" tt="none">
+                      {exchangeStats.transit} from you
+                    </Badge>
+                    <Badge variant="light" color="gray" radius="sm" tt="none">
+                      {exchangeStats.shared} visible to customer
+                    </Badge>
+                  </Group>
+                ) : null}
+              </Paper>
+
+              {exchangeQuery.isPending ? (
+                <Group justify="center" py={40} gap={10}>
+                  <Loader size="sm" color="edr-green" />
+                  <Text size="sm" c="dimmed">
+                    Loading shared documents…
+                  </Text>
+                </Group>
+              ) : exchangeQuery.isError ? (
+                <Text size="sm" c="red">
+                  Could not load the shared documents.
+                </Text>
+              ) : exchangeDocs.length === 0 ? (
+                <EmptyPanel icon={FileText}>
+                  Nothing shared yet. Anything either desk uploads — scans,
+                  correspondence, corrected forms — appears here.
+                </EmptyPanel>
+              ) : (
+                <Stack gap={8}>
+                  {exchangeDocs.map((doc) => {
+                    const side = SIDES[doc.side];
+                    const canPreview = isViewable({
+                      name: doc.file.name,
+                      url: "",
+                    });
+                    return (
+                      <Paper key={doc.id} withBorder radius="md" p="sm">
+                        <Group
+                          justify="space-between"
+                          wrap="nowrap"
+                          align="flex-start"
+                          gap="sm"
+                        >
+                          <Group
+                            gap={12}
+                            wrap="nowrap"
+                            align="flex-start"
+                            style={{ minWidth: 0 }}
+                          >
+                            <ThemeIcon
+                              variant="light"
+                              color={side.color}
+                              radius="md"
+                              size={40}
+                            >
+                              <FileText size={18} />
+                            </ThemeIcon>
+                            <Box style={{ minWidth: 0 }}>
+                              <Group gap={8} wrap="nowrap">
+                                <Text size="sm" fw={700} truncate>
+                                  {doc.title}
+                                </Text>
+                                <Badge
+                                  size="xs"
+                                  variant="light"
+                                  color={side.color}
+                                  radius="sm"
+                                  tt="none"
+                                >
+                                  {side.label}
+                                </Badge>
+                                <Badge
+                                  size="xs"
+                                  variant="light"
+                                  color={doc.visibleToCustomer ? "teal" : "gray"}
+                                  radius="sm"
+                                  tt="none"
+                                  leftSection={
+                                    doc.visibleToCustomer ? (
+                                      <Eye size={11} />
+                                    ) : (
+                                      <EyeOff size={11} />
+                                    )
+                                  }
+                                >
+                                  {doc.visibleToCustomer
+                                    ? "Visible to customer"
+                                    : "GL only"}
+                                </Badge>
+                              </Group>
+                              <Text size="xs" c="dimmed" mt={4} truncate>
+                                {doc.file.name} · {formatBytes(doc.file.size)} ·{" "}
+                                {doc.uploadedByName ?? "Global Logistics"} ·{" "}
+                                {formatDateTime(doc.uploadedAt)}
+                              </Text>
+                            </Box>
+                          </Group>
+
+                          <Group gap={6} wrap="nowrap">
+                            {canPreview ? (
+                              <Tooltip label="Preview">
+                                <Button
+                                  size="compact-xs"
+                                  variant="default"
+                                  radius="md"
+                                  leftSection={<Eye size={13} />}
+                                  onClick={() =>
+                                    void fetchViewableFile(
+                                      doc.file.id,
+                                      doc.file.name,
+                                    ).then(view)
+                                  }
+                                >
+                                  View
+                                </Button>
+                              </Tooltip>
+                            ) : null}
+                            <Tooltip label="Download">
+                              <Button
+                                size="compact-xs"
+                                variant="light"
+                                radius="md"
+                                leftSection={<Download size={13} />}
+                                onClick={() =>
+                                  void downloadStoredFile(
+                                    doc.file.id,
+                                    doc.file.name,
+                                  )
+                                }
+                              >
+                                Download
+                              </Button>
+                            </Tooltip>
+                          </Group>
+                        </Group>
+                      </Paper>
+                    );
+                  })}
+                </Stack>
+              )}
+            </Stack>
+          </Tabs.Panel>
+
+
+          {/* ── History ────────────────────────────────────────────── */}
+          <Tabs.Panel value="history">
+            {historyQuery.isPending ? (
+              <Group justify="center" py="xl" gap={10}>
+                <Loader size="sm" color="edr-green" />
+                <Text c="dimmed">Loading history…</Text>
+              </Group>
+            ) : historyQuery.isError ? (
+              <Alert color="red" variant="light" icon={<AlertCircle size={16} />}>
+                History is not available for this shipment.
+              </Alert>
+            ) : historyEvents.length === 0 ? (
+              <Paper withBorder radius="md" p="lg">
+                <Text size="sm" c="dimmed">
+                  No clearance actions recorded yet. Actions from now on —
+                  approvals, queries, workflow steps, charges — appear here
+                  automatically.
+                </Text>
+              </Paper>
+            ) : (
+              <Paper withBorder radius="md" p="lg" maw={760}>
+                <Timeline
+                  bulletSize={22}
+                  lineWidth={2}
+                  active={historyEvents.length - 1}
+                  color="gray"
+                >
+                  {historyEvents.map((ev) => {
+                    const meta = eventMeta(ev.action);
+                    const Icon = meta.icon;
+                    const actor = ACTOR_BADGE[ev.actorType];
+                    const note =
+                      typeof ev.metadata?.note === "string"
+                        ? ev.metadata.note
+                        : null;
+                    return (
+                      <Timeline.Item
+                        key={ev.id}
+                        color={meta.color}
+                        bullet={<Icon size={12} />}
+                        title={
+                          <Group gap={8} wrap="wrap">
+                            <Text fz="13px" fw={600} c="edr-text" lh={1.35}>
+                              {ev.label}
+                            </Text>
+                            <Badge
+                              size="xs"
+                              variant="light"
+                              color={actor.color}
+                              radius="sm"
+                            >
+                              {actor.label}
+                            </Badge>
+                          </Group>
+                        }
+                      >
+                        <Text fz="11.5px" c="dimmed">
+                          {ev.actorName ? `${ev.actorName} · ` : ""}
+                          {formatDateTime(ev.at)}
+                        </Text>
+                        {note ? (
+                          <Text fz="12px" c="red.8" mt={2}>
+                            {note}
+                          </Text>
+                        ) : null}
+                      </Timeline.Item>
+                    );
+                  })}
+                </Timeline>
+              </Paper>
+            )}
+          </Tabs.Panel>
+
+          {/* ── Incidents ──────────────────────────────────────────── */}
+          <Tabs.Panel value="incidents">
+            <SectionCard icon={AlertTriangle} title="Incident reports">
+              <Stack gap="sm">
+                <Text size="sm" c="dimmed">
+                  Container or seal issues discovered during clearance handling.
+                  Logged by the Djibouti desk — read-only here.
+                </Text>
+                {incidentsQuery.isPending ? (
+                  <Group py="lg" justify="center">
+                    <Loader size="sm" color="edr-green" />
+                  </Group>
+                ) : incidentsQuery.isError ? (
+                  <Alert color="red" variant="light" icon={<AlertCircle size={16} />}>
+                    Incident reports are not available for this shipment.
+                  </Alert>
+                ) : (incidentsQuery.data ?? []).length > 0 ? (
+                  <Stack gap="xs">
+                    {(incidentsQuery.data ?? []).map(
+                      (inc: Freight.IClearanceIncident) => (
+                        <Card key={inc.id} withBorder radius="md" p="sm">
+                          <Group gap={10} wrap="nowrap" align="flex-start">
+                            <ThemeIcon variant="light" color="red" radius="md" size={32}>
+                              <AlertTriangle size={15} />
+                            </ThemeIcon>
+                            <Box style={{ minWidth: 0 }}>
+                              <Text fz={13} fw={600}>
+                                {prettyStatus(inc.incidentType)}
+                              </Text>
+                              {inc.description ? (
+                                <Text fz={12.5} c="edr-text" mt={2}>
+                                  {inc.description}
+                                </Text>
+                              ) : null}
+                              <Text fz={11} c="edr-muted" mt={3}>
+                                {formatDate(inc.createdAt)}
+                              </Text>
+                            </Box>
+                          </Group>
+                        </Card>
+                      ),
+                    )}
+                  </Stack>
+                ) : (
+                  <Group gap={8}>
+                    <CheckCircle2 size={15} className="text-edr-muted" />
+                    <Text fz={13} c="dimmed">
+                      No incidents reported for this shipment.
+                    </Text>
+                  </Group>
+                )}
+              </Stack>
+            </SectionCard>
+          </Tabs.Panel>
+        </Tabs>
+      </Stack>
+
+      <ShareExchangeModal
+        opened={shareOpen}
+        bookingId={bookingId!}
+        onClose={() => setShareOpen(false)}
+        onShared={() => void exchangeQuery.refetch()}
+      />
+
+      {viewer}
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentBookingsPage.tsx b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentBookingsPage.tsx
new file mode 100644
index 000000000..fba9f354e
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentBookingsPage.tsx
@@ -0,0 +1,791 @@
+import {
+  ActionIcon,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Group,
+  Select,
+  Skeleton,
+  Stack,
+  Text,
+  TextInput,
+  ThemeIcon,
+  Title,
+  UnstyledButton,
+} from "@mantine/core";
+import { useDebouncedValue, useInterval } from "@mantine/hooks";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import {
+  DataTable,
+  usePagination,
+  type ColumnDef,
+  type DataTableFooterProps,
+} from "@edr/ui-common";
+import type { LucideIcon } from "lucide-react";
+import {
+  ArrowUpRight,
+  Building2,
+  CheckCircle2,
+  ChevronRight,
+  Clock3,
+  Inbox,
+  Layers,
+  PackageCheck,
+  Paperclip,
+  RefreshCw,
+  Search,
+  ShipWheel,
+  Train,
+  Truck,
+  X,
+} from "lucide-react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { Pagination } from "@mantine/core";
+
+import {
+  transitAssignmentsService,
+  type TransitAssignment,
+  type TransitAssignmentStatus,
+} from "@/services/transit-assignments.service";
+import "./transit-bookings-table.css";
+
+/** Matches the GL Djibouti queue's header cell treatment. */
+const headerCell =
+  "whitespace-nowrap text-[10px] font-semibold uppercase tracking-[0.08em] text-edr-muted";
+
+const prettyStatus = (s?: string | null) =>
+  (s ?? "")
+    .toLowerCase()
+    .replace(/_/g, " ")
+    .replace(/^\w/, (c) => c.toUpperCase());
+
+/** Minutes as "5h 30m" — the raw integer is unreadable in a grid. */
+function formatMinutes(minutes: number | null): string {
+  if (minutes === null) return "—";
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return hours ? `${hours}h ${rest}m` : `${rest}m`;
+}
+
+const STATUS_META: Record<
+  TransitAssignmentStatus,
+  { label: string; color: string }
+> = {
+  NOT_STARTED: { label: "Not started", color: "gray" },
+  IN_PROGRESS: { label: "In progress", color: "blue" },
+  FINISHED: { label: "Finished", color: "edr-green" },
+};
+
+/** Booking scheduling state → badge tint, mirroring the GL queue's scale. */
+function shipmentColor(status?: string | null): string {
+  switch (status) {
+    case "DISPATCHED":
+      return "teal";
+    case "SCHEDULED":
+      return "blue";
+    case "MANUAL_ONLY":
+      return "orange";
+    default:
+      return "gray";
+  }
+}
+
+const SHIPMENT_OPTIONS = [
+  { value: "DISPATCHED", label: "Dispatched (in transit)" },
+  { value: "SCHEDULED", label: "Scheduled" },
+];
+
+// ── Tabs ─────────────────────────────────────────────────────────────────────
+
+type TabKey = "all" | "NOT_STARTED" | "IN_PROGRESS" | "FINISHED";
+
+const TABS: { key: TabKey; label: string; icon: LucideIcon }[] = [
+  { key: "all", label: "All", icon: Layers },
+  { key: "NOT_STARTED", label: "Not started", icon: Clock3 },
+  { key: "IN_PROGRESS", label: "In progress", icon: Train },
+  { key: "FINISHED", label: "Finished", icon: CheckCircle2 },
+];
+
+// ── Shell pieces ─────────────────────────────────────────────────────────────
+// Ported from the backoffice's `components/page/*`, which the portal does not
+// have. Kept local rather than promoted to @edr/ui-common: one consumer.
+
+function LivePill({ updatedAt }: { updatedAt: number }) {
+  // Re-render every 30s so "Xm ago" keeps ticking between refetches.
+  const [, setTick] = useState(0);
+  useInterval(() => setTick((t) => t + 1), 30_000, { autoInvoke: true });
+  const mins = Math.max(0, Math.round((Date.now() - updatedAt) / 60_000));
+  const label = !updatedAt
+    ? "Connecting…"
+    : mins < 1
+      ? "Live · updated just now"
+      : `Live · updated ${mins}m ago`;
+  return (
+    <span className="inline-flex shrink-0 items-center gap-1.5 whitespace-nowrap rounded-full bg-edr-soft px-2.5 py-1 text-[11px] font-medium text-edr-green-7">
+      <span className="size-1.5 rounded-full bg-edr-green-7" />
+      {label}
+    </span>
+  );
+}
+
+function Spark({ values, color }: { values: number[]; color: string }) {
+  const max = Math.max(1, ...values);
+  return (
+    <div className="flex h-[26px] shrink-0 items-end gap-[3px]" aria-hidden>
+      {values.map((v, i) => (
+        <div
+          key={i}
+          className="w-1 rounded-sm"
+          style={{
+            height: Math.max(3, Math.round((v / max) * 26)),
+            background: `var(--mantine-color-${color}-7)`,
+            opacity: i === values.length - 1 ? 0.9 : 0.28,
+          }}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface KpiItem {
+  label: string;
+  value: number | string;
+  icon: LucideIcon;
+  color: string;
+  spark?: number[];
+  hint?: string;
+}
+
+/** One bordered card split into cells, matching the GL queue's KPI strip. */
+function KpiStrip({
+  items,
+  loading = false,
+}: {
+  items: KpiItem[];
+  loading?: boolean;
+}) {
+  return (
+    <Card withBorder shadow="sm" radius="lg" p={0} className="overflow-hidden">
+      <div className="flex flex-col sm:flex-row">
+        {items.slice(0, 5).map((item, index) => {
+          const Icon = item.icon;
+          return (
+            <div
+              key={item.label}
+              className={[
+                "flex min-w-0 flex-1 flex-col justify-center gap-2 px-[18px] py-4",
+                index > 0
+                  ? "border-t border-edr-border sm:border-l sm:border-t-0"
+                  : "",
+              ].join(" ")}
+            >
+              <div className="flex items-center gap-2">
+                <div
+                  className="flex size-7 shrink-0 items-center justify-center rounded-lg"
+                  style={{
+                    background: `var(--mantine-color-${item.color}-0)`,
+                    color: `var(--mantine-color-${item.color}-7)`,
+                  }}
+                >
+                  <Icon size={14} strokeWidth={2} />
+                </div>
+                <Text fz={12} fw={500} c="edr-muted" truncate>
+                  {item.label}
+                </Text>
+              </div>
+
+              <div className="flex items-center justify-between gap-3">
+                <div className="flex min-w-0 items-center gap-2">
+                  {loading ? (
+                    <Skeleton height={28} width={64} radius="sm" />
+                  ) : (
+                    <Text
+                      fw={600}
+                      fz={27}
+                      lh={1}
+                      c="edr-text"
+                      style={{ letterSpacing: "-0.03em" }}
+                      truncate
+                    >
+                      {item.value}
+                    </Text>
+                  )}
+                  {!loading && item.hint ? (
+                    <span
+                      className="inline-flex shrink-0 items-center gap-1 rounded-full px-[7px] py-[2px] text-[10px] font-medium leading-none"
+                      style={{
+                        background: "var(--mantine-color-edr-green-0)",
+                        color: "var(--mantine-color-edr-green-7)",
+                      }}
+                    >
+                      <ArrowUpRight size={10} />
+                      {item.hint}
+                    </span>
+                  ) : null}
+                </div>
+                {item.spark?.length ? (
+                  <Spark values={item.spark} color={item.color} />
+                ) : null}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </Card>
+  );
+}
+
+/** DataTable footer: row range left, rows-per-page + pager right. */
+function TablePager<T>({
+  table,
+  pagination,
+  noun = "rows",
+  pageSizes = [10, 25, 50],
+}: DataTableFooterProps<T> & { noun?: string; pageSizes?: number[] }) {
+  const pageIndex = pagination.pageIndex ?? 0;
+  const pageSize = pagination.pageSize ?? 10;
+  const total = pagination.totalCount ?? 0;
+  const pageCount = Math.max(
+    1,
+    pagination.pageCount ?? Math.ceil(total / pageSize),
+  );
+  const start = total === 0 ? 0 : pageIndex * pageSize + 1;
+  const end = Math.min((pageIndex + 1) * pageSize, total);
+
+  return (
+    <Group
+      justify="space-between"
+      gap="sm"
+      wrap="wrap"
+      px="md"
+      py={10}
+      style={{ borderTop: "1px solid var(--mantine-color-edr-divider-6)" }}
+    >
+      <Text fz={12} c="edr-muted">
+        Showing {start}–{end} of {total} {noun}
+      </Text>
+      <Group gap="sm" wrap="nowrap">
+        <Group gap={6} wrap="nowrap">
+          <Text fz={12} c="edr-muted">
+            Rows
+          </Text>
+          <Select
+            size="xs"
+            w={70}
+            radius="md"
+            value={String(pageSize)}
+            data={pageSizes.map(String)}
+            onChange={(v) => v && table.setPageSize(Number(v))}
+            allowDeselect={false}
+            comboboxProps={{ withinPortal: true }}
+            aria-label="Rows per page"
+          />
+        </Group>
+        <div className="h-5 w-px bg-edr-border" />
+        <Pagination
+          size="sm"
+          radius="md"
+          color="edr-ink"
+          total={pageCount}
+          value={pageIndex + 1}
+          onChange={(p) => table.setPageIndex(p - 1)}
+          siblings={1}
+          boundaries={1}
+        />
+      </Group>
+    </Group>
+  );
+}
+
+// ── Page ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The transit agent's work list: every booking assigned to them, with the
+ * document action for each. Laid out to match the backoffice's GL Djibouti
+ * clearance queue — same header, KPI strip, tab bar, filter bar and table.
+ *
+ * Filtering and paging stay SERVER-side (unlike the GL queue, which holds its
+ * whole queue in the browser): this roster grows without bound. The tab and
+ * the status filter therefore feed one server parameter, and the tab counts
+ * come from a separate stats call rather than from the current page.
+ *
+ * Uploading is gated on the API's own `canUploadDocuments`, never re-derived
+ * here, so a row's action cannot promise something the server will reject.
+ */
+export default function TransitAgentBookingsPage() {
+  const navigate = useNavigate();
+  const [query, setQuery] = useState("");
+  const [debouncedQuery] = useDebouncedValue(query, 300);
+  const [tab, setTab] = useState<TabKey>("all");
+  const [shipment, setShipment] = useState<string | null>(null);
+  const { pagination, setPagination } = usePagination({ pageSize: 10 });
+
+  const resetPage = useCallback(
+    () => setPagination({ pageIndex: 0, pageSize: pagination.pageSize }),
+    [setPagination, pagination.pageSize],
+  );
+
+  // Any filter change invalidates the current page number: staying on page 3 of
+  // a freshly narrowed result set shows an empty table.
+  useEffect(() => {
+    resetPage();
+  }, [debouncedQuery, tab, shipment, resetPage]);
+
+  const status = tab === "all" ? undefined : (tab as TransitAssignmentStatus);
+
+  const {
+    data,
+    isPending,
+    isError,
+    error,
+    isFetching,
+    dataUpdatedAt,
+    refetch,
+  } = useQuery({
+    queryKey: [
+      "transit-assignments",
+      {
+        search: debouncedQuery,
+        status,
+        shipment,
+        page: pagination.pageIndex + 1,
+        pageSize: pagination.pageSize,
+      },
+    ],
+    queryFn: () =>
+      transitAssignmentsService.list({
+        search: debouncedQuery || undefined,
+        status,
+        schedulingStatus: shipment ?? undefined,
+        page: pagination.pageIndex + 1,
+        pageSize: pagination.pageSize,
+      }),
+    // Keeps the previous page visible while the next one loads, so paging does
+    // not flash an empty table.
+    placeholderData: keepPreviousData,
+  });
+
+  // KPIs describe the WHOLE roster, not the current page — deriving them from
+  // a paginated slice would under-report the agent's real workload.
+  const { data: stats, isPending: statsPending } = useQuery({
+    queryKey: ["transit-assignments", "stats"],
+    queryFn: () => transitAssignmentsService.stats(),
+  });
+
+  const items = data?.items ?? [];
+  const meta = data?.meta;
+  const total = meta?.total ?? 0;
+  const pageCount = meta?.totalPages ?? 1;
+  const hasFilters = Boolean(query || shipment || tab !== "all");
+
+  // Counts come from `/stats`, which spans the whole roster. They are NOT read
+  // off `stats.items` (capped at 12 server-side) nor off the current page —
+  // either would under-report the agent's real workload.
+  const tabCounts = useMemo<Record<TabKey, number>>(
+    () => ({
+      all: stats?.totals.assignments ?? 0,
+      NOT_STARTED: stats?.totals.notStarted ?? 0,
+      IN_PROGRESS: stats?.totals.inProgress ?? 0,
+      FINISHED: stats?.totals.finished ?? 0,
+    }),
+    [stats],
+  );
+
+  const clearFilters = useCallback(() => {
+    setQuery("");
+    setShipment(null);
+    setTab("all");
+    resetPage();
+  }, [resetPage]);
+
+  const columns: ColumnDef<TransitAssignment, unknown>[] = useMemo(
+    () => [
+      {
+        id: "booking",
+        header: () => <span className={headerCell}>Booking</span>,
+        cell: ({ row }) => {
+          const r = row.original;
+          return (
+            <div className="flex items-center gap-2.5 py-1">
+              <div className="flex size-[30px] shrink-0 items-center justify-center rounded-[9px] bg-edr-divider text-edr-muted">
+                <PackageCheck size={15} strokeWidth={1.75} />
+              </div>
+              <div className="min-w-0">
+                <Text fz={13} fw={600} c="edr-text">
+                  {r.booking?.reference ?? "—"}
+                </Text>
+                <Group gap={4} wrap="nowrap" align="flex-start">
+                  <Building2
+                    size={10}
+                    className="mt-[3px] shrink-0 text-edr-muted opacity-70"
+                  />
+                  <Text fz={11} c="edr-muted" className="cell-wrap">
+                    {r.customerName ?? "—"}
+                  </Text>
+                </Group>
+              </div>
+            </div>
+          );
+        },
+      },
+      {
+        id: "shipment",
+        header: () => <span className={headerCell}>Shipment</span>,
+        cell: ({ row }) => {
+          const b = row.original.booking;
+          const isImport = b?.tradeDirection === "IMPORT";
+          const Icon = isImport ? Truck : ShipWheel;
+          return (
+            <Stack gap={5} py={2}>
+              <Badge
+                size="sm"
+                variant="light"
+                radius="sm"
+                color={shipmentColor(b?.schedulingStatus)}
+              >
+                {prettyStatus(b?.schedulingStatus) || "—"}
+              </Badge>
+              {b?.tradeDirection ? (
+                <span
+                  className="inline-flex w-fit items-center gap-1 rounded-[5px] px-1.5 py-[2px] text-[10px] font-medium leading-none"
+                  style={{
+                    background: `var(--mantine-color-${isImport ? "blue" : "teal"}-0)`,
+                    color: `var(--mantine-color-${isImport ? "blue" : "teal"}-7)`,
+                  }}
+                >
+                  <Icon size={10} />
+                  {prettyStatus(b.tradeDirection)}
+                </span>
+              ) : null}
+            </Stack>
+          );
+        },
+      },
+      {
+        id: "status",
+        header: () => <span className={headerCell}>My status</span>,
+        cell: ({ row }) => {
+          const m = STATUS_META[row.original.status];
+          return (
+            <Badge size="sm" variant="light" color={m.color} radius="sm">
+              {m.label}
+            </Badge>
+          );
+        },
+      },
+      {
+        id: "docs",
+        header: () => <span className={headerCell}>Docs</span>,
+        cell: ({ row }) => {
+          const count = row.original.files?.length ?? 0;
+          return (
+            <Group gap={5} wrap="nowrap">
+              <Paperclip size={12} className="shrink-0 text-edr-muted" />
+              <Text fz={12.5} c={count ? "edr-text" : "edr-muted"}>
+                {count || "—"}
+              </Text>
+            </Group>
+          );
+        },
+      },
+      {
+        id: "elapsed",
+        header: () => <span className={headerCell}>Time after arrival</span>,
+        cell: ({ row }) => (
+          <Group gap={5} wrap="nowrap">
+            <Clock3 size={12} className="shrink-0 text-edr-muted" />
+            <Text fz={11.5} c="edr-muted">
+              {formatMinutes(row.original.timeAfterTrainArrives)}
+            </Text>
+          </Group>
+        ),
+      },
+      {
+        id: "chevron",
+        size: 40,
+        header: "",
+        cell: () => (
+          <Group justify="flex-end" pr="xs">
+            <ChevronRight size={16} className="text-edr-muted" />
+          </Group>
+        ),
+      },
+    ],
+    [],
+  );
+
+  return (
+    <Box px="lg" py="lg" mx="auto" w="100%" maw={1600}>
+      <Stack gap="lg">
+        {/* ── Header ───────────────────────────────────────────────── */}
+        <Group justify="space-between" align="flex-start" gap="md">
+          <div style={{ minWidth: 0, maxWidth: 640 }}>
+            <Group gap="sm" align="center" wrap="nowrap">
+              <Title order={2} className="truncate" style={{ minWidth: 0 }}>
+                Bookings
+              </Title>
+              <LivePill updatedAt={dataUpdatedAt} />
+            </Group>
+            <Text c="dimmed" size="sm" mt={4}>
+              Shipments assigned to you for transit. Documents can be uploaded
+              once a booking is dispatched, and are locked when you finish it.
+            </Text>
+          </div>
+          <Button
+            variant="default"
+            radius="md"
+            size="sm"
+            leftSection={<RefreshCw size={14} />}
+            loading={isFetching}
+            onClick={() => void refetch()}
+          >
+            Refresh
+          </Button>
+        </Group>
+
+        <KpiStrip
+          loading={statsPending}
+          items={[
+            {
+              label: "Assigned to you",
+              value: stats?.totals.assignments ?? 0,
+              icon: Train,
+              color: "blue",
+            },
+            {
+              label: "Open",
+              value: stats?.totals.open ?? 0,
+              icon: Clock3,
+              color: "yellow",
+            },
+            {
+              label: "Uploads due",
+              value: stats?.totals.actionNeeded ?? 0,
+              icon: CheckCircle2,
+              color: "edr-green",
+            },
+            {
+              label: "Documents filed",
+              value: stats
+                ? stats.documents.ro +
+                  stats.documents.do +
+                  stats.documents.t1 +
+                  stats.documents.gatePass +
+                  stats.documents.djiboutiT1 +
+                  stats.documents.own
+                : 0,
+              icon: Paperclip,
+              color: "gray",
+            },
+          ]}
+        />
+
+        <Card
+          p={0}
+          withBorder
+          shadow="sm"
+          radius="lg"
+          style={{ overflow: "hidden" }}
+        >
+          <Stack gap={0}>
+            {/* ── Tabs ─────────────────────────────────────────────── */}
+            <Group
+              justify="space-between"
+              align="stretch"
+              px="md"
+              h={46}
+              wrap="nowrap"
+              style={{
+                borderBottom: "1px solid var(--mantine-color-edr-border-6)",
+              }}
+            >
+              <Group gap={2} wrap="nowrap" align="stretch">
+                {TABS.map((t) => {
+                  const isActive = tab === t.key;
+                  const Icon = t.icon;
+                  return (
+                    <UnstyledButton
+                      key={t.key}
+                      onClick={() => {
+                        setTab(t.key);
+                        resetPage();
+                      }}
+                      px={13}
+                      className="flex items-center gap-2 transition-colors"
+                      style={{
+                        borderBottom: `2px solid ${
+                          isActive
+                            ? "var(--mantine-color-edr-green-6)"
+                            : "transparent"
+                        }`,
+                        marginBottom: -1,
+                      }}
+                      aria-pressed={isActive}
+                    >
+                      <Icon
+                        size={14}
+                        style={{
+                          color: isActive
+                            ? "var(--mantine-color-edr-green-6)"
+                            : "var(--mantine-color-gray-5)",
+                        }}
+                      />
+                      <Text
+                        fz={13}
+                        fw={isActive ? 600 : 500}
+                        c={isActive ? "edr-text" : "edr-muted"}
+                      >
+                        {t.label}
+                      </Text>
+                      <span
+                        className="rounded-full px-1.5 py-px text-[10.5px] font-semibold leading-[1.4]"
+                        style={{
+                          background: isActive
+                            ? "var(--mantine-color-edr-green-0)"
+                            : "var(--mantine-color-gray-1)",
+                          color: isActive
+                            ? "var(--mantine-color-edr-green-7)"
+                            : "var(--mantine-color-edr-muted-6)",
+                        }}
+                      >
+                        {tabCounts[t.key]}
+                      </span>
+                    </UnstyledButton>
+                  );
+                })}
+              </Group>
+              <Text
+                fz={12}
+                c="edr-muted"
+                className="self-center whitespace-nowrap"
+              >
+                {total} record{total !== 1 ? "s" : ""}
+              </Text>
+            </Group>
+
+            {/* ── Filter bar ───────────────────────────────────────── */}
+            <Group
+              gap={9}
+              px="md"
+              py={12}
+              wrap="wrap"
+              style={{
+                borderBottom: "1px solid var(--mantine-color-edr-divider-6)",
+              }}
+            >
+              <TextInput
+                placeholder="Search booking reference or customer…"
+                leftSection={<Search size={15} />}
+                value={query}
+                onChange={(e) => setQuery(e.currentTarget.value)}
+                rightSection={
+                  query ? (
+                    <ActionIcon
+                      size="sm"
+                      color="gray"
+                      radius="md"
+                      variant="transparent"
+                      onClick={() => setQuery("")}
+                      aria-label="Clear search"
+                    >
+                      <X size={14} />
+                    </ActionIcon>
+                  ) : null
+                }
+                radius="md"
+                size="sm"
+                styles={{
+                  input: { background: "var(--mantine-color-gray-0)" },
+                }}
+                style={{ flex: 1, minWidth: 220 }}
+              />
+              <Select
+                placeholder="Shipment"
+                data={SHIPMENT_OPTIONS}
+                value={shipment}
+                onChange={setShipment}
+                clearable
+                radius="md"
+                size="sm"
+                w={210}
+                comboboxProps={{ withinPortal: true }}
+                aria-label="Filter by shipment state"
+              />
+              {hasFilters ? (
+                <Button
+                  variant="subtle"
+                  color="gray"
+                  size="compact-sm"
+                  radius="md"
+                  leftSection={<X size={14} />}
+                  onClick={clearFilters}
+                >
+                  Clear
+                </Button>
+              ) : null}
+            </Group>
+
+            {!isPending && !isError && total === 0 ? (
+              <Stack align="center" gap={8} py={48}>
+                <ThemeIcon variant="light" color="gray" radius="xl" size={48}>
+                  <Inbox size={22} />
+                </ThemeIcon>
+                <Text c="dimmed">
+                  {hasFilters
+                    ? "No bookings match these filters."
+                    : "No bookings have been assigned to you yet."}
+                </Text>
+                {hasFilters ? (
+                  <Button
+                    variant="light"
+                    color="gray"
+                    size="compact-sm"
+                    radius="md"
+                    onClick={clearFilters}
+                  >
+                    Clear filters
+                  </Button>
+                ) : null}
+              </Stack>
+            ) : (
+              <Box w="100%" miw={0}>
+                <DataTable<TransitAssignment, unknown>
+                  columns={columns}
+                  data={items}
+                  status={
+                    isPending ? "loading" : isError ? "error" : "success"
+                  }
+                  error={
+                    isError
+                      ? {
+                          message: (error as Error).message,
+                          onRetry: () => void refetch(),
+                        }
+                      : undefined
+                  }
+                  onRowClick={(row) => navigate(`/transit-agent/bookings/${row.id}`)}
+                  pagination={{
+                    pageIndex: pagination.pageIndex,
+                    pageSize: pagination.pageSize,
+                    pageCount,
+                    totalCount: total,
+                  }}
+                  tableOptions={{
+                    state: { pagination },
+                    onPaginationChange: setPagination,
+                    manualPagination: true,
+                    pageCount,
+                  }}
+                  containerClassName="edr-transit-table border-0 shadow-none rounded-none bg-transparent"
+                  footer={(p) => <TablePager {...p} noun="bookings" />}
+                />
+              </Box>
+            )}
+          </Stack>
+        </Card>
+      </Stack>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentDocumentsModal.tsx b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentDocumentsModal.tsx
new file mode 100644
index 000000000..36f76a243
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentDocumentsModal.tsx
@@ -0,0 +1,682 @@
+import {
+  ActionIcon,
+  Alert,
+  Badge,
+  Button,
+  Card,
+  Center,
+  FileButton,
+  Group,
+  Image,
+  Loader,
+  Modal,
+  Paper,
+  ScrollArea,
+  Stack,
+  Text,
+  Textarea,
+  TextInput,
+  ThemeIcon,
+  Tooltip,
+} from "@mantine/core";
+import { resolveViewerKind } from "@edr/ui-common";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  AlertCircle,
+  CheckCircle2,
+  Eye,
+  File as FileIcon,
+  FileSpreadsheet,
+  FileText,
+  Film,
+  ImageIcon,
+  Lock,
+  Trash2,
+  Upload,
+  X,
+} from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { useFileViewer } from "@/hooks/useFileViewer";
+import { fetchViewableFile, filesService } from "@/services/files.service";
+import {
+  transitAssignmentsService,
+  type TransitAssignment,
+  type TransitAssignmentFile,
+} from "@/services/transit-assignments.service";
+
+const formatBytes = (bytes: number): string =>
+  bytes >= 1024 * 1024
+    ? `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+    : `${Math.max(1, Math.round(bytes / 1024))} KB`;
+
+/** Icon + colour per viewer kind, so a file's type reads at a glance. */
+function kindVisuals(name: string, mimeType?: string | null) {
+  const kind = resolveViewerKind({ name, url: "", mimeType });
+  switch (kind) {
+    case "image":
+      return { icon: <ImageIcon size={18} />, color: "grape" };
+    case "pdf":
+      return { icon: <FileText size={18} />, color: "red" };
+    case "video":
+    case "audio":
+      return { icon: <Film size={18} />, color: "indigo" };
+    case "office":
+      return { icon: <FileSpreadsheet size={18} />, color: "teal" };
+    case "text":
+      return { icon: <FileText size={18} />, color: "blue" };
+    default:
+      return { icon: <FileIcon size={18} />, color: "gray" };
+  }
+}
+
+/** One already-uploaded document. */
+function UploadedFileCard({
+  file,
+  locked,
+  busy,
+  onView,
+  onRemove,
+}: {
+  file: TransitAssignmentFile;
+  locked: boolean;
+  busy: boolean;
+  onView: () => void;
+  onRemove: () => void;
+}) {
+  const visuals = kindVisuals(file.name, file.mimeType);
+  const isImage = (file.mimeType ?? "").startsWith("image/");
+  const [thumb, setThumb] = useState<string | null>(null);
+
+  /**
+   * Thumbnails are fetched through the API, not linked straight from `file.url`.
+   * That URL points at MinIO, which is not reachable from the browser, and
+   * `GET /api/files/:id` is JWT-guarded — so a bare `<img src>` gets either a
+   * DNS failure or a 401. The bytes come down the authenticated axios client
+   * and become a blob URL, revoked when the card unmounts.
+   */
+  useEffect(() => {
+    if (!isImage) return;
+    let objectUrl: string | null = null;
+    let cancelled = false;
+
+    void filesService
+      .download(file.id)
+      .then((blob) => {
+        if (cancelled) return;
+        objectUrl = URL.createObjectURL(blob);
+        setThumb(objectUrl);
+      })
+      // A failed thumbnail is not worth surfacing — the card falls back to its
+      // type icon and the preview button still reports any real error.
+      .catch(() => undefined);
+
+    return () => {
+      cancelled = true;
+      if (objectUrl) URL.revokeObjectURL(objectUrl);
+    };
+  }, [file.id, isImage]);
+
+  return (
+    <Paper withBorder radius="md" p="sm">
+      <Group gap="sm" wrap="nowrap" align="flex-start">
+        {isImage && thumb ? (
+          // A thumbnail is worth more than an icon for scanned paperwork, which
+          // is most of what gets filed here.
+          <Image
+            src={thumb}
+            alt={file.name}
+            w={44}
+            h={44}
+            radius="sm"
+            fit="cover"
+          />
+        ) : (
+          <ThemeIcon
+            variant="light"
+            color={visuals.color}
+            size={44}
+            radius="sm"
+          >
+            {visuals.icon}
+          </ThemeIcon>
+        )}
+
+        <Stack gap={2} style={{ flex: 1, minWidth: 0 }}>
+          <Tooltip label={file.title || file.name} openDelay={400}>
+            <Text size="sm" fw={500} truncate>
+              {file.title || file.name}
+            </Text>
+          </Tooltip>
+          <Text size="xs" c="dimmed">
+            {formatBytes(file.size)} ·{" "}
+            {new Date(file.uploadedAt).toLocaleString()}
+          </Text>
+          {file.uploadedByName ? (
+            <Text size="xs" c="dimmed" truncate>
+              by {file.uploadedByName}
+            </Text>
+          ) : null}
+        </Stack>
+
+        <Group gap={4} wrap="nowrap">
+          <Tooltip label="Preview">
+            <ActionIcon variant="subtle" onClick={onView}>
+              <Eye size={16} />
+            </ActionIcon>
+          </Tooltip>
+          {locked ? null : (
+            <Tooltip label="Remove">
+              <ActionIcon
+                variant="subtle"
+                color="red"
+                disabled={busy}
+                onClick={onRemove}
+              >
+                <Trash2 size={16} />
+              </ActionIcon>
+            </Tooltip>
+          )}
+        </Group>
+      </Group>
+    </Paper>
+  );
+}
+
+/** A file chosen but not yet uploaded: local preview plus the name to file it under. */
+function PendingFileCard({
+  file,
+  title,
+  previewUrl,
+  onTitleChange,
+  onView,
+  onRemove,
+  disabled,
+}: {
+  file: File;
+  title: string;
+  previewUrl: string;
+  onTitleChange: (title: string) => void;
+  onView: () => void;
+  onRemove: () => void;
+  disabled: boolean;
+}) {
+  const visuals = kindVisuals(file.name, file.type);
+  const isImage = file.type.startsWith("image/");
+
+  return (
+    <Paper withBorder radius="md" p="xs" bg="var(--mantine-color-blue-light)">
+      <Group gap="sm" wrap="nowrap">
+        {isImage ? (
+          <Image
+            src={previewUrl}
+            alt={file.name}
+            w={36}
+            h={36}
+            radius="sm"
+            fit="cover"
+          />
+        ) : (
+          <ThemeIcon
+            variant="light"
+            color={visuals.color}
+            size={36}
+            radius="sm"
+          >
+            {visuals.icon}
+          </ThemeIcon>
+        )}
+        <Stack gap={4} style={{ flex: 1, minWidth: 0 }}>
+          <TextInput
+            size="xs"
+            placeholder="Document name (optional)"
+            value={title}
+            disabled={disabled}
+            onChange={(e) => onTitleChange(e.currentTarget.value)}
+          />
+          <Text size="xs" c="dimmed" truncate>
+            {file.name} · {formatBytes(file.size)}
+          </Text>
+        </Stack>
+        <Group gap={2} wrap="nowrap">
+          <Tooltip label="Preview before uploading">
+            <ActionIcon variant="subtle" onClick={onView}>
+              <Eye size={15} />
+            </ActionIcon>
+          </Tooltip>
+          <Tooltip label="Remove from selection">
+            <ActionIcon
+              variant="subtle"
+              color="red"
+              disabled={disabled}
+              onClick={onRemove}
+            >
+              <X size={15} />
+            </ActionIcon>
+          </Tooltip>
+        </Group>
+      </Group>
+    </Paper>
+  );
+}
+
+/**
+ * Documents for one transit assignment: what has been filed, and what is about
+ * to be.
+ *
+ * Uploading is gated on the server by two rules — the booking must be
+ * dispatched, and the assignment must not be finished. Rather than
+ * re-implementing them here, the modal reads the server's own
+ * `canUploadDocuments`, so the disabled state can never disagree with what the
+ * API would accept.
+ */
+export default function TransitAgentDocumentsModal({
+  assignment,
+  onClose,
+}: {
+  assignment: TransitAssignment | null;
+  onClose: () => void;
+}) {
+  const queryClient = useQueryClient();
+  const { view, viewer } = useFileViewer();
+  /**
+   * Files chosen but not yet uploaded, each with the name the agent gives it.
+   * Kept as objects rather than two parallel arrays so removing one entry
+   * cannot desynchronise a file from its title.
+   */
+  const [pending, setPending] = useState<{ file: File; title: string }[]>([]);
+  const [note, setNote] = useState("");
+
+  /**
+   * Object URLs for the staged files, keyed by File identity.
+   *
+   * Keyed rather than rebuilt as an array: removing one file from the selection
+   * would otherwise re-create every URL and revoke the old ones, which kills the
+   * preview of a DIFFERENT file if the viewer happens to be open on it. Only
+   * URLs whose file has actually left the selection are revoked.
+   */
+  const previewsRef = useRef(new Map<File, string>());
+  const previews = useMemo(() => {
+    const next = new Map<File, string>();
+    for (const { file } of pending) {
+      next.set(
+        file,
+        previewsRef.current.get(file) ?? URL.createObjectURL(file),
+      );
+    }
+    for (const [file, url] of previewsRef.current) {
+      if (!next.has(file)) URL.revokeObjectURL(url);
+    }
+    previewsRef.current = next;
+    return next;
+  }, [pending]);
+
+  // Last resort: revoke whatever is still held when the modal unmounts.
+  useEffect(
+    () => () => {
+      for (const url of previewsRef.current.values()) URL.revokeObjectURL(url);
+      previewsRef.current = new Map();
+    },
+    [],
+  );
+
+  // Each assignment opens a fresh sheet — files staged for one must not follow
+  // the modal onto another.
+  useEffect(() => {
+    setPending([]);
+    setNote(assignment?.note ?? "");
+  }, [assignment?.id, assignment?.note]);
+
+  const detailQuery = useQuery({
+    queryKey: ["transit-assignment", assignment?.id],
+    queryFn: () => transitAssignmentsService.getById(assignment!.id),
+    enabled: assignment !== null,
+  });
+
+  const detail = detailQuery.data ?? assignment;
+  const locked = !detail?.canUploadDocuments;
+  const isFinished = detail?.status === "FINISHED";
+
+  const invalidate = async () => {
+    await Promise.all([
+      queryClient.invalidateQueries({ queryKey: ["transit-assignments"] }),
+      queryClient.invalidateQueries({
+        queryKey: ["transit-assignment", assignment?.id],
+      }),
+    ]);
+  };
+
+  const uploadMutation = useMutation({
+    mutationFn: () =>
+      transitAssignmentsService.uploadFiles(assignment!.id, pending),
+    onSuccess: async () => {
+      setPending([]);
+      await invalidate();
+    },
+  });
+
+  /**
+   * Save = persist everything the agent has entered, without closing the work.
+   *
+   * Staged files are uploaded FIRST, then the note is saved: a Save that left
+   * the chosen files sitting in the browser would look like it had stored them,
+   * and they would be silently lost on close. The status only ever moves to
+   * IN_PROGRESS here — finishing is a separate, deliberate action.
+   */
+  const saveMutation = useMutation({
+    mutationFn: async () => {
+      if (pending.length > 0) {
+        await transitAssignmentsService.uploadFiles(assignment!.id, pending);
+      }
+      return transitAssignmentsService.submit(assignment!.id, {
+        finish: false,
+        note,
+      });
+    },
+    onSuccess: async () => {
+      setPending([]);
+      await invalidate();
+    },
+  });
+
+  const removeMutation = useMutation({
+    mutationFn: (fileId: string) =>
+      transitAssignmentsService.removeFile(assignment!.id, fileId),
+    onSuccess: invalidate,
+  });
+
+  // Save keeps the assignment open; finish closes it AND locks the documents,
+  // which is why the button asks first.
+  const finishMutation = useMutation({
+    mutationFn: async () => {
+      // Flush anything still staged before closing: finishing locks uploads, so
+      // a file left behind here could never be filed afterwards.
+      if (pending.length > 0) {
+        await transitAssignmentsService.uploadFiles(assignment!.id, pending);
+      }
+      return transitAssignmentsService.submit(assignment!.id, {
+        finish: true,
+        note,
+      });
+    },
+    onSuccess: async () => {
+      setPending([]);
+      await invalidate();
+      onClose();
+    },
+  });
+
+  /**
+   * Open a stored document in the viewer.
+   *
+   * The bytes are fetched through the authenticated API rather than linked from
+   * `file.url`: that column holds the MinIO object URL, which the browser
+   * cannot reach, and `GET /api/files/:id` requires the Bearer token that a
+   * raw `<iframe>`/`<img>` load would not carry.
+   */
+  const [viewerError, setViewerError] = useState<string | null>(null);
+  const openUploaded = (file: TransitAssignmentFile) => {
+    setViewerError(null);
+    void fetchViewableFile(file.id, file.title || file.name)
+      .then((viewable) =>
+        view({ ...viewable, mimeType: viewable.mimeType ?? file.mimeType }),
+      )
+      .catch((error: Error) =>
+        setViewerError(error.message || "Could not open this document."),
+      );
+  };
+
+  const files = detail?.files ?? [];
+  const busy =
+    uploadMutation.isPending ||
+    removeMutation.isPending ||
+    saveMutation.isPending ||
+    finishMutation.isPending;
+
+  return (
+    <>
+      <Modal
+        opened={assignment !== null}
+        onClose={onClose}
+        title={
+          <Group gap="xs">
+            <Text fw={600}>Documents</Text>
+            <Text c="dimmed">{detail?.booking?.reference ?? ""}</Text>
+          </Group>
+        }
+        size="lg"
+        centered
+      >
+        {detailQuery.isPending ? (
+          <Center py="xl">
+            <Loader size="sm" />
+          </Center>
+        ) : (
+          <Stack gap="md">
+            {detail?.customerName ? (
+              <Text size="sm" c="dimmed">
+                {detail.customerName}
+              </Text>
+            ) : null}
+
+            {isFinished ? (
+              <Alert
+                color="teal"
+                variant="light"
+                icon={<CheckCircle2 size={16} />}
+              >
+                This assignment is finished. Its documents are locked and can no
+                longer be added to or removed.
+              </Alert>
+            ) : locked ? (
+              <Alert
+                color="yellow"
+                variant="light"
+                icon={<AlertCircle size={16} />}
+              >
+                Documents can be uploaded once this booking has been dispatched.
+                It is currently{" "}
+                {detail?.booking?.schedulingStatus
+                  ?.toLowerCase()
+                  .replace(/_/g, " ") ?? "not dispatched"}
+                .
+              </Alert>
+            ) : null}
+
+            {viewerError ? (
+              <Alert
+                color="red"
+                variant="light"
+                icon={<AlertCircle size={16} />}
+              >
+                {viewerError}
+              </Alert>
+            ) : null}
+
+            <Stack gap="xs">
+              <Group gap="xs">
+                <Text size="sm" fw={600}>
+                  Uploaded
+                </Text>
+                <Badge size="sm" variant="light" circle={files.length < 10}>
+                  {files.length}
+                </Badge>
+              </Group>
+
+              {files.length === 0 ? (
+                <Card withBorder radius="md" py="lg">
+                  <Stack align="center" gap={4}>
+                    <FileIcon size={22} opacity={0.35} />
+                    <Text size="sm" c="dimmed">
+                      No documents uploaded yet.
+                    </Text>
+                  </Stack>
+                </Card>
+              ) : (
+                <ScrollArea.Autosize mah={260}>
+                  <Stack gap="xs">
+                    {files.map((file) => (
+                      <UploadedFileCard
+                        key={file.id}
+                        file={file}
+                        locked={locked}
+                        busy={busy}
+                        onView={() => openUploaded(file)}
+                        onRemove={() => removeMutation.mutate(file.id)}
+                      />
+                    ))}
+                  </Stack>
+                </ScrollArea.Autosize>
+              )}
+            </Stack>
+
+            {locked ? null : (
+              <>
+                <Stack gap="xs">
+                  <Group justify="space-between" align="center">
+                    <Text size="sm" fw={600}>
+                      Add documents
+                    </Text>
+                    <FileButton
+                      multiple
+                      onChange={(chosen) =>
+                        setPending((current) => [
+                          ...current,
+                          // Appended, not replaced: picking a second time must
+                          // add to the batch rather than discard the first pick
+                          // and the names already typed for it.
+                          ...chosen.map((file) => ({ file, title: "" })),
+                        ])
+                      }
+                    >
+                      {(props) => (
+                        <Button
+                          {...props}
+                          size="compact-sm"
+                          variant="light"
+                          leftSection={<Upload size={14} />}
+                          disabled={busy}
+                        >
+                          Choose files
+                        </Button>
+                      )}
+                    </FileButton>
+                  </Group>
+
+                  {pending.length > 0 ? (
+                    <>
+                      <ScrollArea.Autosize mah={180}>
+                        <Stack gap={6}>
+                          {pending.map((entry, index) => (
+                            <PendingFileCard
+                              key={`${entry.file.name}-${index}`}
+                              file={entry.file}
+                              title={entry.title}
+                              previewUrl={previews.get(entry.file) ?? ""}
+                              disabled={busy}
+                              onTitleChange={(title) =>
+                                setPending((current) =>
+                                  current.map((item, i) =>
+                                    i === index ? { ...item, title } : item,
+                                  ),
+                                )
+                              }
+                              onView={() =>
+                                view({
+                                  name: entry.title || entry.file.name,
+                                  url: previews.get(entry.file) ?? "",
+                                  mimeType: entry.file.type,
+                                })
+                              }
+                              onRemove={() =>
+                                setPending((current) =>
+                                  current.filter((_, i) => i !== index),
+                                )
+                              }
+                            />
+                          ))}
+                        </Stack>
+                      </ScrollArea.Autosize>
+                      <Group>
+                        <Button
+                          leftSection={<Upload size={15} />}
+                          loading={uploadMutation.isPending}
+                          onClick={() => uploadMutation.mutate()}
+                        >
+                          Upload {pending.length} file
+                          {pending.length === 1 ? "" : "s"}
+                        </Button>
+                        <Button
+                          variant="subtle"
+                          color="gray"
+                          disabled={busy}
+                          onClick={() => setPending([])}
+                        >
+                          Clear
+                        </Button>
+                      </Group>
+                    </>
+                  ) : null}
+
+                  {uploadMutation.isError ? (
+                    <Alert
+                      color="red"
+                      variant="light"
+                      icon={<AlertCircle size={16} />}
+                    >
+                      {(uploadMutation.error as Error).message}
+                    </Alert>
+                  ) : null}
+                </Stack>
+
+                <Textarea
+                  label="Note"
+                  placeholder="Anything worth recording about this clearance"
+                  value={note}
+                  onChange={(e) => setNote(e.currentTarget.value)}
+                  minRows={3}
+                  autosize
+                />
+
+                <Group justify="flex-end">
+                  <Button
+                    variant="default"
+                    loading={saveMutation.isPending}
+                    disabled={busy}
+                    onClick={() => saveMutation.mutate()}
+                  >
+                    {pending.length > 0
+                      ? `Save & upload ${pending.length}`
+                      : "Save"}
+                  </Button>
+                  <Button
+                    color="teal"
+                    leftSection={<Lock size={15} />}
+                    loading={finishMutation.isPending}
+                    disabled={busy}
+                    onClick={() => {
+                      // Finishing is one-way: it closes the assignment and locks
+                      // its documents, so confirm before doing it.
+                      if (
+                        window.confirm(
+                          pending.length > 0
+                            ? `Upload ${pending.length} staged file(s) and finish this assignment? Its documents will then be locked.`
+                            : "Finish this assignment? Its documents will be locked and can no longer be changed.",
+                        )
+                      ) {
+                        finishMutation.mutate();
+                      }
+                    }}
+                  >
+                    Finish
+                  </Button>
+                </Group>
+              </>
+            )}
+          </Stack>
+        )}
+      </Modal>
+      {viewer}
+    </>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentOverviewPage.tsx b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentOverviewPage.tsx
new file mode 100644
index 000000000..0e62ec710
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitAgentOverviewPage.tsx
@@ -0,0 +1,1050 @@
+import { Box, Button, Center, Group, Loader, Stack, Text, Tooltip } from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
+import {
+  AlertCircle,
+  ArrowRight,
+  CheckCircle2,
+  Clock3,
+  FileStack,
+  FileText,
+  Hourglass,
+  MapPin,
+  PackageCheck,
+  Route,
+  Ship,
+  ShieldCheck,
+  Timer,
+  Train,
+  Upload,
+} from "lucide-react";
+import { useMemo } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { Card } from "@/pages/MyPortalPage/components";
+import { cv } from "@/pages/MyPortalPage/constants";
+import {
+  transitAssignmentsService,
+  type TransitDocumentKind,
+  type TransitStatItem,
+  type TransitStats,
+  type TransitTimingKey,
+  type TransitTimingSummary,
+} from "@/services/transit-assignments.service";
+
+// ── Formatting ───────────────────────────────────────────────────────────────
+
+/** Minutes as "2d 4h", "3h 10m", "45m" — raw integers are unreadable in a grid. */
+function formatMinutes(minutes: number | null | undefined): string {
+  if (minutes === null || minutes === undefined) return "—";
+  if (minutes < 1) return "<1m";
+  const d = Math.floor(minutes / 1440);
+  const h = Math.floor((minutes % 1440) / 60);
+  const m = minutes % 60;
+  if (d) return `${d}d${h ? ` ${h}h` : ""}`;
+  if (h) return `${h}h${m ? ` ${m}m` : ""}`;
+  return `${m}m`;
+}
+
+/** Split a duration so the number and its unit can be styled apart. */
+function splitDuration(minutes: number | null): [string, string] {
+  if (minutes === null) return ["—", ""];
+  if (minutes < 90) return [String(minutes), "min"];
+  if (minutes < 2880) return [(minutes / 60).toFixed(1), "hrs"];
+  return [(minutes / 1440).toFixed(1), "days"];
+}
+
+function formatStamp(value?: string | null): string {
+  if (!value) return "—";
+  return new Date(value).toLocaleString(undefined, {
+    day: "numeric",
+    month: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** "3h ago" / "2d ago" — for the action list, where recency is the point. */
+function ago(value?: string | null): string | null {
+  if (!value) return null;
+  const minutes = Math.max(
+    Math.floor((Date.now() - new Date(value).getTime()) / 60_000),
+    0,
+  );
+  return `${formatMinutes(minutes)} ago`;
+}
+
+const pctOf = (part: number, total: number) =>
+  total ? Math.round((part / total) * 100) : 0;
+
+type Tone = "green" | "amber" | "blue" | "slate" | "red";
+
+const TONES: Record<Tone, { soft: string; ink: string }> = {
+  green: { soft: cv("edr-soft"), ink: cv("edr-green.7") },
+  amber: { soft: cv("edr-amber-soft"), ink: cv("edr-amber-text") },
+  blue: { soft: cv("edr-blue-soft"), ink: cv("edr-blue") },
+  slate: { soft: cv("edr-slate-soft"), ink: cv("edr-slate") },
+  red: { soft: cv("edr-red-soft"), ink: cv("edr-red") },
+};
+
+const DOC_ICON: Record<TransitDocumentKind, typeof FileText> = {
+  ro: Ship,
+  do: PackageCheck,
+  t1: FileStack,
+  gate_pass: ShieldCheck,
+  djibouti_t1: FileStack,
+};
+
+/** Every timing the API measures, with the copy that explains each one. */
+const TIMINGS: Array<{
+  key: TransitTimingKey;
+  label: string;
+  caption: string;
+  icon: typeof Timer;
+  tone: Tone;
+  direction?: "IMPORT" | "EXPORT";
+}> = [
+  {
+    key: "transit",
+    label: "Transit time",
+    caption: "train departure → arrival",
+    icon: Route,
+    tone: "blue",
+  },
+  {
+    key: "declarationToRo",
+    label: "Declaration → RO",
+    caption: "customs declaration → Release Order",
+    icon: Ship,
+    tone: "green",
+    direction: "EXPORT",
+  },
+  {
+    key: "arrivalToGatePass",
+    label: "Arrival → gate pass",
+    caption: "train arrival → first gate pass",
+    icon: ShieldCheck,
+    tone: "green",
+    direction: "EXPORT",
+  },
+  {
+    key: "arrivalToDjiboutiT1",
+    label: "Arrival → Djibouti T1",
+    caption: "train arrival → first Djibouti T1",
+    icon: FileStack,
+    tone: "green",
+    direction: "EXPORT",
+  },
+  {
+    key: "bookingToDo",
+    label: "Booking → DO",
+    caption: "booking created → Delivery Order",
+    icon: PackageCheck,
+    tone: "green",
+    direction: "IMPORT",
+  },
+  {
+    key: "departureToT1",
+    label: "Departure → T1",
+    caption: "train departure → T1 documents",
+    icon: FileStack,
+    tone: "green",
+    direction: "IMPORT",
+  },
+  {
+    key: "arrivalToFinish",
+    label: "Arrival → finished",
+    caption: "train arrival → assignment finished",
+    icon: CheckCircle2,
+    tone: "amber",
+  },
+];
+
+// ── Pieces ───────────────────────────────────────────────────────────────────
+
+function PanelHead({
+  title,
+  hint,
+  right,
+}: {
+  title: string;
+  hint?: string;
+  right?: React.ReactNode;
+}) {
+  return (
+    <Group justify="space-between" align="start" wrap="nowrap" mb="md">
+      <Box>
+        <Text fz={15} fw={700} c="edr-text">
+          {title}
+        </Text>
+        {hint ? (
+          <Text fz={12} c="edr-muted" mt={2}>
+            {hint}
+          </Text>
+        ) : null}
+      </Box>
+      {right}
+    </Group>
+  );
+}
+
+/** One headline count: soft icon chip, tight numeral, muted label. */
+function CountKpi({
+  icon: Icon,
+  label,
+  value,
+  caption,
+  tone,
+  divider,
+}: {
+  icon: typeof Timer;
+  label: string;
+  value: number;
+  caption: string;
+  tone: Tone;
+  divider?: boolean;
+}) {
+  const t = TONES[tone];
+  return (
+    <Box
+      className={
+        divider
+          ? "flex flex-col border-t border-edr-divider pt-5 lg:border-l lg:border-t-0 lg:pl-6 lg:pt-0"
+          : "flex flex-col"
+      }
+    >
+      <Group gap={12} wrap="nowrap" align="start">
+        <Box
+          className="flex size-10 shrink-0 items-center justify-center rounded-xl"
+          style={{ background: t.soft }}
+        >
+          <Icon size={18} color={t.ink} strokeWidth={2} />
+        </Box>
+        <Box className="min-w-0">
+          <Text fz={26} fw={800} lh={1.05} c="edr-text" className="tracking-tight">
+            {value}
+          </Text>
+          <Text fz={12} fw={600} c="edr-text" mt={6} truncate>
+            {label}
+          </Text>
+          <Text fz={11} c="edr-muted" truncate>
+            {caption}
+          </Text>
+        </Box>
+      </Group>
+    </Box>
+  );
+}
+
+/** One measured duration: the median headline, with the spread underneath. */
+function TimingKpi({
+  icon: Icon,
+  label,
+  caption,
+  summary,
+  tone,
+}: {
+  icon: typeof Timer;
+  label: string;
+  caption: string;
+  summary: TransitTimingSummary;
+  tone: Tone;
+}) {
+  const t = TONES[summary.measured ? tone : "slate"];
+  const [value, unit] = splitDuration(summary.median);
+  return (
+    <Box
+      className="rounded-2xl border border-edr-border p-4"
+      style={{ background: summary.measured ? "#fff" : cv("edr-slate-soft2") }}
+    >
+      <Group gap={10} wrap="nowrap" align="center" mb={10}>
+        <Box
+          className="flex size-8 shrink-0 items-center justify-center rounded-lg"
+          style={{ background: t.soft }}
+        >
+          <Icon size={15} color={t.ink} strokeWidth={2} />
+        </Box>
+        <Box className="min-w-0">
+          <Text fz={12} fw={700} c="edr-text" truncate>
+            {label}
+          </Text>
+          <Text fz={10.5} c="edr-muted" truncate>
+            {caption}
+          </Text>
+        </Box>
+      </Group>
+      <Group gap={5} align="baseline" wrap="nowrap">
+        <Text fz={24} fw={800} lh={1.05} c="edr-text" className="tracking-tight">
+          {value}
+        </Text>
+        {unit ? (
+          <Text fz={12} fw={600} c="edr-muted">
+            {unit}
+          </Text>
+        ) : null}
+        <Text fz={11} c="edr-muted" ml={4}>
+          median
+        </Text>
+      </Group>
+      <Text fz={11} c="edr-muted" mt={6}>
+        {summary.measured
+          ? `${summary.measured} measured · fastest ${formatMinutes(summary.fastest)} · slowest ${formatMinutes(summary.slowest)}`
+          : "Nothing measured yet"}
+      </Text>
+    </Box>
+  );
+}
+
+function DirectionChip({ direction }: { direction: "IMPORT" | "EXPORT" }) {
+  const tone: Tone = direction === "EXPORT" ? "green" : "blue";
+  return (
+    <Box
+      px={7}
+      py={2}
+      className="shrink-0 rounded-md"
+      style={{ background: TONES[tone].soft }}
+    >
+      <Text fz={10} fw={700} style={{ color: TONES[tone].ink }}>
+        {direction === "EXPORT" ? "EXP" : "IMP"}
+      </Text>
+    </Box>
+  );
+}
+
+/** Where a shipment is on the rail leg, from its own stamps. */
+function movementOf(item: TransitStatItem): { label: string; tone: Tone } {
+  if (item.status === "FINISHED") return { label: "Finished", tone: "green" };
+  if (item.arrivedAt) return { label: "Arrived", tone: "green" };
+  if (item.departedAt) return { label: "In transit", tone: "blue" };
+  return { label: "Awaiting departure", tone: "slate" };
+}
+
+/** A small "+3h 20m" chip for one document's offset from its reference event. */
+function OffsetChip({
+  icon: Icon,
+  minutes,
+  title,
+  tone = "green",
+}: {
+  icon: typeof FileText;
+  minutes: number | null;
+  title: string;
+  tone?: Tone;
+}) {
+  if (minutes === null) return null;
+  const t = TONES[minutes < 0 ? "slate" : tone];
+  return (
+    <Tooltip label={title} withArrow>
+      <Group
+        gap={4}
+        px={6}
+        py={2}
+        wrap="nowrap"
+        className="rounded-md"
+        style={{ background: t.soft }}
+      >
+        <Icon size={10} color={t.ink} />
+        <Text fz={10} fw={700} style={{ color: t.ink }} className="font-mono">
+          {minutes < 0 ? "−" : "+"}
+          {formatMinutes(Math.abs(minutes))}
+        </Text>
+      </Group>
+    </Tooltip>
+  );
+}
+
+/**
+ * One shipment's rail leg on a shared scale — departure to arrival — with the
+ * paperwork timed against it. A still-rolling train shows its time so far.
+ */
+function MovementRow({
+  item,
+  scaleMax,
+  onOpen,
+}: {
+  item: TransitStatItem;
+  scaleMax: number;
+  onOpen: () => void;
+}) {
+  const movement = movementOf(item);
+  const transit =
+    item.timings.transit ??
+    (item.departedAt
+      ? Math.floor((Date.now() - new Date(item.departedAt).getTime()) / 60_000)
+      : null);
+  const live = item.timings.transit === null && item.departedAt !== null;
+  const width = transit !== null ? `${Math.min((transit / scaleMax) * 100, 100)}%` : "0%";
+  const isExport = item.tradeDirection === "EXPORT";
+
+  return (
+    <Box
+      onClick={onOpen}
+      className="cursor-pointer rounded-xl px-2 py-3 transition-colors hover:bg-edr-slate-soft2"
+    >
+      <Group gap="md" wrap="nowrap" align="center">
+        <Box className="w-[190px] shrink-0">
+          <Group gap={6} wrap="nowrap">
+            <DirectionChip direction={item.tradeDirection} />
+            <Text fz={12} fw={700} c="edr-text" className="font-mono" truncate>
+              {item.reference ?? "—"}
+            </Text>
+          </Group>
+          <Text fz={10.5} c="edr-muted" truncate mt={2}>
+            {item.customerName ?? "—"}
+            {item.trainLabel ? ` · ${item.trainLabel}` : ""}
+          </Text>
+        </Box>
+
+        <Box className="w-[118px] shrink-0">
+          <Text fz={10} c="edr-muted">
+            Departed
+          </Text>
+          <Text fz={11.5} fw={600} c="edr-text">
+            {formatStamp(item.departedAt)}
+          </Text>
+        </Box>
+
+        <Box className="relative flex h-7 flex-1 items-center overflow-hidden rounded-lg bg-edr-slate-soft2">
+          {transit !== null ? (
+            <Box
+              className="h-7 shrink-0 rounded-lg"
+              style={{
+                width,
+                background: live ? cv("edr-blue-dot") : TONES.blue.ink,
+                opacity: live ? 0.55 : 1,
+              }}
+            />
+          ) : null}
+          <Text
+            fz={10.5}
+            fw={700}
+            className="absolute left-2 font-mono"
+            style={{ color: transit !== null ? "#fff" : cv("edr-muted") }}
+          >
+            {transit === null
+              ? "not departed"
+              : live
+                ? `${formatMinutes(transit)} so far`
+                : formatMinutes(transit)}
+          </Text>
+        </Box>
+
+        <Box className="w-[118px] shrink-0">
+          <Text fz={10} c="edr-muted">
+            Arrived
+          </Text>
+          <Text fz={11.5} fw={600} c="edr-text">
+            {item.arrivedAt ? formatStamp(item.arrivedAt) : live ? "in transit" : "—"}
+          </Text>
+        </Box>
+
+        <Group gap={4} wrap="nowrap" className="w-[210px] shrink-0 justify-end">
+          {isExport ? (
+            <>
+              <OffsetChip
+                icon={Ship}
+                minutes={item.timings.declarationToRo}
+                title="Release Order after the customs declaration"
+              />
+              <OffsetChip
+                icon={ShieldCheck}
+                minutes={item.timings.arrivalToGatePass}
+                title="First gate pass after arrival"
+              />
+              <OffsetChip
+                icon={FileStack}
+                minutes={item.timings.arrivalToDjiboutiT1}
+                title="First Djibouti T1 after arrival"
+              />
+            </>
+          ) : (
+            <>
+              <OffsetChip
+                icon={PackageCheck}
+                minutes={item.timings.bookingToDo}
+                title="Delivery Order after the booking was created"
+              />
+              <OffsetChip
+                icon={FileStack}
+                minutes={item.timings.departureToT1}
+                title="T1 documents after train departure"
+              />
+            </>
+          )}
+          <Box
+            px={8}
+            py={3}
+            className="shrink-0 rounded-full"
+            style={{ background: TONES[movement.tone].soft }}
+          >
+            <Text fz={10} fw={700} style={{ color: TONES[movement.tone].ink }}>
+              {movement.label}
+            </Text>
+          </Box>
+        </Group>
+      </Group>
+    </Box>
+  );
+}
+
+/** A shipment that needs an upload now, with the context that makes it urgent. */
+function ActionRow({ item, onOpen }: { item: TransitStatItem; onOpen: () => void }) {
+  const doc = item.nextAction.document ?? "ro";
+  const Icon = DOC_ICON[doc];
+  // The reference event for this upload — what the clock is running from.
+  const since =
+    doc === "ro"
+      ? { label: "declared", at: item.declaredAt }
+      : doc === "do"
+        ? { label: "booked", at: item.bookingCreatedAt }
+        : doc === "t1"
+          ? { label: "departed", at: item.departedAt }
+          : { label: "arrived", at: item.arrivedAt };
+  const waited = since.at
+    ? Math.floor((Date.now() - new Date(since.at).getTime()) / 60_000)
+    : null;
+  const tone: Tone = waited === null ? "slate" : waited > 720 ? "red" : waited > 240 ? "amber" : "green";
+
+  return (
+    <Group
+      justify="space-between"
+      wrap="nowrap"
+      gap="md"
+      px={24}
+      py={12}
+      className="border-t border-edr-divider"
+    >
+      <Group gap={12} wrap="nowrap" className="min-w-0 flex-1">
+        <Box
+          className="flex size-9 shrink-0 items-center justify-center rounded-xl"
+          style={{ background: TONES[tone].soft }}
+        >
+          <Icon size={16} color={TONES[tone].ink} />
+        </Box>
+        <Box className="min-w-0">
+          <Group gap={6} wrap="nowrap">
+            <DirectionChip direction={item.tradeDirection} />
+            <Text fz={12.5} fw={700} c="edr-text" className="font-mono" truncate>
+              {item.reference ?? "—"}
+            </Text>
+            <Text fz={12} c="edr-muted" truncate>
+              {item.customerName ?? "—"}
+            </Text>
+          </Group>
+          <Text fz={11.5} c="edr-muted" mt={2} truncate>
+            <Text span fw={600} c="edr-text">
+              {item.nextAction.label}
+            </Text>
+            {since.at ? ` · ${since.label} ${ago(since.at)}` : ""}
+          </Text>
+        </Box>
+      </Group>
+      <Group gap={10} wrap="nowrap" className="shrink-0">
+        {waited !== null ? (
+          <Text fz={12} fw={700} className="font-mono" style={{ color: TONES[tone].ink }}>
+            {formatMinutes(waited)}
+          </Text>
+        ) : null}
+        <Button
+          size="compact-sm"
+          color="edr-green"
+          radius="md"
+          leftSection={<Upload size={13} />}
+          onClick={onOpen}
+        >
+          Upload
+        </Button>
+      </Group>
+    </Group>
+  );
+}
+
+function DocCountRow({
+  icon: Icon,
+  label,
+  count,
+  pending,
+}: {
+  icon: typeof FileText;
+  label: string;
+  count: number;
+  pending: number;
+}) {
+  return (
+    <Group justify="space-between" wrap="nowrap">
+      <Group gap={8} wrap="nowrap">
+        <Icon size={14} color={cv("edr-muted")} />
+        <Text fz={12.5} c="edr-text">
+          {label}
+        </Text>
+      </Group>
+      <Group gap={8} wrap="nowrap">
+        {pending > 0 ? (
+          <Text fz={11} fw={700} style={{ color: cv("edr-amber-text") }}>
+            {pending} pending
+          </Text>
+        ) : null}
+        <Text fz={12.5} fw={700} c="edr-text" className="w-6 text-right font-mono">
+          {count}
+        </Text>
+      </Group>
+    </Group>
+  );
+}
+
+function StageBar({
+  label,
+  count,
+  total,
+  tone,
+}: {
+  label: string;
+  count: number;
+  total: number;
+  tone: Tone;
+}) {
+  const pct = pctOf(count, total);
+  return (
+    <Box>
+      <Group justify="space-between" mb={6} wrap="nowrap">
+        <Group gap={8} wrap="nowrap">
+          <Box className="size-2 shrink-0 rounded-full" style={{ background: TONES[tone].ink }} />
+          <Text fz={12} fw={600} c="edr-text">
+            {label}
+          </Text>
+        </Group>
+        <Text fz={12} c="edr-muted">
+          {count} · {pct}%
+        </Text>
+      </Group>
+      <Box className="h-1.5 overflow-hidden rounded-full bg-edr-slate-soft2">
+        <Box className="h-full rounded-full" style={{ width: `${pct}%`, background: TONES[tone].ink }} />
+      </Box>
+    </Box>
+  );
+}
+
+// ── Page ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The transit agent's home: where each shipment is on the rail leg, what
+ * paperwork is due next, and how long each document takes measured from the
+ * event that unlocks it — the train's departure and arrival, the customs
+ * declaration, the booking's creation.
+ *
+ * Every figure comes from `GET /transit-assignments/my/stats`, derived there
+ * from timestamps that already exist. The page renders what the API measured
+ * rather than recomputing, so the two cannot disagree.
+ */
+export default function TransitAgentOverviewPage() {
+  const navigate = useNavigate();
+  const query = useQuery({
+    queryKey: ["transit-stats"],
+    queryFn: transitAssignmentsService.stats,
+    refetchInterval: 60_000,
+  });
+
+  const s: TransitStats | undefined = query.data;
+
+  const actions = useMemo(
+    () => (s?.items ?? []).filter((i) => i.nextAction.kind === "upload"),
+    [s],
+  );
+  const movements = useMemo(
+    () => (s?.items ?? []).filter((i) => i.departedAt || i.status !== "FINISHED").slice(0, 8),
+    [s],
+  );
+
+  // One shared scale: the longest completed transit, padded — a single
+  // multi-day outlier is capped so the others do not vanish into a sliver.
+  const scaleMax = useMemo(() => {
+    const measured = movements
+      .map((i) => i.timings.transit)
+      .filter((v): v is number => v !== null);
+    return Math.min(Math.max(...measured, 360) * 1.15, 4320);
+  }, [movements]);
+
+  // Show only the timings that can apply to this agent's mix of shipments.
+  const timingCards = useMemo(() => {
+    if (!s) return [];
+    return TIMINGS.filter(
+      (t) =>
+        !t.direction ||
+        (t.direction === "EXPORT" ? s.totals.exports > 0 : s.totals.imports > 0),
+    );
+  }, [s]);
+
+  if (query.isPending) {
+    return (
+      <Center h={420}>
+        <Loader size="sm" color="edr-green" />
+      </Center>
+    );
+  }
+
+  if (query.isError || !s) {
+    return (
+      <Box p={{ base: 16, sm: 24, lg: 32 }}>
+        <Card>
+          <Group gap="sm">
+            <AlertCircle size={18} color={cv("edr-red")} />
+            <Text fz={14} c="edr-text">
+              {(query.error as Error)?.message ?? "Could not load your overview."}
+            </Text>
+          </Group>
+        </Card>
+      </Box>
+    );
+  }
+
+  const { totals, timings, documents, pending } = s;
+  const openDetail = (item: TransitStatItem) => navigate(`/transit-agent/bookings/${item.id}`);
+  const waiting = s.items.filter((i) => i.nextAction.kind === "wait");
+
+  return (
+    <Box className="bg-edr-bg" p={{ base: 16, sm: 24, lg: 32 }}>
+      <Stack gap="lg">
+        <Group justify="space-between" align="end" wrap="wrap" gap="sm">
+          <Box>
+            <Text fz={26} fw={800} c="edr-text" className="tracking-tight">
+              Transit overview
+            </Text>
+            <Text fz={13} c="edr-muted" mt={4}>
+              Where your shipments are on the rail leg, what paperwork is due,
+              and how long each document takes from the moment it unlocks
+            </Text>
+          </Box>
+          <Group gap="sm" wrap="nowrap">
+            {totals.actionNeeded > 0 ? (
+              <Group
+                gap={8}
+                px={12}
+                py={7}
+                className="rounded-full"
+                style={{ background: cv("edr-amber-soft") }}
+                wrap="nowrap"
+              >
+                <Box className="size-1.5 rounded-full" style={{ background: cv("edr-amber-text") }} />
+                <Text fz={12} fw={700} style={{ color: cv("edr-amber-text") }}>
+                  {totals.actionNeeded} upload{totals.actionNeeded === 1 ? "" : "s"} due
+                </Text>
+              </Group>
+            ) : totals.open > 0 ? (
+              <Group
+                gap={8}
+                px={12}
+                py={7}
+                className="rounded-full"
+                style={{ background: cv("edr-soft") }}
+                wrap="nowrap"
+              >
+                <Box className="size-1.5 rounded-full" style={{ background: cv("edr-green.6") }} />
+                <Text fz={12} fw={700} style={{ color: cv("edr-green.7") }}>
+                  {totals.open} active · paperwork up to date
+                </Text>
+              </Group>
+            ) : null}
+            <Button
+              variant="default"
+              radius="md"
+              rightSection={<ArrowRight size={14} />}
+              onClick={() => navigate("/transit-agent/bookings")}
+            >
+              All bookings
+            </Button>
+          </Group>
+        </Group>
+
+        {/* ── Where the shipments are ──────────────────────────────── */}
+        <Card>
+          <Box className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-5">
+            <CountKpi
+              icon={Train}
+              label="Assigned to you"
+              value={totals.assignments}
+              caption={`${totals.exports} export · ${totals.imports} import`}
+              tone="slate"
+            />
+            <CountKpi
+              icon={Hourglass}
+              label="Awaiting departure"
+              value={totals.awaitingDeparture}
+              caption="open, train not yet departed"
+              tone="slate"
+              divider
+            />
+            <CountKpi
+              icon={Route}
+              label="In transit"
+              value={totals.inTransit}
+              caption="departed, not yet arrived"
+              tone="blue"
+              divider
+            />
+            <CountKpi
+              icon={MapPin}
+              label="Arrived"
+              value={totals.arrived}
+              caption="at destination, still open"
+              tone="green"
+              divider
+            />
+            <CountKpi
+              icon={Upload}
+              label="Uploads due"
+              value={totals.actionNeeded}
+              caption="documents you can file now"
+              tone={totals.actionNeeded > 0 ? "amber" : "green"}
+              divider
+            />
+          </Box>
+        </Card>
+
+        {/* ── Timings ──────────────────────────────────────────────── */}
+        <Card>
+          <PanelHead
+            title="How long each step takes"
+            hint="Median across your shipments, each measured from the event that unlocks it. A replaced document counts from its last update."
+          />
+          <Box className="grid grid-cols-1 gap-3 sm:grid-cols-2 xl:grid-cols-4">
+            {timingCards.map((t) => (
+              <TimingKpi
+                key={t.key}
+                icon={t.icon}
+                label={t.label}
+                caption={t.caption}
+                summary={timings[t.key]}
+                tone={t.tone}
+              />
+            ))}
+          </Box>
+        </Card>
+
+        <Box className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+          {/* ── Action needed ────────────────────────────────────── */}
+          <Box className="lg:col-span-2">
+            <Card padding={0}>
+              <Box px={24} pt={20} pb={14}>
+                <PanelHead
+                  title="Paperwork due now"
+                  hint="Uploads the detail page will accept right now, oldest wait first"
+                  right={
+                    <Text fz={11} c="edr-muted">
+                      {waiting.length} waiting on the train or the desk
+                    </Text>
+                  }
+                />
+              </Box>
+              {actions.length === 0 ? (
+                <Box px={24} pb={24}>
+                  <Group
+                    gap={10}
+                    p={14}
+                    align="start"
+                    wrap="nowrap"
+                    className="rounded-xl"
+                    style={{ background: cv("edr-soft") }}
+                  >
+                    <CheckCircle2 size={16} color={cv("edr-green.7")} className="shrink-0" />
+                    <Box>
+                      <Text fz={12.5} fw={700} style={{ color: cv("edr-green.7") }}>
+                        Nothing to upload right now.
+                      </Text>
+                      <Text fz={11.5} lh={1.5} c="edr-muted" mt={2}>
+                        {waiting.length > 0
+                          ? `${waiting.length} shipment${waiting.length === 1 ? " is" : "s are"} waiting on a declaration or on the train — they will appear here the moment an upload unlocks.`
+                          : "Every shipment assigned to you has its paperwork complete."}
+                      </Text>
+                    </Box>
+                  </Group>
+                </Box>
+              ) : (
+                <Box pb={6}>
+                  {[...actions]
+                    .sort((a, b) => {
+                      const ref = (i: TransitStatItem) =>
+                        i.nextAction.document === "ro"
+                          ? i.declaredAt
+                          : i.nextAction.document === "do"
+                            ? i.bookingCreatedAt
+                            : i.nextAction.document === "t1"
+                              ? i.departedAt
+                              : i.arrivedAt;
+                      return (ref(a) ?? "9").localeCompare(ref(b) ?? "9");
+                    })
+                    .map((item) => (
+                      <ActionRow key={item.id} item={item} onOpen={() => openDetail(item)} />
+                    ))}
+                </Box>
+              )}
+            </Card>
+          </Box>
+
+          {/* ── Documents + stages ───────────────────────────────── */}
+          <Stack gap="md">
+            <Card>
+              <PanelHead
+                title="Documents on file"
+                hint="Across every shipment assigned to you"
+                right={
+                  <Text fz={11} c="edr-muted">
+                    {documents.ro + documents.do + documents.t1 + documents.gatePass + documents.djiboutiT1 + documents.own}{" "}
+                    files
+                  </Text>
+                }
+              />
+              <Stack gap={10}>
+                {totals.exports > 0 ? (
+                  <>
+                    <DocCountRow icon={Ship} label="Release Orders" count={documents.ro} pending={pending.ro} />
+                    <DocCountRow icon={ShieldCheck} label="Gate passes" count={documents.gatePass} pending={pending.gatePass} />
+                    <DocCountRow icon={FileStack} label="Djibouti T1" count={documents.djiboutiT1} pending={pending.djiboutiT1} />
+                  </>
+                ) : null}
+                {totals.imports > 0 ? (
+                  <>
+                    <DocCountRow icon={PackageCheck} label="Delivery Orders" count={documents.do} pending={pending.do} />
+                    <DocCountRow icon={FileStack} label="T1 documents" count={documents.t1} pending={pending.t1} />
+                  </>
+                ) : null}
+                <DocCountRow icon={FileText} label="Your own documents" count={documents.own} pending={0} />
+              </Stack>
+            </Card>
+
+            <Card>
+              <PanelHead
+                title="Shipment stages"
+                right={
+                  <Text fz={11} c="edr-muted">
+                    {totals.assignments} total
+                  </Text>
+                }
+              />
+              <Stack gap={14}>
+                <StageBar label="Awaiting departure" count={totals.awaitingDeparture} total={totals.assignments} tone="slate" />
+                <StageBar label="In transit" count={totals.inTransit} total={totals.assignments} tone="blue" />
+                <StageBar label="Arrived, open" count={totals.arrived} total={totals.assignments} tone="amber" />
+                <StageBar label="Finished" count={totals.finished} total={totals.assignments} tone="green" />
+              </Stack>
+            </Card>
+          </Stack>
+        </Box>
+
+        {/* ── Train movements ──────────────────────────────────────── */}
+        <Card padding={0}>
+          <Box px={24} pt={20} pb={6}>
+            <PanelHead
+              title="Train movements"
+              hint="Departure to arrival for each shipment, with its paperwork timed against the train"
+              right={
+                <Group gap={14} wrap="nowrap">
+                  {(
+                    [
+                      [TONES.blue.ink, "arrived"],
+                      [cv("edr-blue-dot"), "still rolling"],
+                      [TONES.green.soft, "doc offset"],
+                    ] as const
+                  ).map(([color, label]) => (
+                    <Group gap={6} key={label} wrap="nowrap">
+                      <Box className="size-2 rounded-sm" style={{ background: color }} />
+                      <Text fz={11} c="edr-muted">
+                        {label}
+                      </Text>
+                    </Group>
+                  ))}
+                </Group>
+              }
+            />
+          </Box>
+          {movements.length === 0 ? (
+            <Text fz={13} c="edr-muted" ta="center" py={40}>
+              No shipments on the rail yet.
+            </Text>
+          ) : (
+            <Box px={16} pb={12} className="overflow-x-auto">
+              <Stack gap={2} className="min-w-[900px]">
+                {movements.map((item) => (
+                  <MovementRow
+                    key={item.id}
+                    item={item}
+                    scaleMax={scaleMax}
+                    onOpen={() => openDetail(item)}
+                  />
+                ))}
+              </Stack>
+            </Box>
+          )}
+        </Card>
+
+        {/* ── Recent assignments ───────────────────────────────────── */}
+        <Card padding={0}>
+          <Box px={24} pt={20} pb={14}>
+            <PanelHead
+              title="Recent assignments"
+              right={
+                <Text fz={11} c="edr-muted">
+                  {totals.assignments} total
+                </Text>
+              }
+            />
+          </Box>
+          {s.items.slice(0, 8).map((item) => {
+            const movement = movementOf(item);
+            return (
+              <Group
+                key={item.id}
+                justify="space-between"
+                px={24}
+                py={12}
+                wrap="nowrap"
+                className="cursor-pointer border-t border-edr-divider hover:bg-edr-slate-soft2"
+                onClick={() => openDetail(item)}
+              >
+                <Group gap="md" wrap="nowrap" className="min-w-0 flex-1">
+                  <DirectionChip direction={item.tradeDirection} />
+                  <Text fz={12} fw={600} c="edr-text" className="w-[132px] font-mono" truncate>
+                    {item.reference ?? "—"}
+                  </Text>
+                  <Box px={9} py={3} className="shrink-0 rounded-full" style={{ background: TONES[movement.tone].soft }}>
+                    <Text fz={10} fw={700} style={{ color: TONES[movement.tone].ink }}>
+                      {movement.label}
+                    </Text>
+                  </Box>
+                  <Text fz={12} c="edr-muted" truncate>
+                    {item.customerName ?? "—"}
+                  </Text>
+                </Group>
+                <Group gap={18} wrap="nowrap" className="shrink-0">
+                  <Group gap={6} wrap="nowrap">
+                    <Clock3 size={12} color={cv("edr-muted")} />
+                    <Text fz={11.5} c="edr-muted" className="font-mono">
+                      {item.arrivedAt
+                        ? `arrived ${ago(item.arrivedAt)}`
+                        : item.departedAt
+                          ? `departed ${ago(item.departedAt)}`
+                          : `assigned ${ago(item.assignedAt)}`}
+                    </Text>
+                  </Group>
+                  <Text
+                    fz={11.5}
+                    fw={600}
+                    className="w-[170px] truncate text-right"
+                    style={{
+                      color:
+                        item.nextAction.kind === "upload"
+                          ? cv("edr-amber-text")
+                          : item.nextAction.kind === "done"
+                            ? cv("edr-green.7")
+                            : cv("edr-muted"),
+                    }}
+                  >
+                    {item.nextAction.label}
+                  </Text>
+                </Group>
+              </Group>
+            );
+          })}
+        </Card>
+      </Stack>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/TransitClearanceActionPanel.tsx b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitClearanceActionPanel.tsx
new file mode 100644
index 000000000..3fe55cfb8
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitClearanceActionPanel.tsx
@@ -0,0 +1,434 @@
+import {
+  Alert,
+  Box,
+  Button,
+  Card,
+  Group,
+  Modal,
+  Progress,
+  Stack,
+  Stepper,
+  Text,
+  Textarea,
+  ThemeIcon,
+} from "@mantine/core";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import {
+  AlertTriangle,
+  ArrowRight,
+  CheckCircle2,
+  Ship,
+  X,
+} from "lucide-react";
+import { useState } from "react";
+import toast from "react-hot-toast";
+import type { Freight } from "@edr/types";
+import { isReleaseOrderFileCode } from "@edr/types";
+
+import { transitAssignmentsService } from "@/services/transit-assignments.service";
+
+interface WizardStep {
+  label: string;
+  description: string;
+  done: boolean;
+}
+
+type MilestoneRow = { milestoneCode?: string | null; status?: string | null };
+
+/** SKIPPED counts as done — a step that does not apply must not stall the flow. */
+function isMilestoneDone(
+  milestones: MilestoneRow[] | undefined,
+  code: string,
+): boolean {
+  const m = milestones?.find((x) => x.milestoneCode === code);
+  return m?.status === "COMPLETED" || m?.status === "SKIPPED";
+}
+
+/**
+ * The clearance stepper a transit agent sees on a shipment assigned to them,
+ * laid out as the backoffice's clearance action panel is, plus the RO
+ * amendment request. The uploads themselves (DO, RO, T1, gate pass, Djibouti
+ * T1) live in the transit documents panel, where their timings are shown.
+ *
+ * The steps are rendered from the clearance payload rather than re-derived.
+ */
+export function TransitClearanceActionPanel({
+  bookingId,
+  clearance,
+  tradeDirection,
+  onChanged,
+}: {
+  bookingId: string;
+  clearance?: Freight.ClearanceView;
+  tradeDirection?: string | null;
+  onChanged: () => void;
+}) {
+  const queryClient = useQueryClient();
+  const [amendOpen, setAmendOpen] = useState(false);
+
+  const isImport = tradeDirection === "IMPORT";
+  const workflowFiles = clearance?.workflowFiles ?? [];
+  const hasRo = workflowFiles.some(
+    (f) => isReleaseOrderFileCode(f.code) && f.file,
+  );
+  const roHoldReason = clearance?.roHoldReason ?? null;
+
+  const refresh = () => {
+    void queryClient.invalidateQueries({ queryKey: ["transit-clearance"] });
+    void queryClient.invalidateQueries({
+      queryKey: ["transit-clearance-history"],
+    });
+    onChanged();
+  };
+
+  // ── Steps ────────────────────────────────────────────────────────────────
+  // The same wizards the GL Djibouti desk sees: 12 import steps, 11 export.
+  // Every `done` reads off the clearance payload — milestones, booking
+  // milestones, or a server-set flag — so a step can never claim to be
+  // complete when the server does not consider it so.
+  // This page is always booking-scoped, and for a booking the clearance view's
+  // milestones ARE the booking milestones — the GL detail page passes the same
+  // array for both on its `kind === "booking"` branch.
+  const ms = clearance?.milestones;
+  const done = (code: string) => isMilestoneDone(ms, code);
+  const bookingDone = (code: string) => isMilestoneDone(ms, code);
+  const dutyRequired = clearance?.dutyRequired ?? false;
+
+  const steps: WizardStep[] = isImport
+    ? [
+        {
+          label: "Customer documents",
+          description: "Reviewed and approved by GL Ethiopia",
+          done: done("DOCUMENTS_APPROVED"),
+        },
+        {
+          label: "Request transit assignee",
+          description: clearance?.transitAssignee?.name
+            ? `Transit assignee: ${clearance.transitAssignee.name}`
+            : "GL Djibouti names the officer handling this shipment",
+          done: Boolean(clearance?.transitAssignee?.name),
+        },
+        {
+          label: "Draft declaration",
+          description: "Customer accepts the estimated price",
+          done: done("DRAFT_DECLARATION_ACCEPTED") || done("DECLARED"),
+        },
+        {
+          label: "Customs declaration",
+          description: "GL Ethiopia uploads declaration documents",
+          done: done("DECLARED"),
+        },
+        {
+          label: "Duty & tax",
+          description: "Amount advised and notice attached",
+          // A shipment with no duty due skips this rather than stalling on it.
+          done: !dutyRequired || done("DUTY_TAXES_ADVISED"),
+        },
+        {
+          label: "Customer payment",
+          description: "Customer uploads the duty payment slip",
+          done: !dutyRequired || done("DUTY_TAX_PAID"),
+        },
+        {
+          label: "Transit Permit",
+          description: "Transit permit documents uploaded",
+          done: done("TRANSIT_PERMIT_UPLOADED"),
+        },
+        {
+          label: "Finalize pre-clearance",
+          description: "GL Ethiopia hands off to GL Djibouti",
+          done: Boolean(clearance?.preClearanceFinalized),
+        },
+        {
+          label: "Delivery Order",
+          description: "You upload the DO with its collection dates",
+          done: done("DO_COLLECTED"),
+        },
+        {
+          label: "Create booking",
+          description: "GL Ethiopia books for the customer",
+          done: Boolean(clearance?.t1) || bookingDone("FREIGHT_PAYMENT_SETTLED"),
+        },
+        {
+          label: "Freight payment",
+          description: "Customer pays the train and service charges",
+          done: bookingDone("FREIGHT_PAYMENT_SETTLED"),
+        },
+        {
+          label: "Gate pass",
+          description: "Secured after payment and wagon allocation",
+          done: Boolean(clearance?.gatepassGranted),
+        },
+      ]
+    : [
+        {
+          label: "Customer documents",
+          description: "Reviewed and approved by GL Ethiopia",
+          done: done("DOCUMENTS_APPROVED"),
+        },
+        {
+          label: "Request transit assignee",
+          description: clearance?.transitAssignee?.name
+            ? `Transit assignee: ${clearance.transitAssignee.name}`
+            : "GL Djibouti names the officer handling this shipment",
+          done: Boolean(clearance?.transitAssignee?.name),
+        },
+        {
+          label: "Customs declaration",
+          description: "GL Ethiopia uploads — releases the export",
+          done: done("DECLARED"),
+        },
+        {
+          label: "Release Order",
+          description: "You upload the RO with the vessel departure date",
+          done: done("RELEASE_ORDER_SECURED") || hasRo,
+        },
+        {
+          label: "Create booking",
+          description: "GL Ethiopia books for the customer",
+          done: bookingDone("FREIGHT_PAYMENT_SETTLED") || Boolean(clearance?.t1),
+        },
+        {
+          label: "Payment & wagon allocation",
+          description: "Customer pays; operations allocates wagons",
+          done:
+            bookingDone("FREIGHT_PAYMENT_SETTLED") &&
+            (bookingDone("WAGON_ALLOCATED") ||
+              Boolean(clearance?.train?.wagonAllocated)),
+        },
+        {
+          label: "Transport document",
+          description: "GL Ethiopia uploads after wagon allocation",
+          done: bookingDone("EXPORT_TRANSPORT_ISSUED"),
+        },
+        {
+          label: "Train to Djibouti",
+          description: "Departure and arrival",
+          done: Boolean(clearance?.train?.arrivedAt),
+        },
+        {
+          label: "Accept T1",
+          description: "You close the T1 once the train arrives",
+          done: Boolean(clearance?.t1Closed),
+        },
+        {
+          label: "Gate pass",
+          description: "Secured on the train schedule after arrival",
+          done: Boolean(clearance?.gatepassGranted),
+        },
+        {
+          label: "Offload",
+          description: "Cargo comes off the train",
+          done: Boolean(clearance?.offloaded ?? clearance?.offload?.offloaded),
+        },
+      ];
+
+  // The wizard sits on the FIRST step not yet done — matching the GL desk's
+  // "Step N of M", which counts the step being worked on, not the ones behind it.
+  const firstPending = steps.findIndex((s) => !s.done);
+  const activeStep = firstPending === -1 ? steps.length : firstPending;
+  const percent = Math.round((activeStep / steps.length) * 100);
+  const currentStep = steps[activeStep] ?? null;
+
+  return (
+    <>
+      <Card withBorder radius="md" p={0} style={{ overflow: "hidden" }}>
+        {/* Header: title, "Step N of M", and the progress bar — the GL desk's
+            own wizard chrome. */}
+        <Group
+          justify="space-between"
+          wrap="nowrap"
+          px={18}
+          py={12}
+          style={{ borderBottom: "1px solid var(--mantine-color-edr-divider-6)" }}
+        >
+          <Group gap={10} wrap="nowrap" style={{ minWidth: 0 }}>
+            <ThemeIcon variant="light" color="edr-green" radius="md" size={32}>
+              <Ship size={16} />
+            </ThemeIcon>
+            <Box style={{ minWidth: 0 }}>
+              <Text fw={700} fz={14} c="edr-text">
+                {isImport
+                  ? "Import pre-booking clearance"
+                  : "Export customs clearance"}
+              </Text>
+              <Text fz={11.5} c="dimmed">
+                Step {Math.min(activeStep + 1, steps.length)} of {steps.length}
+                {currentStep ? ` · ${currentStep.label}` : ""}
+              </Text>
+            </Box>
+          </Group>
+          <Group gap={8} wrap="nowrap" style={{ flexShrink: 0 }}>
+            <Progress
+              value={percent}
+              color="edr-green"
+              radius="xl"
+              size={6}
+              w={110}
+            />
+            <Text fz={11.5} c="#67788A" fw={600}>
+              {percent}%
+            </Text>
+          </Group>
+        </Group>
+
+        {/* Whose desk the flow is sitting on right now. */}
+        {clearance?.nextAction ? (
+          <Group
+            gap={10}
+            wrap="nowrap"
+            px={18}
+            py={12}
+            style={{
+              background: "#E9F1FC",
+              borderBottom: "1px solid #EFF3F7",
+            }}
+          >
+            <ArrowRight size={15} color="#1D6FD1" style={{ flexShrink: 0 }} />
+            <Text
+              fz={10.5}
+              fw={700}
+              lts="0.4px"
+              c="#1D6FD1"
+              style={{ flexShrink: 0 }}
+            >
+              {clearance.nextAction.actor.replace("_", " ").toUpperCase()}
+            </Text>
+            <Text fz={11.5} fw={600} c="edr-text" style={{ minWidth: 0 }}>
+              {clearance.nextAction.action}
+            </Text>
+          </Group>
+        ) : null}
+
+        <Box p="md">
+          {roHoldReason ? (
+            <Alert
+              color="red"
+              variant="light"
+              mb="sm"
+              icon={<AlertTriangle size={16} />}
+              title="RO amendment hold"
+            >
+              {roHoldReason}
+            </Alert>
+          ) : null}
+
+          <Stepper
+            active={activeStep}
+            orientation="vertical"
+            size="sm"
+            iconSize={26}
+            allowNextStepsSelect={false}
+            mb="md"
+          >
+            {steps.map((s) => (
+              <Stepper.Step
+                key={s.label}
+                label={s.label}
+                description={s.description}
+                icon={s.done ? <CheckCircle2 size={14} /> : undefined}
+              />
+            ))}
+          </Stepper>
+
+          {/* Every upload (DO, RO, T1, gate pass, Djibouti T1) lives in the
+              transit documents panel above the grid, where its timings are
+              shown; only the RO amendment request stays here. */}
+          <Stack gap={8}>
+          {!isImport ? (
+            <Button
+              variant="subtle"
+              color="red"
+              radius="md"
+              leftSection={<AlertTriangle size={15} />}
+              onClick={() => setAmendOpen(true)}
+            >
+              Request RO amendment
+            </Button>
+          ) : null}
+          </Stack>
+        </Box>
+      </Card>
+
+      <RoAmendmentModal
+        opened={amendOpen}
+        bookingId={bookingId}
+        onClose={() => setAmendOpen(false)}
+        onSuccess={refresh}
+      />
+    </>
+  );
+}
+
+function RoAmendmentModal({
+  opened,
+  bookingId,
+  onClose,
+  onSuccess,
+}: {
+  opened: boolean;
+  bookingId: string;
+  onClose: () => void;
+  onSuccess: () => void;
+}) {
+  const [note, setNote] = useState("");
+
+  const submit = useMutation({
+    mutationFn: () =>
+      transitAssignmentsService.requestRoAmendment(bookingId, note.trim()),
+    onSuccess: () => {
+      toast.success("RO amendment requested");
+      setNote("");
+      onSuccess();
+      onClose();
+    },
+    onError: (e: unknown) =>
+      toast.error(e instanceof Error ? e.message : "Request failed"),
+  });
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      radius="md"
+      size="md"
+      title={
+        <Group gap={8}>
+          <AlertTriangle size={18} />
+          <Text fw={700}>Request RO amendment</Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <Alert color="orange" variant="light" icon={<AlertTriangle size={16} />}>
+          This puts the shipment on hold until GL Ethiopia amends the Release
+          Order.
+        </Alert>
+        <Textarea
+          label="What needs to change?"
+          placeholder="Describe the correction needed on the Release Order"
+          minRows={3}
+          autosize
+          value={note}
+          onChange={(e) => setNote(e.currentTarget.value)}
+          required
+          withAsterisk
+        />
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" onClick={onClose} disabled={submit.isPending}>
+            Cancel
+          </Button>
+          <Button
+            color="red"
+            loading={submit.isPending}
+            disabled={note.trim().length === 0}
+            leftSection={<X size={16} />}
+            onClick={() => submit.mutate()}
+          >
+            Request amendment
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/TransitDocumentsPanel.tsx b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitDocumentsPanel.tsx
new file mode 100644
index 000000000..d8cc23f49
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/TransitDocumentsPanel.tsx
@@ -0,0 +1,1736 @@
+import {
+  ActionIcon,
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Group,
+  Modal,
+  Paper,
+  SimpleGrid,
+  Stack,
+  Text,
+  ThemeIcon,
+  Tooltip,
+} from "@mantine/core";
+import { DateInput } from "@mantine/dates";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import {
+  AlertTriangle,
+  ArrowRight,
+  CheckCircle2,
+  Clock3,
+  Download,
+  Eye,
+  FileCheck2,
+  FileStack,
+  FileText,
+  Lock,
+  MapPin,
+  PackageCheck,
+  Ship,
+  ShieldCheck,
+  Timer,
+  Train,
+  Trash2,
+  Upload,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+import toast from "react-hot-toast";
+import type { Freight } from "@edr/types";
+import {
+  isDeliveryOrderFileCode,
+  isDjiboutiT1FileCode,
+  isGatePassFileCode,
+  isReleaseOrderFileCode,
+  isT1TransportFileCode,
+} from "@edr/types";
+import { isViewable } from "@edr/ui-common";
+
+import {
+  PortalMultiFileDropzone,
+  formatBytes,
+} from "@/components/contracts/PortalMultiFileDropzone";
+import { BORDER, GREEN, INK, MUTED } from "@/pages/contracts/contract-ui";
+import {
+  downloadStoredFile,
+  fetchViewableFile,
+} from "@/services/files.service";
+import { transitAssignmentsService } from "@/services/transit-assignments.service";
+
+// ── Time helpers ─────────────────────────────────────────────────────────────
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/** "Sep 2, 2026, 14:05" — the officer reads these against a clock, not a calendar. */
+function formatStamp(value?: string | null): string {
+  if (!value) return "—";
+  return new Date(value).toLocaleString(undefined, {
+    dateStyle: "medium",
+    timeStyle: "short",
+  });
+}
+
+/** Signed duration in ms → "2d 4h 13m", "45m", "<1m". */
+function formatDuration(ms: number): string {
+  const abs = Math.abs(ms);
+  if (abs < MINUTE) return "<1m";
+  const days = Math.floor(abs / DAY);
+  const hours = Math.floor((abs % DAY) / HOUR);
+  const minutes = Math.floor((abs % HOUR) / MINUTE);
+  const parts: string[] = [];
+  if (days) parts.push(`${days}d`);
+  if (hours) parts.push(`${hours}h`);
+  if (minutes || parts.length === 0) parts.push(`${minutes}m`);
+  return parts.join(" ");
+}
+
+/** Elapsed between two stamps; null when either is missing. */
+function elapsed(from?: string | null, to?: string | null): string | null {
+  if (!from || !to) return null;
+  return formatDuration(new Date(to).getTime() - new Date(from).getTime());
+}
+
+/**
+ * How far an upload sits from a train event. "after" is the normal case; a
+ * document filed BEFORE the event (paperwork prepared in advance) is labeled
+ * so, never shown as a negative number.
+ */
+function offsetFrom(
+  base: string | null | undefined,
+  at: string | null | undefined,
+  event: string,
+): { text: string; late: boolean } | null {
+  if (!base || !at) return null;
+  const diff = new Date(at).getTime() - new Date(base).getTime();
+  return diff >= 0
+    ? { text: `${formatDuration(diff)} after ${event}`, late: false }
+    : { text: `${formatDuration(diff)} before ${event}`, late: true };
+}
+
+const latestOf = (stamps: Array<string | null | undefined>): string | null =>
+  stamps.reduce<string | null>(
+    (max, s) => (s && (!max || s > max) ? s : max),
+    null,
+  );
+
+const earliestOf = (stamps: Array<string | null | undefined>): string | null =>
+  stamps.reduce<string | null>(
+    (min, s) => (s && (!min || s < min) ? s : min),
+    null,
+  );
+
+/** Newest history event for an action, or null. History is newest-first. */
+function latestEvent(
+  history: Freight.ClearanceHistoryEvent[],
+  action: string,
+): Freight.ClearanceHistoryEvent | null {
+  return history.find((e) => e.action === action) ?? null;
+}
+
+// ── Small presentational pieces ──────────────────────────────────────────────
+
+/** One figure in a stat strip: label, big value, optional footnote. */
+function Stat({
+  icon: Icon,
+  label,
+  value,
+  hint,
+  tone = "default",
+}: {
+  icon: typeof Clock3;
+  label: string;
+  value: React.ReactNode;
+  hint?: React.ReactNode;
+  tone?: "default" | "green" | "blue" | "orange" | "muted";
+}) {
+  const color =
+    tone === "green"
+      ? "edr-green"
+      : tone === "blue"
+        ? "blue"
+        : tone === "orange"
+          ? "orange"
+          : "gray";
+  return (
+    <Paper
+      radius="md"
+      p="sm"
+      style={{
+        border: `1px solid ${BORDER}`,
+        background: tone === "muted" ? "#FAFCFE" : "#fff",
+        minWidth: 0,
+      }}
+    >
+      <Group gap={8} wrap="nowrap" mb={6}>
+        <ThemeIcon variant="light" color={color} radius="md" size={26}>
+          <Icon size={14} />
+        </ThemeIcon>
+        <Text fz={11} fw={700} c="dimmed" tt="uppercase" lts="0.3px" truncate>
+          {label}
+        </Text>
+      </Group>
+      <Text fz={15} fw={700} style={{ color: INK }} truncate>
+        {value}
+      </Text>
+      {hint ? (
+        <Text fz={11.5} c="dimmed" mt={2} truncate>
+          {hint}
+        </Text>
+      ) : null}
+    </Paper>
+  );
+}
+
+function OffsetChip({
+  offset,
+  color,
+}: {
+  offset: { text: string; late: boolean } | null;
+  color: string;
+}) {
+  if (!offset) return null;
+  return (
+    <Badge
+      size="xs"
+      variant="light"
+      radius="sm"
+      tt="none"
+      color={offset.late ? "gray" : color}
+      leftSection={<Timer size={10} />}
+    >
+      {offset.text}
+    </Badge>
+  );
+}
+
+/** A stored document row: name, stamp, train offsets, view / download / remove. */
+function StoredDocumentRow({
+  item,
+  train,
+  onView,
+  onRemove,
+  removing,
+}: {
+  item: Freight.ClearanceWorkflowFile;
+  train?: Freight.ClearanceTrainState | null;
+  onView: (file: { name: string; url: string; mimeType?: string | null }) => void;
+  onRemove?: (file: { id: string; name: string }) => void;
+  removing?: boolean;
+}) {
+  const file = item.file;
+  if (!file) return null;
+  const canPreview = isViewable({ name: file.name, url: "" });
+  const uploadedAt = file.uploadedAt ?? null;
+
+  return (
+    <Paper radius="md" p="sm" style={{ border: `1px solid ${BORDER}` }}>
+      <Group justify="space-between" wrap="nowrap" align="flex-start" gap="sm">
+        <Group gap={10} wrap="nowrap" style={{ minWidth: 0, flex: 1 }}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={38}>
+            <FileText size={17} />
+          </ThemeIcon>
+          <Box style={{ minWidth: 0 }}>
+            <Group gap={6} wrap="nowrap">
+              <Text size="sm" fw={600} truncate style={{ color: INK }}>
+                {item.label}
+              </Text>
+              {file.size ? (
+                <Text size="xs" c="dimmed" style={{ flexShrink: 0 }}>
+                  · {formatBytes(file.size)}
+                </Text>
+              ) : null}
+            </Group>
+            <Text size="xs" c="dimmed" truncate>
+              {file.name}
+            </Text>
+            <Group gap={6} mt={6} wrap="wrap">
+              <Badge
+                size="xs"
+                variant="outline"
+                color="gray"
+                radius="sm"
+                tt="none"
+                leftSection={<Clock3 size={10} />}
+              >
+                {formatStamp(uploadedAt)}
+              </Badge>
+              {train ? (
+                <>
+                  <OffsetChip
+                    offset={offsetFrom(train.departedAt, uploadedAt, "departure")}
+                    color="blue"
+                  />
+                  <OffsetChip
+                    offset={offsetFrom(train.arrivedAt, uploadedAt, "arrival")}
+                    color="edr-green"
+                  />
+                </>
+              ) : null}
+            </Group>
+          </Box>
+        </Group>
+        <Group gap={4} wrap="nowrap" style={{ flexShrink: 0 }}>
+          {canPreview ? (
+            <Tooltip label="Preview" withArrow>
+              <ActionIcon
+                variant="default"
+                radius="md"
+                aria-label="Preview"
+                onClick={() =>
+                  void fetchViewableFile(file.id, file.name).then(onView)
+                }
+              >
+                <Eye size={15} />
+              </ActionIcon>
+            </Tooltip>
+          ) : null}
+          <Tooltip label="Download" withArrow>
+            <ActionIcon
+              variant="default"
+              radius="md"
+              aria-label="Download"
+              onClick={() => void downloadStoredFile(file.id, file.name)}
+            >
+              <Download size={15} />
+            </ActionIcon>
+          </Tooltip>
+          {onRemove ? (
+            <Tooltip label="Remove" withArrow>
+              <ActionIcon
+                variant="subtle"
+                color="red"
+                radius="md"
+                aria-label="Remove"
+                loading={removing}
+                onClick={() => onRemove({ id: file.id, name: file.name })}
+              >
+                <Trash2 size={15} />
+              </ActionIcon>
+            </Tooltip>
+          ) : null}
+        </Group>
+      </Group>
+    </Paper>
+  );
+}
+
+function EmptyDocs({ icon: Icon, children }: { icon: typeof FileText; children: React.ReactNode }) {
+  return (
+    <Box
+      py="lg"
+      px="md"
+      style={{
+        borderRadius: 12,
+        border: `1px dashed ${BORDER}`,
+        background: "#FAFCFE",
+        textAlign: "center",
+      }}
+    >
+      <Stack gap={6} align="center">
+        <ThemeIcon variant="light" color="gray" radius="xl" size={40}>
+          <Icon size={18} />
+        </ThemeIcon>
+        <Text size="sm" c="dimmed" maw={360}>
+          {children}
+        </Text>
+      </Stack>
+    </Box>
+  );
+}
+
+/** Card chrome shared by the three document sections. */
+function DocumentCard({
+  icon: Icon,
+  title,
+  subtitle,
+  status,
+  action,
+  children,
+}: {
+  icon: typeof FileText;
+  title: string;
+  subtitle: string;
+  status?: React.ReactNode;
+  action?: React.ReactNode;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card withBorder radius="md" p={0} style={{ overflow: "hidden", height: "100%" }}>
+      <Group
+        justify="space-between"
+        wrap="nowrap"
+        align="flex-start"
+        px={18}
+        py={14}
+        gap="md"
+        style={{ borderBottom: `1px solid ${BORDER}` }}
+      >
+        <Group gap={10} wrap="nowrap" style={{ minWidth: 0 }}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={36}>
+            <Icon size={18} />
+          </ThemeIcon>
+          <Box style={{ minWidth: 0 }}>
+            <Group gap={8} wrap="nowrap">
+              <Text fw={700} fz={14.5} style={{ color: INK }}>
+                {title}
+              </Text>
+              {status}
+            </Group>
+            <Text fz={11.5} c="dimmed">
+              {subtitle}
+            </Text>
+          </Box>
+        </Group>
+        {action ? <Box style={{ flexShrink: 0 }}>{action}</Box> : null}
+      </Group>
+      <Box p="md">{children}</Box>
+    </Card>
+  );
+}
+
+// ── Train timeline strip ─────────────────────────────────────────────────────
+
+function TrainStrip({ train }: { train?: Freight.ClearanceTrainState | null }) {
+  const departed = train?.departedAt ?? null;
+  const arrived = train?.arrivedAt ?? null;
+  const transit = elapsed(departed, arrived);
+  const sinceDeparture =
+    departed && !arrived ? formatDuration(Date.now() - new Date(departed).getTime()) : null;
+  const sinceArrival = arrived
+    ? formatDuration(Date.now() - new Date(arrived).getTime())
+    : null;
+
+  return (
+    <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
+      <Stat
+        icon={Train}
+        label="Train departed"
+        value={departed ? formatStamp(departed) : "Not departed"}
+        hint={
+          departed
+            ? "Loaded onto the train"
+            : train?.wagonAllocated
+              ? "Wagons allocated — awaiting departure"
+              : "Awaiting wagon allocation"
+        }
+        tone={departed ? "blue" : "muted"}
+      />
+      <Stat
+        icon={MapPin}
+        label="Arrived at Djibouti"
+        value={arrived ? formatStamp(arrived) : departed ? "In transit" : "—"}
+        hint={
+          arrived
+            ? `${sinceArrival} ago`
+            : sinceDeparture
+              ? `${sinceDeparture} since departure`
+              : "Arrival is recorded by operations"
+        }
+        tone={arrived ? "green" : "muted"}
+      />
+      <Stat
+        icon={Timer}
+        label="Transit time"
+        value={transit ?? (sinceDeparture ? `${sinceDeparture} so far` : "—")}
+        hint={transit ? "Departure → arrival" : "Measured once the train arrives"}
+        tone={transit ? "green" : "muted"}
+      />
+    </SimpleGrid>
+  );
+}
+
+// ── Release Order card ───────────────────────────────────────────────────────
+
+function ReleaseOrderCard({
+  bookingId,
+  clearance,
+  history,
+  onView,
+  onChanged,
+}: {
+  bookingId: string;
+  clearance: Freight.ClearanceView;
+  history: Freight.ClearanceHistoryEvent[];
+  onView: (file: { name: string; url: string; mimeType?: string | null }) => void;
+  onChanged: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  const roFiles = (clearance.workflowFiles ?? []).filter(
+    (f) => isReleaseOrderFileCode(f.code) && f.file,
+  );
+  const hasRo = roFiles.length > 0;
+
+  // The customs declaration is the gate: the API refuses an RO before it.
+  const declaredMilestone = clearance.milestones?.find(
+    (m) => m.milestoneCode === "DECLARED",
+  );
+  const declared =
+    declaredMilestone?.status === "COMPLETED" ||
+    declaredMilestone?.status === "SKIPPED";
+  const declaredAt =
+    declaredMilestone?.triggeredAt ??
+    latestEvent(history, "DECLARATION_UPLOADED")?.at ??
+    null;
+
+  // "Uploaded" is the latest stamp on the current RO set — replacing the RO
+  // stores a fresh batch, so this is always the last update, as required.
+  const roEvents = history.filter((e) => e.action === "RELEASE_ORDER_UPLOADED");
+  const roAt =
+    latestOf(roFiles.map((f) => f.file?.uploadedAt)) ?? roEvents[0]?.at ?? null;
+  const roUpdated = roEvents.length > 1;
+  const declarationToRo = elapsed(declaredAt, roAt);
+  const secured =
+    clearance.milestones?.find((m) => m.milestoneCode === "RELEASE_ORDER_SECURED")
+      ?.status === "COMPLETED";
+  const hold = clearance.roHoldReason ?? null;
+
+  const status = hold ? (
+    <Badge size="xs" color="red" variant="light" radius="sm" tt="none">
+      On hold
+    </Badge>
+  ) : secured ? (
+    <Badge
+      size="xs"
+      color="edr-green"
+      variant="light"
+      radius="sm"
+      tt="none"
+      leftSection={<CheckCircle2 size={10} />}
+    >
+      Secured
+    </Badge>
+  ) : hasRo ? (
+    <Badge size="xs" color="orange" variant="light" radius="sm" tt="none">
+      Uploaded
+    </Badge>
+  ) : declared ? (
+    <Badge size="xs" color="blue" variant="light" radius="sm" tt="none">
+      Ready to upload
+    </Badge>
+  ) : (
+    <Badge
+      size="xs"
+      color="gray"
+      variant="light"
+      radius="sm"
+      tt="none"
+      leftSection={<Lock size={10} />}
+    >
+      Waiting for declaration
+    </Badge>
+  );
+
+  return (
+    <>
+      <DocumentCard
+        icon={Ship}
+        title="Release Order"
+        subtitle="Filed with the vessel departure date once GL Ethiopia uploads the customs declaration"
+        status={status}
+        action={
+          <Tooltip
+            label="The customs declaration has not been uploaded yet"
+            disabled={declared}
+            withArrow
+          >
+            <Button
+              color="edr-green"
+              radius="md"
+              size="sm"
+              leftSection={hasRo ? <FileCheck2 size={15} /> : <Upload size={15} />}
+              disabled={!declared}
+              onClick={() => setOpen(true)}
+            >
+              {hasRo ? "Replace Release Order" : "Upload Release Order"}
+            </Button>
+          </Tooltip>
+        }
+      >
+        <Stack gap="md">
+          {hold ? (
+            <Alert
+              color="red"
+              variant="light"
+              icon={<AlertTriangle size={16} />}
+              title="RO amendment hold"
+            >
+              {hold}
+            </Alert>
+          ) : null}
+
+          <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
+            <Stat
+              icon={FileText}
+              label="Declaration uploaded"
+              value={declaredAt ? formatStamp(declaredAt) : declared ? "Done" : "Pending"}
+              hint={declared ? "By GL Ethiopia — RO unlocked" : "Unlocks the Release Order"}
+              tone={declared ? "green" : "muted"}
+            />
+            <Stat
+              icon={Ship}
+              label={roUpdated ? "RO last updated" : "RO uploaded"}
+              value={roAt ? formatStamp(roAt) : "Not yet"}
+              hint={
+                roAt
+                  ? clearance.vesselDepartureDate
+                    ? `Vessel departs ${clearance.vesselDepartureDate}`
+                    : roUpdated
+                      ? `Replaced ${roEvents.length - 1}×`
+                      : "First upload"
+                  : "Upload to record the time"
+              }
+              tone={roAt ? "green" : "muted"}
+            />
+            <Stat
+              icon={Timer}
+              label="Declaration → RO"
+              value={declarationToRo ?? "—"}
+              hint={
+                declarationToRo
+                  ? roUpdated
+                    ? "Measured to the last update"
+                    : "Time to secure the RO"
+                  : "Measured once the RO is uploaded"
+              }
+              tone={declarationToRo ? "blue" : "muted"}
+            />
+          </SimpleGrid>
+
+          {hasRo ? (
+            <Stack gap={8}>
+              {roFiles.map((item) => (
+                <StoredDocumentRow key={item.code} item={item} onView={onView} />
+              ))}
+            </Stack>
+          ) : (
+            <EmptyDocs icon={Ship}>
+              {declared
+                ? "No Release Order on file yet. Upload the RO and confirm the vessel departure date."
+                : "The Release Order can be uploaded as soon as the customs declaration is on file."}
+            </EmptyDocs>
+          )}
+        </Stack>
+      </DocumentCard>
+
+      <ReleaseOrderModal
+        opened={open}
+        bookingId={bookingId}
+        replaceMode={hasRo}
+        vesselDepartureDate={clearance.vesselDepartureDate ?? null}
+        onClose={() => setOpen(false)}
+        onSuccess={onChanged}
+      />
+    </>
+  );
+}
+
+/** `YYYY-MM-DD` in local time — the API column is a DATE, so no UTC shift. */
+function toIsoDate(value: Date | null): string | null {
+  if (!value) return null;
+  const tz = value.getTimezoneOffset() * 60000;
+  return new Date(value.getTime() - tz).toISOString().slice(0, 10);
+}
+
+function ReleaseOrderModal({
+  opened,
+  bookingId,
+  replaceMode,
+  vesselDepartureDate,
+  onClose,
+  onSuccess,
+}: {
+  opened: boolean;
+  bookingId: string;
+  replaceMode: boolean;
+  vesselDepartureDate: string | null;
+  onClose: () => void;
+  onSuccess: () => void;
+}) {
+  const [files, setFiles] = useState<File[]>([]);
+  const [vesselDate, setVesselDate] = useState<Date | null>(
+    vesselDepartureDate ? new Date(vesselDepartureDate) : null,
+  );
+  const today = useMemo(() => {
+    const d = new Date();
+    d.setHours(0, 0, 0, 0);
+    return d;
+  }, []);
+
+  const close = () => {
+    setFiles([]);
+    onClose();
+  };
+
+  const submit = useMutation({
+    mutationFn: () =>
+      transitAssignmentsService.uploadReleaseOrder(
+        bookingId,
+        files,
+        toIsoDate(vesselDate)!,
+      ),
+    onSuccess: (result) => {
+      // The API answers with a hold instead of an error when the vessel date is
+      // too soon — say so rather than reporting a clean success.
+      if (result?.hold) {
+        toast.error(result.holdReason ?? "Vessel date too soon");
+      } else {
+        toast.success(replaceMode ? "Release Order updated" : "Release Order uploaded");
+      }
+      onSuccess();
+      close();
+    },
+    onError: (e: unknown) =>
+      toast.error(e instanceof Error ? e.message : "Upload failed"),
+  });
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={close}
+      radius="md"
+      size="lg"
+      title={
+        <Group gap={8}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={30}>
+            <Ship size={16} />
+          </ThemeIcon>
+          <Text fw={700}>
+            {replaceMode ? "Replace Release Order" : "Upload Release Order"}
+          </Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          Upload the Release Order and confirm the vessel departure date. The
+          upload time is recorded and measured against the customs declaration.
+          {replaceMode
+            ? " Replacing removes the current RO files and records a new time."
+            : ""}
+        </Text>
+
+        <DateInput
+          label="Vessel departure date"
+          placeholder="Select date"
+          value={vesselDate}
+          onChange={(v) => setVesselDate(v ? new Date(v) : null)}
+          minDate={today}
+          size="sm"
+          radius="md"
+          required
+          withAsterisk
+        />
+
+        <PortalMultiFileDropzone
+          label="Release Order files"
+          description="Scanned RO pages or the port's PDF. Every file in this batch replaces what is on file."
+          files={files}
+          onChange={setFiles}
+        />
+
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" radius="md" onClick={close} disabled={submit.isPending}>
+            Cancel
+          </Button>
+          <Button
+            color="edr-green"
+            radius="md"
+            loading={submit.isPending}
+            disabled={files.length === 0 || !vesselDate}
+            leftSection={<Upload size={16} />}
+            onClick={() => submit.mutate()}
+          >
+            {replaceMode ? "Replace RO" : "Upload RO"}
+            {files.length > 1 ? ` (${files.length} files)` : ""}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
+// ── Gate pass / Djibouti T1 cards ────────────────────────────────────────────
+
+type ArrivalKind = "gate_pass" | "djibouti_t1";
+
+const ARRIVAL_SETS: Record<
+  ArrivalKind,
+  {
+    title: string;
+    subtitle: string;
+    icon: typeof FileText;
+    matches: (code: string) => boolean;
+    upload: (bookingId: string, files: File[]) => Promise<{ uploaded: number }>;
+    empty: string;
+    modalHint: string;
+  }
+> = {
+  gate_pass: {
+    title: "Gate pass",
+    subtitle: "Port gate pass documents collected at Djibouti",
+    icon: ShieldCheck,
+    matches: isGatePassFileCode,
+    upload: transitAssignmentsService.uploadGatePassDocuments,
+    empty:
+      "No gate pass documents yet. Add each pass as you collect it — every upload is time-stamped.",
+    modalHint: "Gate pass scans or photos. You can add more later.",
+  },
+  djibouti_t1: {
+    title: "Djibouti T1",
+    subtitle: "T1 transit documents issued at Djibouti customs",
+    icon: FileStack,
+    matches: isDjiboutiT1FileCode,
+    upload: transitAssignmentsService.uploadDjiboutiT1Documents,
+    empty:
+      "No Djibouti T1 documents yet. Add each T1 as customs issues it — every upload is time-stamped.",
+    modalHint: "T1 scans or photos. You can add more later.",
+  },
+};
+
+function ArrivalDocumentsCard({
+  kind,
+  bookingId,
+  clearance,
+  onView,
+  onChanged,
+}: {
+  kind: ArrivalKind;
+  bookingId: string;
+  clearance: Freight.ClearanceView;
+  onView: (file: { name: string; url: string; mimeType?: string | null }) => void;
+  onChanged: () => void;
+}) {
+  const set = ARRIVAL_SETS[kind];
+  const [open, setOpen] = useState(false);
+  const [removingId, setRemovingId] = useState<string | null>(null);
+
+  const items = (clearance.workflowFiles ?? []).filter(
+    (f) => set.matches(f.code) && f.file,
+  );
+  const train = clearance.train ?? null;
+  const stamps = items.map((i) => i.file?.uploadedAt);
+  const firstAt = earliestOf(stamps);
+  const lastAt = latestOf(stamps);
+  const arrivalToFirst = elapsed(train?.arrivedAt, firstAt);
+  const departureToFirst = elapsed(train?.departedAt, firstAt);
+
+  const remove = useMutation({
+    mutationFn: (file: { id: string; name: string }) => {
+      setRemovingId(file.id);
+      return transitAssignmentsService.removeTransitDocument(bookingId, file.id);
+    },
+    onSuccess: (_r, file) => {
+      toast.success(`Removed ${file.name}`);
+      onChanged();
+    },
+    onError: (e: unknown) =>
+      toast.error(e instanceof Error ? e.message : "Could not remove the document"),
+    onSettled: () => setRemovingId(null),
+  });
+
+  return (
+    <>
+      <DocumentCard
+        icon={set.icon}
+        title={set.title}
+        subtitle={set.subtitle}
+        status={
+          items.length > 0 ? (
+            <Badge size="xs" color="edr-green" variant="light" radius="sm" tt="none">
+              {items.length} on file
+            </Badge>
+          ) : (
+            <Badge size="xs" color="gray" variant="light" radius="sm" tt="none">
+              None yet
+            </Badge>
+          )
+        }
+        action={
+          <Button
+            color="edr-green"
+            radius="md"
+            size="sm"
+            variant={items.length > 0 ? "light" : "filled"}
+            leftSection={<Upload size={15} />}
+            onClick={() => setOpen(true)}
+          >
+            {items.length > 0 ? "Add documents" : "Upload documents"}
+          </Button>
+        }
+      >
+        <Stack gap="md">
+          <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
+            <Stat
+              icon={Clock3}
+              label="First uploaded"
+              value={firstAt ? formatStamp(firstAt) : "—"}
+              hint={
+                arrivalToFirst
+                  ? `${arrivalToFirst} after arrival`
+                  : departureToFirst
+                    ? `${departureToFirst} after departure`
+                    : "Measured against the train"
+              }
+              tone={firstAt ? "green" : "muted"}
+            />
+            <Stat
+              icon={Clock3}
+              label="Latest uploaded"
+              value={lastAt ? formatStamp(lastAt) : "—"}
+              hint={
+                lastAt && lastAt !== firstAt
+                  ? `${elapsed(firstAt, lastAt)} after the first`
+                  : lastAt
+                    ? "Single upload so far"
+                    : "No uploads yet"
+              }
+              tone={lastAt ? "green" : "muted"}
+            />
+            <Stat
+              icon={Train}
+              label={train?.arrivedAt ? "Since arrival" : "Since departure"}
+              value={
+                train?.arrivedAt
+                  ? formatDuration(Date.now() - new Date(train.arrivedAt).getTime())
+                  : train?.departedAt
+                    ? formatDuration(Date.now() - new Date(train.departedAt).getTime())
+                    : "—"
+              }
+              hint={
+                train?.arrivedAt
+                  ? `Arrived ${formatStamp(train.arrivedAt)}`
+                  : train?.departedAt
+                    ? `Departed ${formatStamp(train.departedAt)}`
+                    : "Train not departed yet"
+              }
+              tone={train?.arrivedAt ? "blue" : "muted"}
+            />
+          </SimpleGrid>
+
+          {items.length > 0 ? (
+            <Stack gap={8}>
+              {items.map((item) => (
+                <StoredDocumentRow
+                  key={item.code}
+                  item={item}
+                  train={train}
+                  onView={onView}
+                  onRemove={(f) => remove.mutate(f)}
+                  removing={removingId === item.file?.id}
+                />
+              ))}
+            </Stack>
+          ) : (
+            <EmptyDocs icon={set.icon}>{set.empty}</EmptyDocs>
+          )}
+        </Stack>
+      </DocumentCard>
+
+      <ArrivalUploadModal
+        kind={kind}
+        opened={open}
+        bookingId={bookingId}
+        existing={items.length}
+        onClose={() => setOpen(false)}
+        onSuccess={onChanged}
+      />
+    </>
+  );
+}
+
+function ArrivalUploadModal({
+  kind,
+  opened,
+  bookingId,
+  existing,
+  onClose,
+  onSuccess,
+}: {
+  kind: ArrivalKind;
+  opened: boolean;
+  bookingId: string;
+  existing: number;
+  onClose: () => void;
+  onSuccess: () => void;
+}) {
+  const set = ARRIVAL_SETS[kind];
+  const [files, setFiles] = useState<File[]>([]);
+  const Icon = set.icon;
+
+  const close = () => {
+    setFiles([]);
+    onClose();
+  };
+
+  const submit = useMutation({
+    mutationFn: () => set.upload(bookingId, files),
+    onSuccess: (r) => {
+      toast.success(
+        `${r.uploaded} ${set.title} document${r.uploaded === 1 ? "" : "s"} uploaded`,
+      );
+      onSuccess();
+      close();
+    },
+    onError: (e: unknown) =>
+      toast.error(e instanceof Error ? e.message : "Upload failed"),
+  });
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={close}
+      radius="md"
+      size="lg"
+      title={
+        <Group gap={8}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={30}>
+            <Icon size={16} />
+          </ThemeIcon>
+          <Text fw={700}>
+            {existing > 0 ? `Add ${set.title} documents` : `Upload ${set.title} documents`}
+          </Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          {existing > 0
+            ? `${existing} already on file — these are added alongside them. `
+            : ""}
+          Each file is stamped with its upload time and measured against the
+          train's departure and arrival.
+        </Text>
+
+        <PortalMultiFileDropzone
+          label={`${set.title} files`}
+          description={set.modalHint}
+          files={files}
+          onChange={setFiles}
+        />
+
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" radius="md" onClick={close} disabled={submit.isPending}>
+            Cancel
+          </Button>
+          <Button
+            color="edr-green"
+            radius="md"
+            loading={submit.isPending}
+            disabled={files.length === 0}
+            leftSection={<Upload size={16} />}
+            onClick={() => submit.mutate()}
+          >
+            Upload{files.length > 0 ? ` ${files.length} file${files.length === 1 ? "" : "s"}` : ""}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
+// ── Delivery Order card (import) ─────────────────────────────────────────────
+
+function DeliveryOrderCard({
+  bookingId,
+  clearance,
+  history,
+  onView,
+  onChanged,
+}: {
+  bookingId: string;
+  clearance: Freight.ClearanceView;
+  history: Freight.ClearanceHistoryEvent[];
+  onView: (file: { name: string; url: string; mimeType?: string | null }) => void;
+  onChanged: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  const doFiles = (clearance.workflowFiles ?? []).filter(
+    (f) => isDeliveryOrderFileCode(f.code) && f.file,
+  );
+  const hasDo = doFiles.length > 0;
+
+  // The DO clock starts when the booking is created. "Uploaded" is the latest
+  // stamp on the current DO set — replacing stores a fresh batch, so it is
+  // always the last update.
+  const createdAt = clearance.bookingCreatedAt ?? null;
+  const doEvents = history.filter((e) => e.action === "DELIVERY_ORDER_UPLOADED");
+  const doAt =
+    latestOf(doFiles.map((f) => f.file?.uploadedAt)) ?? doEvents[0]?.at ?? null;
+  const doUpdated = doEvents.length > 1;
+  const bookingToDo = elapsed(createdAt, doAt);
+  const collected =
+    clearance.milestones?.find((m) => m.milestoneCode === "DO_COLLECTED")
+      ?.status === "COMPLETED";
+
+  const status = collected ? (
+    <Badge
+      size="xs"
+      color="edr-green"
+      variant="light"
+      radius="sm"
+      tt="none"
+      leftSection={<CheckCircle2 size={10} />}
+    >
+      Collected
+    </Badge>
+  ) : hasDo ? (
+    <Badge size="xs" color="orange" variant="light" radius="sm" tt="none">
+      Uploaded
+    </Badge>
+  ) : (
+    <Badge size="xs" color="blue" variant="light" radius="sm" tt="none">
+      Ready to upload
+    </Badge>
+  );
+
+  return (
+    <>
+      <DocumentCard
+        icon={PackageCheck}
+        title="Delivery Order"
+        subtitle="Collected at the Djibouti port, filed with the vessel arrival and collection dates"
+        status={status}
+        action={
+          <Button
+            color="edr-green"
+            radius="md"
+            size="sm"
+            leftSection={hasDo ? <FileCheck2 size={15} /> : <Upload size={15} />}
+            onClick={() => setOpen(true)}
+          >
+            {hasDo ? "Replace Delivery Order" : "Upload Delivery Order"}
+          </Button>
+        }
+      >
+        <Stack gap="md">
+          <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
+            <Stat
+              icon={Clock3}
+              label="Booking created"
+              value={createdAt ? formatStamp(createdAt) : "—"}
+              hint="The DO clock starts here"
+              tone={createdAt ? "blue" : "muted"}
+            />
+            <Stat
+              icon={PackageCheck}
+              label={doUpdated ? "DO last updated" : "DO uploaded"}
+              value={doAt ? formatStamp(doAt) : "Not yet"}
+              hint={
+                doAt
+                  ? clearance.doCollectedDate
+                    ? `Collected ${clearance.doCollectedDate} · vessel ${clearance.vesselArrivalDate ?? "—"}`
+                    : doUpdated
+                      ? `Replaced ${doEvents.length - 1}×`
+                      : "First upload"
+                  : "Upload to record the time"
+              }
+              tone={doAt ? "green" : "muted"}
+            />
+            <Stat
+              icon={Timer}
+              label="Booking → DO"
+              value={bookingToDo ?? "—"}
+              hint={
+                bookingToDo
+                  ? doUpdated
+                    ? "Measured to the last update"
+                    : "Time to collect the DO"
+                  : "Measured once the DO is uploaded"
+              }
+              tone={bookingToDo ? "blue" : "muted"}
+            />
+          </SimpleGrid>
+
+          {hasDo ? (
+            <Stack gap={8}>
+              {doFiles.map((item) => (
+                <StoredDocumentRow key={item.code} item={item} onView={onView} />
+              ))}
+            </Stack>
+          ) : (
+            <EmptyDocs icon={PackageCheck}>
+              No Delivery Order on file yet. Upload the DO and record when the
+              vessel arrived and when the DO was collected.
+            </EmptyDocs>
+          )}
+        </Stack>
+      </DocumentCard>
+
+      <DeliveryOrderModal
+        opened={open}
+        bookingId={bookingId}
+        replaceMode={hasDo}
+        vesselArrivalDate={clearance.vesselArrivalDate ?? null}
+        doCollectedDate={clearance.doCollectedDate ?? null}
+        onClose={() => setOpen(false)}
+        onSuccess={onChanged}
+      />
+    </>
+  );
+}
+
+function DeliveryOrderModal({
+  opened,
+  bookingId,
+  replaceMode,
+  vesselArrivalDate,
+  doCollectedDate,
+  onClose,
+  onSuccess,
+}: {
+  opened: boolean;
+  bookingId: string;
+  replaceMode: boolean;
+  vesselArrivalDate: string | null;
+  doCollectedDate: string | null;
+  onClose: () => void;
+  onSuccess: () => void;
+}) {
+  const [files, setFiles] = useState<File[]>([]);
+  const [vesselArrival, setVesselArrival] = useState<Date | null>(
+    vesselArrivalDate ? new Date(vesselArrivalDate) : null,
+  );
+  const [collected, setCollected] = useState<Date | null>(
+    doCollectedDate ? new Date(doCollectedDate) : null,
+  );
+
+  // The DO cannot be collected before the vessel docked.
+  const outOfOrder =
+    Boolean(vesselArrival && collected) &&
+    (toIsoDate(collected) ?? "") < (toIsoDate(vesselArrival) ?? "");
+  const datesComplete = Boolean(vesselArrival && collected) && !outOfOrder;
+
+  const close = () => {
+    setFiles([]);
+    onClose();
+  };
+
+  const submit = useMutation({
+    mutationFn: () =>
+      transitAssignmentsService.uploadDeliveryOrder(bookingId, files, {
+        vesselArrivalDate: toIsoDate(vesselArrival)!,
+        doCollectedDate: toIsoDate(collected)!,
+      }),
+    onSuccess: () => {
+      toast.success(replaceMode ? "Delivery Order updated" : "Delivery Order uploaded");
+      onSuccess();
+      close();
+    },
+    onError: (e: unknown) =>
+      toast.error(e instanceof Error ? e.message : "Upload failed"),
+  });
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={close}
+      radius="md"
+      size="lg"
+      title={
+        <Group gap={8}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={30}>
+            <PackageCheck size={16} />
+          </ThemeIcon>
+          <Text fw={700}>
+            {replaceMode ? "Replace Delivery Order" : "Upload Delivery Order"}
+          </Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          Upload the Djibouti Delivery Order and record when the vessel arrived
+          and when the DO was collected. The upload time is recorded and
+          measured from the booking's creation.
+          {replaceMode
+            ? " Replacing removes the current DO files and records a new time."
+            : ""}
+        </Text>
+
+        <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="sm">
+          <DateInput
+            label="Vessel arrival date"
+            placeholder="Select date"
+            value={vesselArrival}
+            onChange={(v) => setVesselArrival(v ? new Date(v) : null)}
+            size="sm"
+            radius="md"
+            required
+            withAsterisk
+          />
+          <DateInput
+            label="DO collected date"
+            placeholder="Select date"
+            value={collected}
+            onChange={(v) => setCollected(v ? new Date(v) : null)}
+            minDate={vesselArrival ?? undefined}
+            size="sm"
+            radius="md"
+            required
+            withAsterisk
+            error={outOfOrder ? "Cannot be before the vessel arrival date." : undefined}
+          />
+        </SimpleGrid>
+
+        <PortalMultiFileDropzone
+          label="Delivery Order files"
+          description="Scanned DO pages or the port's PDF. Every file in this batch replaces what is on file."
+          files={files}
+          onChange={setFiles}
+          accept="*/*"
+          acceptHint="any file type"
+        />
+
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" radius="md" onClick={close} disabled={submit.isPending}>
+            Cancel
+          </Button>
+          <Button
+            color="edr-green"
+            radius="md"
+            loading={submit.isPending}
+            disabled={files.length === 0 || !datesComplete}
+            leftSection={<Upload size={16} />}
+            onClick={() => submit.mutate()}
+          >
+            {replaceMode ? "Replace DO" : "Upload DO"}
+            {files.length > 1 ? ` (${files.length} files)` : ""}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
+// ── T1 transport documents card (import) ────────────────────────────────────
+
+function ImportT1Card({
+  bookingId,
+  clearance,
+  history,
+  onView,
+  onChanged,
+}: {
+  bookingId: string;
+  clearance: Freight.ClearanceView;
+  history: Freight.ClearanceHistoryEvent[];
+  onView: (file: { name: string; url: string; mimeType?: string | null }) => void;
+  onChanged: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  const t1Files = (clearance.workflowFiles ?? []).filter(
+    (f) => isT1TransportFileCode(f.code) && f.file,
+  );
+  const hasT1 = t1Files.length > 0;
+  const train = clearance.train ?? null;
+  const departed = Boolean(train?.departedAt);
+  const closed = Boolean(clearance.t1Closed);
+
+  // Replacing stores a fresh batch, so the latest stamp is the last update.
+  const t1Events = history.filter((e) => e.action === "T1_DOCUMENTS_UPLOADED");
+  const t1At = latestOf(t1Files.map((f) => f.file?.uploadedAt)) ?? null;
+  const t1Updated = t1Events.length > 1;
+  const departureToT1 = elapsed(train?.departedAt, t1At);
+  const arrivalToT1 = elapsed(train?.arrivedAt, t1At);
+
+  const status = closed ? (
+    <Badge
+      size="xs"
+      color="edr-green"
+      variant="light"
+      radius="sm"
+      tt="none"
+      leftSection={<CheckCircle2 size={10} />}
+    >
+      Closed by GL Ethiopia
+    </Badge>
+  ) : hasT1 ? (
+    <Badge size="xs" color="orange" variant="light" radius="sm" tt="none">
+      Uploaded
+    </Badge>
+  ) : departed ? (
+    <Badge size="xs" color="blue" variant="light" radius="sm" tt="none">
+      Ready to upload
+    </Badge>
+  ) : (
+    <Badge
+      size="xs"
+      color="gray"
+      variant="light"
+      radius="sm"
+      tt="none"
+      leftSection={<Lock size={10} />}
+    >
+      Waiting for departure
+    </Badge>
+  );
+
+  const locked = !departed || closed;
+
+  return (
+    <>
+      <DocumentCard
+        icon={FileStack}
+        title="T1 transport documents"
+        subtitle="Filed once the train departs Djibouti; final once GL Ethiopia closes the T1"
+        status={status}
+        action={
+          <Tooltip
+            label={
+              closed
+                ? "GL Ethiopia has closed the T1 — documents are final"
+                : "The train has not departed yet"
+            }
+            disabled={!locked}
+            withArrow
+          >
+            <Button
+              color="edr-green"
+              radius="md"
+              size="sm"
+              leftSection={hasT1 ? <FileCheck2 size={15} /> : <Upload size={15} />}
+              disabled={locked}
+              onClick={() => setOpen(true)}
+            >
+              {hasT1 ? "Replace T1 documents" : "Upload T1 documents"}
+            </Button>
+          </Tooltip>
+        }
+      >
+        <Stack gap="md">
+          <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
+            <Stat
+              icon={Train}
+              label="Train departed"
+              value={train?.departedAt ? formatStamp(train.departedAt) : "Not departed"}
+              hint={departed ? "T1 upload unlocked" : "Unlocks the T1 upload"}
+              tone={departed ? "blue" : "muted"}
+            />
+            <Stat
+              icon={FileStack}
+              label={t1Updated ? "T1 last updated" : "T1 uploaded"}
+              value={t1At ? formatStamp(t1At) : "Not yet"}
+              hint={
+                t1At
+                  ? closed && clearance.t1ClosedAt
+                    ? `Closed ${formatStamp(clearance.t1ClosedAt)}`
+                    : t1Updated
+                      ? `Replaced ${t1Events.length - 1}×`
+                      : "First upload"
+                  : "Upload to record the time"
+              }
+              tone={t1At ? "green" : "muted"}
+            />
+            <Stat
+              icon={Timer}
+              label={arrivalToT1 ? "Arrival → T1" : "Departure → T1"}
+              value={arrivalToT1 ?? departureToT1 ?? "—"}
+              hint={
+                arrivalToT1
+                  ? `${departureToT1} after departure`
+                  : departureToT1
+                    ? train?.arrivedAt
+                      ? "Filed before arrival"
+                      : "Train still in transit"
+                    : "Measured once the T1 is uploaded"
+              }
+              tone={arrivalToT1 || departureToT1 ? "blue" : "muted"}
+            />
+          </SimpleGrid>
+
+          {hasT1 ? (
+            <Stack gap={8}>
+              {t1Files.map((item) => (
+                <StoredDocumentRow key={item.code} item={item} train={train} onView={onView} />
+              ))}
+            </Stack>
+          ) : (
+            <EmptyDocs icon={FileStack}>
+              {departed
+                ? "No T1 transport documents yet. Upload the T1 set — every file is time-stamped against departure and arrival."
+                : "T1 transport documents can be uploaded as soon as the train departs Djibouti."}
+            </EmptyDocs>
+          )}
+        </Stack>
+      </DocumentCard>
+
+      <ImportT1Modal
+        opened={open}
+        bookingId={bookingId}
+        replaceMode={hasT1}
+        onClose={() => setOpen(false)}
+        onSuccess={onChanged}
+      />
+    </>
+  );
+}
+
+function ImportT1Modal({
+  opened,
+  bookingId,
+  replaceMode,
+  onClose,
+  onSuccess,
+}: {
+  opened: boolean;
+  bookingId: string;
+  replaceMode: boolean;
+  onClose: () => void;
+  onSuccess: () => void;
+}) {
+  const [files, setFiles] = useState<File[]>([]);
+
+  const close = () => {
+    setFiles([]);
+    onClose();
+  };
+
+  const submit = useMutation({
+    mutationFn: () => transitAssignmentsService.uploadT1Documents(bookingId, files),
+    onSuccess: () => {
+      toast.success(replaceMode ? "T1 documents updated" : "T1 documents uploaded");
+      onSuccess();
+      close();
+    },
+    onError: (e: unknown) =>
+      toast.error(e instanceof Error ? e.message : "Upload failed"),
+  });
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={close}
+      radius="md"
+      size="lg"
+      title={
+        <Group gap={8}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={30}>
+            <FileStack size={16} />
+          </ThemeIcon>
+          <Text fw={700}>
+            {replaceMode ? "Replace T1 transport documents" : "Upload T1 transport documents"}
+          </Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          Upload the T1 set for this shipment. Every file is stamped with its
+          upload time and measured against the train's departure and arrival.
+          {replaceMode
+            ? " Replacing removes the current T1 files and records a new time."
+            : ""}
+        </Text>
+
+        <PortalMultiFileDropzone
+          label="T1 transport documents"
+          description="Scans or photos of the T1 set. Every file in this batch replaces what is on file."
+          files={files}
+          onChange={setFiles}
+          accept="*/*"
+          acceptHint="any file type"
+        />
+
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" radius="md" onClick={close} disabled={submit.isPending}>
+            Cancel
+          </Button>
+          <Button
+            color="edr-green"
+            radius="md"
+            loading={submit.isPending}
+            disabled={files.length === 0}
+            leftSection={<Upload size={16} />}
+            onClick={() => submit.mutate()}
+          >
+            {replaceMode ? "Replace T1" : "Upload T1"}
+            {files.length > 1 ? ` (${files.length} files)` : ""}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
+// ── Panel ────────────────────────────────────────────────────────────────────
+
+/** Header card shared by both directions: title, flow hint, train strip. */
+function PanelHeader({
+  title,
+  subtitle,
+  flow,
+  train,
+}: {
+  title: string;
+  subtitle: string;
+  flow: string[];
+  train?: Freight.ClearanceTrainState | null;
+}) {
+  return (
+    <Card withBorder radius="md" p="md">
+      <Group justify="space-between" wrap="nowrap" align="flex-start" mb="sm" gap="md">
+        <Group gap={12} wrap="nowrap" style={{ minWidth: 0 }}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={44}>
+            <Train size={20} />
+          </ThemeIcon>
+          <Box style={{ minWidth: 0 }}>
+            <Text fw={700} fz={16} style={{ color: INK }}>
+              {title}
+            </Text>
+            <Text size="xs" c="dimmed">
+              {subtitle}
+            </Text>
+          </Box>
+        </Group>
+        <Group gap={6} wrap="nowrap" style={{ flexShrink: 0 }}>
+          {flow.map((step, i) => (
+            <Group key={step} gap={6} wrap="nowrap">
+              {i > 0 ? <ArrowRight size={12} color={MUTED} /> : null}
+              <Text
+                fz={11}
+                fw={700}
+                c={i === flow.length - 1 ? GREEN : MUTED}
+                tt="uppercase"
+                lts="0.3px"
+              >
+                {step}
+              </Text>
+            </Group>
+          ))}
+        </Group>
+      </Group>
+      <TrainStrip train={train} />
+    </Card>
+  );
+}
+
+/**
+ * The transit agent's import paperwork on one shipment: the Delivery Order
+ * (timed from the booking's creation) and the T1 transport documents
+ * (unlocked by train departure, timed against departure and arrival). Both
+ * are replace-as-a-batch sets, so the stamps shown are always the last update.
+ */
+export function TransitImportDocumentsPanel({
+  bookingId,
+  clearance,
+  history,
+  onView,
+  onChanged,
+}: {
+  bookingId: string;
+  clearance: Freight.ClearanceView;
+  history: Freight.ClearanceHistoryEvent[];
+  onView: (file: { name: string; url: string; mimeType?: string | null }) => void;
+  onChanged: () => void;
+}) {
+  const queryClient = useQueryClient();
+
+  const refresh = () => {
+    void queryClient.invalidateQueries({ queryKey: ["transit-clearance"] });
+    void queryClient.invalidateQueries({ queryKey: ["transit-clearance-history"] });
+    onChanged();
+  };
+
+  return (
+    <Stack gap="md">
+      <PanelHeader
+        title="Import transit documents"
+        subtitle="Your paperwork on this shipment, with every upload time recorded against the booking and the train."
+        flow={["Booking", "DO", "Departure", "T1"]}
+        train={clearance.train}
+      />
+
+      <DeliveryOrderCard
+        bookingId={bookingId}
+        clearance={clearance}
+        history={history}
+        onView={onView}
+        onChanged={refresh}
+      />
+
+      <ImportT1Card
+        bookingId={bookingId}
+        clearance={clearance}
+        history={history}
+        onView={onView}
+        onChanged={refresh}
+      />
+    </Stack>
+  );
+}
+
+
+/**
+ * The transit agent's export paperwork on one shipment: the Release Order
+ * (gated on the customs declaration, timed from it), and the gate pass and
+ * Djibouti T1 sets collected around train arrival (each file timed against
+ * the train's departure and arrival).
+ *
+ * Every timestamp here comes from the server — file `uploadedAt` stamps,
+ * milestone `triggeredAt`, the train state — so what the officer sees is what
+ * the desk and the customer's reports will also see.
+ */
+export function TransitExportDocumentsPanel({
+  bookingId,
+  clearance,
+  history,
+  onView,
+  onChanged,
+}: {
+  bookingId: string;
+  clearance: Freight.ClearanceView;
+  history: Freight.ClearanceHistoryEvent[];
+  onView: (file: { name: string; url: string; mimeType?: string | null }) => void;
+  onChanged: () => void;
+}) {
+  const queryClient = useQueryClient();
+
+  const refresh = () => {
+    void queryClient.invalidateQueries({ queryKey: ["transit-clearance"] });
+    void queryClient.invalidateQueries({ queryKey: ["transit-clearance-history"] });
+    onChanged();
+  };
+
+  return (
+    <Stack gap="md">
+      <PanelHeader
+        title="Export transit documents"
+        subtitle="Your paperwork on this shipment, with every upload time recorded against the declaration and the train."
+        flow={["Declaration", "RO", "Arrival"]}
+        train={clearance.train}
+      />
+
+      <ReleaseOrderCard
+        bookingId={bookingId}
+        clearance={clearance}
+        history={history}
+        onView={onView}
+        onChanged={refresh}
+      />
+
+      <SimpleGrid cols={{ base: 1, lg: 2 }} spacing="md">
+        <ArrivalDocumentsCard
+          kind="gate_pass"
+          bookingId={bookingId}
+          clearance={clearance}
+          onView={onView}
+          onChanged={refresh}
+        />
+        <ArrivalDocumentsCard
+          kind="djibouti_t1"
+          bookingId={bookingId}
+          clearance={clearance}
+          onView={onView}
+          onChanged={refresh}
+        />
+      </SimpleGrid>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/index.ts b/apps/edr-freight-web/portal/src/pages/transit-agent/index.ts
new file mode 100644
index 000000000..c2cd69030
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/index.ts
@@ -0,0 +1,3 @@
+export { default as TransitAgentOverviewPage } from "./TransitAgentOverviewPage";
+export { default as TransitAgentBookingsPage } from "./TransitAgentBookingsPage";
+export { default as TransitAgentBookingDetailPage } from "./TransitAgentBookingDetailPage";
diff --git a/apps/edr-freight-web/portal/src/pages/transit-agent/transit-bookings-table.css b/apps/edr-freight-web/portal/src/pages/transit-agent/transit-bookings-table.css
new file mode 100644
index 000000000..81779f15f
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/transit-agent/transit-bookings-table.css
@@ -0,0 +1,150 @@
+/*
+ * Scoped to .edr-transit-table — the DataTable container div on the
+ * transit agent bookings list. Mirrors the portal's /bookings table
+ * (bookings-table.css): content-sized columns with a 100px floor, no
+ * truncation, horizontal scroll when the table outgrows the card, sticky
+ * header row and a sticky shadowed action column.
+ */
+.edr-transit-table {
+  overflow-x: auto;
+  max-width: 100%;
+  min-width: 0;
+}
+
+/*
+ * width: max-content — the table is exactly as wide as its columns' content
+ * needs, never squeezed to fit the viewport; the container scrolls instead.
+ * min-width: 100% keeps it filling the card when content is narrow.
+ */
+.edr-transit-table table {
+  table-layout: auto;
+  width: max-content;
+  min-width: 100%;
+}
+
+/* 100px floor, no ceiling: cells grow to fit their text, nothing is clipped. */
+.edr-transit-table th,
+.edr-transit-table td:not([colspan]) {
+  min-width: 100px;
+  max-width: none;
+  overflow: visible;
+  text-overflow: clip;
+  white-space: nowrap;
+}
+
+/*
+ * Booking (col 1) and Contract (col 2) carry free-text company/contract names.
+ * Cap those two columns and let their content wrap onto 2+ lines so a very long
+ * name (e.g. "SHAFICI PHARMACEUTICAL MEDICAL SUPPLIES WHOLESALER PARTINERSHIP")
+ * stacks inside its own cell instead of shoving the next column off-screen.
+ * Everything below the header row so the header labels still sit on one line.
+ */
+.edr-transit-table tbody td:not([colspan]):nth-child(1) {
+  max-width: 240px;
+  white-space: normal;
+}
+.edr-transit-table tbody td:not([colspan]):nth-child(2) {
+  max-width: 200px;
+  white-space: normal;
+}
+
+/*
+ * Mantine Badge caps itself at max-width: 100%; inside an auto-layout table
+ * cell that resolves against min-content and clips the label. Let badges size
+ * to their text so the column grows to fit them.
+ */
+.edr-transit-table .mantine-Badge-root {
+  max-width: none;
+}
+
+/*
+ * Opt-out for long free text (company/customer names). The blanket nowrap rule
+ * above keeps every cell on one line so columns size to content; a very long
+ * name would otherwise force the column absurdly wide. Mark such text with
+ * `cell-wrap` to cap it and wrap onto 2+ lines instead of pushing the layout.
+ */
+.edr-transit-table .cell-wrap,
+.edr-transit-table .mantine-Group-root > .cell-wrap {
+  white-space: normal;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+  min-width: 0;
+  max-width: 100%;
+  line-height: 1.3;
+}
+
+/*
+ * Mantine Group's preventGrowOverflow caps every child at 100%/N of the cell.
+ * In an auto-width table cell that resolves against min-content and collapses
+ * the badges/text in the Type, Route and Status columns to nothing. Let group
+ * children size to their content; the column grows and the container scrolls.
+ */
+.edr-transit-table .mantine-Group-root > * {
+  max-width: none;
+  flex-shrink: 0;
+}
+
+/* Sticky header row. */
+.edr-transit-table thead th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+
+/*
+ * Sticky action column, shrunk to its content. The width overrides the inline
+ * width DataTable stamps from tanstack's column size — hence !important.
+ * `:not([colspan])` keeps the full-width error/empty rows out.
+ */
+.edr-transit-table th:last-child,
+.edr-transit-table td:last-child:not([colspan]) {
+  width: 1% !important;
+  min-width: 0;
+  position: sticky;
+  right: 0;
+  box-shadow: -10px 0 14px -8px rgba(16, 32, 47, 0.12);
+}
+
+/*
+ * Sticky cells sit above the scrolling ones, so they need their own opaque
+ * background or the columns underneath show through.
+ */
+.edr-transit-table td:last-child:not([colspan]) {
+  background: var(--mantine-color-body);
+  z-index: 2;
+}
+
+/* Row hover uses the tailwind `hover:bg-accent` class on the <tr>. */
+.edr-transit-table tbody tr:hover td:last-child:not([colspan]) {
+  background: #f7fbf9;
+}
+
+/* Header cell is sticky on both axes — it must outrank the body's sticky column. */
+.edr-transit-table th:last-child {
+  background: var(--mantine-color-gray-0);
+  z-index: 3;
+}
+
+/* ── Design pass: flat head band, 64px rows, hairline dividers ─────────── */
+.edr-transit-table thead th {
+  height: 38px;
+  padding-top: 0;
+  padding-bottom: 0;
+  background: var(--mantine-color-gray-0);
+  border-bottom: 1px solid var(--mantine-color-edr-divider-6);
+}
+
+.edr-transit-table tbody td:not([colspan]) {
+  height: 64px;
+  padding-top: 8px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--mantine-color-edr-divider-6);
+}
+
+.edr-transit-table tbody tr:last-child td:not([colspan]) {
+  border-bottom: 0;
+}
+
+.edr-transit-table tbody tr:hover td {
+  background: #f7fbf9;
+}
diff --git a/apps/edr-freight-web/portal/src/services/bookings.service.ts b/apps/edr-freight-web/portal/src/services/bookings.service.ts
index e07734128..a656830f4 100644
--- a/apps/edr-freight-web/portal/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/portal/src/services/bookings.service.ts
@@ -282,6 +282,8 @@ export interface WagonCancellation {
   feeCurrency: string;
   feeInvoiceId?: string | null;
   feePaidAt?: string | null;
+  /** Who caused the cut: CUSTOMER pays a fee, EDR never does. */
+  fault?: "CUSTOMER" | "EDR" | null;
   status: WagonCancellationStatus;
   reason?: string | null;
   rebookedAt?: string | null;
diff --git a/apps/edr-freight-web/portal/src/services/companies.service.ts b/apps/edr-freight-web/portal/src/services/companies.service.ts
index 466d82470..bd3f7d5e9 100644
--- a/apps/edr-freight-web/portal/src/services/companies.service.ts
+++ b/apps/edr-freight-web/portal/src/services/companies.service.ts
@@ -103,7 +103,7 @@ export interface CompanyProfileResponse {
  * "shipping line" would skip onboarding for customers whenever the request
  * failed. Absent (older responses) means `customer`.
  */
-export type AccountKind = "customer" | "shipping_line";
+export type AccountKind = "customer" | "shipping_line" | "transit_agent";
 
 export interface CompanyInfoResponse {
   accountKind?: AccountKind;
@@ -138,13 +138,38 @@ export interface ShippingLineInfoResponse {
   review: null;
 }
 
-/** `GET /companies/getInfo` serves both portal audiences. */
-export type AccountInfoResponse = CompanyInfoResponse | ShippingLineInfoResponse;
+/**
+ * A signed-in transit agent. Like a shipping line it has no company, no
+ * external profile and no onboarding — the agent record itself is the account.
+ */
+export interface TransitAgentInfoResponse {
+  accountKind: "transit_agent";
+  id: string;
+  name: string;
+  email: string | null;
+  phoneNumber: string | null;
+  isActive: boolean;
+  validFrom: string;
+  validTo: string;
+  company: null;
+  profile: null;
+  review: null;
+}
+
+/** `GET /companies/getInfo` serves every portal audience. */
+export type AccountInfoResponse =
+  | CompanyInfoResponse
+  | ShippingLineInfoResponse
+  | TransitAgentInfoResponse;
 
 export const isShippingLineAccount = (
   info: AccountInfoResponse | null | undefined,
 ): info is ShippingLineInfoResponse => info?.accountKind === "shipping_line";
 
+export const isTransitAgentAccount = (
+  info: AccountInfoResponse | null | undefined,
+): info is TransitAgentInfoResponse => info?.accountKind === "transit_agent";
+
 /** A staged profile-edit review request (portal view). */
 export interface ChangeRequestResponse {
   id: string;
diff --git a/apps/edr-freight-web/portal/src/services/empty-return-requests.service.ts b/apps/edr-freight-web/portal/src/services/empty-return-requests.service.ts
new file mode 100644
index 000000000..4715a72a2
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/services/empty-return-requests.service.ts
@@ -0,0 +1,87 @@
+import { URL_CONSTANTS } from "@/constants/URLS";
+import { client } from "../utils/api";
+
+const E = URL_CONSTANTS.EMPTY_RETURN_REQUESTS;
+
+export type EmptyReturnRequestStatus =
+  | "SUBMITTED"
+  | "APPROVED"
+  | "REJECTED"
+  | "PAID"
+  | "SCHEDULED"
+  | "COMPLETED"
+  | "CANCELLED";
+
+export interface EmptyReturnRequest {
+  id: string;
+  bookingId: string;
+  status: EmptyReturnRequestStatus;
+  containerNumbers: string[];
+  containerCount: number;
+  quotedUnitAmount: number | null;
+  quotedTotalAmount: number | null;
+  currency: string | null;
+  invoiceId: string | null;
+  paidAt: string | null;
+  requestedReturnDate: string | null;
+  truckPlateNumber: string | null;
+  truckDriverName: string | null;
+  truckType: string | null;
+  rejectionReason: string | null;
+  submittedAt: string;
+}
+
+/** Per-container price for the return, off the booking's contract route rate. */
+export interface EmptyReturnQuote {
+  unitAmount: number | null;
+  currency: string;
+  sourceRateUsd: number | null;
+  unavailableReason: string | null;
+}
+
+export interface EmptyReturnEligibility {
+  eligible: boolean;
+  reason: string | null;
+  availableContainerNumbers: string[];
+  maxContainers: number;
+  quote: EmptyReturnQuote;
+}
+
+export interface ScheduleEmptyReturnPayload {
+  returnDate: string;
+  truckPlateNumber: string;
+  truckDriverName: string;
+  truckType?: string;
+}
+
+/**
+ * Returning empties on a booking that was sold WITHOUT the return service:
+ * the customer names the containers, EDR prices and approves, the customer
+ * pays and then books the date and truck.
+ */
+export const emptyReturnRequestsService = {
+  /** Whether this booking can ask, which containers are free, and the price. */
+  eligibility: async (bookingId: string): Promise<EmptyReturnEligibility> => {
+    const { data } = await client.get(E.ELIGIBILITY(bookingId));
+    return data.data ?? data;
+  },
+
+  listForBooking: async (bookingId: string): Promise<EmptyReturnRequest[]> => {
+    const { data } = await client.get(E.BY_BOOKING(bookingId));
+    return data.data ?? data;
+  },
+
+  create: async (bookingId: string, containerNumbers: string[]): Promise<EmptyReturnRequest> => {
+    const { data } = await client.post(E.BASE, { bookingId, containerNumbers });
+    return data.data ?? data;
+  },
+
+  /** Date + truck, once the invoice is paid. */
+  schedule: async (
+    id: string,
+    payload: ScheduleEmptyReturnPayload,
+  ): Promise<EmptyReturnRequest> => {
+    const { data } = await client.post(E.SCHEDULE(id), payload);
+    return data.data ?? data;
+  },
+};
diff --git a/apps/edr-freight-web/portal/src/services/transit-assignments.service.ts b/apps/edr-freight-web/portal/src/services/transit-assignments.service.ts
new file mode 100644
index 000000000..9dfed7b59
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/services/transit-assignments.service.ts
@@ -0,0 +1,381 @@
+import type { Freight } from "@edr/types";
+
+import { client } from "@/utils/api";
+
+const BASE = "/api/transit-assignments/my";
+
+/** One document attached to an assignment. */
+export interface TransitAssignmentFile {
+  id: string;
+  name: string;
+  title: string | null;
+  url: string;
+  size: number;
+  mimeType: string;
+  uploadedAt: string;
+  updatedAt: string;
+  uploadedByName: string | null;
+}
+
+export type TransitAssignmentStatus =
+  | "NOT_STARTED"
+  | "IN_PROGRESS"
+  | "FINISHED";
+
+/**
+ * One booking assigned to the signed-in transit agent.
+ *
+ * `canUploadDocuments` is computed server-side from BOTH gates (the booking is
+ * dispatched, and the assignment is not finished). The UI reads that flag
+ * rather than re-deriving the rule, so the button state cannot drift from what
+ * the API will actually accept.
+ */
+export interface TransitAssignment {
+  id: string;
+  bookingId: string;
+  transitAgentId: string;
+  status: TransitAssignmentStatus;
+  startedAt: string | null;
+  finishedAt: string | null;
+  assignedAt: string;
+  note: string | null;
+  timeAfterTrainArrives: number | null;
+  canUploadDocuments: boolean;
+  /** Whose cargo this is — flattened server-side off the booking's company. */
+  customerName: string | null;
+  files?: TransitAssignmentFile[];
+  booking?: {
+    id: string;
+    reference?: string | null;
+    status?: string | null;
+    schedulingStatus?: string | null;
+    tradeDirection?: string | null;
+    arrivedAt?: string | null;
+  } | null;
+}
+
+export interface TransitAssignmentListParams {
+  search?: string;
+  status?: TransitAssignmentStatus;
+  schedulingStatus?: string;
+  page?: number;
+  pageSize?: number;
+}
+
+export interface TransitAssignmentListResult {
+  items: TransitAssignment[];
+  meta: { total: number; page: number; pageSize: number; totalPages: number };
+}
+
+export type TransitTradeDirection = "IMPORT" | "EXPORT";
+export type TransitDocumentKind = "ro" | "do" | "t1" | "gate_pass" | "djibouti_t1";
+
+/** What the officer should do next on a shipment — mirrors the detail page's gates. */
+export interface TransitNextAction {
+  kind: "upload" | "wait" | "done";
+  label: string;
+  document?: TransitDocumentKind;
+}
+
+/** Minutes, or null when nothing has been measured yet — never zero. */
+export interface TransitTimingSummary {
+  median: number | null;
+  fastest: number | null;
+  slowest: number | null;
+  measured: number;
+}
+
+export type TransitTimingKey =
+  | "transit"
+  | "declarationToRo"
+  | "bookingToDo"
+  | "departureToT1"
+  | "arrivalToT1"
+  | "arrivalToGatePass"
+  | "arrivalToDjiboutiT1"
+  | "arrivalToFinish";
+
+/** One shipment on the overview: train stamps, document stamps, derived timings. */
+export interface TransitStatItem {
+  id: string;
+  bookingId: string;
+  reference: string | null;
+  customerName: string | null;
+  tradeDirection: TransitTradeDirection;
+  status: TransitAssignmentStatus;
+  schedulingStatus: string | null;
+  trainLabel: string | null;
+  assignedAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+  bookingCreatedAt: string | null;
+  departedAt: string | null;
+  arrivedAt: string | null;
+  declaredAt: string | null;
+  roAt: string | null;
+  doAt: string | null;
+  t1At: string | null;
+  t1Closed: boolean;
+  gatePassAt: string | null;
+  djiboutiT1At: string | null;
+  documents: {
+    ro: number;
+    do: number;
+    t1: number;
+    gatePass: number;
+    djiboutiT1: number;
+    own: number;
+  };
+  timings: Record<TransitTimingKey, number | null>;
+  nextAction: TransitNextAction;
+}
+
+/**
+ * Overview figures, all derived server-side from existing timestamps: the
+ * train's departure and arrival, clearance milestones, and each document's
+ * upload time (a replaced batch counts from its last update).
+ */
+export interface TransitStats {
+  totals: {
+    assignments: number;
+    open: number;
+    notStarted: number;
+    inProgress: number;
+    finished: number;
+    imports: number;
+    exports: number;
+    awaitingDeparture: number;
+    inTransit: number;
+    arrived: number;
+    actionNeeded: number;
+  };
+  timings: Record<TransitTimingKey, TransitTimingSummary>;
+  documents: TransitStatItem["documents"];
+  pending: { ro: number; do: number; t1: number; gatePass: number; djiboutiT1: number };
+  items: TransitStatItem[];
+}
+
+export const transitAssignmentsService = {
+  /** Dashboard figures for the signed-in agent. */
+  stats: async (): Promise<TransitStats> => {
+    const { data } = await client.get(`${BASE}/stats`);
+    return data.data ?? data;
+  },
+
+  /**
+   * Bookings assigned to me. Filtering and paging are server-side: an agent's
+   * roster grows without bound, so the page must not depend on holding every
+   * row in the browser.
+   */
+  list: async (
+    params: TransitAssignmentListParams = {},
+  ): Promise<TransitAssignmentListResult> => {
+    const { data } = await client.get(BASE, { params });
+    return data.data ?? data;
+  },
+
+  /** One assignment, with its documents. */
+  getById: async (id: string): Promise<TransitAssignment> => {
+    const { data } = await client.get(`${BASE}/${id}`);
+    return data.data ?? data;
+  },
+
+  /**
+   * Upload staged documents, each with its own display name.
+   *
+   * `titles` is positional: one entry appended per file, in the same order, so
+   * the API can pair index N with file N. Sending them as a keyed object is not
+   * possible here — two files may legitimately share a filename.
+   */
+  uploadFiles: async (
+    id: string,
+    files: { file: File; title?: string }[],
+  ): Promise<TransitAssignmentFile[]> => {
+    const formData = new FormData();
+    // One field name for every file — the API keys each record by
+    // `file.fieldname`, and these are free-form documents with no fixed slots.
+    for (const entry of files) {
+      formData.append("document", entry.file);
+      formData.append("titles", entry.title?.trim() || "");
+    }
+
+    const { data } = await client.post(`${BASE}/${id}/files`, formData, {
+      headers: { "Content-Type": "multipart/form-data" },
+    });
+    return data.data ?? data;
+  },
+
+  removeFile: async (id: string, fileId: string): Promise<void> => {
+    await client.delete(`${BASE}/${id}/files/${fileId}`);
+  },
+
+  /**
+   * Save progress, or finish. Finishing locks the assignment's documents, so
+   * the caller should confirm before passing `finish: true`.
+   */
+  submit: async (
+    id: string,
+    input: { finish: boolean; note?: string },
+  ): Promise<TransitAssignment> => {
+    const { data } = await client.post(`${BASE}/${id}/submit`, input);
+    return data.data ?? data;
+  },
+
+  // ── Clearance reads for an assigned booking ──────────────────────────────
+  // These hit the shared booking/contract endpoints, not `/my`. The API scopes
+  // them to shipments this agent is assigned to and 404s anything else, so the
+  // booking id below is safe to pass straight through.
+
+  /** Clearance action history — reviews, workflow steps, charges (newest first). */
+  clearanceHistory: async (
+    bookingId: string,
+  ): Promise<Freight.ClearanceHistoryEvent[]> => {
+    const { data } = await client.get(
+      `/api/bookings/${bookingId}/clearance/history`,
+    );
+    return data.data ?? data;
+  },
+
+  /** GL Ethiopia ↔ GL Djibouti shared document thread (read-only here). */
+  glExchange: async (
+    bookingId: string,
+  ): Promise<Freight.GlExchangeDocument[]> => {
+    const { data } = await client.get(`/api/gl-exchange/${bookingId}`);
+    return data.data ?? data;
+  },
+
+  /** Cargo exception / damage reports logged against the shipment. */
+  incidents: async (bookingId: string): Promise<Freight.IClearanceIncident[]> => {
+    const { data } = await client.get(
+      `/api/contracts/bookings/${bookingId}/incidents`,
+    );
+    return data.data ?? data;
+  },
+
+  // ── Djibouti-desk writes, filed by the assigned agent ────────────────────
+  // The API gates these on the assignment (see `assertPortalClearanceAccess`),
+  // so an agent can only ever write to a shipment handed to them.
+
+  /** Delivery Order (imports). Both dates are required by the API. */
+  uploadDeliveryOrder: async (
+    bookingId: string,
+    files: File[],
+    dates: { vesselArrivalDate: string; doCollectedDate: string },
+  ): Promise<void> => {
+    const form = new FormData();
+    for (const f of files) form.append("files", f);
+    form.append("vesselArrivalDate", dates.vesselArrivalDate);
+    form.append("doCollectedDate", dates.doCollectedDate);
+    await client.post(
+      `/api/bookings/${bookingId}/clearance/delivery-order`,
+      form,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+  },
+
+  /**
+   * Release Order (exports). The API may answer with a HOLD rather than an
+   * error when the vessel date is too soon — surfaced, not swallowed.
+   */
+  uploadReleaseOrder: async (
+    bookingId: string,
+    files: File[],
+    vesselDepartureDate: string,
+  ): Promise<{ hold?: boolean; holdReason?: string | null }> => {
+    const form = new FormData();
+    for (const f of files) form.append("files", f);
+    form.append("vesselDepartureDate", vesselDepartureDate);
+    const { data } = await client.post(
+      `/api/bookings/${bookingId}/clearance/release-order`,
+      form,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+    return data.data ?? data;
+  },
+
+  /** Ask GL Ethiopia to amend the RO — puts the shipment on hold. */
+  requestRoAmendment: async (
+    bookingId: string,
+    note: string,
+  ): Promise<void> => {
+    await client.post(`/api/bookings/${bookingId}/clearance/ro-amendment`, {
+      note,
+    });
+  },
+
+  /**
+   * Share a document with both GL desks. Posted as the TRANSIT side, so it is
+   * never credited to a desk. `visibleToCustomer` additionally surfaces it in
+   * the customer's own portal.
+   */
+  shareExchangeDocument: async (
+    bookingId: string,
+    input: { file: File; title: string; visibleToCustomer: boolean },
+  ): Promise<Freight.GlExchangeDocument> => {
+    const form = new FormData();
+    form.append("file", input.file);
+    form.append("title", input.title.trim());
+    form.append("visibleToCustomer", String(input.visibleToCustomer));
+    const { data } = await client.post(`/api/gl-exchange/${bookingId}`, form, {
+      headers: { "Content-Type": "multipart/form-data" },
+    });
+    return data.data ?? data;
+  },
+
+  // ── Export arrival paperwork (gate pass / Djibouti T1) ───────────────────
+  // Append-only multi-file sets: each call ADDS files, and a file is removed on
+  // its own. The clearance view returns them under `workflowFiles` with the
+  // `gate_pass_*` / `djibouti_t1_*` codes and an `uploadedAt` stamp per file.
+
+  uploadGatePassDocuments: async (
+    bookingId: string,
+    files: File[],
+  ): Promise<{ uploaded: number }> => {
+    const form = new FormData();
+    for (const f of files) form.append("files", f);
+    const { data } = await client.post(
+      `/api/bookings/${bookingId}/clearance/gate-pass-documents`,
+      form,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+    return data.data ?? data;
+  },
+
+  uploadDjiboutiT1Documents: async (
+    bookingId: string,
+    files: File[],
+  ): Promise<{ uploaded: number }> => {
+    const form = new FormData();
+    for (const f of files) form.append("files", f);
+    const { data } = await client.post(
+      `/api/bookings/${bookingId}/clearance/djibouti-t1-documents`,
+      form,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+    return data.data ?? data;
+  },
+
+  /** Remove one gate pass / Djibouti T1 file. Other document kinds are refused. */
+  removeTransitDocument: async (
+    bookingId: string,
+    fileId: string,
+  ): Promise<void> => {
+    await client.delete(
+      `/api/bookings/${bookingId}/clearance/transit-documents/${fileId}`,
+    );
+  },
+
+  /** T1 transit documents (import); locked once GL Ethiopia closes the T1. */
+  uploadT1Documents: async (
+    bookingId: string,
+    files: File[],
+  ): Promise<void> => {
+    const form = new FormData();
+    for (const f of files) form.append("files", f);
+    await client.post(
+      `/api/contracts/bookings/${bookingId}/t1-documents`,
+      form,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+  },
+};
diff --git a/apps/edr-freight-web/portal/src/utils/truck-assignment-template.ts b/apps/edr-freight-web/portal/src/utils/truck-assignment-template.ts
index 7a0fef1cc..b3b712c6c 100644
--- a/apps/edr-freight-web/portal/src/utils/truck-assignment-template.ts
+++ b/apps/edr-freight-web/portal/src/utils/truck-assignment-template.ts
@@ -1,108 +1,551 @@
-import * as XLSX from 'xlsx';
+import * as XLSX from "xlsx";
+import {
+  CUSTOMER_TRUCK_TYPES,
+  ISO_CONTAINER_NUMBER,
+  type Freight,
+} from "@edr/types";
 
-export function generateTruckAssignmentTemplate(filename = 'truck-assignments.xlsx'): void {
-  const data = [
-    {
-      'Truck Plate Number': '3-12345/67890',
-      'Driver Name': 'John Doe',
-      'Truck Type': 'Flatbed',
-      'Container 1': 'MAEU1234567',
-      'Container 2': 'HLXU7654321',
-    },
-    {
-      'Truck Plate Number': '3-98765/43210',
-      'Driver Name': 'Jane Smith',
-      'Truck Type': 'Flatbed',
-      'Container 1': 'COSCO1111111',
-      'Container 2': '',
-    },
-  ];
+import type { BookingDetail } from "@/pages/bookings/BookingDetailPage/booking-detail-types";
 
-  const instructions = [
-    ['TRUCK ASSIGNMENT BULK UPLOAD - INSTRUCTIONS'],
-    [],
-    ['Column', 'Required', 'Notes'],
-    ['Truck Plate Number', 'Yes', 'Format: 3-XXXXX/XXXXX (Ethiopian plate format)'],
-    ['Driver Name', 'Yes', 'Full name of truck driver'],
-    ['Truck Type', 'Yes', 'e.g., Flatbed, Lowbed, Tanker, Trailer, etc.'],
-    ['Container 1', 'Yes*', '*Required for EXPORT. Leave empty for IMPORT bulk cargo.'],
-    ['Container 2', 'No', 'Optional. ISO format: e.g., MAEU1234567. Max 2 containers per truck.'],
-    [],
-    ['CONTAINER RULES'],
-    ['- A 40ft container fills one truck (max 1 per truck)'],
-    ['- Two 20ft containers fit on one truck (max 2 per truck)'],
-    ['- No size mixing on same truck'],
-    ['- Containers must be from the booking'],
-    [],
-    ['Example Data Below →'],
-  ];
+/**
+ * Bulk self-haul truck assignment via Excel.
+ *
+ * The sheet a customer gets depends on what they booked. A container booking
+ * names the containers each truck carries; a bulk booking has no containers at
+ * all — the truck hauls loose tonnage — and a break-bulk/RoRo booking is counted
+ * in items (machinery units, vehicles), not tons. Emitting one fixed set of
+ * columns for all three is what made this unusable for anything but containers.
+ *
+ * Parsing follows the house pattern in
+ * `pages/contracts/new-shipment-form/container-excel.ts`: read the sheet as a
+ * grid, match headers fuzzily, report 1-based Excel row numbers, and return
+ * all-or-nothing so a half-valid file never posts.
+ */
 
-  const wb = XLSX.utils.book_new();
+/** Two 20ft containers fit a truck bed; one 40ft fills it. Mirrors the API's `MAX_CONTAINERS_PER_TRUCK`. */
+const MAX_CONTAINERS_PER_TRUCK = 2;
 
-  // Instructions sheet
-  const wsInstructions = XLSX.utils.aoa_to_sheet(instructions);
-  wsInstructions['!cols'] = [{ wch: 30 }, { wch: 12 }, { wch: 50 }];
-  XLSX.utils.book_append_sheet(wb, wsInstructions, 'Instructions');
+export type TruckTemplateShape = "CONTAINER" | "PER_TON" | "PER_ITEM";
 
-  // Data template sheet
-  const wsData = XLSX.utils.json_to_sheet(data, {
-    header: ['Truck Plate Number', 'Driver Name', 'Truck Type', 'Container 1', 'Container 2'],
-  });
-  wsData['!cols'] = [{ wch: 20 }, { wch: 20 }, { wch: 15 }, { wch: 18 }, { wch: 18 }];
-  XLSX.utils.book_append_sheet(wb, wsData, 'Trucks');
-
-  XLSX.writeFile(wb, filename);
+export interface TruckTemplateContainer {
+  number: string;
+  /** "20ft" / "40ft", or "" when the booking line never recorded one. */
+  size: string;
+  /** Already riding another truck on this booking. */
+  assigned: boolean;
 }
 
-export function parseTruckAssignmentFile(
+export interface TruckTemplateContext {
+  shape: TruckTemplateShape;
+  reference: string;
+  /** Human label for the cargo, e.g. "Machinery (MACHINERY)" or "Containerised cargo". */
+  cargoLabel: string;
+  /** Unit noun for PER_ITEM cargo — "machinery units", "vehicles", "items". */
+  itemNoun: string;
+  containers: TruckTemplateContainer[];
+  /** Bulk only: tonnage still to be hauled, when the booking declares a total. */
+  remainingTons: number | null;
+}
+
+/** A 40ft (or an unrecorded size, treated as one) fills the bed and travels alone. */
+export function isTwentyFoot(size: string): boolean {
+  return size.includes("20");
+}
+
+/**
+ * PER_ITEM cargo is counted in pieces, and the piece has a name the customer
+ * recognises. RoRo bookings ride in as TRUCK / AUTOMOBILE / CARS.
+ */
+function itemNounFor(code: string | undefined, name: string | undefined): string {
+  switch ((code ?? "").toUpperCase()) {
+    case "TRUCK":
+    case "AUTOMOBILE":
+    case "CARS":
+    case "RORO":
+      return "vehicles";
+    case "MACHINERY":
+      return "machinery units";
+    default:
+      return name ? `${name.trim().toLowerCase()} items` : "items";
+  }
+}
+
+/**
+ * Everything the template and the parser need about one booking. Derived from
+ * data the detail endpoint already returns — no extra request.
+ */
+export function truckTemplateContext(
+  booking: BookingDetail,
+  trucks: Freight.ICustomerTruck[] = [],
+): TruckTemplateContext {
+  const assigned = new Set(
+    trucks.flatMap((t) => (t.containers ?? []).map((c) => c.containerNumber)),
+  );
+
+  // Container size lives on the booking_container LINE; the physical numbers
+  // live on its units. Walk both to get number → size.
+  const containers: TruckTemplateContainer[] = [];
+  for (const line of booking.bookingContainers ?? []) {
+    const size =
+      line.containerSize?.trim() ||
+      (line.containerType?.sizeFt ? `${line.containerType.sizeFt}ft` : "");
+    for (const unit of line.units ?? []) {
+      if (!unit.containerNumber) continue;
+      containers.push({
+        number: unit.containerNumber,
+        size,
+        assigned: assigned.has(unit.containerNumber),
+      });
+    }
+  }
+  // Fall back to the flat list when the line relation didn't come through — the
+  // numbers are still usable, we just can't police sizes client-side.
+  if (containers.length === 0) {
+    for (const number of booking.containerNumbers ?? []) {
+      containers.push({ number, size: "", assigned: assigned.has(number) });
+    }
+  }
+
+  const isContainer = String(booking.freightType) === "CONTAINER";
+  const unit = booking.cargoType?.unitOfMeasure;
+  const shape: TruckTemplateShape = isContainer
+    ? "CONTAINER"
+    : unit === "PER_ITEM"
+      ? "PER_ITEM"
+      : // PER_TON, NUMBER_OF_WAGONS and unset all haul tonnage by truck.
+        "PER_TON";
+
+  const cargoLabel = isContainer
+    ? "Containerised cargo"
+    : booking.cargoType?.cargoTypeName
+      ? `${booking.cargoType.cargoTypeName.trim()}${booking.cargoType.code ? ` (${booking.cargoType.code})` : ""}`
+      : "Bulk cargo";
+
+  // Planned tonnage already committed to live trucks draws the total down; the
+  // API applies the same rule on every add.
+  const totalTons = Number(booking.cargoTotalWeightVgm ?? 0);
+  const committed = trucks.reduce((sum, t) => sum + Number(t.plannedTons ?? 0), 0);
+  const remainingTons =
+    !isContainer && totalTons > 0
+      ? Math.max(0, Math.round((totalTons - committed) * 1000) / 1000)
+      : null;
+
+  return {
+    shape,
+    reference: booking.reference ?? "",
+    cargoLabel,
+    itemNoun: itemNounFor(booking.cargoType?.code, booking.cargoType?.cargoTypeName),
+    containers,
+    remainingTons,
+  };
+}
+
+const PLATE_HEADER = "Truck Plate Number";
+const DRIVER_HEADER = "Driver Name";
+const TYPE_HEADER = "Truck Type";
+const CONTAINER_1_HEADER = "Container 1";
+const CONTAINER_2_HEADER = "Container 2";
+const TONS_HEADER = "Planned Tons";
+const QUANTITY_HEADER = "Planned Quantity";
+
+function headersFor(shape: TruckTemplateShape): string[] {
+  const base = [PLATE_HEADER, DRIVER_HEADER, TYPE_HEADER];
+  if (shape === "CONTAINER") return [...base, CONTAINER_1_HEADER, CONTAINER_2_HEADER];
+  if (shape === "PER_ITEM") return [...base, QUANTITY_HEADER, TONS_HEADER];
+  return [...base, TONS_HEADER];
+}
+
+/** Sample rows built from the booking's own data, so the customer edits rather than invents. */
+function sampleRowsFor(ctx: TruckTemplateContext): Array<Array<string | number>> {
+  const type = CUSTOMER_TRUCK_TYPES[0];
+
+  if (ctx.shape === "CONTAINER") {
+    const free = ctx.containers.filter((c) => !c.assigned);
+    if (free.length === 0) {
+      return [["3-12345 ET", "Abebe Kebede", type, "", ""]];
+    }
+    const rows: Array<Array<string | number>> = [];
+    let i = 0;
+    let plate = 12345;
+    while (i < free.length) {
+      const first = free[i];
+      // Pair only two 20ft; a 40ft (or an unknown size) takes the truck alone.
+      const second =
+        isTwentyFoot(first.size) && free[i + 1] && isTwentyFoot(free[i + 1].size)
+          ? free[i + 1]
+          : null;
+      rows.push([
+        `3-${plate++} ET`,
+        "Abebe Kebede",
+        type,
+        first.number,
+        second?.number ?? "",
+      ]);
+      i += second ? 2 : 1;
+      if (rows.length >= 5) break;
+    }
+    return rows;
+  }
+
+  const tons = ctx.remainingTons && ctx.remainingTons > 0 ? Math.min(30, ctx.remainingTons) : 30;
+  if (ctx.shape === "PER_ITEM") {
+    return [["3-12345 ET", "Abebe Kebede", type, 2, tons]];
+  }
+  return [["3-12345 ET", "Abebe Kebede", type, tons]];
+}
+
+function instructionsFor(ctx: TruckTemplateContext): Array<Array<string | number>> {
+  const rows: Array<Array<string | number>> = [
+    ["TRUCK ASSIGNMENT — BULK UPLOAD"],
+    [],
+    ["Booking", ctx.reference],
+    ["Cargo", ctx.cargoLabel],
+    [],
+    ["Fill in the 'Trucks' sheet. One row per truck. Do not rename the headers."],
+    [],
+    ["Column", "Required", "Notes"],
+    [PLATE_HEADER, "Yes", "The truck's plate, as written on the vehicle."],
+    [DRIVER_HEADER, "Yes", "Full name of the driver."],
+    [TYPE_HEADER, "Yes", `One of: ${CUSTOMER_TRUCK_TYPES.join(", ")}`],
+  ];
+
+  if (ctx.shape === "CONTAINER") {
+    rows.push(
+      [CONTAINER_1_HEADER, "Yes", "A container number from this booking — see the 'Containers' sheet."],
+      [CONTAINER_2_HEADER, "No", "Only when pairing two 20ft containers on one truck."],
+      [],
+      ["TRUCK CAPACITY"],
+      ["One 40ft container fills a truck and travels alone."],
+      ["Two 20ft containers may share one truck."],
+      ["Never mix a 40ft and a 20ft on the same truck."],
+      ["Each container may be assigned to exactly one truck."],
+    );
+  } else if (ctx.shape === "PER_ITEM") {
+    rows.push(
+      [QUANTITY_HEADER, "Yes", `Whole number of ${ctx.itemNoun} on this truck.`],
+      [TONS_HEADER, "No", "Weight in tonnes, if known."],
+      [],
+      ["This cargo is counted in items, not containers — leave containers out entirely."],
+    );
+  } else {
+    rows.push(
+      [TONS_HEADER, "Yes", "Tonnes this truck will haul. Decimals allowed."],
+      [],
+      ["This is bulk cargo — the truck hauls loose tonnage and is weighed on exit."],
+    );
+  }
+
+  if (ctx.remainingTons != null) {
+    rows.push([], ["Tonnage still to be hauled", `${ctx.remainingTons} t`]);
+  }
+
+  return rows;
+}
+
+/** Build and download the template for this booking. */
+export function downloadTruckAssignmentTemplate(
+  ctx: TruckTemplateContext,
+  filename?: string,
+): void {
+  const workbook = XLSX.utils.book_new();
+
+  const instructions = XLSX.utils.aoa_to_sheet(instructionsFor(ctx));
+  instructions["!cols"] = [{ wch: 24 }, { wch: 12 }, { wch: 62 }];
+  XLSX.utils.book_append_sheet(workbook, instructions, "Instructions");
+
+  const headers = headersFor(ctx.shape);
+  const trucks = XLSX.utils.aoa_to_sheet([headers, ...sampleRowsFor(ctx)]);
+  trucks["!cols"] = headers.map((h) => ({ wch: Math.max(h.length + 2, 18) }));
+  XLSX.utils.book_append_sheet(workbook, trucks, "Trucks");
+
+  if (ctx.shape === "CONTAINER") {
+    const reference = XLSX.utils.aoa_to_sheet([
+      ["Container Number", "Size", "Status"],
+      ...ctx.containers.map((c) => [
+        c.number,
+        c.size || "unknown",
+        c.assigned ? "Already on a truck" : "Available",
+      ]),
+    ]);
+    reference["!cols"] = [{ wch: 20 }, { wch: 10 }, { wch: 20 }];
+    XLSX.utils.book_append_sheet(workbook, reference, "Containers");
+  }
+
+  XLSX.writeFile(
+    workbook,
+    filename ?? `truck-assignments-${ctx.reference || "booking"}.xlsx`,
+  );
+}
+
+/** Normalised header key — tolerates case, spaces, punctuation and stray units. */
+function headerKey(raw: string): string {
+  return String(raw ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * Map each template column to the index it occupies in the uploaded sheet.
+ * Matching is by normalised substring so "Planned Tons (t)" still resolves;
+ * the two container columns are matched on their digit so "Container 1" can
+ * never be captured by the looser "container" test.
+ */
+function resolveColumns(headerRow: string[]): Record<string, number> {
+  const keys = headerRow.map(headerKey);
+  const find = (...candidates: string[]): number => {
+    for (const candidate of candidates) {
+      const index = keys.findIndex((k) => k.includes(candidate));
+      if (index >= 0) return index;
+    }
+    return -1;
+  };
+  return {
+    plate: find("plate", "truckplate"),
+    driver: find("driver"),
+    type: find("trucktype", "type"),
+    container1: find("container1", "containerone"),
+    container2: find("container2", "containertwo"),
+    tons: find("plannedtons", "tons", "weight"),
+    quantity: find("plannedquantity", "quantity", "count"),
+  };
+}
+
+const TRUCK_TYPE_LIST = CUSTOMER_TRUCK_TYPES.join(", ");
+
+/** Case-insensitive match onto the canonical spelling the API expects. */
+function canonicalTruckType(raw: string): string | null {
+  const needle = raw.trim().toLowerCase();
+  return CUSTOMER_TRUCK_TYPES.find((t) => t.toLowerCase() === needle) ?? null;
+}
+
+export interface ParsedTruckFile {
+  rows: Freight.AddCustomerTruckPayload[];
+  errors: string[];
+  /** Excel row number each parsed row came from, positionally aligned with `rows`. */
+  rowNumbers: number[];
+}
+
+/**
+ * Parse an uploaded sheet against this booking. Returns every problem at once —
+ * a customer fixing a 30-row file should not discover the mistakes one upload at
+ * a time — and returns no rows at all unless the whole file is clean.
+ */
+export async function parseTruckAssignmentFile(
   file: File,
-): Promise<
-  Array<{
-    truckPlateNumber: string;
-    driverName: string;
-    truckType: string;
-    containerNumbers?: string[];
-  }>
-> {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
+  ctx: TruckTemplateContext,
+): Promise<ParsedTruckFile> {
+  const workbook = XLSX.read(await file.arrayBuffer(), { type: "array" });
+  const sheet =
+    workbook.Sheets["Trucks"] ??
+    Object.values(workbook.Sheets).find((s) => s !== workbook.Sheets["Instructions"]) ??
+    Object.values(workbook.Sheets)[0];
 
-    reader.onload = (e) => {
-      try {
-        const data = e.target?.result as ArrayBuffer;
-        const wb = XLSX.read(data, { type: 'array' });
-        const wsData = wb.Sheets['Trucks'] || Object.values(wb.Sheets)[0];
+  if (!sheet) {
+    return { rows: [], errors: ["The file has no sheets."], rowNumbers: [] };
+  }
 
-        if (!wsData) {
-          reject(new Error('No data sheet found in Excel file'));
-          return;
-        }
+  const grid = XLSX.utils.sheet_to_json<string[]>(sheet, {
+    header: 1,
+    raw: false,
+    defval: "",
+  });
 
-        const jsonData = XLSX.utils.sheet_to_json(wsData) as Array<Record<string, any>>;
+  // The header is the first row that names the plate column — customers add
+  // titles and notes above the table.
+  const headerIndex = grid.findIndex((row) =>
+    row.some((cell) => headerKey(cell).includes("plate")),
+  );
+  if (headerIndex < 0) {
+    return {
+      rows: [],
+      errors: [
+        `Could not find the "${PLATE_HEADER}" column. Use the downloaded template and keep its headers.`,
+      ],
+      rowNumbers: [],
+    };
+  }
 
-        const trucks = jsonData.map((row) => {
-          const containers = [
-            row['Container 1'],
-            row['Container 2'],
-          ]
-            .filter((c) => c && c.trim())
-            .map((c) => c.trim().toUpperCase());
+  const columns = resolveColumns(grid[headerIndex]);
+  const errors: string[] = [];
+  const rows: Freight.AddCustomerTruckPayload[] = [];
+  const rowNumbers: number[] = [];
 
-          return {
-            truckPlateNumber: row['Truck Plate Number']?.trim() || '',
-            driverName: row['Driver Name']?.trim() || '',
-            truckType: row['Truck Type']?.trim() || '',
-            containerNumbers: containers.length > 0 ? containers : undefined,
-          };
-        });
+  const containerSizes = new Map(ctx.containers.map((c) => [c.number, c.size]));
+  const alreadyAssigned = new Set(
+    ctx.containers.filter((c) => c.assigned).map((c) => c.number),
+  );
+  const plateSeen = new Map<string, number>();
+  const containerSeen = new Map<string, number>();
+  let tonsInFile = 0;
 
-        resolve(trucks);
-      } catch (error) {
-        reject(error);
-      }
+  for (let i = headerIndex + 1; i < grid.length; i++) {
+    const row = grid[i];
+    const rowNo = i + 1; // 1-based, as shown in Excel
+    const cell = (key: string): string => {
+      const index = columns[key];
+      return index >= 0 ? String(row[index] ?? "").trim() : "";
     };
 
-    reader.onerror = () => reject(new Error('Failed to read file'));
-    reader.readAsArrayBuffer(file);
-  });
+    const plate = cell("plate");
+    const driver = cell("driver");
+    const rawType = cell("type");
+
+    // A trailing blank row is normal, not an error.
+    if (!plate && !driver && !rawType && row.every((c) => !String(c ?? "").trim())) {
+      continue;
+    }
+
+    let rowOk = true;
+    if (!plate) {
+      errors.push(`Row ${rowNo}: truck plate number is required.`);
+      rowOk = false;
+    }
+    if (!driver) {
+      errors.push(`Row ${rowNo}: driver name is required.`);
+      rowOk = false;
+    }
+
+    const truckType = canonicalTruckType(rawType);
+    if (!truckType) {
+      errors.push(
+        `Row ${rowNo}: truck type "${rawType || "—"}" is not accepted. Use one of: ${TRUCK_TYPE_LIST}.`,
+      );
+      rowOk = false;
+    }
+
+    const plateKey = plate.toUpperCase();
+    if (plate) {
+      const seenAt = plateSeen.get(plateKey);
+      if (seenAt) {
+        errors.push(`Row ${rowNo}: plate ${plate} already appears on row ${seenAt}.`);
+        rowOk = false;
+      } else {
+        plateSeen.set(plateKey, rowNo);
+      }
+    }
+
+    const payload: Freight.AddCustomerTruckPayload = {
+      truckPlateNumber: plateKey,
+      driverName: driver,
+      truckType: truckType ?? "",
+    };
+
+    if (ctx.shape === "CONTAINER") {
+      const numbers = [cell("container1"), cell("container2")]
+        .map((n) => n.trim().toUpperCase())
+        .filter(Boolean);
+
+      if (numbers.length === 0) {
+        errors.push(`Row ${rowNo}: at least one container number is required.`);
+        rowOk = false;
+      }
+      if (numbers.length > MAX_CONTAINERS_PER_TRUCK) {
+        errors.push(`Row ${rowNo}: a truck carries at most ${MAX_CONTAINERS_PER_TRUCK} containers.`);
+        rowOk = false;
+      }
+      if (numbers.length === 2 && numbers[0] === numbers[1]) {
+        errors.push(`Row ${rowNo}: container ${numbers[0]} is listed twice on the same truck.`);
+        rowOk = false;
+      }
+
+      for (const number of numbers) {
+        if (!ISO_CONTAINER_NUMBER.test(number)) {
+          errors.push(
+            `Row ${rowNo}: container "${number}" is not a valid ISO number (four letters then seven digits, e.g. ABCD1234567).`,
+          );
+          rowOk = false;
+          continue;
+        }
+        if (ctx.containers.length > 0 && !containerSizes.has(number)) {
+          errors.push(`Row ${rowNo}: container ${number} is not on this booking.`);
+          rowOk = false;
+          continue;
+        }
+        if (alreadyAssigned.has(number)) {
+          errors.push(`Row ${rowNo}: container ${number} is already loaded onto another truck.`);
+          rowOk = false;
+          continue;
+        }
+        const seenAt = containerSeen.get(number);
+        if (seenAt) {
+          errors.push(`Row ${rowNo}: container ${number} is already used on row ${seenAt}.`);
+          rowOk = false;
+          continue;
+        }
+        containerSeen.set(number, rowNo);
+      }
+
+      // Pairing is allowed only when both are explicitly 20ft — a 40ft, or a
+      // container whose size was never recorded, fills the bed on its own. Same
+      // rule the API enforces in `assertTruckLoad`.
+      if (numbers.length === 2) {
+        const sizes = numbers.map((n) => containerSizes.get(n) ?? "");
+        if (sizes.some((size) => !isTwentyFoot(size))) {
+          errors.push(
+            `Row ${rowNo}: a truck carries either one 40ft container or two 20ft containers — ${numbers
+              .map((n, idx) => `${n} (${sizes[idx] || "size unknown"})`)
+              .join(" and ")} cannot share one.`,
+          );
+          rowOk = false;
+        }
+      }
+
+      payload.containerNumbers = numbers;
+    } else {
+      const tonsRaw = cell("tons");
+      const tons = Number(tonsRaw);
+      const quantityRaw = cell("quantity");
+      const quantity = Number(quantityRaw);
+
+      if (ctx.shape === "PER_ITEM") {
+        if (!quantityRaw || !Number.isInteger(quantity) || quantity <= 0) {
+          errors.push(
+            `Row ${rowNo}: planned quantity "${quantityRaw || "—"}" must be a whole number of ${ctx.itemNoun} greater than 0.`,
+          );
+          rowOk = false;
+        } else {
+          payload.plannedQuantity = quantity;
+        }
+        if (tonsRaw) {
+          if (Number.isNaN(tons) || tons <= 0) {
+            errors.push(`Row ${rowNo}: planned tons "${tonsRaw}" must be a number greater than 0.`);
+            rowOk = false;
+          } else {
+            payload.plannedTons = tons;
+            tonsInFile += tons;
+          }
+        }
+      } else {
+        if (!tonsRaw || Number.isNaN(tons) || tons <= 0) {
+          errors.push(
+            `Row ${rowNo}: planned tons "${tonsRaw || "—"}" must be a number greater than 0.`,
+          );
+          rowOk = false;
+        } else {
+          payload.plannedTons = tons;
+          tonsInFile += tons;
+        }
+      }
+    }
+
+    if (rowOk) {
+      rows.push(payload);
+      rowNumbers.push(rowNo);
+    }
+  }
+
+  if (
+    ctx.remainingTons != null &&
+    tonsInFile > ctx.remainingTons + 0.001 // numeric(14,3) — tolerate float drift
+  ) {
+    errors.push(
+      `The file plans ${Math.round(tonsInFile * 1000) / 1000} t but only ${ctx.remainingTons} t are left to haul on this booking.`,
+    );
+  }
+
+  if (rows.length === 0 && errors.length === 0) {
+    errors.push("The sheet has no truck rows below the header.");
+  }
+
+  return errors.length > 0
+    ? { rows: [], errors, rowNumbers: [] }
+    : { rows, errors: [], rowNumbers };
 }
diff --git a/apps/edr-passenger-api/src/common/throttle-sign-in.decorator.ts b/apps/edr-passenger-api/src/common/throttle-sign-in.decorator.ts
new file mode 100644
index 000000000..40c1ee106
--- /dev/null
+++ b/apps/edr-passenger-api/src/common/throttle-sign-in.decorator.ts
@@ -0,0 +1,4 @@
+import { applyDecorators, UseGuards } from '@nestjs/common';
+import { Throttle, ThrottlerGuard } from '@nestjs/throttler';
+export const ThrottleSignIn = (limit = 20) =>
+  applyDecorators(UseGuards(ThrottlerGuard), Throttle({ auth: { limit, ttl: 60_000 } }));
diff --git a/apps/edr-passenger-api/src/modules/auth/auth.controller.ts b/apps/edr-passenger-api/src/modules/auth/auth.controller.ts
index ce076c970..76cbb8477 100644
--- a/apps/edr-passenger-api/src/modules/auth/auth.controller.ts
+++ b/apps/edr-passenger-api/src/modules/auth/auth.controller.ts
@@ -21,7 +21,7 @@ import {
   ApiBearerAuth,
 } from "@nestjs/swagger";
 import { IsPublic } from "@tria-plc/api-common/modules/auth/decorators/public.decorator";
-import { Throttle, ThrottlerGuard } from "@nestjs/throttler";
+import { ThrottleSignIn } from "../../common/throttle-sign-in.decorator";
 import { PassengerAuthService } from "./passenger-auth.service";
 import {
   RegisterDto,
@@ -37,16 +37,12 @@ import { JwtGuard } from "../../common/jwt.guard";
 
 @ApiTags("Passenger Auth")
 @Controller("auth")
-// Scoped to this controller rather than registered as a global APP_GUARD: the staged sign-in
-// exposes an account-existence lookup, and rate limiting is the mitigation for it. Applying the
-// guard app-wide would change the behaviour of every other module at the same time.
-@UseGuards(ThrottlerGuard)
-@Throttle({ auth: { limit: 20, ttl: 60_000 } })
 export class AuthController {
   constructor(private passengerAuthService: PassengerAuthService) {}
 
   @Post("register")
   @IsPublic()
+  @ThrottleSignIn()
   @ApiOperation({
     summary: "Register new passenger account (sends SMS verification code)",
   })
@@ -66,6 +62,7 @@ export class AuthController {
 
   @Post("register/resend-code")
   @IsPublic()
+  @ThrottleSignIn()
   @HttpCode(HttpStatus.OK)
   @ApiOperation({
     summary: "Resend the registration verification code for a pending account",
@@ -84,6 +81,7 @@ export class AuthController {
 
   @Post("login")
   @IsPublic()
+  @ThrottleSignIn()
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: "Login with email and password" })
   @ApiResponse({
@@ -199,11 +197,11 @@ export class AuthController {
 
   @Post("identifier/lookup")
   @IsPublic()
+  // Tighter than the other sign-in endpoints: this is the one that answers "does this account
+  // exist", so it is the one worth making expensive to sweep. Still roomy enough that a
+  // passenger correcting a typo two or three times is unaffected.
+  @ThrottleSignIn(10)
   @HttpCode(HttpStatus.OK)
-  // Tighter than the rest of the controller: this is the endpoint that answers "does this
-  // account exist", so it is the one worth making expensive to sweep. Still roomy enough
-  // that a passenger correcting a typo two or three times is unaffected.
-  @Throttle({ auth: { limit: 10, ttl: 60_000 } })
   @ApiOperation({
     summary: "Step 1 of sign-in — decide what to ask the user for next",
     description:
@@ -222,6 +220,7 @@ export class AuthController {
 
   @Post("password-setup/request")
   @IsPublic()
+  @ThrottleSignIn()
   @HttpCode(HttpStatus.OK)
   @ApiOperation({
     summary: "Send the SMS code that lets an account with no password set one",
@@ -237,6 +236,7 @@ export class AuthController {
 
   @Post("password-setup/complete")
   @IsPublic()
+  @ThrottleSignIn()
   @HttpCode(HttpStatus.OK)
   @ApiOperation({
     summary: "Redeem the code, set the password, and sign in",
@@ -256,6 +256,7 @@ export class AuthController {
 
   @Post("fayda/request-password-setup")
   @IsPublic()
+  @ThrottleSignIn()
   @HttpCode(HttpStatus.OK)
   @ApiOperation({
     summary: "Send OTP to phone for Fayda-verified account password setup",
@@ -277,6 +278,7 @@ export class AuthController {
 
   @Post("fayda/verify-and-login")
   @IsPublic()
+  @ThrottleSignIn()
   @HttpCode(HttpStatus.OK)
   @ApiOperation({
     summary: "Verify OTP and receive session token for Fayda-verified account",
diff --git a/apps/edr-passenger-api/src/modules/bookings/bookings.controller.ts b/apps/edr-passenger-api/src/modules/bookings/bookings.controller.ts
index ecd3b4043..36f2b7250 100644
--- a/apps/edr-passenger-api/src/modules/bookings/bookings.controller.ts
+++ b/apps/edr-passenger-api/src/modules/bookings/bookings.controller.ts
@@ -22,7 +22,7 @@ import {
   ApiBody,
 } from "@nestjs/swagger";
 import { IsPublic } from "@tria-plc/api-common/modules/auth/decorators/public.decorator";
-import { BookingsService } from "./bookings.service";
+import { BookingsService, BookingScope } from "./bookings.service";
 import { GuestBookingService } from "./guest-booking.service";
 import {
   CreateBookingDto,
@@ -38,6 +38,8 @@ import { PassengerAdmin, PassengerStaff, PassengerStaffStrict } from "../../comm
 import { PASSENGER_PERMS } from "../../seed/passenger-permissions.registry";
 import { SeatsService } from "../seats/seats.service";
 
+const BOOKING_SCOPES: BookingScope[] = ["upcoming", "past", "cancelled", "all"];
+
 @ApiTags("Booking")
 @Controller("bookings")
 // @Throttle({ strict: { limit: 20, ttl: 60_000 } })
@@ -66,6 +68,13 @@ export class BookingsController {
     required: false,
     description: "Filter by booking status",
   })
+  @ApiQuery({
+    name: "scope",
+    required: false,
+    enum: ["upcoming", "past", "cancelled", "all"],
+    description:
+      "Which slice of the history to return. 'upcoming' and 'past' split on the schedule's departure and exclude cancelled/refunded bookings; 'cancelled' returns only those. Defaults to 'all'.",
+  })
   @ApiQuery({ name: "page", required: false, description: "Page number" })
   @ApiQuery({
     name: "pageSize",
@@ -80,6 +89,7 @@ export class BookingsController {
     @Req() req: any,
     @Query("search") search?: string,
     @Query("status") status?: string,
+    @Query("scope") scope?: BookingScope,
     @Query("page") page?: string,
     @Query("pageSize") pageSize?: string,
   ) {
@@ -88,6 +98,7 @@ export class BookingsController {
     return this.service.findByIamUserId(iamUserId, {
       search,
       status,
+      scope: BOOKING_SCOPES.includes(scope as BookingScope) ? scope : "all",
       page: page ? parseInt(page) : 1,
       pageSize: pageSize ? parseInt(pageSize) : 20,
     });
diff --git a/apps/edr-passenger-api/src/modules/bookings/bookings.service.ts b/apps/edr-passenger-api/src/modules/bookings/bookings.service.ts
index 7a447690a..b627d64ba 100644
--- a/apps/edr-passenger-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-passenger-api/src/modules/bookings/bookings.service.ts
@@ -15,7 +15,7 @@ import { FareEngineService } from '../fare-engine/fare-engine.service';
 import { PaymentsService } from '../payments/payments.service';
 import { MAX_PAYMENT_HOURS } from '../../common/utils/payment-deadline.utils';
 import { normalizePhoneVariants } from '../../common/utils/phone.utils';
-import { Currency, PassengerCategory, IdDocumentType } from '@prisma/client';
+import { BookingStatus, Currency, PassengerCategory, IdDocumentType } from '@prisma/client';
 import { JourneyDirection } from '../seats/seats.dto';
 import { resolveCurrencyFromNationality } from '../fare-engine/fare-engine.dto';
 import { DeleteOperationException } from '../../common/exceptions/delete-operation.exception';
@@ -67,8 +67,15 @@ interface BookingFilters {
   dateTo?: string;
   page?: number;
   pageSize?: number;
+  /** Portal "My bookings" tabs. Only honoured by findByPassengerId. */
+  scope?: BookingScope;
 }
 
+export type BookingScope = 'upcoming' | 'past' | 'cancelled' | 'all';
+
+/** Statuses that mean the reservation is off — used by the `cancelled` scope. */
+const CLOSED_BOOKING_STATUSES: BookingStatus[] = ['CANCELLED', 'REFUNDED'];
+
 @Injectable()
 export class BookingsService {
   private readonly logger = new Logger(BookingsService.name);
@@ -87,16 +94,34 @@ export class BookingsService {
   ) {}
 
   async findByIamUserId(iamUserId: string, filters: BookingFilters = {}) {
-    const passenger = await this.prisma.passenger.findUniqueOrThrow({ where: { iamUserId }, select: { id: true } });
+    // An IAM user with no Passenger row is normal, not an error: a freshly registered
+    // account that has never booked, or a staff account. findUniqueOrThrow raised P2025
+    // here, which surfaced as a 500 on the portal's "My bookings" page. Empty page instead.
+    const passenger = await this.prisma.passenger.findUnique({ where: { iamUserId }, select: { id: true } });
+    if (!passenger) {
+      const page = filters.page ?? 1;
+      const pageSize = filters.pageSize ?? 20;
+      return { items: [], meta: { page, pageSize, total: 0, totalPages: 0 } };
+    }
     return this.findByPassengerId(passenger.id, filters);
   }
 
+  /**
+   * The portal's authenticated "My bookings" history (GET /bookings/my).
+   *
+   * `scope` drives the Upcoming / Past / Cancelled tabs server-side so each tab paginates
+   * correctly, rather than the client filtering one page at a time. Note it filters on
+   * `schedule.departureAt` — the schedule's own origin departure — while each item's
+   * displayed `departureAt` comes from resolveBookingSegment, i.e. the passenger's own
+   * boarding stop. They differ by the run time to that stop; that is close enough for a
+   * tab filter and avoids a correlated stopTimes query per row.
+   */
   async findByPassengerId(passengerId: string, filters: BookingFilters = {}) {
-    const { search, status, page = 1, pageSize = 20 } = filters;
+    const { search, status, scope = 'all', page = 1, pageSize = 20 } = filters;
     const skip = (page - 1) * pageSize;
-    
+
     const where: any = { passengerId };
-    
+
     if (search) {
       where.OR = [
         { bookingRef: { contains: search, mode: 'insensitive' } },
@@ -104,22 +129,41 @@ export class BookingsService {
         { schedule: { destinationStation: { name: { contains: search, mode: 'insensitive' } } } },
       ];
     }
-    
-    if (status) {
+
+    // `status` used to be forwarded raw, so an unrecognised value threw a Prisma
+    // validation error (a 500) rather than being ignored. Only accept real enum members.
+    if (status && (Object.values(BookingStatus) as string[]).includes(status)) {
       where.status = status;
     }
-    
+
+    const now = new Date();
+    let orderBy: any = { createdAt: 'desc' };
+    if (scope === 'cancelled') {
+      where.status = { in: CLOSED_BOOKING_STATUSES };
+    } else if (scope === 'upcoming' || scope === 'past') {
+      // Don't clobber an explicit `status` filter — intersect with it.
+      if (!where.status) where.status = { notIn: CLOSED_BOOKING_STATUSES };
+      where.schedule = {
+        ...(where.schedule ?? {}),
+        departureAt: scope === 'upcoming' ? { gte: now } : { lt: now },
+      };
+      orderBy = { schedule: { departureAt: scope === 'upcoming' ? 'asc' : 'desc' } };
+    }
+
     const [items, total] = await Promise.all([
       this.prisma.booking.findMany({
         where,
         skip,
         take: pageSize,
-        orderBy: { createdAt: 'desc' },
+        orderBy,
         include: {
           schedule: { include: { originStation: true, destinationStation: true, train: true, stopTimes: { include: { station: true } } } },
           paymentIntent: true,
-          seats: { include: { seat: true } },
+          seats: { include: { seat: { include: { coach: { select: { number: true } } } } } },
           priceTier: { select: { priceMinor: true } },
+          // A rescheduled booking stays CONFIRMED — there is no RESCHEDULED status — so the
+          // portal needs this to show a "Rescheduled" chip alongside the real status.
+          reschedules: { where: { status: 'APPLIED' }, select: { id: true } },
         },
       }),
       this.prisma.booking.count({ where }),
@@ -150,6 +194,21 @@ export class BookingsService {
           },
           paymentIntent: booking.paymentIntent,
           seatCount: booking.seats.length,
+          // Seat/coach per passenger, so the history table can show a Seat / Coach column
+          // without a round trip to GET /bookings/:ref for every row. `leg` disambiguates
+          // outbound (1) from return (2) on a round trip.
+          seats: booking.seats.map((bs: any) => ({
+            leg: bs.leg ?? 1,
+            passengerName: bs.passengerName,
+            seatNumber: bs.seat?.seatNumber ?? null,
+            coachNumber: bs.seat?.coach?.number ?? null,
+          })),
+          rescheduled: ((booking as any).reschedules?.length ?? 0) > 0,
+          // These three let the portal apply the same coarse reschedule gate the booking
+          // detail page uses, without fetching each booking in full.
+          outboundBoardedAt: (booking as any).outboundBoardedAt ?? null,
+          isPackageBooking: !!(booking as any).packageId,
+          contactPhone: (booking as any).contactPhone ?? null,
         };
       }),
       meta: {
diff --git a/apps/edr-passenger-api/src/modules/reports/finance-trip-type.spec.ts b/apps/edr-passenger-api/src/modules/reports/finance-trip-type.spec.ts
new file mode 100644
index 000000000..8c25abd35
--- /dev/null
+++ b/apps/edr-passenger-api/src/modules/reports/finance-trip-type.spec.ts
@@ -0,0 +1,35 @@
+import { tripTypeFor } from './finance-trip-type';
+import { FinanceTripType } from './reports.dto';
+
+describe('tripTypeFor', () => {
+  it('counts a trip between two Ethiopian stations as intercity', () => {
+    // Sebeta → Dire Dawa
+    expect(tripTypeFor('ET', 'ET')).toBe(FinanceTripType.INTERCITY);
+  });
+
+  it('counts a trip leaving Ethiopia as international', () => {
+    // Sebeta → Nagad
+    expect(tripTypeFor('ET', 'DJ')).toBe(FinanceTripType.INTERNATIONAL);
+  });
+
+  it('counts a trip arriving in Ethiopia as international', () => {
+    // Nagad → Sebeta
+    expect(tripTypeFor('DJ', 'ET')).toBe(FinanceTripType.INTERNATIONAL);
+  });
+
+  it('counts a trip wholly inside Djibouti as international', () => {
+    // Alisabieh → Nagad — international because neither endpoint is Ethiopian, not because
+    // the trip crosses a border.
+    expect(tripTypeFor('DJ', 'DJ')).toBe(FinanceTripType.INTERNATIONAL);
+  });
+
+  it('treats a station with no country code as Ethiopian', () => {
+    expect(tripTypeFor(null, null)).toBe(FinanceTripType.INTERCITY);
+    expect(tripTypeFor(undefined, 'ET')).toBe(FinanceTripType.INTERCITY);
+  });
+
+  it('still reports international when only the known endpoint is outside Ethiopia', () => {
+    expect(tripTypeFor(null, 'DJ')).toBe(FinanceTripType.INTERNATIONAL);
+    expect(tripTypeFor('DJ', undefined)).toBe(FinanceTripType.INTERNATIONAL);
+  });
+});
diff --git a/apps/edr-passenger-api/src/modules/reports/finance-trip-type.ts b/apps/edr-passenger-api/src/modules/reports/finance-trip-type.ts
new file mode 100644
index 000000000..401a11834
--- /dev/null
+++ b/apps/edr-passenger-api/src/modules/reports/finance-trip-type.ts
@@ -0,0 +1,34 @@
+/**
+ * Finance trip type — the domestic / cross-border rule.
+ *
+ * Deliberately free of Prisma and Nest, in the same spirit as
+ * `blocked-seats-loss.calculator.ts`: `ReportsService` fetches the stations, this module
+ * decides what the station pair means. Every case below has a unit test in
+ * `finance-trip-type.spec.ts`.
+ */
+
+import { FinanceTripType } from './reports.dto';
+
+/** The country a station has to sit in for a trip to count as domestic Ethiopian traffic. */
+export const DOMESTIC_COUNTRY = 'ET';
+
+/**
+ * Classifies a trip from its endpoints' `Station.countryCode`: intercity when both endpoints
+ * are Ethiopian, international as soon as either is not — so Sebeta → Nagad, Nagad → Sebeta
+ * and Alisabieh → Nagad are all international.
+ *
+ * A station with no `countryCode` is treated as Ethiopian. The column is nullable and the
+ * back-office station form defaults it to `'ET'`, which is the same assumption the portal
+ * makes when deciding whether a passenger needs a Fayda ID. Defaulting rather than carrying
+ * an "unknown" bucket keeps the invariant that intercity + international equals the
+ * unfiltered total.
+ */
+export function tripTypeFor(
+  originCountry: string | null | undefined,
+  destinationCountry: string | null | undefined,
+): FinanceTripType {
+  const bothDomestic =
+    (originCountry ?? DOMESTIC_COUNTRY) === DOMESTIC_COUNTRY &&
+    (destinationCountry ?? DOMESTIC_COUNTRY) === DOMESTIC_COUNTRY;
+  return bothDomestic ? FinanceTripType.INTERCITY : FinanceTripType.INTERNATIONAL;
+}
diff --git a/apps/edr-passenger-api/src/modules/reports/reports.controller.ts b/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
index 6cf12a9f6..8e92c12f4 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
@@ -122,16 +122,29 @@ export class ReportsController {
 
   @Get("finance")
   @ApiOperation({
-    summary: "Finance summary — revenue by period, origin/destination segment, payment method, and currency",
+    summary: "Finance summary — revenue by period, origin/destination segment, trip type, booking type, payment method, and currency",
     description:
       "Revenue collected in the window (PaymentIntent.paidAt), grouped by day/week/month, origin → " +
       "destination station pair, payment method, and currency. Amounts are never converted to ETB — a " +
       "Waafi payment is reported in whatever currency Waafi actually charged, and with no method filter " +
       "every currency present is listed separately rather than summed. Filter by originStationId and/or " +
       "destinationStationId independently to query any station-pair segment (A→B, A→D, B→C), not just a " +
-      "whole predefined route. Only counts CONFIRMED/BOARDED bookings with a SUCCEEDED payment — the same " +
-      "revenue definition as the dashboard and /payments confirmed-revenue filter. Returns per-bucket rows " +
-      "plus roll-ups by period, segment, and method for charting.",
+      "whole predefined route. Pass `tripType` to split domestic from cross-border traffic: a trip is " +
+      "`intercity` only when both endpoints sit in Ethiopia, and `international` as soon as either endpoint " +
+      "is outside it — so Sebeta → Nagad, Nagad → Sebeta and Alisabieh → Nagad are all international. Pass " +
+      "`bookingType` to separate travel-package revenue from ordinary ticket sales: `package` is a booking " +
+      "carrying a `packageId`, `regular` is one without — unrelated to the ONE_WAY/ROUND_TRIP booking type, " +
+      "and not counting the legacy standalone `PackageBooking` table, which this report has never included. " +
+      "Pass `revenueType` to isolate one revenue stream: `ticket` is the booking fare, `excess_baggage` a " +
+      "collected luggage fee, `outstanding` a recovered underpayment, and `other` every remaining " +
+      "supplementary charge (upgrade, reschedule, and any reason added later). Fare revenue counts " +
+      "CONFIRMED/BOARDED bookings with a SUCCEEDED payment — the same definition as the dashboard and the " +
+      "/payments confirmed-revenue filter. Charges count as collected on their own status (PAID, plus " +
+      "CASH_COLLECTED for baggage) and are deliberately NOT re-checked against the booking: a fee that was " +
+      "collected stays collected even if the booking is cancelled afterwards, unlike the fare. Charge rows " +
+      "report `UNKNOWN` as their payment method because settling a charge records only a providerTxnId, and " +
+      "a `method` filter therefore excludes them. Returns per-bucket rows plus roll-ups by period, segment, " +
+      "trip type, booking type, revenue type, and method for charting.",
   })
   getFinanceSummary(@Query() query: FinanceSummaryQueryDto) {
     return this.service.getFinanceSummary(query);
diff --git a/apps/edr-passenger-api/src/modules/reports/reports.dto.ts b/apps/edr-passenger-api/src/modules/reports/reports.dto.ts
index 6c6b304d4..6c824bea8 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.dto.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.dto.ts
@@ -113,6 +113,41 @@ export enum FinanceGranularity {
   MONTHLY = 'monthly',
 }
 
+/**
+ * Domestic vs cross-border traffic, derived from the endpoints' `Station.countryCode`:
+ * a trip is INTERCITY only when both endpoints sit in Ethiopia, and INTERNATIONAL as soon
+ * as either endpoint is outside it — which on this line means Djibouti (Alisabieh, Holhol,
+ * Nagad). A trip wholly inside Djibouti counts as INTERNATIONAL too.
+ */
+export enum FinanceTripType {
+  INTERCITY = 'intercity',
+  INTERNATIONAL = 'international',
+}
+
+/**
+ * Travel-package revenue vs ordinary ticket sales, derived from `Booking.packageId`.
+ * NOT the `Booking.bookingType` column, which holds ONE_WAY / ROUND_TRIP — every package
+ * booking happens to be ROUND_TRIP, but that is a different question from this one.
+ */
+export enum FinanceBookingType {
+  REGULAR = 'regular',
+  PACKAGE = 'package',
+}
+
+/**
+ * Which revenue stream a row came from. `ticket` is the booking fare — all this report used to
+ * count. The rest are fees collected after the fare: `excess_baggage` from ExcessBaggageCharge,
+ * `outstanding` from a PAID SupplementaryCharge with reason UNDERPAYMENT, and `other` from every
+ * remaining supplementary reason (UPGRADE, RESCHEDULE, and anything added later — `reason` is a
+ * free-text column, so this bucket is deliberately open-ended).
+ */
+export enum FinanceRevenueType {
+  TICKET = 'ticket',
+  EXCESS_BAGGAGE = 'excess_baggage',
+  OUTSTANDING = 'outstanding',
+  OTHER = 'other',
+}
+
 export class FinanceSummaryQueryDto {
   @ApiProperty({ example: '2026-07-01', description: 'Start of the window, inclusive, matched on PaymentIntent.paidAt.' })
   @IsDateString() dateFrom: string;
@@ -131,4 +166,29 @@ export class FinanceSummaryQueryDto {
 
   @ApiPropertyOptional({ enum: PaymentMethodType, description: 'Restrict to payments made with this method.' })
   @IsOptional() @IsEnum(PaymentMethodType) method?: PaymentMethodType;
+
+  @ApiPropertyOptional({
+    enum: FinanceTripType,
+    description:
+      'Restrict to trips wholly inside Ethiopia (intercity) or trips touching a station outside ' +
+      'Ethiopia (international — in practice Djibouti). Omit for all trips.',
+  })
+  @IsOptional() @IsEnum(FinanceTripType) tripType?: FinanceTripType;
+
+  @ApiPropertyOptional({
+    enum: FinanceBookingType,
+    description:
+      'Restrict to ordinary ticket sales (regular) or travel-package bookings (package). ' +
+      'Omit for all bookings. Unrelated to the ONE_WAY/ROUND_TRIP booking type.',
+  })
+  @IsOptional() @IsEnum(FinanceBookingType) bookingType?: FinanceBookingType;
+
+  @ApiPropertyOptional({
+    enum: FinanceRevenueType,
+    description:
+      'Restrict to one revenue stream: the booking fare (ticket), excess-baggage fees ' +
+      '(excess_baggage), recovered underpayments (outstanding), or every other supplementary ' +
+      'charge such as upgrades and reschedules (other). Omit for all revenue.',
+  })
+  @IsOptional() @IsEnum(FinanceRevenueType) revenueType?: FinanceRevenueType;
 }
diff --git a/apps/edr-passenger-api/src/modules/reports/reports.service.ts b/apps/edr-passenger-api/src/modules/reports/reports.service.ts
index d727014ee..2af120d02 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.service.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.service.ts
@@ -11,11 +11,15 @@ import { FareEngineService } from "../fare-engine/fare-engine.service";
 import {
   BlockedSeatsLossSortBy,
   BlockedSeatsRevenueLossQueryDto,
+  FinanceBookingType,
   FinanceGranularity,
+  FinanceRevenueType,
   FinanceSummaryQueryDto,
+  FinanceTripType,
   GenerateReportDto,
   ReportType,
 } from "./reports.dto";
+import { tripTypeFor } from "./finance-trip-type";
 import {
   assembleReport,
   isDiningCoach,
@@ -146,11 +150,36 @@ function periodKeyFor(date: Date, granularity: FinanceGranularity): string {
   return date.toISOString().split("T")[0];
 }
 
+/** The `SupplementaryCharge.reason` that means a passenger under-paid and later settled up. */
+const UNDERPAYMENT_REASON = "UNDERPAYMENT";
+
+/**
+ * Payment method reported for a charge row. Settling a supplementary or excess-baggage fee
+ * records only a providerTxnId — the method is never stored — so charge revenue lands in one
+ * explicit bucket rather than being dropped from the method breakdown, which keeps that
+ * roll-up summing to the report total.
+ */
+const CHARGE_METHOD_UNKNOWN = "UNKNOWN";
+
+/** The dimensions every revenue row takes off its booking, whether it is a fare or a fee. */
+interface FinanceRowBooking {
+  originStationId: string | null;
+  destinationStationId: string | null;
+  packageId: string | null;
+  schedule: { originStationId: string; destinationStationId: string };
+}
+
 export interface FinanceBucket {
   period: string;
   originStationId: string;
   destinationStationId: string;
   segmentLabel: string;
+  tripType: FinanceTripType;
+  /** regular vs package — from `Booking.packageId`, not the ONE_WAY/ROUND_TRIP column. */
+  bookingType: FinanceBookingType;
+  /** Which revenue stream this row came from — the fare, or a fee collected after it. */
+  revenueType: FinanceRevenueType;
+  /** `UNKNOWN` on every charge row: nothing records how a supplementary or baggage fee was paid. */
   method: string;
   currency: string;
   bookingCount: number;
@@ -1766,77 +1795,218 @@ export class ReportsService {
     const dateTo = new Date(query.dateTo + "T23:59:59.999Z");
     const granularity = query.granularity ?? FinanceGranularity.DAILY;
 
-    const bookings = await this.prisma.booking.findMany({
-      where: {
-        // Same revenue definition as the dashboard's backoffice-stats and the /payments
-        // "confirmed revenue" filter: the booking must still be CONFIRMED/BOARDED (a booking
-        // that was paid and later cancelled is not revenue) and the payment itself must have
-        // actually succeeded, not just carry a stale paidAt.
-        status: { in: ["CONFIRMED", "BOARDED"] },
-        paymentIntent: {
-          status: "SUCCEEDED",
-          paidAt: { gte: dateFrom, lte: dateTo },
-          ...(query.method ? { method: query.method } : {}),
-        },
-        ...(query.originStationId ? { originStationId: query.originStationId } : {}),
-        ...(query.destinationStationId ? { destinationStationId: query.destinationStationId } : {}),
-      },
+    // Charge rows carry no payment method — paying a supplementary or baggage fee records only
+    // a providerTxnId — so a method filter can never match one, and asking for a charge stream
+    // means the booking query has nothing to contribute. Skip the queries the filter rules out
+    // rather than fetching rows that will all be discarded.
+    const wantsTicket = !query.revenueType || query.revenueType === FinanceRevenueType.TICKET;
+    const wantsCharges = !query.method && query.revenueType !== FinanceRevenueType.TICKET;
+    const wantsBaggage =
+      wantsCharges && (!query.revenueType || query.revenueType === FinanceRevenueType.EXCESS_BAGGAGE);
+    const wantsSupplementary =
+      wantsCharges &&
+      (!query.revenueType ||
+        query.revenueType === FinanceRevenueType.OUTSTANDING ||
+        query.revenueType === FinanceRevenueType.OTHER);
+
+    // The station / package filters reach a charge through its parent booking, exactly as they
+    // reach a fare through the booking itself.
+    const bookingScope = {
+      ...(query.originStationId ? { originStationId: query.originStationId } : {}),
+      ...(query.destinationStationId ? { destinationStationId: query.destinationStationId } : {}),
+      ...(query.bookingType
+        ? { packageId: query.bookingType === FinanceBookingType.PACKAGE ? { not: null } : null }
+        : {}),
+    };
+    // Every charge needs the same dimensions a fare row carries, and they all live on the booking.
+    const chargeBookingSelect = {
       select: {
-        totalMinor: true,
-        currency: true,
-        displayTotalMinor: true,
-        displayCurrency: true,
         originStationId: true,
         destinationStationId: true,
+        packageId: true,
         schedule: { select: { originStationId: true, destinationStationId: true } },
-        paymentIntent: { select: { paidAt: true, method: true } },
       },
-    });
+    };
+
+    const bookings = wantsTicket
+      ? await this.prisma.booking.findMany({
+          where: {
+            // Same revenue definition as the dashboard's backoffice-stats and the /payments
+            // "confirmed revenue" filter: the booking must still be CONFIRMED/BOARDED (a booking
+            // that was paid and later cancelled is not revenue) and the payment itself must have
+            // actually succeeded, not just carry a stale paidAt.
+            status: { in: ["CONFIRMED", "BOARDED"] },
+            paymentIntent: {
+              status: "SUCCEEDED",
+              paidAt: { gte: dateFrom, lte: dateTo },
+              ...(query.method ? { method: query.method } : {}),
+            },
+            ...bookingScope,
+          },
+          select: {
+            totalMinor: true,
+            packageId: true,
+            currency: true,
+            displayTotalMinor: true,
+            displayCurrency: true,
+            originStationId: true,
+            destinationStationId: true,
+            schedule: { select: { originStationId: true, destinationStationId: true } },
+            paymentIntent: { select: { paidAt: true, method: true } },
+          },
+        })
+      : [];
+
+    // Charges are NOT re-checked against the booking's status. A fee that was collected stays
+    // collected even if the booking is cancelled afterwards — unlike the fare, which this report
+    // drops on cancellation. CASH_COLLECTED counts as settled: it is the paid test the
+    // excess-baggage service itself uses, and it stamps paidAt when the cash is taken.
+    const baggageCharges = wantsBaggage
+      ? await this.prisma.excessBaggageCharge.findMany({
+          where: {
+            status: { in: ["PAID", "CASH_COLLECTED"] },
+            paidAt: { gte: dateFrom, lte: dateTo },
+            ...(Object.keys(bookingScope).length > 0 ? { booking: bookingScope } : {}),
+          },
+          select: { totalMinor: true, currency: true, paidAt: true, booking: chargeBookingSelect },
+        })
+      : [];
+
+    const supplementaryCharges = wantsSupplementary
+      ? await this.prisma.supplementaryCharge.findMany({
+          where: {
+            status: "PAID",
+            paidAt: { gte: dateFrom, lte: dateTo },
+            ...(query.revenueType === FinanceRevenueType.OUTSTANDING
+              ? { reason: UNDERPAYMENT_REASON }
+              : {}),
+            ...(query.revenueType === FinanceRevenueType.OTHER
+              ? { reason: { not: UNDERPAYMENT_REASON } }
+              : {}),
+            ...(Object.keys(bookingScope).length > 0 ? { booking: bookingScope } : {}),
+          },
+          select: {
+            amountMinor: true,
+            currency: true,
+            paidAt: true,
+            reason: true,
+            booking: chargeBookingSelect,
+          },
+        })
+      : [];
 
     // Booking.originStationId/destinationStationId are set on every create path (guest and
     // authenticated booking both pass them from the DTO); the schedule's own endpoints are
     // only a fallback for the rare legacy row that predates those columns.
     const stationIds = new Set<string>();
-    for (const b of bookings) {
-      const origin = b.originStationId ?? b.schedule.originStationId;
-      const destination = b.destinationStationId ?? b.schedule.destinationStationId;
+    const collectStations = (row: FinanceRowBooking) => {
+      const origin = row.originStationId ?? row.schedule.originStationId;
+      const destination = row.destinationStationId ?? row.schedule.destinationStationId;
       if (origin) stationIds.add(origin);
       if (destination) stationIds.add(destination);
-    }
+    };
+    for (const b of bookings) collectStations(b);
+    for (const c of baggageCharges) collectStations(c.booking);
+    for (const c of supplementaryCharges) collectStations(c.booking);
+
     const stations = stationIds.size > 0
-      ? await this.prisma.station.findMany({ where: { id: { in: [...stationIds] } }, select: { id: true, name: true } })
+      ? await this.prisma.station.findMany({
+          where: { id: { in: [...stationIds] } },
+          select: { id: true, name: true, countryCode: true },
+        })
       : [];
     const stationName = new Map(stations.map((s) => [s.id, s.name]));
+    const stationCountry = new Map(stations.map((s) => [s.id, s.countryCode]));
 
     const buckets = new Map<string, FinanceBucket>();
-    const bucketFor = (
-      period: string,
-      originStationId: string,
-      destinationStationId: string,
-      segmentLabel: string,
+
+    /**
+     * One revenue item — a paid fare or a collected fee — folded into its bucket. Every source
+     * takes its dimensions off the same booking shape, so they share this path instead of each
+     * re-deriving the segment label and the trip-type rule.
+     *
+     * `tripType` is a pure function of the station pair, so it never splits a bucket that the
+     * origin/destination part of the key hasn't split already — it rides along on the bucket
+     * rather than joining the key. `bookingType` and `revenueType` are not: a package and a
+     * regular booking, or a baggage fee and an underpayment on the same booking, can share every
+     * other dimension, so both belong in the key or a mixed bucket would take whichever label
+     * happened to land first.
+     */
+    const addRow = (
+      booking: FinanceRowBooking,
+      paidAt: Date,
+      revenueType: FinanceRevenueType,
       method: string,
       currency: string,
-    ): FinanceBucket => {
-      const key = `${period}|${originStationId}|${destinationStationId}|${method}|${currency}`;
+      amountMinor: number,
+    ) => {
+      const originStationId = booking.originStationId ?? booking.schedule.originStationId ?? "UNKNOWN";
+      const destinationStationId =
+        booking.destinationStationId ?? booking.schedule.destinationStationId ?? "UNKNOWN";
+
+      // Filtered here rather than pushed into the Prisma `where`: the endpoints that decide the
+      // trip type are `booking.originStationId ?? schedule.originStationId`, and a
+      // `{ in: ethiopianStationIds }` clause would mis-bucket any legacy row whose booking-level
+      // station columns are null.
+      const tripType = tripTypeFor(
+        stationCountry.get(originStationId),
+        stationCountry.get(destinationStationId),
+      );
+      if (query.tripType && tripType !== query.tripType) return;
+
+      const period = periodKeyFor(paidAt, granularity);
+      const segmentLabel = `${stationName.get(originStationId) ?? "Unknown"} → ${stationName.get(destinationStationId) ?? "Unknown"}`;
+      const bookingType = booking.packageId ? FinanceBookingType.PACKAGE : FinanceBookingType.REGULAR;
+      const key = `${period}|${originStationId}|${destinationStationId}|${bookingType}|${revenueType}|${method}|${currency}`;
+
       let bucket = buckets.get(key);
       if (!bucket) {
-        bucket = { period, originStationId, destinationStationId, segmentLabel, method, currency, bookingCount: 0, revenueMinor: 0 };
+        bucket = {
+          period,
+          originStationId,
+          destinationStationId,
+          segmentLabel,
+          tripType,
+          bookingType,
+          revenueType,
+          method,
+          currency,
+          bookingCount: 0,
+          revenueMinor: 0,
+        };
         buckets.set(key, bucket);
       }
-      return bucket;
+      bucket.bookingCount += 1;
+      bucket.revenueMinor += amountMinor;
     };
 
     for (const b of bookings) {
       const pi = b.paymentIntent!;
-      const period = periodKeyFor(pi.paidAt!, granularity);
-      const originStationId = b.originStationId ?? b.schedule.originStationId ?? "UNKNOWN";
-      const destinationStationId = b.destinationStationId ?? b.schedule.destinationStationId ?? "UNKNOWN";
-      const segmentLabel = `${stationName.get(originStationId) ?? "Unknown"} → ${stationName.get(destinationStationId) ?? "Unknown"}`;
-      const currency = (b.displayCurrency as string | null) ?? b.currency;
-      const amountMinor = b.displayTotalMinor ?? b.totalMinor;
-      const bucket = bucketFor(period, originStationId, destinationStationId, segmentLabel, pi.method, currency);
-      bucket.bookingCount += 1;
-      bucket.revenueMinor += amountMinor;
+      addRow(
+        b,
+        pi.paidAt!,
+        FinanceRevenueType.TICKET,
+        pi.method,
+        (b.displayCurrency as string | null) ?? b.currency,
+        b.displayTotalMinor ?? b.totalMinor,
+      );
+    }
+
+    for (const c of baggageCharges) {
+      addRow(
+        c.booking,
+        c.paidAt!,
+        FinanceRevenueType.EXCESS_BAGGAGE,
+        CHARGE_METHOD_UNKNOWN,
+        c.currency,
+        c.totalMinor,
+      );
+    }
+
+    for (const c of supplementaryCharges) {
+      const revenueType =
+        c.reason === UNDERPAYMENT_REASON ? FinanceRevenueType.OUTSTANDING : FinanceRevenueType.OTHER;
+      addRow(c.booking, c.paidAt!, revenueType, CHARGE_METHOD_UNKNOWN, c.currency, c.amountMinor);
     }
 
     const rows = [...buckets.values()].sort((a, b) =>
@@ -1868,10 +2038,16 @@ export class ReportsService {
       granularity,
       dateFrom: query.dateFrom,
       dateTo: query.dateTo,
+      tripType: query.tripType ?? null,
+      bookingType: query.bookingType ?? null,
+      revenueType: query.revenueType ?? null,
       totals,
       byPeriod: rollUp((r) => `${r.period}|${r.currency}`, (r) => r.period),
       bySegment: rollUp((r) => `${r.originStationId}|${r.destinationStationId}|${r.currency}`, (r) => r.segmentLabel),
       byMethod: rollUp((r) => `${r.method}|${r.currency}`, (r) => r.method),
+      byTripType: rollUp((r) => `${r.tripType}|${r.currency}`, (r) => r.tripType),
+      byBookingType: rollUp((r) => `${r.bookingType}|${r.currency}`, (r) => r.bookingType),
+      byRevenueType: rollUp((r) => `${r.revenueType}|${r.currency}`, (r) => r.revenueType),
       rows,
     };
   }
@@ -1880,10 +2056,13 @@ export class ReportsService {
   async exportFinanceSummaryCsv(query: FinanceSummaryQueryDto): Promise<string> {
     const report = await this.getFinanceSummary(query);
 
-    const headers = ["Period", "Origin → Destination", "Payment Method", "Currency", "Bookings", "Revenue"];
+    const headers = ["Period", "Origin → Destination", "Trip Type", "Booking Type", "Revenue Type", "Payment Method", "Currency", "Items", "Revenue"];
     const rows = report.rows.map((r) => [
       r.period,
       r.segmentLabel,
+      r.tripType,
+      r.bookingType,
+      r.revenueType,
       r.method,
       r.currency,
       r.bookingCount,
diff --git a/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx b/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
index b83e96ca7..b6e2ea714 100644
--- a/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
+++ b/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
@@ -9,7 +9,7 @@ import {
 } from 'recharts';
 import { toPng } from 'html-to-image';
 import { apiClient } from '@/lib/api-client';
-import { financeApi, type FinanceGranularity, type FinanceSummaryFilters } from '@/lib/api/finance';
+import { financeApi, type FinanceBookingType, type FinanceGranularity, type FinanceRevenueType, type FinanceSummaryFilters, type FinanceTripType } from '@/lib/api/finance';
 import { buildFinanceWorkbook, type ChartImage } from '@/lib/export/finance-workbook';
 import ActionButton from '@/components/ui/ActionButton';
 import Pagination from '@/components/ui/Pagination';
@@ -42,6 +42,40 @@ function methodLabel(method: string): string {
   return PAYMENT_METHOD_LABELS[method] ?? method;
 }
 
+// Intercity = both endpoints in Ethiopia; international = either endpoint outside it (Djibouti),
+// including a trip wholly inside Djibouti. Fixed order so each keeps its colour when filtered.
+const TRIP_TYPE_ORDER = ['intercity', 'international'] as const;
+const TRIP_TYPE_LABELS: Record<string, string> = {
+  intercity: 'Intercity (Ethiopia)',
+  international: 'International (Djibouti)',
+};
+function tripTypeLabel(tripType: string): string {
+  return TRIP_TYPE_LABELS[tripType] ?? tripType;
+}
+
+// Package = a booking carrying a packageId; regular = ordinary ticket sales. Not the
+// ONE_WAY/ROUND_TRIP booking type. Fixed order so each keeps its colour when filtered.
+const BOOKING_TYPE_ORDER = ['regular', 'package'] as const;
+const BOOKING_TYPE_LABELS: Record<string, string> = {
+  regular: 'Regular',
+  package: 'Package',
+};
+function bookingTypeLabel(bookingType: string): string {
+  return BOOKING_TYPE_LABELS[bookingType] ?? bookingType;
+}
+
+// The fare, and the fees collected after it. Fixed order so each keeps its colour when filtered.
+const REVENUE_TYPE_ORDER = ['ticket', 'excess_baggage', 'outstanding', 'other'] as const;
+const REVENUE_TYPE_LABELS: Record<string, string> = {
+  ticket: 'Ticket fare',
+  excess_baggage: 'Excess baggage',
+  outstanding: 'Outstanding',
+  other: 'Other charges',
+};
+function revenueTypeLabel(revenueType: string): string {
+  return REVENUE_TYPE_LABELS[revenueType] ?? revenueType;
+}
+
 function periodLabel(period: string, granularity: FinanceGranularity): string {
   if (granularity === 'monthly') {
     return new Date(`${period}-01T00:00:00`).toLocaleDateString('en-US', { month: 'short', year: 'numeric' });
@@ -112,6 +146,9 @@ export default function FinanceReportPage() {
   const [originStationId, setOriginStationId] = useState('');
   const [destinationStationId, setDestinationStationId] = useState('');
   const [method, setMethod] = useState('');
+  const [tripType, setTripType] = useState<'' | FinanceTripType>('');
+  const [bookingType, setBookingType] = useState<'' | FinanceBookingType>('');
+  const [revenueType, setRevenueType] = useState<'' | FinanceRevenueType>('');
   const [exporting, setExporting] = useState(false);
 
   // Chart cards are captured for the Excel export. There's one Trend/Segment/Method set per
@@ -155,8 +192,11 @@ export default function FinanceReportPage() {
       originStationId: originStationId || undefined,
       destinationStationId: destinationStationId || undefined,
       method: method || undefined,
+      tripType: tripType || undefined,
+      bookingType: bookingType || undefined,
+      revenueType: revenueType || undefined,
     }),
-    [dateFrom, dateTo, granularity, originStationId, destinationStationId, method],
+    [dateFrom, dateTo, granularity, originStationId, destinationStationId, method, tripType, bookingType, revenueType],
   );
 
   const { data: stations = [] } = useQuery<StationOption[]>({
@@ -181,6 +221,9 @@ export default function FinanceReportPage() {
     setOriginStationId('');
     setDestinationStationId('');
     setMethod('');
+    setTripType('');
+    setBookingType('');
+    setRevenueType('');
   };
 
   /** Captures a chart card as a PNG data URL, sized to the card's actual on-screen pixels. */
@@ -195,15 +238,18 @@ export default function FinanceReportPage() {
     if (!data) return;
     setExporting(true);
     try {
-      const imagesByCurrency: Record<string, { trend?: ChartImage; segment?: ChartImage; method?: ChartImage }> = {};
+      const imagesByCurrency: Record<string, { trend?: ChartImage; segment?: ChartImage; method?: ChartImage; tripType?: ChartImage; bookingType?: ChartImage; revenueType?: ChartImage }> = {};
       await Promise.all(
         currencySections.map(async (section) => {
-          const [trend, segment, methodImg] = await Promise.all([
+          const [trend, segment, methodImg, tripTypeImg, bookingTypeImg, revenueTypeImg] = await Promise.all([
             captureCard(chartRefs.current[`${section.currency}-trend`]),
             captureCard(chartRefs.current[`${section.currency}-segment`]),
             captureCard(chartRefs.current[`${section.currency}-method`]),
+            captureCard(chartRefs.current[`${section.currency}-tripType`]),
+            captureCard(chartRefs.current[`${section.currency}-bookingType`]),
+            captureCard(chartRefs.current[`${section.currency}-revenueType`]),
           ]);
-          imagesByCurrency[section.currency] = { trend, segment, method: methodImg };
+          imagesByCurrency[section.currency] = { trend, segment, method: methodImg, tripType: tripTypeImg, bookingType: bookingTypeImg, revenueType: revenueTypeImg };
         }),
       );
 
@@ -218,8 +264,14 @@ export default function FinanceReportPage() {
           originLabel: originStationId ? stationLabel(originStationId) : 'Any',
           destinationLabel: destinationStationId ? stationLabel(destinationStationId) : 'Any',
           methodLabel: method ? methodLabel(method) : 'All',
+          tripTypeLabel: tripType ? tripTypeLabel(tripType) : 'All',
+          bookingTypeLabel: bookingType ? bookingTypeLabel(bookingType) : 'All',
+          revenueTypeLabel: revenueType ? revenueTypeLabel(revenueType) : 'All',
         },
         methodLabel,
+        tripTypeLabel,
+        bookingTypeLabel,
+        revenueTypeLabel,
         periodLabel,
         imagesByCurrency,
       });
@@ -239,8 +291,10 @@ export default function FinanceReportPage() {
     () => (data?.totals ?? []).slice().sort((a, b) => b.revenueMinor - a.revenueMinor),
     [data],
   );
-  const totalBookings = totals.reduce((sum, t) => sum + t.bookingCount, 0);
-  const hasData = totalBookings > 0;
+  // Every revenue item, not every booking: a collected baggage fee or underpayment counts here
+  // too, so this is deliberately no longer labelled "Bookings" in the UI.
+  const totalItems = totals.reduce((sum, t) => sum + t.bookingCount, 0);
+  const hasData = totalItems > 0;
 
   // Money is never comparable across currencies, so rather than scoping every chart to
   // whichever currency happens to be biggest overall (which would silently drop a
@@ -259,7 +313,9 @@ export default function FinanceReportPage() {
         .filter((r) => r.currency === t.currency)
         .slice()
         .sort((a, b) => b.revenueMinor - a.revenueMinor)
-        .map((r) => ({ label: r.label, revenue: r.revenueMinor }));
+        // Minor units → major, same as trendData above. Plotting revenueMinor raw made every
+        // segment bar read 100× its real value (an ETB 10.9M segment charted as 1.09 billion).
+        .map((r) => ({ label: r.label, revenue: r.revenueMinor / 100 }));
 
       const methodRows = data.byMethod.filter((r) => r.currency === t.currency);
       const methodTotal = methodRows.reduce((sum, r) => sum + r.revenueMinor, 0);
@@ -272,6 +328,43 @@ export default function FinanceReportPage() {
           sharePercent: methodTotal > 0 ? (r.revenueMinor / methodTotal) * 100 : 0,
         }));
 
+      // Intercity vs international for this currency. Shares are against this currency's own
+      // trip-type total, never a cross-currency sum.
+      const tripTypeRows = data.byTripType.filter((r) => r.currency === t.currency);
+      const tripTypeTotal = tripTypeRows.reduce((sum, r) => sum + r.revenueMinor, 0);
+      const tripTypeBreakdown = tripTypeRows
+        .slice()
+        .sort((a, b) => TRIP_TYPE_ORDER.indexOf(a.label as any) - TRIP_TYPE_ORDER.indexOf(b.label as any))
+        .map((r) => ({
+          ...r,
+          color: categoricalColor(palette, TRIP_TYPE_ORDER.indexOf(r.label as any)),
+          sharePercent: tripTypeTotal > 0 ? (r.revenueMinor / tripTypeTotal) * 100 : 0,
+        }));
+
+      // Regular vs package for this currency, same share rule as the trip-type card.
+      const bookingTypeRows = data.byBookingType.filter((r) => r.currency === t.currency);
+      const bookingTypeTotal = bookingTypeRows.reduce((sum, r) => sum + r.revenueMinor, 0);
+      const bookingTypeBreakdown = bookingTypeRows
+        .slice()
+        .sort((a, b) => BOOKING_TYPE_ORDER.indexOf(a.label as any) - BOOKING_TYPE_ORDER.indexOf(b.label as any))
+        .map((r) => ({
+          ...r,
+          color: categoricalColor(palette, BOOKING_TYPE_ORDER.indexOf(r.label as any)),
+          sharePercent: bookingTypeTotal > 0 ? (r.revenueMinor / bookingTypeTotal) * 100 : 0,
+        }));
+
+      // Fare vs the fees collected after it, same share rule as the other breakdown cards.
+      const revenueTypeRows = data.byRevenueType.filter((r) => r.currency === t.currency);
+      const revenueTypeTotal = revenueTypeRows.reduce((sum, r) => sum + r.revenueMinor, 0);
+      const revenueTypeBreakdown = revenueTypeRows
+        .slice()
+        .sort((a, b) => REVENUE_TYPE_ORDER.indexOf(a.label as any) - REVENUE_TYPE_ORDER.indexOf(b.label as any))
+        .map((r) => ({
+          ...r,
+          color: categoricalColor(palette, REVENUE_TYPE_ORDER.indexOf(r.label as any)),
+          sharePercent: revenueTypeTotal > 0 ? (r.revenueMinor / revenueTypeTotal) * 100 : 0,
+        }));
+
       return {
         currency: t.currency,
         revenueMinor: t.revenueMinor,
@@ -279,6 +372,9 @@ export default function FinanceReportPage() {
         trendData,
         segmentData,
         methodBreakdown,
+        tripTypeBreakdown,
+        bookingTypeBreakdown,
+        revenueTypeBreakdown,
       };
     });
   }, [data, totals, palette]);
@@ -347,6 +443,32 @@ export default function FinanceReportPage() {
               ))}
             </select>
           </div>
+          <div>
+            <label className="label">Trip Type</label>
+            <select className="input" value={tripType} onChange={(e) => setTripType(e.target.value as '' | FinanceTripType)}>
+              <option value="">All trips</option>
+              <option value="intercity">Intercity — within Ethiopia</option>
+              <option value="international">International — to/from Djibouti</option>
+            </select>
+          </div>
+          <div>
+            <label className="label">Booking Type</label>
+            <select className="input" value={bookingType} onChange={(e) => setBookingType(e.target.value as '' | FinanceBookingType)}>
+              <option value="">All bookings</option>
+              <option value="regular">Regular — ticket sales</option>
+              <option value="package">Package — travel packages</option>
+            </select>
+          </div>
+          <div>
+            <label className="label">Revenue Type</label>
+            <select className="input" value={revenueType} onChange={(e) => setRevenueType(e.target.value as '' | FinanceRevenueType)}>
+              <option value="">All revenue</option>
+              <option value="ticket">Ticket fare</option>
+              <option value="excess_baggage">Excess baggage — luggage</option>
+              <option value="outstanding">Outstanding — underpayments</option>
+              <option value="other">Other charges — upgrade, reschedule</option>
+            </select>
+          </div>
           <div>
             <label className="label">Payment Method</label>
             <select className="input" value={method} onChange={(e) => setMethod(e.target.value)}>
@@ -371,7 +493,7 @@ export default function FinanceReportPage() {
       ) : !hasData ? (
         <div className="card py-16 text-center text-muted-foreground">
           <Banknote className="h-10 w-10 mx-auto mb-3 opacity-30" />
-          <p>No paid bookings in this window.</p>
+          <p>No revenue collected in this window.</p>
           <p className="text-xs mt-1">Widen the date range, or clear the origin/destination/method filters.</p>
         </div>
       ) : (
@@ -391,19 +513,19 @@ export default function FinanceReportPage() {
                   <span className="text-sm font-medium">{t.currency}</span>
                   <span className="text-right">
                     <span className="text-sm font-semibold tabular-nums">{formatCurrency(t.revenueMinor, t.currency)}</span>
-                    <span className="ml-2 text-xs text-muted-foreground tabular-nums">{t.bookingCount.toLocaleString()} bookings</span>
+                    <span className="ml-2 text-xs text-muted-foreground tabular-nums">{t.bookingCount.toLocaleString()} items</span>
                   </span>
                 </div>
               ))}
             </div>
             <div className="card flex flex-col gap-1">
               <div className="flex items-center justify-between">
-                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Bookings</p>
+                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Revenue items</p>
                 <div className="rounded-lg bg-blue-100 dark:bg-blue-900/30 p-1.5">
                   <BookOpen className="h-4 w-4 text-blue-600 dark:text-blue-400" />
                 </div>
               </div>
-              <p className="text-2xl font-bold tabular-nums mt-1">{totalBookings.toLocaleString()}</p>
+              <p className="text-2xl font-bold tabular-nums mt-1">{totalItems.toLocaleString()}</p>
               <p className="text-xs text-muted-foreground mt-auto pt-2 border-t border-border">
                 Across {totals.length} currenc{totals.length === 1 ? 'y' : 'ies'}
               </p>
@@ -419,7 +541,7 @@ export default function FinanceReportPage() {
               <div className="flex items-center gap-3">
                 <h2 className="text-lg font-semibold text-foreground">{section.currency}</h2>
                 <span className="text-xs text-muted-foreground">
-                  {formatCurrency(section.revenueMinor, section.currency)} · {section.bookingCount.toLocaleString()} bookings
+                  {formatCurrency(section.revenueMinor, section.currency)} · {section.bookingCount.toLocaleString()} items
                 </span>
               </div>
 
@@ -463,6 +585,163 @@ export default function FinanceReportPage() {
                 </div>
               </div>
 
+              {/* Intercity vs international — same part-to-whole treatment as the method card.
+                  A trip is intercity only when both endpoints are Ethiopian; anything touching
+                  Djibouti (including a trip wholly inside it) is international. */}
+              <div className="card" ref={setChartRef(`${section.currency}-tripType`)}>
+                <h3 className="text-base font-semibold text-foreground">
+                  Revenue by Trip Type <span className="text-xs font-normal text-muted-foreground">({section.currency})</span>
+                </h3>
+                <p className="text-xs text-muted-foreground mt-1 mb-4">
+                  Share of {section.currency} revenue between trips within Ethiopia and trips touching Djibouti
+                </p>
+                <div
+                  className="flex w-full h-7 rounded-md overflow-hidden"
+                  role="img"
+                  aria-label={`${section.currency} revenue by trip type: ${section.tripTypeBreakdown
+                    .map((t) => `${tripTypeLabel(t.label)} ${t.sharePercent.toFixed(0)}%`)
+                    .join(', ')}`}
+                >
+                  {section.tripTypeBreakdown.map((t, i) => (
+                    <div
+                      key={t.key}
+                      className="h-full"
+                      style={{ width: `${t.sharePercent}%`, background: t.color, marginRight: i < section.tripTypeBreakdown.length - 1 ? 2 : 0 }}
+                      title={`${tripTypeLabel(t.label)} — ${formatCurrency(t.revenueMinor, t.currency)}`}
+                    />
+                  ))}
+                </div>
+                <table className="w-full text-sm mt-4">
+                  <thead>
+                    <tr className="text-xs uppercase tracking-wider text-muted-foreground">
+                      <th className="text-left font-medium py-2">Trip Type</th>
+                      <th className="text-right font-medium py-2">Items</th>
+                      <th className="text-right font-medium py-2">Share</th>
+                      <th className="text-right font-medium py-2">Revenue</th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-border">
+                    {section.tripTypeBreakdown.map((t) => (
+                      <tr key={t.key}>
+                        <td className="py-2">
+                          <span className="flex items-center gap-2">
+                            <span className="h-2.5 w-2.5 rounded-sm shrink-0" style={{ background: t.color }} aria-hidden="true" />
+                            <span className="text-foreground">{tripTypeLabel(t.label)}</span>
+                          </span>
+                        </td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{t.bookingCount.toLocaleString()}</td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{t.sharePercent.toFixed(1)}%</td>
+                        <td className="py-2 text-right tabular-nums text-foreground font-medium">{formatCurrency(t.revenueMinor, t.currency)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+
+              {/* Regular vs package — package revenue is a booking carrying a packageId; the
+                  legacy standalone PackageBooking table is not counted here, as it never was. */}
+              <div className="card" ref={setChartRef(`${section.currency}-bookingType`)}>
+                <h3 className="text-base font-semibold text-foreground">
+                  Revenue by Booking Type <span className="text-xs font-normal text-muted-foreground">({section.currency})</span>
+                </h3>
+                <p className="text-xs text-muted-foreground mt-1 mb-4">
+                  Share of {section.currency} revenue between ordinary ticket sales and travel packages
+                </p>
+                <div
+                  className="flex w-full h-7 rounded-md overflow-hidden"
+                  role="img"
+                  aria-label={`${section.currency} revenue by booking type: ${section.bookingTypeBreakdown
+                    .map((b) => `${bookingTypeLabel(b.label)} ${b.sharePercent.toFixed(0)}%`)
+                    .join(', ')}`}
+                >
+                  {section.bookingTypeBreakdown.map((b, i) => (
+                    <div
+                      key={b.key}
+                      className="h-full"
+                      style={{ width: `${b.sharePercent}%`, background: b.color, marginRight: i < section.bookingTypeBreakdown.length - 1 ? 2 : 0 }}
+                      title={`${bookingTypeLabel(b.label)} — ${formatCurrency(b.revenueMinor, b.currency)}`}
+                    />
+                  ))}
+                </div>
+                <table className="w-full text-sm mt-4">
+                  <thead>
+                    <tr className="text-xs uppercase tracking-wider text-muted-foreground">
+                      <th className="text-left font-medium py-2">Booking Type</th>
+                      <th className="text-right font-medium py-2">Items</th>
+                      <th className="text-right font-medium py-2">Share</th>
+                      <th className="text-right font-medium py-2">Revenue</th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-border">
+                    {section.bookingTypeBreakdown.map((b) => (
+                      <tr key={b.key}>
+                        <td className="py-2">
+                          <span className="flex items-center gap-2">
+                            <span className="h-2.5 w-2.5 rounded-sm shrink-0" style={{ background: b.color }} aria-hidden="true" />
+                            <span className="text-foreground">{bookingTypeLabel(b.label)}</span>
+                          </span>
+                        </td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{b.bookingCount.toLocaleString()}</td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{b.sharePercent.toFixed(1)}%</td>
+                        <td className="py-2 text-right tabular-nums text-foreground font-medium">{formatCurrency(b.revenueMinor, b.currency)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+
+              {/* Ticket fare vs the fees collected after it. Charge revenue is new to this
+                  report — it was invisible here until the revenue-type work. */}
+              <div className="card" ref={setChartRef(`${section.currency}-revenueType`)}>
+                <h3 className="text-base font-semibold text-foreground">
+                  Revenue by Revenue Type <span className="text-xs font-normal text-muted-foreground">({section.currency})</span>
+                </h3>
+                <p className="text-xs text-muted-foreground mt-1 mb-4">
+                  Share of {section.currency} revenue between the ticket fare and the fees collected after it
+                </p>
+                <div
+                  className="flex w-full h-7 rounded-md overflow-hidden"
+                  role="img"
+                  aria-label={`${section.currency} revenue by revenue type: ${section.revenueTypeBreakdown
+                    .map((r) => `${revenueTypeLabel(r.label)} ${r.sharePercent.toFixed(0)}%`)
+                    .join(', ')}`}
+                >
+                  {section.revenueTypeBreakdown.map((r, i) => (
+                    <div
+                      key={r.key}
+                      className="h-full"
+                      style={{ width: `${r.sharePercent}%`, background: r.color, marginRight: i < section.revenueTypeBreakdown.length - 1 ? 2 : 0 }}
+                      title={`${revenueTypeLabel(r.label)} — ${formatCurrency(r.revenueMinor, r.currency)}`}
+                    />
+                  ))}
+                </div>
+                <table className="w-full text-sm mt-4">
+                  <thead>
+                    <tr className="text-xs uppercase tracking-wider text-muted-foreground">
+                      <th className="text-left font-medium py-2">Revenue Type</th>
+                      <th className="text-right font-medium py-2">Items</th>
+                      <th className="text-right font-medium py-2">Share</th>
+                      <th className="text-right font-medium py-2">Revenue</th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-border">
+                    {section.revenueTypeBreakdown.map((r) => (
+                      <tr key={r.key}>
+                        <td className="py-2">
+                          <span className="flex items-center gap-2">
+                            <span className="h-2.5 w-2.5 rounded-sm shrink-0" style={{ background: r.color }} aria-hidden="true" />
+                            <span className="text-foreground">{revenueTypeLabel(r.label)}</span>
+                          </span>
+                        </td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{r.bookingCount.toLocaleString()}</td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{r.sharePercent.toFixed(1)}%</td>
+                        <td className="py-2 text-right tabular-nums text-foreground font-medium">{formatCurrency(r.revenueMinor, r.currency)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+
               {/* Payment method breakdown — part-to-whole stacked bar + legend table */}
               <div className="card" ref={setChartRef(`${section.currency}-method`)}>
                 <h3 className="text-base font-semibold text-foreground">
@@ -489,7 +768,7 @@ export default function FinanceReportPage() {
                   <thead>
                     <tr className="text-xs uppercase tracking-wider text-muted-foreground">
                       <th className="text-left font-medium py-2">Method</th>
-                      <th className="text-right font-medium py-2">Bookings</th>
+                      <th className="text-right font-medium py-2">Items</th>
                       <th className="text-right font-medium py-2">Share</th>
                       <th className="text-right font-medium py-2">Revenue</th>
                     </tr>
@@ -525,7 +804,7 @@ export default function FinanceReportPage() {
               <table className="w-full text-sm">
                 <thead className="bg-gray-50 dark:bg-gray-800">
                   <tr>
-                    {['Period', 'Segment', 'Method', 'Currency', 'Bookings', 'Revenue'].map((h) => (
+                    {['Period', 'Segment', 'Type', 'Booking', 'Revenue Type', 'Method', 'Currency', 'Items', 'Revenue'].map((h) => (
                       <th key={h} className="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-400 whitespace-nowrap">
                         {h}
                       </th>
@@ -537,6 +816,9 @@ export default function FinanceReportPage() {
                     <tr key={`${r.period}-${r.originStationId}-${r.destinationStationId}-${r.method}-${i}`} className="hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
                       <td className="px-4 py-3 whitespace-nowrap text-foreground">{periodLabel(r.period, granularity)}</td>
                       <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{r.segmentLabel}</td>
+                      <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{tripTypeLabel(r.tripType)}</td>
+                      <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{bookingTypeLabel(r.bookingType)}</td>
+                      <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{revenueTypeLabel(r.revenueType)}</td>
                       <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{methodLabel(r.method)}</td>
                       <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{r.currency}</td>
                       <td className="px-4 py-3 tabular-nums whitespace-nowrap">{r.bookingCount.toLocaleString()}</td>
@@ -545,7 +827,7 @@ export default function FinanceReportPage() {
                   ))}
                   {pg.paged.length === 0 && (
                     <tr>
-                      <td colSpan={6} className="py-8 text-center text-sm text-muted-foreground">No rows on this page</td>
+                      <td colSpan={9} className="py-8 text-center text-sm text-muted-foreground">No rows on this page</td>
                     </tr>
                   )}
                 </tbody>
diff --git a/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts b/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
index fa0bc943d..d818172eb 100644
--- a/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
+++ b/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
@@ -2,6 +2,26 @@ import { apiClient } from '@/lib/api-client';
 
 export type FinanceGranularity = 'daily' | 'weekly' | 'monthly';
 
+/**
+ * Domestic vs cross-border traffic. `intercity` means both endpoints sit in Ethiopia;
+ * `international` means either endpoint is outside it — in practice Djibouti, including a
+ * trip wholly inside Djibouti. Mirrors `FinanceTripType` on the API.
+ */
+export type FinanceTripType = 'intercity' | 'international';
+
+/**
+ * Travel-package revenue vs ordinary ticket sales. `package` is a booking carrying a
+ * `packageId`; `regular` is one without. Unrelated to the ONE_WAY/ROUND_TRIP booking type.
+ */
+export type FinanceBookingType = 'regular' | 'package';
+
+/**
+ * Which revenue stream a row came from. `ticket` is the booking fare; the rest are fees
+ * collected after it — an excess-baggage charge, a recovered underpayment, or any other
+ * supplementary charge (upgrade, reschedule, and anything added later).
+ */
+export type FinanceRevenueType = 'ticket' | 'excess_baggage' | 'outstanding' | 'other';
+
 export interface FinanceSummaryFilters {
   dateFrom: string;
   dateTo: string;
@@ -9,6 +29,9 @@ export interface FinanceSummaryFilters {
   originStationId?: string;
   destinationStationId?: string;
   method?: string;
+  tripType?: FinanceTripType;
+  bookingType?: FinanceBookingType;
+  revenueType?: FinanceRevenueType;
 }
 
 export interface FinanceBucketRow {
@@ -16,6 +39,10 @@ export interface FinanceBucketRow {
   originStationId: string;
   destinationStationId: string;
   segmentLabel: string;
+  tripType: FinanceTripType;
+  bookingType: FinanceBookingType;
+  revenueType: FinanceRevenueType;
+  /** `UNKNOWN` on charge rows — settling a charge records no payment method. */
   method: string;
   currency: string;
   bookingCount: number;
@@ -35,11 +62,23 @@ export interface FinanceSummaryReport {
   granularity: FinanceGranularity;
   dateFrom: string;
   dateTo: string;
+  /** The trip-type filter that was applied, or `null` when every trip is included. */
+  tripType: FinanceTripType | null;
+  /** The booking-type filter that was applied, or `null` when every booking is included. */
+  bookingType: FinanceBookingType | null;
+  /** The revenue-type filter that was applied, or `null` when every stream is included. */
+  revenueType: FinanceRevenueType | null;
   /** Grand totals, one entry per currency present — never summed across currencies. */
   totals: FinanceRollupRow[];
   byPeriod: FinanceRollupRow[];
   bySegment: FinanceRollupRow[];
   byMethod: FinanceRollupRow[];
+  /** Intercity vs international split. One entry per trip type per currency. */
+  byTripType: FinanceRollupRow[];
+  /** Regular vs package split. One entry per booking type per currency. */
+  byBookingType: FinanceRollupRow[];
+  /** Fare vs baggage/outstanding/other split. One entry per revenue type per currency. */
+  byRevenueType: FinanceRollupRow[];
   rows: FinanceBucketRow[];
 }
 
@@ -50,6 +89,9 @@ function toParams(filters: FinanceSummaryFilters): Record<string, string> {
   if (filters.originStationId) params.originStationId = filters.originStationId;
   if (filters.destinationStationId) params.destinationStationId = filters.destinationStationId;
   if (filters.method) params.method = filters.method;
+  if (filters.tripType) params.tripType = filters.tripType;
+  if (filters.bookingType) params.bookingType = filters.bookingType;
+  if (filters.revenueType) params.revenueType = filters.revenueType;
   return params;
 }
 
diff --git a/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts b/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
index 066d6b355..43f0b796a 100644
--- a/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
+++ b/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
@@ -32,11 +32,14 @@ export interface ChartImage {
 
 export interface FinanceWorkbookInput {
   report: FinanceSummaryReport;
-  filters: { dateFrom: string; dateTo: string; granularity: FinanceGranularity; originLabel: string; destinationLabel: string; methodLabel: string };
+  filters: { dateFrom: string; dateTo: string; granularity: FinanceGranularity; originLabel: string; destinationLabel: string; methodLabel: string; tripTypeLabel: string; bookingTypeLabel: string; revenueTypeLabel: string };
   methodLabel: (method: string) => string;
+  tripTypeLabel: (tripType: string) => string;
+  bookingTypeLabel: (bookingType: string) => string;
+  revenueTypeLabel: (revenueType: string) => string;
   periodLabel: (period: string, granularity: FinanceGranularity) => string;
-  /** One Trend/Segment/Method image set per currency present — mirrors the on-screen per-currency sections. */
-  imagesByCurrency: Record<string, { trend?: ChartImage; segment?: ChartImage; method?: ChartImage }>;
+  /** One chart image set per currency present — mirrors the on-screen per-currency sections. */
+  imagesByCurrency: Record<string, { trend?: ChartImage; segment?: ChartImage; method?: ChartImage; tripType?: ChartImage; bookingType?: ChartImage; revenueType?: ChartImage }>;
 }
 
 function styleHeaderCell(cell: ExcelJS.Cell) {
@@ -159,10 +162,14 @@ function addImage(wb: ExcelJS.Workbook, ws: ExcelJS.Worksheet, image: ChartImage
 export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise<Blob> {
   const { report, filters, imagesByCurrency } = input;
   const methodLabel = input.methodLabel;
+  const tripTypeLabel = input.tripTypeLabel;
+  const bookingTypeLabel = input.bookingTypeLabel;
+  const revenueTypeLabel = input.revenueTypeLabel;
   const periodLabel = input.periodLabel;
 
   const totals = [...report.totals].sort((a, b) => b.revenueMinor - a.revenueMinor);
-  const totalBookings = totals.reduce((sum, t) => sum + t.bookingCount, 0);
+  // Every revenue item, not every booking — a collected baggage fee or underpayment counts too.
+  const totalItems = totals.reduce((sum, t) => sum + t.bookingCount, 0);
 
   const wb = new ExcelJS.Workbook();
   wb.creator = 'EDR Passenger Backoffice';
@@ -175,7 +182,7 @@ export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise
   titleBanner(
     summary,
     'EDR Passenger — Finance Summary',
-    `${filters.dateFrom} to ${filters.dateTo} · ${filters.granularity} · Origin: ${filters.originLabel} · Destination: ${filters.destinationLabel} · Method: ${filters.methodLabel} · Generated ${new Date().toLocaleString('en-US')}`,
+    `${filters.dateFrom} to ${filters.dateTo} · ${filters.granularity} · Origin: ${filters.originLabel} · Destination: ${filters.destinationLabel} · Method: ${filters.methodLabel} · Trip type: ${filters.tripTypeLabel} · Booking type: ${filters.bookingTypeLabel} · Revenue type: ${filters.revenueTypeLabel} · Generated ${new Date().toLocaleString('en-US')}`,
     6,
   );
 
@@ -187,7 +194,7 @@ export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise
     accent: BRAND_DARK,
   }));
   const cursorAfterKpis = kpiRow(summary, 4, [
-    { label: 'Bookings', value: totalBookings.toLocaleString('en-US'), accent: INK },
+    { label: 'Revenue items', value: totalItems.toLocaleString('en-US'), accent: INK },
     ...revenueCards,
   ]);
 
@@ -198,13 +205,16 @@ export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise
     const images = imagesByCurrency[t.currency] ?? {};
     cursor = addImage(wb, summary, images.trend, cursor, `Revenue Trend (${t.currency})`) + 1;
     cursor = addImage(wb, summary, images.segment, cursor, `Revenue by Segment (${t.currency})`) + 1;
+    cursor = addImage(wb, summary, images.tripType, cursor, `Revenue by Trip Type (${t.currency})`) + 1;
+    cursor = addImage(wb, summary, images.bookingType, cursor, `Revenue by Booking Type (${t.currency})`) + 1;
+    cursor = addImage(wb, summary, images.revenueType, cursor, `Revenue by Revenue Type (${t.currency})`) + 1;
     cursor = addImage(wb, summary, images.method, cursor, `Revenue by Payment Method (${t.currency})`) + 1;
   }
 
   // ── By Period sheet ──────────────────────────────────────────────────────
   const byPeriod = wb.addWorksheet('By Period', { views: [{ state: 'frozen', ySplit: 1 }] });
   byPeriod.columns = [{ width: 18 }, { width: 12 }, { width: 14 }, { width: 20 }];
-  addTableHeader(byPeriod, 1, ['Period', 'Currency', 'Bookings', 'Revenue'], new Set([1, 2]));
+  addTableHeader(byPeriod, 1, ['Period', 'Currency', 'Items', 'Revenue'], new Set([1, 2]));
   const periodRows = [...report.byPeriod].sort((a, b) => a.key.localeCompare(b.key));
   periodRows.forEach((p, i) => {
     const r = byPeriod.getRow(i + 2);
@@ -222,7 +232,7 @@ export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise
   // ── By Segment sheet ─────────────────────────────────────────────────────
   const bySegment = wb.addWorksheet('By Segment', { views: [{ state: 'frozen', ySplit: 1 }] });
   bySegment.columns = [{ width: 34 }, { width: 12 }, { width: 14 }, { width: 20 }];
-  addTableHeader(bySegment, 1, ['Origin → Destination', 'Currency', 'Bookings', 'Revenue'], new Set([1, 2]));
+  addTableHeader(bySegment, 1, ['Origin → Destination', 'Currency', 'Items', 'Revenue'], new Set([1, 2]));
   report.bySegment.forEach((s, i) => {
     const r = bySegment.getRow(i + 2);
     r.getCell(1).value = s.label;
@@ -236,12 +246,85 @@ export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise
   });
   bySegment.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 4 } };
 
+  // ── By Trip Type sheet ───────────────────────────────────────────────────
+  // Intercity = both endpoints in Ethiopia; international = either endpoint outside it
+  // (Djibouti), including a trip wholly inside Djibouti. Share is against the same
+  // currency's grand total, never a cross-currency sum.
+  const byTripType = wb.addWorksheet('By Trip Type', { views: [{ state: 'frozen', ySplit: 1 }] });
+  byTripType.columns = [{ width: 26 }, { width: 12 }, { width: 14 }, { width: 20 }, { width: 12 }];
+  addTableHeader(byTripType, 1, ['Trip Type', 'Currency', 'Items', 'Revenue', 'Share'], new Set([1, 2, 3]));
+  const tripTypeCurrencyTotal = new Map(totals.map((t) => [t.currency, t.revenueMinor]));
+  report.byTripType.forEach((t, i) => {
+    const r = byTripType.getRow(i + 2);
+    const currencyTotal = tripTypeCurrencyTotal.get(t.currency) ?? 0;
+    r.getCell(1).value = tripTypeLabel(t.label);
+    r.getCell(2).value = t.currency;
+    r.getCell(3).value = t.bookingCount;
+    r.getCell(3).alignment = { horizontal: 'right' };
+    r.getCell(4).value = t.revenueMinor / 100;
+    r.getCell(4).numFmt = currencyFmt(t.currency);
+    r.getCell(4).alignment = { horizontal: 'right' };
+    r.getCell(5).value = currencyTotal > 0 ? t.revenueMinor / currencyTotal : 0;
+    r.getCell(5).numFmt = '0.0%';
+    r.getCell(5).alignment = { horizontal: 'right' };
+    bandRow(byTripType, i + 2, 5, i % 2 === 1);
+  });
+  byTripType.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 5 } };
+
+  // ── By Booking Type sheet ────────────────────────────────────────────────
+  // Package = a booking carrying a packageId; regular = ordinary ticket sales. Share is
+  // against the same currency's grand total, never a cross-currency sum.
+  const byBookingType = wb.addWorksheet('By Booking Type', { views: [{ state: 'frozen', ySplit: 1 }] });
+  byBookingType.columns = [{ width: 26 }, { width: 12 }, { width: 14 }, { width: 20 }, { width: 12 }];
+  addTableHeader(byBookingType, 1, ['Booking Type', 'Currency', 'Items', 'Revenue', 'Share'], new Set([1, 2, 3]));
+  const bookingTypeCurrencyTotal = new Map(totals.map((t) => [t.currency, t.revenueMinor]));
+  report.byBookingType.forEach((b, i) => {
+    const r = byBookingType.getRow(i + 2);
+    const currencyTotal = bookingTypeCurrencyTotal.get(b.currency) ?? 0;
+    r.getCell(1).value = bookingTypeLabel(b.label);
+    r.getCell(2).value = b.currency;
+    r.getCell(3).value = b.bookingCount;
+    r.getCell(3).alignment = { horizontal: 'right' };
+    r.getCell(4).value = b.revenueMinor / 100;
+    r.getCell(4).numFmt = currencyFmt(b.currency);
+    r.getCell(4).alignment = { horizontal: 'right' };
+    r.getCell(5).value = currencyTotal > 0 ? b.revenueMinor / currencyTotal : 0;
+    r.getCell(5).numFmt = '0.0%';
+    r.getCell(5).alignment = { horizontal: 'right' };
+    bandRow(byBookingType, i + 2, 5, i % 2 === 1);
+  });
+  byBookingType.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 5 } };
+
+  // ── By Revenue Type sheet ────────────────────────────────────────────────
+  // Ticket fare vs the fees collected after it (baggage, recovered underpayments, other
+  // supplementary charges). Share is against the same currency's grand total.
+  const byRevenueType = wb.addWorksheet('By Revenue Type', { views: [{ state: 'frozen', ySplit: 1 }] });
+  byRevenueType.columns = [{ width: 26 }, { width: 12 }, { width: 14 }, { width: 20 }, { width: 12 }];
+  addTableHeader(byRevenueType, 1, ['Revenue Type', 'Currency', 'Items', 'Revenue', 'Share'], new Set([1, 2, 3]));
+  const revenueTypeCurrencyTotal = new Map(totals.map((t) => [t.currency, t.revenueMinor]));
+  report.byRevenueType.forEach((rt, i) => {
+    const r = byRevenueType.getRow(i + 2);
+    const currencyTotal = revenueTypeCurrencyTotal.get(rt.currency) ?? 0;
+    r.getCell(1).value = revenueTypeLabel(rt.label);
+    r.getCell(2).value = rt.currency;
+    r.getCell(3).value = rt.bookingCount;
+    r.getCell(3).alignment = { horizontal: 'right' };
+    r.getCell(4).value = rt.revenueMinor / 100;
+    r.getCell(4).numFmt = currencyFmt(rt.currency);
+    r.getCell(4).alignment = { horizontal: 'right' };
+    r.getCell(5).value = currencyTotal > 0 ? rt.revenueMinor / currencyTotal : 0;
+    r.getCell(5).numFmt = '0.0%';
+    r.getCell(5).alignment = { horizontal: 'right' };
+    bandRow(byRevenueType, i + 2, 5, i % 2 === 1);
+  });
+  byRevenueType.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 5 } };
+
   // ── By Method sheet ──────────────────────────────────────────────────────
   // Share is computed against the grand total for that same currency (`totals`), never
   // against a sum spanning multiple currencies.
   const byMethod = wb.addWorksheet('By Method', { views: [{ state: 'frozen', ySplit: 1 }] });
   byMethod.columns = [{ width: 20 }, { width: 12 }, { width: 14 }, { width: 20 }, { width: 12 }];
-  addTableHeader(byMethod, 1, ['Payment Method', 'Currency', 'Bookings', 'Revenue', 'Share'], new Set([1, 2, 3]));
+  addTableHeader(byMethod, 1, ['Payment Method', 'Currency', 'Items', 'Revenue', 'Share'], new Set([1, 2, 3]));
   const totalByCurrency = new Map(totals.map((t) => [t.currency, t.revenueMinor]));
   report.byMethod.forEach((m, i) => {
     const r = byMethod.getRow(i + 2);
@@ -262,22 +345,25 @@ export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise
 
   // ── Detail sheet — every row, unpaginated ───────────────────────────────
   const detail = wb.addWorksheet('Detail', { views: [{ state: 'frozen', ySplit: 1 }] });
-  detail.columns = [{ width: 18 }, { width: 34 }, { width: 18 }, { width: 12 }, { width: 14 }, { width: 20 }];
-  addTableHeader(detail, 1, ['Period', 'Origin → Destination', 'Payment Method', 'Currency', 'Bookings', 'Revenue'], new Set([2, 3]));
+  detail.columns = [{ width: 18 }, { width: 34 }, { width: 26 }, { width: 16 }, { width: 20 }, { width: 18 }, { width: 12 }, { width: 14 }, { width: 20 }];
+  addTableHeader(detail, 1, ['Period', 'Origin → Destination', 'Trip Type', 'Booking Type', 'Revenue Type', 'Payment Method', 'Currency', 'Items', 'Revenue'], new Set([5, 6]));
   report.rows.forEach((row, i) => {
     const r = detail.getRow(i + 2);
     r.getCell(1).value = periodLabel(row.period, report.granularity);
     r.getCell(2).value = row.segmentLabel;
-    r.getCell(3).value = methodLabel(row.method);
-    r.getCell(4).value = row.currency;
-    r.getCell(5).value = row.bookingCount;
-    r.getCell(5).alignment = { horizontal: 'right' };
-    r.getCell(6).value = row.revenueMinor / 100;
-    r.getCell(6).numFmt = currencyFmt(row.currency);
-    r.getCell(6).alignment = { horizontal: 'right' };
-    bandRow(detail, i + 2, 6, i % 2 === 1);
+    r.getCell(3).value = tripTypeLabel(row.tripType);
+    r.getCell(4).value = bookingTypeLabel(row.bookingType);
+    r.getCell(5).value = revenueTypeLabel(row.revenueType);
+    r.getCell(6).value = methodLabel(row.method);
+    r.getCell(7).value = row.currency;
+    r.getCell(8).value = row.bookingCount;
+    r.getCell(8).alignment = { horizontal: 'right' };
+    r.getCell(9).value = row.revenueMinor / 100;
+    r.getCell(9).numFmt = currencyFmt(row.currency);
+    r.getCell(9).alignment = { horizontal: 'right' };
+    bandRow(detail, i + 2, 9, i % 2 === 1);
   });
-  detail.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 6 } };
+  detail.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 9 } };
 
   const buffer = await wb.xlsx.writeBuffer();
   return new Blob([buffer], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
diff --git a/apps/edr-passenger-web/portal/src/app/booking/lookup/page.tsx b/apps/edr-passenger-web/portal/src/app/booking/lookup/page.tsx
index 123cd5710..1fbe4080e 100644
--- a/apps/edr-passenger-web/portal/src/app/booking/lookup/page.tsx
+++ b/apps/edr-passenger-web/portal/src/app/booking/lookup/page.tsx
@@ -6,6 +6,7 @@ import { useState } from "react";
 import { apiClient } from "@/lib/api-client";
 import { format } from "date-fns";
 import { toZonedDate } from "@/utils/format";
+import { STATUS_LABELS } from "@/lib/api/bookings";
 
 type SearchMode = "pnr" | "phone";
 
@@ -30,15 +31,6 @@ interface BookingListItem {
   seatCount: number;
 }
 
-const STATUS_LABELS: Record<string, { label: string; className: string }> = {
-  CONFIRMED:       { label: "Confirmed",       className: "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300" },
-  PENDING_PAYMENT: { label: "Pending Payment", className: "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300" },
-  CANCELLED:       { label: "Cancelled",       className: "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300" },
-  BOARDED:         { label: "Boarded",         className: "bg-blue-100 text-blue-800 dark:bg-blue-900/40 dark:text-blue-300" },
-  NO_SHOW:         { label: "No Show",         className: "bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300" },
-  REFUNDED:        { label: "Refunded",        className: "bg-purple-100 text-purple-800 dark:bg-purple-900/40 dark:text-purple-300" },
-};
-
 export default function BookingLookupPage() {
   const router = useRouter();
   const [mode, setMode] = useState<SearchMode>("pnr");
diff --git a/apps/edr-passenger-web/portal/src/app/bookings/page.tsx b/apps/edr-passenger-web/portal/src/app/bookings/page.tsx
new file mode 100644
index 000000000..6092e4cb2
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/app/bookings/page.tsx
@@ -0,0 +1,62 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useRouter } from 'next/navigation';
+import Link from 'next/link';
+import { Loader2, Search } from 'lucide-react';
+import { useAuthStore } from '@/lib/auth-store';
+import MyBookingsTable from '@/components/MyBookingsTable';
+
+/**
+ * "My Bookings" for a signed-in customer — every booking on the account, without the
+ * BRN / phone lookup a guest has to go through at /booking/lookup.
+ *
+ * The portal's middleware does no auth gating (it only sets the CSP nonce), so pages
+ * self-check. Same shape as /profile and /booking/reschedule.
+ */
+export default function MyBookingsPage() {
+  const router = useRouter();
+  const { isAuthenticated, isInitialized, initialize } = useAuthStore();
+
+  useEffect(() => {
+    initialize();
+  }, [initialize]);
+
+  useEffect(() => {
+    if (isInitialized && !isAuthenticated) {
+      router.push('/login?redirect=/bookings');
+    }
+  }, [isInitialized, isAuthenticated, router]);
+
+  if (!isInitialized || !isAuthenticated) {
+    return (
+      <div className="min-h-[60vh] flex items-center justify-center">
+        <Loader2 className="w-8 h-8 animate-spin text-[rgb(20,113,76)]" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-6xl mx-auto px-4 py-8">
+      <div className="flex flex-wrap items-start justify-between gap-3 mb-6">
+        <div>
+          <h1 className="text-2xl font-bold text-gray-900 dark:text-white">My Bookings</h1>
+          <p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
+            Every trip booked on this account.
+          </p>
+        </div>
+        {/* A customer can still hold a booking made under a different phone number as a
+            guest — that one is only reachable by reference, so keep the door open. */}
+        <Link
+          href="/booking/lookup"
+          className="inline-flex items-center gap-2 px-3 py-2 rounded-lg border border-gray-300 dark:border-gray-600 text-sm font-medium text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors"
+        >
+          <Search className="w-4 h-4" />
+          Look up another booking
+        </Link>
+      </div>
+
+      <MyBookingsTable />
+    </div>
+  );
+}
diff --git a/apps/edr-passenger-web/portal/src/app/profile/page.tsx b/apps/edr-passenger-web/portal/src/app/profile/page.tsx
index 37ffdabfb..ef21631b1 100644
--- a/apps/edr-passenger-web/portal/src/app/profile/page.tsx
+++ b/apps/edr-passenger-web/portal/src/app/profile/page.tsx
@@ -4,32 +4,19 @@ import { useState, useEffect } from 'react';
 import { useRouter } from 'next/navigation';
 import { useAuthStore } from '@/lib/auth-store';
 import { useTheme } from '@/components/ThemeProvider';
-import { 
-  User, Settings, Ticket, Calendar, MapPin, 
-  Download, Trash2, Lock, Bell, CreditCard, 
+import {
+  User, Settings, Ticket,
+  Download, Trash2, Lock, Bell,
   MapPinned, Palette, CheckCircle,
-  Eye, Edit, LogOut, X
+  Edit, LogOut, X
 } from 'lucide-react';
 import { apiClient } from '@/lib/api-client';
-import { useQuery, useMutation } from '@tanstack/react-query';
+import { useMutation } from '@tanstack/react-query';
 import CustomModal from '@/components/CustomModal';
+import MyBookingsTable from '@/components/MyBookingsTable';
 
 type Tab = 'bookings' | 'profile' | 'settings';
 
-interface Booking {
-  id: string;
-  pnr: string;
-  status: string;
-  totalMinor: number;
-  createdAt: string;
-  trip?: {
-    trainNumber: string;
-    departureAt: string;
-    origin?: { name: string };
-    destination?: { name: string };
-  };
-}
-
 export default function ProfilePage() {
   const router = useRouter();
   const { user, isAuthenticated, logout, initialize, updateUser, isInitialized, fetchProfile } = useAuthStore();
@@ -82,18 +69,6 @@ export default function ProfilePage() {
     }
   }, [isInitialized, isAuthenticated, user, router, fetchProfile]);
 
-  const { data: bookings, isLoading: loadingBookings } = useQuery({
-    queryKey: ['user-bookings'],
-    queryFn: async () => {
-      try {
-        return await apiClient.get('/bookings/my-bookings');
-      } catch {
-        return [];
-      }
-    },
-    enabled: isAuthenticated && activeTab === 'bookings',
-  });
-
   const updateProfileMutation = useMutation({
     mutationFn: (data: any) => apiClient.patch('/auth/profile', data),
     onSuccess: (response) => {
@@ -229,16 +204,6 @@ export default function ProfilePage() {
     setShowModal(true);
   };
 
-  const getStatusBadge = (status: string) => {
-    const styles = {
-      CONFIRMED: 'bg-green-100 dark:bg-green-900/30 text-green-800 dark:text-green-300',
-      PENDING: 'bg-yellow-100 dark:bg-yellow-900/30 text-yellow-800 dark:text-yellow-300',
-      CANCELLED: 'bg-red-100 dark:bg-red-900/30 text-red-800 dark:text-red-300',
-      COMPLETED: 'bg-blue-100 dark:bg-blue-900/30 text-blue-800 dark:text-blue-300',
-    };
-    return styles[status as keyof typeof styles] || styles.PENDING;
-  };
-
   if (!isInitialized || !user) {
     return (
       <div className="min-h-screen bg-gray-50 dark:bg-gray-900 flex items-center justify-center">
@@ -322,71 +287,11 @@ export default function ProfilePage() {
           {activeTab === 'bookings' && (
             <div className="space-y-4">
               <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-4">Bookings</h2>
-              
-              {loadingBookings ? (
-                <div className="card text-center py-12">
-                  <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-[rgb(20_113_76)] mx-auto"></div>
-                  <p className="text-gray-600 dark:text-gray-400 mt-4">Loading bookings...</p>
-                </div>
-              ) : bookings && Array.isArray(bookings) && bookings.length > 0 ? (
-                bookings.map((booking: Booking) => (
-                  <div key={booking.id} className="card hover:shadow-lg transition-shadow">
-                    <div className="flex items-center justify-between">
-                      <div className="flex-1">
-                        <div className="flex items-center gap-3 mb-3">
-                          <span className={`badge ${getStatusBadge(booking.status)}`}>
-                            {booking.status}
-                          </span>
-                          <span className="text-sm font-semibold text-gray-900 dark:text-gray-100">
-                            PNR: {booking.pnr}
-                          </span>
-                        </div>
-                        
-                        <div className="grid md:grid-cols-3 gap-4 text-sm">
-                          <div className="flex items-center gap-2">
-                            <Calendar className="w-4 h-4 text-gray-400" />
-                            <span className="text-gray-600 dark:text-gray-400">
-                              {booking.trip?.departureAt
-                                ? new Date(booking.trip.departureAt).toLocaleDateString('en-US', { timeZone: 'Africa/Addis_Ababa' })
-                                : 'N/A'}
-                            </span>
-                          </div>
-                          <div className="flex items-center gap-2">
-                            <MapPin className="w-4 h-4 text-gray-400" />
-                            <span className="text-gray-600 dark:text-gray-400">
-                              {booking.trip?.origin?.name} → {booking.trip?.destination?.name}
-                            </span>
-                          </div>
-                          <div className="flex items-center gap-2">
-                            <CreditCard className="w-4 h-4 text-gray-400" />
-                            <span className="text-gray-900 dark:text-gray-100 font-semibold">
-                              ETB {((booking.totalMinor || 0) / 100).toFixed(2)}
-                            </span>
-                          </div>
-                        </div>
-                      </div>
-                      
-                      <div className="flex items-center gap-2 ml-4">
-                        <button
-                          onClick={() => router.push(`/booking/confirmation?id=${booking.id}`)}
-                          className="btn-secondary text-sm flex items-center gap-2"
-                        >
-                          <Eye className="w-4 h-4" />
-                          View
-                        </button>
-                      </div>
-                    </div>
-                  </div>
-                ))
-              ) : (
-                <div className="card text-center py-12">
-                  <Ticket className="w-16 h-16 text-gray-300 dark:text-gray-600 mx-auto mb-4" />
-                  <p className="text-gray-600 dark:text-gray-400 mb-4">No bookings yet</p>
-                  <button onClick={() => router.push('/booking/search')} className="btn-primary">
-                    Book Your First Trip
-                  </button>
-                </div>
-              )}
+              {/* Same component as /bookings, so the two never drift. It replaces a card
+                  list that called GET /bookings/my-bookings — a route that does not exist
+                  (the real one is GET /bookings/my), whose 404 was swallowed, so this tab
+                  always read "No bookings yet". */}
+              <MyBookingsTable />
             </div>
           )}
 
diff --git a/apps/edr-passenger-web/portal/src/components/AppSidebar.tsx b/apps/edr-passenger-web/portal/src/components/AppSidebar.tsx
index a621c5d83..7565712ba 100644
--- a/apps/edr-passenger-web/portal/src/components/AppSidebar.tsx
+++ b/apps/edr-passenger-web/portal/src/components/AppSidebar.tsx
@@ -39,9 +39,12 @@ const BOOKING_STEP_MAP: Record<string, string> = {
   '/booking/confirmation': 'confirmation',
 };
 
-const NAV_LINKS = [
+// "My Bookings" resolves differently by session: a signed-in customer gets their own
+// account history at /bookings, a guest gets the BRN / phone lookup form. Same label
+// either way, because it is the same intent.
+const navLinks = (isAuthenticated: boolean) => [
   { href: '/', label: 'Home', icon: Home },
-  { href: '/booking/lookup', label: 'My Bookings', icon: Ticket },
+  { href: isAuthenticated ? '/bookings' : '/booking/lookup', label: 'My Bookings', icon: Ticket },
   { href: '/contact', label: 'Contact', icon: Phone },
   { href: '/help', label: 'Help', icon: HelpCircle },
 ];
@@ -83,7 +86,7 @@ export default function AppSidebar() {
       </Link>
 
       <nav className="flex-1 overflow-y-auto px-3 py-4 space-y-1">
-        {NAV_LINKS.map(({ href, label, icon: Icon }) => {
+        {navLinks(isAuthenticated).map(({ href, label, icon: Icon }) => {
           const isActive = href === '/' ? pathname === '/' : pathname?.startsWith(href);
           return (
             <Link
diff --git a/apps/edr-passenger-web/portal/src/components/BottomTabBar.tsx b/apps/edr-passenger-web/portal/src/components/BottomTabBar.tsx
index ee4cdccad..d2775ddd5 100644
--- a/apps/edr-passenger-web/portal/src/components/BottomTabBar.tsx
+++ b/apps/edr-passenger-web/portal/src/components/BottomTabBar.tsx
@@ -28,7 +28,14 @@ export default function BottomTabBar() {
 
   const tabs = [
     { href: '/', label: 'Home', icon: Home, match: (p: string) => p === '/' },
-    { href: '/booking/lookup', label: 'Bookings', icon: Ticket, match: (p: string) => p.startsWith('/booking/lookup') || p.startsWith('/booking/detail') },
+    // Signed in: straight to the account's own history. Signed out: the guest lookup form.
+    {
+      href: isAuthenticated ? '/bookings' : '/booking/lookup',
+      label: 'Bookings',
+      icon: Ticket,
+      match: (p: string) =>
+        p.startsWith('/bookings') || p.startsWith('/booking/lookup') || p.startsWith('/booking/detail'),
+    },
     { href: '/contact', label: 'Contact', icon: Phone, match: (p: string) => p.startsWith('/contact') },
     {
       href: isAuthenticated ? '/profile' : '/login',
diff --git a/apps/edr-passenger-web/portal/src/components/MyBookingsTable.tsx b/apps/edr-passenger-web/portal/src/components/MyBookingsTable.tsx
new file mode 100644
index 000000000..2d3cf7d64
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/components/MyBookingsTable.tsx
@@ -0,0 +1,379 @@
+'use client';
+
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { useQuery, keepPreviousData } from '@tanstack/react-query';
+import { format } from 'date-fns';
+import {
+  Ticket,
+  Loader2,
+  ChevronLeft,
+  ChevronRight,
+  Clock,
+  Eye,
+  CreditCard,
+  RefreshCw,
+  AlertCircle,
+} from 'lucide-react';
+import { toZonedDate } from '@/utils/format';
+import { samePhone } from '@/utils/phone';
+import { useAuthStore } from '@/lib/auth-store';
+import {
+  fetchMyBookings,
+  statusBadge,
+  type BookingScope,
+  type MyBookingItem,
+} from '@/lib/api/bookings';
+
+const PAGE_SIZE = 10;
+
+const SCOPES: { id: BookingScope; label: string }[] = [
+  { id: 'upcoming', label: 'Upcoming' },
+  { id: 'past', label: 'Past' },
+  { id: 'cancelled', label: 'Cancelled' },
+];
+
+const EMPTY_COPY: Record<BookingScope, string> = {
+  upcoming: 'No upcoming trips.',
+  past: 'No past trips yet.',
+  cancelled: 'No cancelled bookings.',
+  all: 'No bookings yet.',
+};
+
+function formatTravelDate(iso: string) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '—';
+  return format(toZonedDate(d), 'dd MMM yyyy, HH:mm');
+}
+
+/**
+ * "CRS-0002 · 12, 14" for one leg. Round trips carry leg-2 seats on the same booking.
+ * Coach.number is already a full code on this data (e.g. "CRS-0002"), so it is printed
+ * as-is rather than prefixed.
+ */
+function describeSeats(seats: MyBookingItem['seats'], leg: number) {
+  const forLeg = (seats ?? []).filter((s) => (s.leg ?? 1) === leg);
+  const numbers = forLeg.map((s) => s.seatNumber).filter(Boolean);
+  if (numbers.length === 0) return null;
+  const coaches = Array.from(new Set(forLeg.map((s) => s.coachNumber).filter(Boolean)));
+  const coachLabel = coaches.length > 0 ? `${coaches.join(' / ')} · ` : '';
+  return `${coachLabel}${numbers.join(', ')}`;
+}
+
+interface RowActions {
+  canReschedule: boolean;
+  rescheduleBlocker: string | null;
+  isPendingPayment: boolean;
+}
+
+/**
+ * The coarse reschedule gate, mirroring booking/detail/page.tsx. The per-leg rules
+ * (fare-class policy, cutoff, seats still free) belong to the reschedule page, which
+ * names them as blockers — this only avoids sending the customer somewhere that is
+ * certain to reject them. The phone test matches the API's own ownership check
+ * (reschedule.service.ts loadOwnedBooking), which is phone-based, not account-based.
+ */
+function resolveActions(b: MyBookingItem, userPhone?: string): RowActions {
+  const isPendingPayment = b.status === 'PENDING_PAYMENT' || b.status === 'DRAFT';
+
+  let rescheduleBlocker: string | null = null;
+  if (b.status !== 'CONFIRMED') rescheduleBlocker = 'Only a confirmed booking can be rescheduled';
+  else if (b.isPackageBooking) rescheduleBlocker = 'Package bookings cannot be rescheduled online';
+  else if (!['ONE_WAY', 'ROUND_TRIP'].includes(b.bookingType))
+    rescheduleBlocker = 'Transit bookings cannot be rescheduled online';
+  else if (b.outboundBoardedAt) rescheduleBlocker = 'This trip has already been boarded';
+  else if (b.contactPhone && !samePhone(userPhone, b.contactPhone))
+    rescheduleBlocker = 'Only the person who made this booking can reschedule it';
+
+  return { canReschedule: rescheduleBlocker === null, rescheduleBlocker, isPendingPayment };
+}
+
+/**
+ * The signed-in customer's own booking history, from GET /bookings/my — no BRN or
+ * phone lookup. Rendered by /bookings and by the /profile Bookings tab, so both stay
+ * one implementation.
+ */
+export default function MyBookingsTable() {
+  const router = useRouter();
+  const userPhone = useAuthStore((s) => s.user?.phone);
+  const [scope, setScope] = useState<BookingScope>('upcoming');
+  const [page, setPage] = useState(1);
+
+  const { data, isLoading, isError, refetch, isFetching } = useQuery({
+    queryKey: ['my-bookings', scope, page],
+    queryFn: () => fetchMyBookings({ scope, page, pageSize: PAGE_SIZE }),
+    // Keeps the current rows on screen while a tab or page change is in flight instead
+    // of collapsing to the spinner and jumping the scroll position.
+    placeholderData: keepPreviousData,
+  });
+
+  const items = data?.items ?? [];
+  const meta = data?.meta;
+  const totalPages = meta?.totalPages ?? 0;
+
+  const switchScope = (next: BookingScope) => {
+    setScope(next);
+    setPage(1);
+  };
+
+  const openDetail = (b: MyBookingItem) => router.push(`/booking/detail?ref=${b.bookingRef}`);
+  const openReschedule = (b: MyBookingItem) => router.push(`/booking/reschedule?ref=${b.bookingRef}`);
+
+  const cardClass =
+    'bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700';
+
+  return (
+    <div>
+      {/* Scope tabs */}
+      <div className="flex flex-wrap items-center gap-2 mb-5">
+        {SCOPES.map(({ id, label }) => (
+          <button
+            key={id}
+            onClick={() => switchScope(id)}
+            className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
+              scope === id
+                ? 'bg-[rgb(20,113,76)] text-white'
+                : 'bg-white dark:bg-gray-800 text-gray-600 dark:text-gray-300 border border-gray-200 dark:border-gray-700 hover:bg-gray-50 dark:hover:bg-gray-700'
+            }`}
+          >
+            {label}
+          </button>
+        ))}
+        {isFetching && !isLoading && (
+          <Loader2 className="w-4 h-4 animate-spin text-gray-400" aria-hidden="true" />
+        )}
+      </div>
+
+      {isLoading ? (
+        <div className={`${cardClass} py-16 text-center`}>
+          <Loader2 className="w-8 h-8 animate-spin text-[rgb(20,113,76)] mx-auto" />
+          <p className="text-gray-600 dark:text-gray-400 mt-3 text-sm">Loading your bookings…</p>
+        </div>
+      ) : isError ? (
+        <div className={`${cardClass} py-16 text-center`}>
+          <AlertCircle className="w-10 h-10 text-red-400 mx-auto mb-3" />
+          <p className="text-gray-700 dark:text-gray-300 mb-4 text-sm">
+            We could not load your bookings just now.
+          </p>
+          <button
+            onClick={() => refetch()}
+            className="inline-flex items-center gap-2 px-4 py-2 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 text-sm font-medium"
+          >
+            <RefreshCw className="w-4 h-4" />
+            Try again
+          </button>
+        </div>
+      ) : items.length === 0 ? (
+        <div className={`${cardClass} py-16 text-center`}>
+          <Ticket className="w-14 h-14 text-gray-300 dark:text-gray-600 mx-auto mb-4" />
+          <p className="text-gray-600 dark:text-gray-400 mb-4">{EMPTY_COPY[scope]}</p>
+          <button
+            onClick={() => router.push('/booking/search')}
+            className="px-4 py-2 rounded-lg bg-[rgb(20,113,76)] hover:bg-[rgb(16,89,60)] text-white text-sm font-medium transition-colors"
+          >
+            Book a trip
+          </button>
+        </div>
+      ) : (
+        <>
+          {/* Desktop: the tabular view */}
+          <div className={`hidden lg:block ${cardClass} overflow-x-auto`}>
+            <table className="w-full text-sm">
+              <thead>
+                <tr className="border-b border-gray-200 dark:border-gray-700 text-left text-xs uppercase tracking-wide text-gray-500 dark:text-gray-400">
+                  <th scope="col" className="px-4 py-3 font-semibold">Booking Ref</th>
+                  <th scope="col" className="px-4 py-3 font-semibold">Travel date &amp; time</th>
+                  <th scope="col" className="px-4 py-3 font-semibold">Route</th>
+                  <th scope="col" className="px-4 py-3 font-semibold">Seat / Coach</th>
+                  <th scope="col" className="px-4 py-3 font-semibold">Status</th>
+                  <th scope="col" className="px-4 py-3 font-semibold text-right">Actions</th>
+                </tr>
+              </thead>
+              <tbody>
+                {items.map((b) => {
+                  const badge = statusBadge(b.status);
+                  const actions = resolveActions(b, userPhone);
+                  const outbound = describeSeats(b.seats, 1);
+                  const inbound = describeSeats(b.seats, 2);
+                  return (
+                    <tr
+                      key={b.id}
+                      className="border-b border-gray-100 dark:border-gray-700/60 last:border-0 hover:bg-gray-50 dark:hover:bg-gray-700/40 transition-colors"
+                    >
+                      <td className="px-4 py-3 font-mono font-semibold tracking-wider text-gray-900 dark:text-white whitespace-nowrap">
+                        {b.bookingRef}
+                      </td>
+                      <td className="px-4 py-3 text-gray-700 dark:text-gray-300 whitespace-nowrap">
+                        {formatTravelDate(b.schedule.departureAt)}
+                      </td>
+                      <td className="px-4 py-3 text-gray-700 dark:text-gray-300">
+                        {b.schedule.originStation.name} → {b.schedule.destinationStation.name}
+                        {b.bookingType === 'ROUND_TRIP' && (
+                          <span className="ml-2 text-xs text-gray-500 dark:text-gray-400">
+                            (round trip)
+                          </span>
+                        )}
+                      </td>
+                      <td className="px-4 py-3 text-gray-700 dark:text-gray-300 whitespace-nowrap">
+                        {outbound ?? <span className="text-gray-400">—</span>}
+                        {inbound && (
+                          <span className="block text-xs text-gray-500 dark:text-gray-400">
+                            Return: {inbound}
+                          </span>
+                        )}
+                      </td>
+                      <td className="px-4 py-3 whitespace-nowrap">
+                        <span className={`text-xs px-2 py-0.5 rounded-full font-medium ${badge.className}`}>
+                          {badge.label}
+                        </span>
+                        {b.rescheduled && (
+                          <span className="ml-1.5 text-xs px-2 py-0.5 rounded-full font-medium bg-indigo-100 text-indigo-800 dark:bg-indigo-900/40 dark:text-indigo-300">
+                            Rescheduled
+                          </span>
+                        )}
+                      </td>
+                      <td className="px-4 py-3">
+                        <div className="flex items-center justify-end gap-2">
+                          <button
+                            onClick={() => openDetail(b)}
+                            className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 text-xs font-medium transition-colors whitespace-nowrap"
+                          >
+                            {actions.isPendingPayment ? (
+                              <>
+                                <CreditCard className="w-3.5 h-3.5" />
+                                Complete payment
+                              </>
+                            ) : (
+                              <>
+                                <Eye className="w-3.5 h-3.5" />
+                                View ticket
+                              </>
+                            )}
+                          </button>
+                          {!actions.isPendingPayment && (
+                            <button
+                              onClick={() => openReschedule(b)}
+                              disabled={!actions.canReschedule}
+                              title={
+                                actions.rescheduleBlocker ??
+                                'Change the date, train or seats on this booking'
+                              }
+                              className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 disabled:opacity-40 disabled:cursor-not-allowed text-xs font-medium transition-colors whitespace-nowrap"
+                            >
+                              <Clock className="w-3.5 h-3.5" />
+                              Reschedule
+                            </button>
+                          )}
+                        </div>
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+
+          {/* Mobile: the same rows as cards — the portal's established list pattern */}
+          <div className="lg:hidden space-y-3">
+            {items.map((b) => {
+              const badge = statusBadge(b.status);
+              const actions = resolveActions(b, userPhone);
+              const outbound = describeSeats(b.seats, 1);
+              const inbound = describeSeats(b.seats, 2);
+              return (
+                <div key={b.id} className={`${cardClass} p-4`}>
+                  <div className="flex items-start justify-between gap-2 mb-2">
+                    <span className="font-mono font-bold tracking-wider text-gray-900 dark:text-white">
+                      {b.bookingRef}
+                    </span>
+                    <div className="flex flex-wrap justify-end gap-1">
+                      <span className={`text-xs px-2 py-0.5 rounded-full font-medium ${badge.className}`}>
+                        {badge.label}
+                      </span>
+                      {b.rescheduled && (
+                        <span className="text-xs px-2 py-0.5 rounded-full font-medium bg-indigo-100 text-indigo-800 dark:bg-indigo-900/40 dark:text-indigo-300">
+                          Rescheduled
+                        </span>
+                      )}
+                    </div>
+                  </div>
+
+                  <p className="text-sm text-gray-700 dark:text-gray-300">
+                    {b.schedule.originStation.name} → {b.schedule.destinationStation.name}
+                  </p>
+                  <p className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">
+                    {formatTravelDate(b.schedule.departureAt)}
+                  </p>
+                  <p className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">
+                    Seat / Coach: {outbound ?? '—'}
+                    {inbound && ` · Return: ${inbound}`}
+                  </p>
+
+                  <div className="flex flex-wrap gap-2 mt-3">
+                    <button
+                      onClick={() => openDetail(b)}
+                      className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-200 text-xs font-medium"
+                    >
+                      {actions.isPendingPayment ? (
+                        <>
+                          <CreditCard className="w-3.5 h-3.5" />
+                          Complete payment
+                        </>
+                      ) : (
+                        <>
+                          <Eye className="w-3.5 h-3.5" />
+                          View ticket
+                        </>
+                      )}
+                    </button>
+                    {!actions.isPendingPayment && (
+                      <button
+                        onClick={() => openReschedule(b)}
+                        disabled={!actions.canReschedule}
+                        title={
+                          actions.rescheduleBlocker ??
+                          'Change the date, train or seats on this booking'
+                        }
+                        className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-200 disabled:opacity-40 disabled:cursor-not-allowed text-xs font-medium"
+                      >
+                        <Clock className="w-3.5 h-3.5" />
+                        Reschedule
+                      </button>
+                    )}
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+
+          {totalPages > 1 && (
+            <div className="flex items-center justify-between gap-3 mt-4">
+              <p className="text-xs text-gray-500 dark:text-gray-400">
+                Page {meta?.page ?? page} of {totalPages} · {meta?.total ?? items.length} booking
+                {(meta?.total ?? items.length) !== 1 ? 's' : ''}
+              </p>
+              <div className="flex gap-2">
+                <button
+                  onClick={() => setPage((p) => Math.max(1, p - 1))}
+                  disabled={page <= 1}
+                  className="inline-flex items-center gap-1 px-3 py-1.5 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 disabled:opacity-40 disabled:cursor-not-allowed text-xs font-medium"
+                >
+                  <ChevronLeft className="w-4 h-4" />
+                  Previous
+                </button>
+                <button
+                  onClick={() => setPage((p) => Math.min(totalPages, p + 1))}
+                  disabled={page >= totalPages}
+                  className="inline-flex items-center gap-1 px-3 py-1.5 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 disabled:opacity-40 disabled:cursor-not-allowed text-xs font-medium"
+                >
+                  Next
+                  <ChevronRight className="w-4 h-4" />
+                </button>
+              </div>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
diff --git a/apps/edr-passenger-web/portal/src/lib/api/bookings.ts b/apps/edr-passenger-web/portal/src/lib/api/bookings.ts
new file mode 100644
index 000000000..d87cd97f9
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/lib/api/bookings.ts
@@ -0,0 +1,94 @@
+import { apiClient } from '@/lib/api-client';
+
+/**
+ * The authenticated booking history: GET /bookings/my (JwtGuard). This is the
+ * account-linked list — no BRN or phone lookup — as opposed to the public
+ * /bookings/by-phone and /bookings/:bookingRef used by the guest lookup page.
+ */
+
+export type BookingScope = 'upcoming' | 'past' | 'cancelled' | 'all';
+
+export interface MyBookingSeat {
+  leg: number;
+  passengerName: string;
+  seatNumber: string | null;
+  coachNumber: string | null;
+}
+
+export interface MyBookingItem {
+  id: string;
+  bookingRef: string;
+  status: string;
+  totalMinor: number;
+  currency?: string | null;
+  displayCurrency?: string | null;
+  displayTotalMinor?: number | null;
+  adultCount: number;
+  childCount: number;
+  bookingType: string;
+  returnLegStatus?: string | null;
+  createdAt: string;
+  schedule: {
+    train?: { number?: string; name?: string } | null;
+    originStation: { id?: string; name: string; code?: string; city?: string };
+    destinationStation: { id?: string; name: string; code?: string; city?: string };
+    departureAt: string;
+    arrivalAt?: string | null;
+  };
+  paymentIntent?: { method?: string; status?: string } | null;
+  seatCount: number;
+  seats: MyBookingSeat[];
+  rescheduled: boolean;
+  outboundBoardedAt: string | null;
+  isPackageBooking: boolean;
+  contactPhone: string | null;
+}
+
+export interface MyBookingsResponse {
+  items: MyBookingItem[];
+  meta: { page: number; pageSize: number; total: number; totalPages: number };
+}
+
+const EMPTY_META = { page: 1, pageSize: 20, total: 0, totalPages: 0 };
+
+export async function fetchMyBookings(params: {
+  scope?: BookingScope;
+  page?: number;
+  pageSize?: number;
+  search?: string;
+}): Promise<MyBookingsResponse> {
+  const query = new URLSearchParams();
+  if (params.scope) query.set('scope', params.scope);
+  if (params.page) query.set('page', String(params.page));
+  if (params.pageSize) query.set('pageSize', String(params.pageSize));
+  if (params.search?.trim()) query.set('search', params.search.trim());
+
+  // apiClient.get already unwraps `response.data?.data || response.data`, but the API
+  // has been seen to return both shapes for list endpoints — mirror the defensive read
+  // the guest lookup page uses for /bookings/by-phone.
+  const resp: any = await apiClient.get(`/bookings/my?${query.toString()}`);
+  return {
+    items: resp?.items ?? resp?.data?.items ?? [],
+    meta: resp?.meta ?? resp?.data?.meta ?? { ...EMPTY_META, pageSize: params.pageSize ?? 20 },
+  };
+}
+
+/**
+ * Badge presentation for `BookingStatus`. The enum has no COMPLETED and no
+ * RESCHEDULED member (schema.prisma) — BOARDED is what "travelled" looks like, and a
+ * rescheduled booking stays CONFIRMED, so that is shown as a separate chip.
+ * Shared with the guest lookup page so the two lists cannot drift.
+ */
+export const STATUS_LABELS: Record<string, { label: string; className: string }> = {
+  CONFIRMED:       { label: 'Confirmed',       className: 'bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300' },
+  PENDING_PAYMENT: { label: 'Pending Payment', className: 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300' },
+  DRAFT:           { label: 'Draft',           className: 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300' },
+  CANCELLED:       { label: 'Cancelled',       className: 'bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300' },
+  BOARDED:         { label: 'Completed',       className: 'bg-blue-100 text-blue-800 dark:bg-blue-900/40 dark:text-blue-300' },
+  NO_SHOW:         { label: 'No Show',         className: 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300' },
+  REFUNDED:        { label: 'Refunded',        className: 'bg-purple-100 text-purple-800 dark:bg-purple-900/40 dark:text-purple-300' },
+};
+
+export function statusBadge(status: string) {
+  return STATUS_LABELS[status] ?? { label: status, className: 'bg-gray-100 text-gray-700 dark:bg-gray-700 dark:text-gray-300' };
+}
diff --git a/apps/edr-passenger-web/portal/src/middleware.ts b/apps/edr-passenger-web/portal/src/middleware.ts
index 9604317f7..7766a1311 100644
--- a/apps/edr-passenger-web/portal/src/middleware.ts
+++ b/apps/edr-passenger-web/portal/src/middleware.ts
@@ -3,6 +3,8 @@ import { NextRequest, NextResponse } from 'next/server';
 // Routes that should NOT redirect to home on hard refresh
 const PRESERVED_ROUTES = [
   '/booking/',
+  // Note the trailing slash above: '/booking/' does not match '/bookings'.
+  '/bookings',
   '/login',
   '/register',
   '/forgot-password',
@@ -117,6 +119,7 @@ export function middleware(request: NextRequest) {
   // Tell crawlers not to index private/transactional routes.
   const NOINDEX_PREFIXES = [
     '/booking/',
+    '/bookings',
     '/login',
     '/register',
     '/forgot-password',
diff --git a/packages/types/src/freight/clearance-files.catalog.ts b/packages/types/src/freight/clearance-files.catalog.ts
index 8fa50cba4..9a4468af0 100644
--- a/packages/types/src/freight/clearance-files.catalog.ts
+++ b/packages/types/src/freight/clearance-files.catalog.ts
@@ -99,7 +99,16 @@ export interface ClearanceWorkflowFile {
   label: string;
   uploadedBy: ClearanceWorkflowFileOwner;
   category: ClearanceWorkflowFileCategory;
-  file: { id: string; name: string; url: string } | null;
+  file: {
+    id: string;
+    name: string;
+    url: string;
+    /** When this file record was stored — a replaced batch carries the new stamp. */
+    uploadedAt?: string | null;
+    updatedAt?: string | null;
+    size?: number | null;
+    mimeType?: string | null;
+  } | null;
 }
 
 const CATALOG_BY_CODE = new Map(
@@ -239,6 +248,39 @@ export function exportTransportFileLabel(code: string, index?: number): string {
   return code;
 }
 
+// ── Transit agent arrival paperwork (export) ────────────────────────────────
+// Filed by the assigned transit officer at Djibouti around train arrival. Both
+// are append-only multi-file sets: each upload adds files, and a file can be
+// removed on its own, unlike the DO/RO batches that replace as a whole.
+
+/** Multi-file Djibouti gate pass uploads use `gate_pass_0`, `gate_pass_1`, … */
+export const GATE_PASS_FILE_PREFIX = "gate_pass_";
+
+export function isGatePassFileCode(code: string | null | undefined): boolean {
+  if (!code) return false;
+  return code.toLowerCase().startsWith(GATE_PASS_FILE_PREFIX);
+}
+
+export function gatePassFileLabel(index?: number): string {
+  return index != null ? `Gate pass ${index + 1}` : "Gate pass";
+}
+
+/** Multi-file Djibouti T1 uploads use `djibouti_t1_0`, `djibouti_t1_1`, … */
+export const DJIBOUTI_T1_FILE_PREFIX = "djibouti_t1_";
+
+export function isDjiboutiT1FileCode(code: string | null | undefined): boolean {
+  if (!code) return false;
+  return code.toLowerCase().startsWith(DJIBOUTI_T1_FILE_PREFIX);
+}
+
+export function djiboutiT1FileLabel(index?: number): string {
+  return index != null ? `Djibouti T1 ${index + 1}` : "Djibouti T1";
+}
+
+/** The two transit-agent arrival document sets, keyed by the API route segment. */
+export const TRANSIT_ARRIVAL_DOCUMENT_KINDS = ["gate_pass", "djibouti_t1"] as const;
+export type TransitArrivalDocumentKind = (typeof TRANSIT_ARRIVAL_DOCUMENT_KINDS)[number];
+
 export function catalogEntriesForTradeDirection(
   tradeDirection: string,
 ): ClearanceWorkflowFileCatalogEntry[] {
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 6e4f7c6da..f1ac43c6e 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -439,6 +439,123 @@ export interface IWagonMovement extends BaseEntity {
   note?: string | null;
 }
 
+/** Which slice of a wagon's life an event belongs to — the history filter axis. */
+export enum WagonEventCategory {
+  Lifecycle = "LIFECYCLE",
+  Yard = "YARD",
+  Train = "TRAIN",
+  Schedule = "SCHEDULE",
+  Status = "STATUS",
+  Cargo = "CARGO",
+}
+
+/**
+ * Every recorded transition in a wagon's history (`freight.wagon_events`).
+ * One row per wagon per transition, append-only, written inside the same
+ * transaction as the change itself.
+ */
+export enum WagonEventType {
+  // Lifecycle
+  Registered = "REGISTERED",
+  DetailsUpdated = "DETAILS_UPDATED",
+  Deleted = "DELETED",
+  Purged = "PURGED",
+  // Yard (where the wagon physically is)
+  MovedManually = "MOVED_MANUALLY",
+  MovedWithTrain = "MOVED_WITH_TRAIN",
+  PassedCheckpoint = "PASSED_CHECKPOINT",
+  CutAtYard = "CUT_AT_YARD",
+  SettledOnArrival = "SETTLED_ON_ARRIVAL",
+  ReleasedAtUnload = "RELEASED_AT_UNLOAD",
+  ReturnedOnCancel = "RETURNED_ON_CANCEL",
+  // Built train / consist
+  CoupledToTrain = "COUPLED_TO_TRAIN",
+  UncoupledFromTrain = "UNCOUPLED_FROM_TRAIN",
+  SequenceChanged = "SEQUENCE_CHANGED",
+  TrainMerged = "TRAIN_MERGED",
+  TrainDisbanded = "TRAIN_DISBANDED",
+  // Schedule slot
+  PinnedToSchedule = "PINNED_TO_SCHEDULE",
+  UnpinnedFromSchedule = "UNPINNED_FROM_SCHEDULE",
+  Dispatched = "DISPATCHED",
+  ReleasedFromSchedule = "RELEASED_FROM_SCHEDULE",
+  // Status
+  StatusChanged = "STATUS_CHANGED",
+  // Cargo
+  CargoLoaded = "CARGO_LOADED",
+  CargoUnloaded = "CARGO_UNLOADED",
+  BookingUnassigned = "BOOKING_UNASSIGNED",
+  BookingCancelled = "BOOKING_CANCELLED",
+  LoadMovedIn = "LOAD_MOVED_IN",
+  LoadMovedOut = "LOAD_MOVED_OUT",
+  ContainerPlaced = "CONTAINER_PLACED",
+  ContainerRemoved = "CONTAINER_REMOVED",
+}
+
+export const WAGON_EVENT_CATEGORY: Record<WagonEventType, WagonEventCategory> = {
+  [WagonEventType.Registered]: WagonEventCategory.Lifecycle,
+  [WagonEventType.DetailsUpdated]: WagonEventCategory.Lifecycle,
+  [WagonEventType.Deleted]: WagonEventCategory.Lifecycle,
+  [WagonEventType.Purged]: WagonEventCategory.Lifecycle,
+  [WagonEventType.MovedManually]: WagonEventCategory.Yard,
+  [WagonEventType.MovedWithTrain]: WagonEventCategory.Yard,
+  [WagonEventType.PassedCheckpoint]: WagonEventCategory.Yard,
+  [WagonEventType.CutAtYard]: WagonEventCategory.Yard,
+  [WagonEventType.SettledOnArrival]: WagonEventCategory.Yard,
+  [WagonEventType.ReleasedAtUnload]: WagonEventCategory.Yard,
+  [WagonEventType.ReturnedOnCancel]: WagonEventCategory.Yard,
+  [WagonEventType.CoupledToTrain]: WagonEventCategory.Train,
+  [WagonEventType.UncoupledFromTrain]: WagonEventCategory.Train,
+  [WagonEventType.SequenceChanged]: WagonEventCategory.Train,
+  [WagonEventType.TrainMerged]: WagonEventCategory.Train,
+  [WagonEventType.TrainDisbanded]: WagonEventCategory.Train,
+  [WagonEventType.PinnedToSchedule]: WagonEventCategory.Schedule,
+  [WagonEventType.UnpinnedFromSchedule]: WagonEventCategory.Schedule,
+  [WagonEventType.Dispatched]: WagonEventCategory.Schedule,
+  [WagonEventType.ReleasedFromSchedule]: WagonEventCategory.Schedule,
+  [WagonEventType.StatusChanged]: WagonEventCategory.Status,
+  [WagonEventType.CargoLoaded]: WagonEventCategory.Cargo,
+  [WagonEventType.CargoUnloaded]: WagonEventCategory.Cargo,
+  [WagonEventType.BookingUnassigned]: WagonEventCategory.Cargo,
+  [WagonEventType.BookingCancelled]: WagonEventCategory.Cargo,
+  [WagonEventType.LoadMovedIn]: WagonEventCategory.Cargo,
+  [WagonEventType.LoadMovedOut]: WagonEventCategory.Cargo,
+  [WagonEventType.ContainerPlaced]: WagonEventCategory.Cargo,
+  [WagonEventType.ContainerRemoved]: WagonEventCategory.Cargo,
+};
+
+/** One row of a wagon's history as served by `GET /wagons/:id/history` (labels resolved). */
+export interface WagonHistoryEvent {
+  id: string;
+  wagonId: string;
+  wagonNumber: string | null;
+  type: WagonEventType;
+  category: WagonEventCategory;
+  occurredAt: string;
+  actorUserId: string | null;
+  actorName: string | null;
+  fromYardId: string | null;
+  fromYardLabel: string | null;
+  toYardId: string | null;
+  toYardLabel: string | null;
+  trainId: string | null;
+  trainCode: string | null;
+  trainScheduleId: string | null;
+  scheduleLabel: string | null;
+  bookingId: string | null;
+  bookingReference: string | null;
+  fromValue: string | null;
+  toValue: string | null;
+  reason: string | null;
+  metadata: Record<string, unknown> | null;
+}
+
+/** Keyset page of a wagon's history, newest first. `nextCursor` is null on the last page. */
+export interface WagonHistoryPage {
+  items: WagonHistoryEvent[];
+  nextCursor: string | null;
+}
+
 /**
  * Lifecycle of a two-person wagon-transfer request. A requester asks for N
  * wagons of a type to move from one yard to another (count only, no specific
@@ -648,6 +765,25 @@ export interface ICustomerTruckContainer {
   containerNumber: string;
 }
 
+/**
+ * The truck-type vocabulary a customer picks from when self-hauling. The API
+ * validates against this exact list (`@IsIn`), the portal's dropdown renders it,
+ * and the bulk-upload template documents it — all three read this constant so a
+ * value the customer can type can never be one the API rejects.
+ */
+export const CUSTOMER_TRUCK_TYPES = [
+  "Flatbed",
+  "Container Chassis",
+  "Lowboy",
+  "Box Truck",
+  "Tipper",
+] as const;
+
+export type CustomerTruckType = (typeof CUSTOMER_TRUCK_TYPES)[number];
+
+/** ISO 6346 container number: four letters then seven digits, e.g. ABCD1234567. */
+export const ISO_CONTAINER_NUMBER = /^[A-Z]{4}\d{7}$/;
+
 /** A customer self-haul truck on a booking, carrying 1–2 containers. */
 export interface ICustomerTruck {
   id: string;
@@ -659,6 +795,10 @@ export interface ICustomerTruck {
   arrivedAt?: string | null;
   departedAt?: string | null;
   containers?: ICustomerTruckContainer[];
+  /** Bulk: planned tonnage this truck hauls. `numeric` — serialises as a string. */
+  plannedTons?: number | string | null;
+  /** Bulk PER_ITEM: planned item/piece count on this truck. */
+  plannedQuantity?: number | null;
 }
 
 /** Payload to add a customer self-haul truck (1–2 container numbers). */
@@ -666,7 +806,12 @@ export interface AddCustomerTruckPayload {
   truckPlateNumber: string;
   driverName: string;
   truckType: string;
-  containerNumbers: string[];
+  /** Container bookings only — bulk trucks haul loose tonnage instead. */
+  containerNumbers?: string[];
+  /** Bulk: planned tonnage, drawn down against the booking's declared VGM. */
+  plannedTons?: number;
+  /** Bulk PER_ITEM: planned item/piece count. */
+  plannedQuantity?: number;
 }
 
 export interface IBooking extends BaseEntity {
@@ -1010,8 +1155,11 @@ export interface GlExchangeDocument {
   /** Booking or contract id the document is attached to. */
   entityId: string;
   title: string;
-  /** Desk that uploaded it. */
-  side: "ET" | "DJ";
+  /**
+   * Who uploaded it: either Global Logistics desk, or the transit agent
+   * assigned to the shipment. Both desks see all three.
+   */
+  side: "ET" | "DJ" | "TRANSIT";
   visibleToCustomer: boolean;
   uploadedById: string | null;
   uploadedByName: string | null;
@@ -1029,6 +1177,8 @@ export interface GlExchangeDocument {
 
 /** The clearance view for a booking, driving both portals' clearance UI. */
 export interface ClearanceView {
+  /** When the booking was created — the import DO clock starts here. */
+  bookingCreatedAt?: string | null;
   status: string;
   includesCustoms: boolean;
   inputCode: string | null;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a89b5ee80..6e9da8bbc 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -481,6 +481,9 @@ importers:
       react-pdf-html:
         specifier: ^2.1.5
         version: 2.1.5(@react-pdf/renderer@4.5.1(react@19.2.6))(react@19.2.6)
+      react-phone-number-input:
+        specifier: ^3.4.17
+        version: 3.4.17(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       react-quill-new:
         specifier: ^3.8.3
         version: 3.8.3(quill-delta@5.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)