@fleetbase/fleetops-engine 0.6.66 → 0.6.67

package/server/tests/ProviderContractsTest.php

@@ -95,6 +95,7 @@ class FleetOpsProviderContractsAppFake
 class FleetOpsProviderContractsScheduledEventFake
 {
     public array $methods = [];
+    public int $expiresAt = 1440;
 
     public function __construct(public string $command)
     {
@@ -121,8 +122,9 @@ class FleetOpsProviderContractsScheduledEventFake
         return $this;
     }
 
-    public function withoutOverlapping(): self
+    public function withoutOverlapping($expiresAt = 1440): self
     {
+        $this->expiresAt = $expiresAt;
         $this->methods[] = ['withoutOverlapping'];
 
         return $this;
@@ -274,9 +276,12 @@ test('fleetops service provider executes package registration and boot wiring',
                 'fleetops:send-maintenance-reminders',
                 'fleetops:process-operational-alerts',
                 'fleetops:sync-telematics',
+                'fleetops:drain-telematic-inbox',
             ])
             ->and($provider->schedule?->commands['fleetops:dispatch-orders']->methods)->toContain(['everyMinute'], ['withoutOverlapping'], ['storeOutputInDb'])
             ->and($provider->schedule?->commands['fleetops:update-estimations']->methods)->toContain(['everyTenMinutes'], ['withoutOverlapping'])
+            ->and($provider->schedule?->commands['fleetops:sync-telematics']->expiresAt)->toBe(2)
+            ->and($provider->schedule?->commands['fleetops:drain-telematic-inbox']->expiresAt)->toBe(2)
             ->and($orchestrationRegistry->has('vroom'))->toBeTrue()
             ->and($orchestrationRegistry->has('greedy'))->toBeTrue()
             ->and($orchestrationRegistry->has('capacity'))->toBeTrue()
@@ -407,3 +412,47 @@ test('event service provider maps order geofence and schedule listeners', functi
         NotifyOrderEvent::class
     );
 });
+
+test('telemetry scheduler overlap leases expire after interruption without clearing unrelated locks', function () {
+    $originalNotifications = NotificationRegistry::$notifications;
+    $originalNotifiables   = NotificationRegistry::$notifiables;
+    Illuminate\Support\Carbon::setTestNow('2026-09-17 12:00:00 UTC');
+
+    try {
+        $provider = new FleetOpsProviderContractsProviderProbe(new FleetOpsProviderContractsAppFake());
+        $provider->boot();
+        $cache   = new Illuminate\Cache\Repository(new Illuminate\Cache\ArrayStore());
+        $factory = new class($cache) implements Illuminate\Contracts\Cache\Factory {
+            public function __construct(private $cache)
+            {
+            }
+
+            public function store($name = null)
+            {
+                return $this->cache;
+            }
+        };
+        $mutex  = new Illuminate\Console\Scheduling\CacheEventMutex($factory);
+        $events = [];
+        foreach (['fleetops:sync-telematics', 'fleetops:drain-telematic-inbox', 'fleetops:dispatch-orders'] as $command) {
+            $registered = $provider->schedule->commands[$command];
+            $event      = new Illuminate\Console\Scheduling\Event($mutex, $command);
+            $event->withoutOverlapping($registered->expiresAt);
+            expect($mutex->create($event))->toBeTrue();
+            $events[$command] = $event;
+        }
+
+        // Simulate process loss: do not invoke the normal scheduler finish/cleanup.
+        Illuminate\Support\Carbon::setTestNow('2026-09-17 12:01:59 UTC');
+        expect($mutex->exists($events['fleetops:sync-telematics']))->toBeTrue()
+            ->and($mutex->exists($events['fleetops:drain-telematic-inbox']))->toBeTrue();
+        Illuminate\Support\Carbon::setTestNow('2026-09-17 12:02:01 UTC');
+        expect($mutex->create($events['fleetops:sync-telematics']))->toBeTrue()
+            ->and($mutex->create($events['fleetops:drain-telematic-inbox']))->toBeTrue()
+            ->and($mutex->exists($events['fleetops:dispatch-orders']))->toBeTrue();
+    } finally {
+        NotificationRegistry::$notifications = $originalNotifications;
+        NotificationRegistry::$notifiables   = $originalNotifiables;
+        Illuminate\Support\Carbon::setTestNow();
+    }
+});

package/server/tests/Support/AfaqyTestCrypto.php

@@ -1,27 +1,10 @@
 <?php
 
-// Package fixtures use authenticated OpenSSL encryption at the Crypt boundary.
-// Production resolves Laravel's encrypter from the host application.
-function afaqyTestCrypto(): object
-{
-    return new class {
-        public function encryptString(string $value): string
-        {
-            $iv     = random_bytes(12);
-            $cipher = openssl_encrypt($value, 'aes-256-gcm', str_repeat('t', 32), OPENSSL_RAW_DATA, $iv, $tag);
-
-            return base64_encode($iv . $tag . $cipher);
-        }
+use Illuminate\Encryption\Encrypter;
 
-        public function decryptString(string $value): string
-        {
-            $bytes = base64_decode($value, true);
-            $plain = openssl_decrypt(substr($bytes, 28), 'aes-256-gcm', str_repeat('t', 32), OPENSSL_RAW_DATA, substr($bytes, 0, 12), substr($bytes, 12, 16));
-            if ($plain === false) {
-                throw new RuntimeException('Invalid encrypted fixture.');
-            }
-
-            return $plain;
-        }
-    };
+// Exercise the same authenticated payload format and exceptions as Laravel.
+// This key is synthetic and used only by isolated test fixtures.
+function afaqyTestCrypto(): Encrypter
+{
+    return new Encrypter(str_repeat('t', 32), 'aes-256-cbc');
 }

package/server/tests/SupportJobAndAiCoverageTest.php

@@ -22,9 +22,10 @@ use Illuminate\Validation\ValidationException;
 
 class FleetOpsSyncTelematicJobFake extends Telematic
 {
-    public bool $refreshed  = false;
-    public bool $saved      = false;
-    public int $saveCount   = 0;
+    public bool $refreshed    = false;
+    public bool $saved        = false;
+    public int $saveCount     = 0;
+    public array $savedStates = [];
 
     public function refresh()
     {
@@ -37,6 +38,7 @@ class FleetOpsSyncTelematicJobFake extends Telematic
     {
         $this->saved = true;
         $this->saveCount++;
+        $this->savedStates[] = ['status' => $this->status, 'meta' => $this->meta];
 
         return true;
     }
@@ -191,7 +193,8 @@ class FleetOpsTelematicSyncRegistryFake extends TelematicProviderRegistry
 
 class FleetOpsTelematicSyncServiceFake extends TelematicService
 {
-    public array $ingested = [];
+    public array $ingested        = [];
+    public ?Closure $beforeIngest = null;
 
     public function __construct(public array $results = [], public array $failFor = [])
     {
@@ -200,6 +203,9 @@ class FleetOpsTelematicSyncServiceFake extends TelematicService
     public function ingestDeviceSnapshot(Telematic $telematic, Fleetbase\FleetOps\Contracts\TelematicProviderInterface $provider, array $payload): array
     {
         $this->ingested[] = $payload;
+        if ($this->beforeIngest) {
+            ($this->beforeIngest)($telematic, $payload, count($this->ingested));
+        }
 
         if (in_array($payload['_id'] ?? $payload['id'] ?? null, $this->failFor, true)) {
             throw ValidationException::withMessages(['device_id' => ['missing provider identity']]);
@@ -610,7 +616,6 @@ test('sync telematic devices job handles paginated inventory enrichment skips an
             ->and($service->ingested)->toHaveCount(6)
             ->and($lock->releaseCount)->toBe(1)
             ->and($telematic->saved)->toBeTrue()
-            ->and($telematic->saveCount)->toBe(2)
             ->and($telematic->status)->toBe('active')
             ->and($telematic->meta)->toMatchArray([
                 'existing'                              => 'kept',
@@ -677,6 +682,98 @@ test('sync telematic devices job handles paginated inventory enrichment skips an
     }
 });
 
+test('manual sync persists fetched pages before ingestion and bounded applied checkpoints', function () {
+    Carbon::setTestNow('2026-07-25 12:00:00 UTC');
+    $originalCache = Cache::getFacadeRoot();
+
+    try {
+        $telematic = new FleetOpsSyncTelematicJobFake();
+        $telematic->setRawAttributes(['uuid' => 'progress-connection', 'provider' => 'safee', 'status' => 'synchronizing', 'meta' => ['last_sync_result' => 'queued', 'unrelated' => 'preserved']], true);
+        $devices  = array_map(fn ($number) => ['_id' => 'unit-' . $number, 'device_id' => 'unit-' . $number], range(1, 52));
+        $provider = new FleetOpsTelematicSyncProviderFake([
+            ['devices' => $devices, 'pagination' => ['allCount' => 52, 'filtersCount' => 52], 'has_more' => false],
+        ]);
+        $service               = new FleetOpsTelematicSyncServiceFake();
+        $observed              = [];
+        $service->beforeIngest = function ($connection, $payload, $number) use (&$observed) {
+            if (in_array($number, [1, 26, 51], true)) {
+                $observed[$number] = end($connection->savedStates);
+            }
+        };
+        $lock = new FleetOpsTelematicSyncLockFake(true);
+        Cache::swap(new FleetOpsTelematicSyncCacheFake($lock));
+
+        (new SyncTelematicDevicesJob($telematic, [], 'progress-job'))->handle(new FleetOpsTelematicSyncRegistryFake($provider), $service);
+
+        expect($observed[1]['status'])->toBe('synchronizing');
+        expect($observed[1]['meta'])->toMatchArray([
+            'last_sync_job_id'        => 'progress-job', 'last_sync_result' => 'running', 'last_sync_phase' => 'ingesting_inventory',
+            'last_sync_fetched_total' => 52, 'last_sync_inventory_total' => 52, 'last_sync_provider_total' => 52,
+            'last_sync_page_count'    => 1, 'last_sync_linked_total' => 0, 'last_sync_progress_at' => '2026-07-25 12:00:00',
+        ]);
+        expect($observed[26]['meta']['last_sync_linked_total'])->toBe(25)
+            ->and($observed[51]['meta']['last_sync_linked_total'])->toBe(50);
+        expect($telematic->meta)->toMatchArray(['last_sync_result' => 'success', 'last_sync_phase' => 'completed', 'last_sync_linked_total' => 52, 'unrelated' => 'preserved']);
+        expect($telematic->saveCount)->toBeLessThan(20);
+        expect($lock->releaseCount)->toBe(1);
+    } finally {
+        Cache::swap($originalCache);
+        Carbon::setTestNow();
+    }
+});
+
+test('manual sync checkpoints elapsed progress and retains partial counters when an item throws a PHP error', function () {
+    Carbon::setTestNow('2026-07-25 12:00:00 UTC');
+    $originalCache = Cache::getFacadeRoot();
+
+    try {
+        $telematic = new FleetOpsSyncTelematicJobFake();
+        $telematic->setRawAttributes(['uuid' => 'partial-connection', 'provider' => 'safee', 'status' => 'synchronizing', 'meta' => ['last_sync_result' => 'queued']], true);
+        $devices  = array_map(fn ($number) => ['_id' => 'unit-' . $number, 'device_id' => 'unit-' . $number], range(1, 3));
+        $provider = new FleetOpsTelematicSyncProviderFake([
+            ['devices' => $devices, 'pagination' => ['allCount' => 3], 'has_more' => false],
+        ]);
+        $service                 = new FleetOpsTelematicSyncServiceFake();
+        $checkpointBeforeFailure = null;
+        $service->beforeIngest   = function ($connection, $payload, $number) use (&$checkpointBeforeFailure) {
+            if ($number === 1) {
+                Carbon::setTestNow('2026-07-25 12:00:06 UTC');
+
+                return;
+            }
+            $checkpointBeforeFailure = end($connection->savedStates)['meta'];
+            throw new TypeError('Invalid normalized unit field');
+        };
+        $lock = new FleetOpsTelematicSyncLockFake(true);
+        Cache::swap(new FleetOpsTelematicSyncCacheFake($lock));
+        $job = new SyncTelematicDevicesJob($telematic, [], 'partial-job');
+
+        expect(fn () => $job->handle(new FleetOpsTelematicSyncRegistryFake($provider), $service))->toThrow(TypeError::class, 'Invalid normalized unit field');
+        expect($checkpointBeforeFailure)->toMatchArray([
+            'last_sync_result'        => 'running', 'last_sync_phase' => 'ingesting_inventory',
+            'last_sync_fetched_total' => 3, 'last_sync_linked_total' => 1, 'last_sync_inventory_linked_total' => 1,
+            'last_sync_page_count'    => 1, 'last_sync_progress_at' => '2026-07-25 12:00:06',
+        ]);
+        expect(end($telematic->savedStates)['meta'])->toMatchArray([
+            'last_sync_result'        => 'failed', 'last_sync_error_type' => 'TypeError',
+            'last_sync_fetched_total' => 3, 'last_sync_inventory_total' => 3,
+            'last_sync_linked_total'  => 1, 'last_sync_inventory_linked_total' => 1,
+            'last_sync_page_count'    => 1, 'last_sync_error' => 'Invalid normalized unit field',
+        ]);
+        expect($telematic->status)->toBe('error')->and($lock->releaseCount)->toBe(1);
+
+        // Queue failure callbacks receive persisted checkpoints, not the handler's local counters.
+        $job->failed(new TimeoutExceededException('Queue timeout'));
+        expect($telematic->meta)->toMatchArray([
+            'last_sync_result'        => 'failed', 'last_sync_failed_reason' => 'job_timeout',
+            'last_sync_fetched_total' => 3, 'last_sync_linked_total' => 1, 'last_sync_page_count' => 1,
+        ]);
+    } finally {
+        Cache::swap($originalCache);
+        Carbon::setTestNow();
+    }
+});
+
 test('sync telematics command filters pollable providers and exits cleanly without work', function () {
     $registry = new TelematicProviderRegistry();
     $registry->register(new TelematicProviderDescriptor([

package/server/tests/TelematicsHardeningTest.php

@@ -1065,9 +1065,9 @@ test('safee endpoint helpers account for identities enrichment and failures', fu
         ]);
 
     $provider->queuePostResponse('/api/v2/vehicle/last-state', [
+        'code'   => 0,
         'result' => [
             ['vehicle' => ['id' => 105], 'status' => 'online'],
-            'ignored',
             ['id' => 106, 'status' => 'offline'],
         ],
     ]);
@@ -1078,15 +1078,13 @@ test('safee endpoint helpers account for identities enrichment and failures', fu
     expect($lastStates['105']['status'])->toBe('online')
         ->and($lastStates['106']['status'])->toBe('offline');
 
+    // Live polling must not report malformed, unrequested or failed batches as an empty fleet.
+    $provider->queuePostResponse('/api/v2/vehicle/last-state', ['code' => 0, 'result' => [['id' => 105], 'ignored']]);
+    expect(fn () => $provider->fetchLastStatesByVehicleForTest([105], $stats))->toThrow(Fleetbase\FleetOps\Exceptions\TelematicProviderException::class, 'invalid list record');
+    $provider->queuePostResponse('/api/v2/vehicle/last-state', ['code' => 0, 'result' => [['id' => 999]]]);
+    expect(fn () => $provider->fetchLastStatesByVehicleForTest([105], $stats))->toThrow(Fleetbase\FleetOps\Exceptions\TelematicProviderException::class, 'unrequested');
     $provider->queuePostException('/api/v2/vehicle/last-state', new RuntimeException('token=abc123 password=secret failed'));
-    $failedStats = ['failures' => []];
-
-    expect($provider->fetchLastStatesByVehicleForTest([107], $failedStats))->toBe([])
-        ->and($failedStats['failures'][0])->toMatchArray([
-            'endpoint'   => '/api/v2/vehicle/last-state',
-            'vehicle_id' => null,
-            'message'    => 'token=[redacted] password=[redacted] failed',
-        ]);
+    expect(fn () => $provider->fetchLastStatesByVehicleForTest([107], $stats))->toThrow(RuntimeException::class);
 
     $provider->queuePostResponse('/api/v2/vehicle/positions', [
         'result' => [
@@ -1152,16 +1150,23 @@ test('safee endpoint helpers account for identities enrichment and failures', fu
 test('safee normalization helpers cover status position sensor and timestamp variants', function () {
     $provider = new FleetOpsSafeeProviderProbe();
 
+    // Enrichment only fills gaps unless its source timestamp is strictly newer than the live state.
     expect($provider->currentTelemetryPayloadForTest([
         '_safee' => [
             'current_state' => ['status' => 'offline', 'speed' => 10],
             'current_info'  => ['speed' => 12, 'odometer' => 500],
         ],
     ]))->toBe([
-        'status'   => 'offline',
-        'speed'    => 12,
+        'speed'    => 10,
         'odometer' => 500,
+        'status'   => 'offline',
     ])
+        ->and($provider->currentTelemetryPayloadForTest([
+            '_safee' => [
+                'current_state' => ['date' => 1782206100, 'speed' => 10],
+                'current_info'  => ['date' => 1782206140, 'speed' => 12],
+            ],
+        ]))->toBe(['date' => 1782206140, 'speed' => 12])
         ->and($provider->currentTelemetryPayloadForTest(['_safee' => ['current_info' => ['speed' => 7]]]))->toBe(['speed' => 7])
         ->and($provider->currentTelemetryPayloadForTest(['_safee' => ['current_state' => ['speed' => 6]]]))->toBe(['speed' => 6])
         ->and($provider->currentTelemetryPayloadForTest(['_safee' => []]))->toBeNull()
@@ -1172,7 +1177,7 @@ test('safee normalization helpers cover status position sensor and timestamp var
         ->and($provider->resolveVehicleNameForTest([], [], 108))->toBe('Safee Vehicle 108')
         ->and($provider->resolveVehicleNameForTest([], [], null))->toBe('Unknown Safee Vehicle')
         ->and($provider->sanitizeProviderMessageForTest('access_token=abc&password=secret client_secret=top'))->toBe('access_token=[redacted]&password=[redacted] client_secret=[redacted]')
-        ->and($provider->extractPositionForTest(['loc' => ['coordinates' => [55.2, 25.2]]]))->toBe(['lat' => 25.2, 'lng' => 55.2])
+        ->and($provider->extractPositionForTest(['loc' => ['coordinates' => [55.2, 25.2]]]))->toBe(['lat' => 25.2, 'lng' => 55.2, 'alt' => null])
         ->and($provider->parseTimestampForTest(null))->toBeNull()
         ->and($provider->parseTimestampForTest(1782206140500))->toBe(Carbon::createFromTimestamp(1782206140.5)->toDateTimeString())
         ->and($provider->parseTimestampForTest('2026-06-23T09:15:40Z'))->toBe('2026-06-23 09:15:40')
@@ -1396,7 +1401,7 @@ test('afaqy sync stores compact device diagnostics and paginates complete units
         ->toContain('= 15;')
         ->toContain('protected int $connectionTestTimeout')
         ->toContain('= 30;')
-        ->toContain('protected int $connectionTestConnectTimeout = 10')
+        ->toContain('protected int $connectionTestConnectTimeout  = 10')
         ->toContain('->timeout($timeout)')
         ->toContain('->connectTimeout($connectTimeout)')
         ->toContain('ConnectionException')

package/server/tests/Unit/Console/SyncTelematicsCommandTest.php

@@ -1,5 +1,7 @@
 <?php
 
+require_once __DIR__ . '/../../Support/ExampleTelemetryProvider.php';
+
 use Fleetbase\FleetOps\Console\Commands\SyncTelematics;
 use Fleetbase\FleetOps\Contracts\TelematicProviderDescriptor;
 use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
@@ -134,3 +136,141 @@ test('sync telematics filters providers by request and webhook flags', function
     expect($command->handle($registry))->toBe(0)
         ->and($command->messages)->toContain(['info', 'No pollable telematics providers found.']);
 });
+
+test('sync telematics command releases its bounded lock and recovers an interrupted lease', function () {
+    fleetopsSyncTelematicsBoot();
+    $originalCache = Illuminate\Support\Facades\Cache::getFacadeRoot();
+    Illuminate\Support\Carbon::setTestNow('2026-09-17 12:00:00 UTC');
+
+    try {
+        $store = new class extends Illuminate\Cache\ArrayStore {
+            public array $requestedLocks = [];
+
+            public function lock($name, $seconds = 0, $owner = null)
+            {
+                $this->requestedLocks[] = [$name, $seconds];
+
+                return parent::lock($name, $seconds, $owner);
+            }
+        };
+        Illuminate\Support\Facades\Cache::swap(new Illuminate\Cache\Repository($store));
+        $command                     = new FleetOpsSyncTelematicsProbe();
+        $command->options['no-lock'] = false;
+        $registry                    = fleetopsSyncTelematicsRegistry([]);
+        expect($command->handle($registry))->toBe(0);
+        expect($store->requestedLocks[0])->toBe(['fleetops:sync-telematics', 120]);
+        expect($store->locks)->toBe([]);
+
+        // Leave a lease behind as if the previous command process had stopped.
+        [$key, $ttl] = $store->requestedLocks[0];
+        expect($store->lock($key, $ttl)->get())->toBeTrue();
+        $command->messages = [];
+        Illuminate\Support\Carbon::setTestNow('2026-09-17 12:01:59 UTC');
+        expect($command->handle($registry))->toBe(0)
+            ->and($command->messages)->toContain(['warn', 'Another telematics sync run appears to be in progress.']);
+
+        $command->messages = [];
+        Illuminate\Support\Carbon::setTestNow('2026-09-17 12:02:01 UTC');
+        expect($command->handle($registry))->toBe(0)
+            ->and($command->messages)->toContain(['info', 'No pollable telematics providers found.']);
+        expect($store->locks)->toBe([]);
+    } finally {
+        Illuminate\Support\Facades\Cache::swap($originalCache);
+        Illuminate\Support\Carbon::setTestNow();
+    }
+});
+
+test('sync telematics reports successful durable and legacy dispatches without counting coalesced polls', function () {
+    $connection = fleetopsSyncTelematicsBoot();
+    $connection->table('telematics')->insert([
+        ['uuid' => 'durable-connection', 'company_uuid' => 'company-1', 'provider' => 'example', 'status' => 'active'],
+        ['uuid' => 'legacy-connection', 'company_uuid' => 'company-1', 'provider' => 'traccar', 'status' => 'active'],
+    ]);
+    $registry = fleetopsSyncTelematicsRegistry([
+        ['key' => 'example', 'label' => 'Example', 'supports_discovery' => true, 'driver_class' => ExampleTelemetryProvider::class, 'metadata' => ['telemetry' => ['durable_ingestion' => true]]],
+        ['key' => 'traccar', 'label' => 'Traccar', 'supports_discovery' => true],
+    ]);
+    $originalCache       = Illuminate\Support\Facades\Cache::getFacadeRoot();
+    $originalCacheConfig = config('cache', []);
+    $dispatcherContract  = Illuminate\Contracts\Bus\Dispatcher::class;
+    $originalDispatcher  = app()->bound($dispatcherContract) ? app($dispatcherContract) : null;
+
+    try {
+        config(['cache.default' => 'array', 'cache.stores.array' => ['driver' => 'array']]);
+        Illuminate\Support\Facades\Cache::swap(new Illuminate\Cache\CacheManager(app()));
+        $dispatcher = new class(app()) extends Illuminate\Bus\Dispatcher {
+            public array $jobs = [];
+
+            public function dispatch($command)
+            {
+                $this->jobs[] = $command;
+
+                return $command;
+            }
+        };
+        app()->instance($dispatcherContract, $dispatcher);
+        $command = new FleetOpsSyncTelematicsProbe();
+
+        expect($command->handle($registry))->toBe(0)
+            ->and($command->messages)->toContain(['info', 'Queued 2 telematics sync job(s).']);
+        expect($dispatcher->jobs)->toHaveCount(1)
+            ->and($dispatcher->jobs[0])->toBeInstanceOf(Fleetbase\FleetOps\Jobs\PollTelematicTelemetry::class)
+            ->and(DispatchRecorder::$dispatched)->toHaveCount(1);
+
+        // The real unique lock suppresses a second durable poll; legacy dispatch remains eligible.
+        $command->messages = [];
+        expect($command->handle($registry))->toBe(0)
+            ->and($command->messages)->toContain(['info', 'Queued 1 telematics sync job(s).']);
+        expect($dispatcher->jobs)->toHaveCount(1)
+            ->and(DispatchRecorder::$dispatched)->toHaveCount(2);
+
+        $command->messages            = [];
+        $command->options['provider'] = ['example'];
+        expect($command->handle($registry))->toBe(0)
+            ->and($command->messages)->toContain(['info', 'Queued 0 telematics sync job(s).']);
+        expect($dispatcher->jobs)->toHaveCount(1);
+    } finally {
+        Illuminate\Support\Facades\Cache::swap($originalCache);
+        config(['cache' => $originalCacheConfig]);
+        if ($originalDispatcher) {
+            app()->instance($dispatcherContract, $originalDispatcher);
+        } else {
+            app()->offsetUnset($dispatcherContract);
+        }
+    }
+});
+
+class PausedBatchTelemetryProvider extends ExampleTelemetryProvider
+{
+    public function telemetryOptions(): array
+    {
+        return ['polling_enabled' => false, 'manual_batch_sync' => true];
+    }
+}
+
+class PausedReconciledTelemetryProvider extends ExampleTelemetryProvider
+{
+    public function telemetryOptions(): array
+    {
+        return ['polling_enabled' => false];
+    }
+}
+
+test('sync telematics pauses batch-only providers instead of queueing legacy syncs that would fail', function () {
+    $connection = fleetopsSyncTelematicsBoot();
+    $connection->table('telematics')->insert([
+        ['uuid' => 'batch-connection', 'company_uuid' => 'company-1', 'provider' => 'batch', 'status' => 'error'],
+        ['uuid' => 'reconciled-connection', 'company_uuid' => 'company-1', 'provider' => 'reconciled', 'status' => 'active'],
+    ]);
+    $registry = fleetopsSyncTelematicsRegistry([
+        ['key' => 'batch', 'label' => 'Batch', 'supports_discovery' => true, 'driver_class' => PausedBatchTelemetryProvider::class, 'metadata' => ['telemetry' => ['durable_ingestion' => true]]],
+        ['key' => 'reconciled', 'label' => 'Reconciled', 'supports_discovery' => true, 'driver_class' => PausedReconciledTelemetryProvider::class, 'metadata' => ['telemetry' => ['durable_ingestion' => true]]],
+    ]);
+    $command = new FleetOpsSyncTelematicsProbe();
+
+    // Providers without batch sync keep their existing legacy reconciliation while polling is paused.
+    expect($command->handle($registry))->toBe(0)
+        ->and(DispatchRecorder::$dispatched)->toHaveCount(1)
+        ->and(DispatchRecorder::$dispatched[0]['arguments'][0]->uuid)->toBe('reconciled-connection')
+        ->and($command->messages)->toContain(['info', 'Queued 1 telematics sync job(s).']);
+});

package/server/tests/Unit/Support/Telematics/Providers/AfaqyProviderTransportTest.php

@@ -22,6 +22,13 @@ use Illuminate\Support\Facades\Http;
  */
 class FleetOpsAfaqyTransportProbe extends AfaqyProvider
 {
+    public ?float $clock = null;
+
+    protected function requestTime(): float
+    {
+        return $this->clock ?? parent::requestTime();
+    }
+
     public function setCredentialsForTest(array $credentials): void
     {
         $this->credentials = $credentials;
@@ -144,3 +151,128 @@ test('transport errors and helper extractors resolve metadata', function () {
     expect($probe->callHelper('resolveSensorName', ['param' => 'fuel'], 'fallback'))->toBe('fuel')
         ->and($probe->callHelper('resolveSensorName', [], 'fallback'))->toBe('fallback');
 });
+
+test('unreadable cached tokens are evicted even when reauthentication fails', function () {
+    fleetopsAfaqyTransportBoot();
+    $key = 'afaqy:token:' . hash('sha256', 'https://api.afaqy.sa|user') . ':' . hash('sha256', 'secret');
+    Illuminate\Support\Facades\Cache::put($key, 'not-an-encrypted-payload', 3600);
+    Http::preventStrayRequests();
+    Http::fake(['*/auth/login' => Http::response(['message' => 'denied'], 401)]);
+    $connection              = new Fleetbase\FleetOps\Models\Telematic();
+    $connection->credentials = ['username' => 'user', 'password' => 'secret'];
+    expect(fn () => (new AfaqyProvider())->connect($connection))->toThrow(TelematicProviderException::class, 'authentication failed with status 401');
+    expect(Illuminate\Support\Facades\Cache::has($key))->toBeFalse();
+    expect(Illuminate\Support\Facades\Cache::get('afaqy:rate:' . hash('sha256', 'https://api.afaqy.sa|user')))->toHaveCount(1);
+    Http::assertSentCount(1);
+});
+
+test('rejected token refresh and retry share the original HTTP time budget', function () {
+    fleetopsAfaqyTransportBoot();
+    $probe        = fleetopsAfaqyTransportProbe(['token' => 'stale-token', 'username' => 'user', 'password' => 'secret']);
+    $probe->clock = 100;
+    $timeouts     = [];
+    Http::fake(function ($request, $options) use ($probe, &$timeouts) {
+        $timeouts[] = [$options['timeout'], $options['connect_timeout']];
+        if (count($timeouts) === 1) {
+            $probe->clock += 20;
+
+            return Http::response(['message' => 'expired'], 401);
+        }
+        if (str_ends_with($request->url(), '/auth/login')) {
+            $probe->clock += 10;
+
+            return Http::response(['data' => ['token' => 'refreshed-token']], 200);
+        }
+
+        return Http::response(['data' => ['ok' => true]], 200);
+    });
+
+    expect($probe->callHelper('afaqyPost', '/units/list', [], false, 45, 5))->toBe(['data' => ['ok' => true]])
+        ->and($timeouts)->toBe([[45, 5], [25, 15], [15, 5]]);
+    Http::assertSentCount(3);
+});
+
+test('exhausted refresh budget prevents a retry and is reset for the next request', function () {
+    fleetopsAfaqyTransportBoot();
+    $probe        = fleetopsAfaqyTransportProbe(['token' => 'stale-token', 'username' => 'user', 'password' => 'secret']);
+    $probe->clock = 100;
+    $timeouts     = [];
+    Http::fake(function ($request, $options) use ($probe, &$timeouts) {
+        $timeouts[] = $options['timeout'];
+        if (count($timeouts) === 1) {
+            $probe->clock += 20;
+
+            return Http::response(['message' => 'expired'], 401);
+        }
+        if (str_ends_with($request->url(), '/auth/login')) {
+            $probe->clock += 24.5;
+
+            return Http::response(['data' => ['token' => 'refreshed-token']], 200);
+        }
+
+        return Http::response(['data' => []], 200);
+    });
+
+    expect(fn () => $probe->callHelper('afaqyPost', '/units/list', [], false, 45, 5))
+        ->toThrow(TelematicProviderException::class, 'time budget exhausted');
+    Http::assertSentCount(2);
+    expect($timeouts)->toBe([45, 25]);
+
+    $probe->clock += 60;
+    expect($probe->callHelper('afaqyPost', '/units/list', [], false, 45, 5))->toBe(['data' => []]);
+    expect($timeouts)->toBe([45, 25, 45]);
+    Http::assertSentCount(3);
+});
+
+test('token lock wait consumes the refresh budget before authentication starts', function () {
+    fleetopsAfaqyTransportBoot();
+    $probe         = fleetopsAfaqyTransportProbe(['token' => 'stale-token', 'username' => 'user', 'password' => 'secret']);
+    $probe->clock  = 100;
+    $originalCache = Illuminate\Support\Facades\Cache::getFacadeRoot();
+    $cache         = new class($originalCache, $probe) {
+        public array $waits = [];
+
+        public function __construct(public $repository, public FleetOpsAfaqyTransportProbe $probe)
+        {
+        }
+
+        public function lock(string $key, int $seconds)
+        {
+            return new class($this, $key) {
+                public function __construct(public $cache, public string $key)
+                {
+                }
+
+                public function block($seconds, $callback)
+                {
+                    $this->cache->waits[] = $seconds;
+                    if (str_starts_with($this->key, 'afaqy:token:')) {
+                        $this->cache->probe->clock += 1.2;
+                    }
+
+                    return $callback();
+                }
+            };
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->repository->{$method}(...$arguments);
+        }
+    };
+    Illuminate\Support\Facades\Cache::swap($cache);
+    try {
+        Http::fake(function () use ($probe) {
+            $probe->clock += 43;
+
+            return Http::response(['message' => 'expired'], 401);
+        });
+
+        expect(fn () => $probe->callHelper('afaqyPost', '/units/list', [], false, 45, 5))
+            ->toThrow(TelematicProviderException::class, 'time budget exhausted');
+        expect($cache->waits)->toBe([2, 2]);
+        Http::assertSentCount(1);
+    } finally {
+        Illuminate\Support\Facades\Cache::swap($originalCache);
+    }
+});

package/server/tests/Unit/Support/Telematics/Providers/ProviderTransportSeamsTest.php

@@ -129,5 +129,5 @@ test('safee authentication rejects a successful response that carries no token',
     ]);
 
     expect(fn () => $probe->callHelper('authenticate'))
-        ->toThrow(RuntimeException::class, 'Safee authentication did not return an access token.');
+        ->toThrow(Fleetbase\FleetOps\Exceptions\TelematicProviderException::class, 'Safee authentication did not return an access token.');
 });