SmartSessionController.cpp

// SPDX-License-Identifier: GPL-3.0-or-later

#include "SmartSessionController.hpp"

#include "DeviceController.hpp"
#include "FirmwareManager.hpp"
#include "SclProfileModel.hpp"

#include <QVariantMap>
#include <QStringList>

#include <algorithm>
#include <limits>
#include <utility>

#ifndef ARSTACK_STUDIO_VERSION
#define ARSTACK_STUDIO_VERSION "0.1.0"
#endif

namespace {
constexpr int kMaxUpdateReconnectAttempts = 6;
}

QString SmartSessionController::chooseRecoveryPort(
    const QString& recommendedPort,
    const QStringList& visiblePorts) {
    const QString recommended = recommendedPort.trimmed();
    if (!recommended.isEmpty() && visiblePorts.contains(recommended, Qt::CaseInsensitive)) {
        return recommended;
    }
    if (visiblePorts.size() != 1) return {};
    return visiblePorts.front().trimmed();
}

quint64 SmartSessionController::nextSessionGeneration(const quint64 current) noexcept {
    if (current == std::numeric_limits<quint64>::max()) return 1;
    return current + 1;
}

bool SmartSessionController::profileGenerationAdvanced(
    const QString& baseline,
    const QString& observed) noexcept {
    bool observedOk = false;
    const qulonglong observedGeneration = observed.trimmed().toULongLong(&observedOk);
    if (!observedOk) return false;

    bool baselineOk = false;
    const qulonglong baselineGeneration = baseline.trimmed().toULongLong(&baselineOk);
    if (!baselineOk) return true;
    // Within one verified boot epoch, a committed profile generation must
    // strictly advance. Rollback is stale evidence, not a successful sync.
    return observedGeneration > baselineGeneration;
}

SmartSessionController::SmartSessionController(QObject* parent) : QObject(parent) {
    discoveryTimer_.setInterval(2500);
    discoveryTimer_.setSingleShot(false);
    connect(&discoveryTimer_, &QTimer::timeout, this, [this] {
        if (!started_ || device_ == nullptr || updateRequested_ || blankBoardDetected_ || setupError_) return;
        if (firmware_ != nullptr && firmware_->busy()) return;
        // A slow serial reply is NOT evidence that firmware is absent.
        // Retry semantic discovery after a bounded 5s cool-down; do not
        // endlessly hold the single COM port or auto-flash a live board.
        if (device_->identificationState() == DeviceController::IdentificationState::Unidentified) {
            if (manualRecoveryArmed_) return;
            ++unidentifiedDiscoveryTicks_;
            if (unidentifiedDiscoveryTicks_ < 2) return;
        }
        if (!device_->deviceVerified() && !device_->discovering() && !device_->connected()) {
            unidentifiedDiscoveryTicks_ = 0;
            static_cast<void>(startDeviceDiscovery());
        }
    });

    prepareTimer_.setInterval(650);
    prepareTimer_.setSingleShot(true);
    connect(&prepareTimer_, &QTimer::timeout, this, &SmartSessionController::reconcile);

    profileSyncTimer_.setInterval(profileSyncTimeoutMs());
    profileSyncTimer_.setSingleShot(true);
    connect(&profileSyncTimer_, &QTimer::timeout, this, [this] {
        if (profileSyncStage_ != ProfileSyncStage::deploying) return;
        const QString progress = device_ == nullptr ? QStringLiteral("device unavailable")
            : device_->profileDeploymentProgressSummary();
        handleProfileSyncAttemptFailure(QStringLiteral(
            "Firmware profile acknowledgement timed out (%1).").arg(progress));
        reconcile();
    });

    // Retry timer never grants START; it only re-enters the verified
    // profile handshake with bounded exponential-like backoff.
    profileRetryTimer_.setSingleShot(true);
    connect(&profileRetryTimer_, &QTimer::timeout, this, &SmartSessionController::reconcile);

    // ACK progress alone must never keep PREPARING forever.
    profileSyncTotalTimer_.setInterval(profileSyncHardDeadlineMs());
    profileSyncTotalTimer_.setSingleShot(true);
    connect(&profileSyncTotalTimer_, &QTimer::timeout, this, [this] {
        if (profileSyncStage_ != ProfileSyncStage::deploying) return;
        handleProfileSyncAttemptFailure(QStringLiteral(
            "Profile preparation exceeded the absolute %1 ms safety deadline (%2).")
            .arg(profileSyncHardDeadlineMs())
            .arg(device_ == nullptr ? QStringLiteral("device missing")
                                  : device_->profileDeploymentProgressSummary()));
        reconcile();
    });

    reconnectTimer_.setInterval(3000);
    reconnectTimer_.setSingleShot(true);
    connect(&reconnectTimer_, &QTimer::timeout, this, [this] {
        if (device_ == nullptr || !updateRequested_ || updateStage_ != UpdateStage::reconnecting) return;
        if (device_->deviceVerified()) {
            reconcile();
            return;
        }
        if (device_->discovering() || device_->connected()) {
            reconnectTimer_.start();
            return;
        }
        if (updateReconnectAttempts_ >= kMaxUpdateReconnectAttempts) {
            latchFirmwareFailure(QStringLiteral(
                "Firmware was written, but Studio could not reconnect and verify the ESP32-P4. Reconnect USB and retry firmware setup."));
            emit firmwareUpdateFinished(false);
            reconcile();
            return;
        }
        ++updateReconnectAttempts_;
        static_cast<void>(startDeviceDiscovery());
        reconnectTimer_.start();
        reconcile();
    });
}

SmartSessionController::~SmartSessionController() {
    shutdown();
}

void SmartSessionController::shutdown() {
    if (shuttingDown_) return;
    shuttingDown_ = true;
    started_ = false;
    discoveryTimer_.stop();
    prepareTimer_.stop();
    reconnectTimer_.stop();
    profileSyncTimer_.stop();
    profileRetryTimer_.stop();
    profileSyncTotalTimer_.stop();
    firmwareHandoffWatchdog_.shutdown();
    deviceRecoveryMonitor_.shutdown();
    updateRequested_ = false;
    pendingReleaseGeneration_ = 0;
    profileSyncStage_ = ProfileSyncStage::idle;
    if (device_ != nullptr) QObject::disconnect(device_, nullptr, this, nullptr);
    if (profiles_ != nullptr) QObject::disconnect(profiles_, nullptr, this, nullptr);
    if (firmware_ != nullptr) QObject::disconnect(firmware_, nullptr, this, nullptr);
    device_ = nullptr;
    profiles_ = nullptr;
    firmware_ = nullptr;
}

QObject* SmartSessionController::device() const noexcept { return device_; }
QObject* SmartSessionController::profiles() const noexcept { return profiles_; }
QObject* SmartSessionController::firmware() const noexcept { return firmware_; }
QString SmartSessionController::state() const { return state_; }
QString SmartSessionController::statusText() const { return statusText_; }
bool SmartSessionController::startReady() const noexcept { return startReady_; }
bool SmartSessionController::canDeployProfile() const noexcept {
    if (!deviceControlAvailable() || profiles_ == nullptr || device_->running() || device_->profileDeploying()) {
        return false;
    }
    const QVariantMap profile = profiles_->selectedProfile();
    return profile.value(QStringLiteral("compatibilityClass")).toString() == QStringLiteral("A") &&
        profile.value(QStringLiteral("deviceSupport")).toString() == QStringLiteral("ready");
}
bool SmartSessionController::liveControlReady() const noexcept {
    return deviceControlAvailable() && !device_->profileDeploying() &&
        (startReady_ || device_->running());
}
bool SmartSessionController::engineeringEditable() const noexcept {
    return device_ != nullptr && !device_->running() && !updateRequested_ &&
        portOwner_ != PortOwner::firmwareTool && (firmware_ == nullptr || !firmware_->busy());
}
bool SmartSessionController::firmwareUpdateRequired() const noexcept { return firmwareUpdateRequired_; }
bool SmartSessionController::firmwareUpdateAvailable() const noexcept {
    return device_ != nullptr && firmware_ != nullptr && device_->deviceVerified() &&
        firmware_->bundleReady() && !firmware_->busy() && !updateRequested_ &&
        firmwareIsCompatible() && !firmwareIsCurrent();
}
bool SmartSessionController::firmwareUpdateCanCancel() const noexcept {
    return updateRequested_ && updateWasOptional_ && updateStage_ == UpdateStage::waitingForBootloader &&
        firmware_ != nullptr && !firmware_->busy();
}
bool SmartSessionController::firmwareReinstallAvailable() const noexcept {
    return device_ != nullptr && firmware_ != nullptr && device_->deviceVerified() &&
        firmware_->bundleReady() && !firmware_->busy() && !updateRequested_ && firmwareIsCurrent();
}
bool SmartSessionController::firmwareInstallRequired() const noexcept {
    return blankBoardDetected_ && !updateRequested_;
}
bool SmartSessionController::firmwareRetryAvailable() const noexcept {
    return setupError_ && !updatePort_.trimmed().isEmpty() && firmware_ != nullptr && !firmware_->busy();
}
bool SmartSessionController::profileSyncRetryAvailable() const noexcept {
    return profileSyncStage_ == ProfileSyncStage::failed && device_ != nullptr &&
        device_->deviceVerified() && !device_->running() && portOwner_ == PortOwner::deviceSession;
}
bool SmartSessionController::updatingFirmware() const noexcept {
    return updateStage_ == UpdateStage::stopping || updateStage_ == UpdateStage::releasingPort ||
        updateStage_ == UpdateStage::probing || updateStage_ == UpdateStage::flashing ||
        updateStage_ == UpdateStage::reconnecting;
}
bool SmartSessionController::updateNeedsBootloaderHelp() const noexcept {
    return updateStage_ == UpdateStage::waitingForBootloader;
}
int SmartSessionController::firmwareProgress() const noexcept {
    if (firmware_ == nullptr || updateStage_ != UpdateStage::flashing) return -1;
    return firmware_->flashProgress();
}
QString SmartSessionController::updateStatus() const {
    if (firmware_ == nullptr) return {};
    switch (updateStage_) {
    case UpdateStage::stopping:
        return QStringLiteral("Stopping SMV output safely…");
    case UpdateStage::releasingPort:
        return QStringLiteral("Releasing the device serial session before firmware access…");
    case UpdateStage::probing:
    case UpdateStage::flashing:
        return firmware_->status();
    case UpdateStage::reconnecting:
        return QStringLiteral("Firmware written. Reconnecting and verifying the board… %1/%2")
            .arg(std::min(updateReconnectAttempts_ + 1, kMaxUpdateReconnectAttempts))
            .arg(kMaxUpdateReconnectAttempts);
    case UpdateStage::waitingForBootloader:
        return QStringLiteral("Put the board in Download mode: hold BOOT, press and release RESET, then release BOOT.");
    case UpdateStage::idle:
        return {};
    }
    return {};
}
QString SmartSessionController::firmwareSetupPort() const { return blankBoardPort_; }
QString SmartSessionController::expectedFirmwareVersion() const { return QStringLiteral(ARSTACK_STUDIO_VERSION); }
QString SmartSessionController::expectedFirmwareBuildId() const {
    return firmware_ != nullptr ? firmware_->firmwareBuildId() : QString{};
}
QString SmartSessionController::deviceFirmwareVersion() const { return deviceFirmwareVersion_; }
QString SmartSessionController::deviceFirmwareBuildId() const { return deviceFirmwareBuildId_; }

quint64 SmartSessionController::advanceSessionGeneration() {
    sessionGeneration_ = nextSessionGeneration(sessionGeneration_);
    if (device_ != nullptr) device_->setSessionGeneration(sessionGeneration_);
    if (firmware_ != nullptr) firmware_->setSessionGeneration(sessionGeneration_);
    emit stateChanged();
    return sessionGeneration_;
}

void SmartSessionController::setPortOwner(const PortOwner owner) {
    if (portOwner_ == owner) return;
    portOwner_ = owner;
    emit stateChanged();
}

bool SmartSessionController::startDeviceDiscovery() {
    if (device_ == nullptr || portOwner_ == PortOwner::firmwareTool ||
        device_->connected() || device_->discovering()) {
        return false;
    }
    manualRecoveryArmed_ = false;
    advanceSessionGeneration();
    setPortOwner(PortOwner::deviceSession);
    return device_->autoDetectAndConnect();
}

void SmartSessionController::setDevice(QObject* object) {
    auto* next = qobject_cast<DeviceController*>(object);
    if (device_ == next) return;
    if (device_ != nullptr) disconnect(device_, nullptr, this, nullptr);
    device_ = next;
    deviceFirmwareVersion_.clear();
    profileSyncBootId_.clear();
    resetProfileSync(true);
    clearBlankBoardContext();
    if (device_ != nullptr) {
        advanceSessionGeneration();
    }
    reconnectDeviceSignals();
    emit dependenciesChanged();
    reconcile();
}

void SmartSessionController::setProfiles(QObject* object) {
    auto* next = qobject_cast<SclProfileModel*>(object);
    if (profiles_ == next) return;
    if (profiles_ != nullptr) disconnect(profiles_, nullptr, this, nullptr);
    profiles_ = next;
    resetProfileSync(true);
    reconnectProfileSignals();
    emit dependenciesChanged();
    reconcile();
}

void SmartSessionController::setFirmware(QObject* object) {
    auto* next = qobject_cast<FirmwareManager*>(object);
    if (firmware_ == next) return;
    if (firmware_ != nullptr) disconnect(firmware_, nullptr, this, nullptr);
    firmware_ = next;
    if (firmware_ != nullptr) {
        if (sessionGeneration_ == 0) advanceSessionGeneration();
        else firmware_->setSessionGeneration(sessionGeneration_);
    }
    clearBlankBoardContext();
    reconnectFirmwareSignals();
    emit dependenciesChanged();
    reconcile();
}

void SmartSessionController::start() {
    if (started_ || shuttingDown_) return;
    started_ = true;
    if (profiles_ != nullptr) static_cast<void>(ensureDefaultProfile());
    discoveryTimer_.start();

    QTimer::singleShot(0, this, [this] {
        if (!started_ || device_ == nullptr || updateRequested_) return;
        if (!device_->deviceVerified() && !device_->discovering() && !device_->connected()) {
            static_cast<void>(startDeviceDiscovery());
        }
        refreshRecoveryOfferFromIdentity();
        reconcile();
    });
}

bool SmartSessionController::requestStart() {
    // Legacy callers must not bypass the fresh scenario snapshot supplied by the UI.
    // requestStartWithScenario remains the only guided START entry point.
    return false;
}

bool SmartSessionController::requestStartWithScenario(const QVariantMap& scenario) {
    if (!startReady_ || !deviceControlAvailable() || device_ == nullptr || device_->running()) return false;
    return device_->startWithScenario(scenario);
}

bool SmartSessionController::requestStop() {
    if (device_ == nullptr) return false;
    // STOP is a cancellation authority even before SV RUNNING telemetry: an
    // ACKed staging transaction may still be advancing toward START.
    if (!device_->running() && !device_->scenarioApplying()) return true;
    if (portOwner_ != PortOwner::deviceSession || updateRequested_) return false;
    return device_->stop();
}

bool SmartSessionController::requestConnect() {
    if (!started_ || device_ == nullptr || updateRequested_ ||
        portOwner_ == PortOwner::firmwareTool || device_->discovering()) {
        return false;
    }
    if (device_->deviceVerified()) return true;
    if (device_->connected()) return false;
    if (firmware_ != nullptr && firmware_->busy()) return false;

    clearBlankBoardContext();
    const bool accepted = startDeviceDiscovery();
    reconcile();
    return accepted;
}

void SmartSessionController::requestRefreshPorts() {
    if (device_ == nullptr || updateRequested_ || portOwner_ == PortOwner::firmwareTool ||
        (firmware_ != nullptr && firmware_->busy())) {
        return;
    }
    device_->refreshPorts();
}

bool SmartSessionController::requestConnectPort(const QString& portName) {
    const QString requested = portName.trimmed();
    if (!started_ || device_ == nullptr || requested.isEmpty() || updateRequested_ ||
        portOwner_ == PortOwner::firmwareTool || device_->connected() || device_->discovering() ||
        (firmware_ != nullptr && firmware_->busy())) {
        return false;
    }

    clearBlankBoardContext();
    manualRecoveryArmed_ = true;
    advanceSessionGeneration();
    setPortOwner(PortOwner::deviceSession);
    const bool accepted = device_->connectPort(requested);
    reconcile();
    return accepted;
}

bool SmartSessionController::requestDisconnect() {
    if (device_ == nullptr || updateRequested_ || portOwner_ != PortOwner::deviceSession) return false;
    if (!device_->connected()) return true;
    if (device_->running()) return false;
    device_->disconnectPort();
    return true;
}

bool SmartSessionController::requestProfileSync() {
    if (!canDeployProfile()) return false;
    resetProfileSync(true);
    QTimer::singleShot(0, this, &SmartSessionController::reconcile);
    return true;
}

bool SmartSessionController::requestSetFrequency(const double hz) {
    return liveControlReady() && device_ != nullptr && device_->setFrequency(hz);
}

bool SmartSessionController::requestSetSignal(
    const QString& signalId,
    const double magnitude,
    const double phaseDegrees,
    const quint32 quality,
    const double currentCountsPerAmp,
    const double voltageCountsPerVolt) {
    return liveControlReady() && device_ != nullptr &&
        device_->setSignal(
            signalId,
            magnitude,
            phaseDegrees,
            quality,
            currentCountsPerAmp,
            voltageCountsPerVolt);
}

bool SmartSessionController::requestSetQuality(const QString& signalId, const quint32 quality) {
    return liveControlReady() && device_ != nullptr && device_->setQuality(signalId, quality);
}

bool SmartSessionController::requestSetCtSaturation(
    const bool enabled,
    const double dcOffsetPercent,
    const double harmonicPercent,
    const int harmonicOrder,
    const double clipPercent) {
    return liveControlReady() && device_ != nullptr &&
        device_->setCtSaturation(
            enabled,
            dcOffsetPercent,
            harmonicPercent,
            harmonicOrder,
            clipPercent);
}

bool SmartSessionController::requestZero() {
    return liveControlReady() && device_ != nullptr && device_->zero();
}

bool SmartSessionController::requestPtpRefresh() {
    // A guided START owns its ACK/readback order; do not interleave SHOWs.
    if (!deviceControlAvailable() || device_ == nullptr || device_->ptpStarting() ||
        device_->profileDeploying() || profileSyncStage_ == ProfileSyncStage::deploying ||
        device_->scenarioApplying()) return false;
    const bool ptp = device_->sendPtpShow();
    const bool sync = device_->sendSmpSynchShow();
    return ptp && sync;
}

bool SmartSessionController::requestSyncDiagnostics() {
    // Read-only operator request; serialize behind the existing device
    // session. Never interleave with START/CFG or firmware port handoff.
    if (!deviceControlAvailable() || device_ == nullptr ||
        device_->ptpStarting() || device_->profileDeploying() ||
        profileSyncStage_ == ProfileSyncStage::deploying ||
        device_->scenarioApplying() || updateRequested_) return false;
    return device_->sendPtpDiagnostics();
}

bool SmartSessionController::requestPtpRole(const QString& role) {
    return deviceControlAvailable() && device_ != nullptr && device_->setPtpRole(role);
}

bool SmartSessionController::requestSmpSynch(const QString& mode) {
    return deviceControlAvailable() && device_ != nullptr && device_->setSmpSynchPolicy(mode);
}

bool SmartSessionController::requestConfigurePtp(const QVariantMap& profile) {
    return deviceControlAvailable() && device_ != nullptr && device_->configurePtp(profile);
}

bool SmartSessionController::requestStartPtp() {
    return deviceControlAvailable() && device_ != nullptr && device_->startPtp();
}

bool SmartSessionController::requestStartPtpConfigured(const QString& role,
                                                        const QVariantMap& profile) {
    return deviceControlAvailable() && device_ != nullptr &&
           device_->startPtpConfigured(role, profile);
}

bool SmartSessionController::requestStopPtp() {
    return deviceControlAvailable() && device_ != nullptr && device_->stopPtp();
}

bool SmartSessionController::beginFirmwareUpdate() {
    if (device_ == nullptr || firmware_ == nullptr || !device_->deviceVerified() ||
        !firmware_->bundleReady() || firmware_->busy()) {
        return false;
    }
    updateWasOptional_ = firmwareUpdateAvailable() && !firmwareUpdateRequired_;
    return beginFirmwareOperation(device_->portName());
}

bool SmartSessionController::beginFirmwareReinstall() {
    if (!firmwareReinstallAvailable() || device_ == nullptr) return false;
    updateWasOptional_ = true;
    return beginFirmwareOperation(device_->portName());
}

bool SmartSessionController::beginFirmwareInstall() {
    updateWasOptional_ = false;
    refreshRecoveryOfferFromIdentity();
    if (device_ == nullptr || firmware_ == nullptr || !blankBoardDetected_ ||
        !firmware_->bundleReady() || firmware_->busy() || blankBoardPort_.isEmpty()) {
        return false;
    }
    return beginFirmwareOperation(blankBoardPort_);
}

bool SmartSessionController::beginFirmwareOperation(const QString& portName) {
    const QString port = portName.trimmed();
    if (device_ == nullptr || firmware_ == nullptr || port.isEmpty() || firmware_->busy()) return false;

    updatePort_ = port;
    updateRequested_ = true;
    updateReconnectAttempts_ = 0;
    pendingReleaseGeneration_ = 0;
    profileSyncBootId_.clear();
    resetProfileSync(true);
    setupError_ = false;
    setupErrorStatus_.clear();
    lastFirmwareUpdateResult_.clear();

    if (device_->running()) {
        updateStage_ = UpdateStage::stopping;
        setPresentation(
            QStringLiteral("UPDATING FIRMWARE"),
            QStringLiteral("Stopping SMV output before firmware installation…"),
            false,
            false);
        if (!device_->stop()) {
            updateRequested_ = false;
            updateStage_ = UpdateStage::idle;
            reconcile();
            return false;
        }
        return true;
    }

    continueFirmwareUpdate();
    return true;
}

bool SmartSessionController::retryFirmwareUpdate() {
    if (device_ == nullptr || firmware_ == nullptr || updatePort_.isEmpty() || firmware_->busy()) return false;
    setupError_ = false;
    setupErrorStatus_.clear();
    lastFirmwareUpdateResult_.clear();
    blankBoardDetected_ = false;
    updateRequested_ = true;
    updateReconnectAttempts_ = 0;
    pendingReleaseGeneration_ = 0;
    continueFirmwareUpdate();
    return updateRequested_;
}

bool SmartSessionController::cancelFirmwareUpdate() {
    if (!firmwareUpdateCanCancel() || device_ == nullptr) return false;
    reconnectTimer_.stop();
    updateRequested_ = false;
    updateWasOptional_ = false;
    updateStage_ = UpdateStage::idle;
    updateReconnectAttempts_ = 0;
    pendingReleaseGeneration_ = 0;
    setupError_ = false;
    setupErrorStatus_.clear();
    blankBoardDetected_ = false;
    blankBoardPort_.clear();
    if (portOwner_ == PortOwner::firmwareTool) setPortOwner(PortOwner::none);
    if (started_ && !device_->connected() && !device_->discovering()) {
        QTimer::singleShot(0, this, [this] {
            if (!started_ || updateRequested_ || device_ == nullptr || device_->connected() || device_->discovering()) return;
            static_cast<void>(startDeviceDiscovery());
            reconcile();
        });
    } else {
        reconcile();
    }
    return true;
}

bool SmartSessionController::retryFirmwareSetup() {
    if (!firmwareRetryAvailable()) return false;
    return retryFirmwareUpdate();
}

bool SmartSessionController::retryIdentification() {
    if (!started_ || device_ == nullptr || updateRequested_ || device_->connected() ||
        device_->discovering() || (firmware_ != nullptr && firmware_->busy())) {
        return false;
    }

    clearBlankBoardContext();
    const bool started = startDeviceDiscovery();
    reconcile();
    return started;
}

bool SmartSessionController::retryProfileSync() {
    if (!profileSyncRetryAvailable()) return false;
    resetProfileSync(true);
    QTimer::singleShot(0, this, &SmartSessionController::reconcile);
    return true;
}

bool SmartSessionController::startFirmwareProbe() {
    if (!updateRequested_ || device_ == nullptr || firmware_ == nullptr ||
        firmware_->busy() || device_->connected()) {
        return false;
    }

    // A new firmware attempt gets a fresh generation after the serial handle is
    // proven released. This retires every late serial callback before espflash.
    advanceSessionGeneration();
    setPortOwner(PortOwner::firmwareTool);
    firmware_->setSessionGeneration(sessionGeneration_);
    updateStage_ = UpdateStage::probing;
    setPresentation(
        QStringLiteral("UPDATING FIRMWARE"),
        QStringLiteral("Verifying ESP32-P4 before firmware installation…"),
        false,
        false);

    if (!firmwareOwnershipValid(portOwner_, device_->connected())) {
        latchFirmwareFailure(QStringLiteral("Firmware tool ownership was not established after serial release."));
        emit firmwareUpdateFinished(false);
        reconcile();
        return false;
    }

    if (!firmware_->probeTarget(updatePort_)) {
        latchFirmwareFailure(firmware_->status());
        emit firmwareUpdateFinished(false);
        reconcile();
        return false;
    }
    return true;
}

void SmartSessionController::continueFirmwareUpdate() {
    if (!updateRequested_ || device_ == nullptr || firmware_ == nullptr) return;
    if (device_->running()) {
        updateStage_ = UpdateStage::stopping;
        return;
    }

    if (portOwner_ == PortOwner::firmwareTool) {
        static_cast<void>(startFirmwareProbe());
        return;
    }

    if (device_->connected()) {
        updateStage_ = UpdateStage::releasingPort;
        pendingReleaseGeneration_ = sessionGeneration_;
        setPresentation(
            QStringLiteral("UPDATING FIRMWARE"),
            QStringLiteral("Releasing the device serial session before firmware access…"),
            false,
            false);
        device_->disconnectPort();
        return;
    }

    pendingReleaseGeneration_ = 0;
    setPortOwner(PortOwner::none);
    static_cast<void>(startFirmwareProbe());
}

void SmartSessionController::reconnectDeviceSignals() {
    if (device_ == nullptr) return;

    connect(device_, &DeviceController::deviceVerifiedChanged, this, [this] {
        if (device_ != nullptr && device_->deviceVerified()) {
            if (portOwner_ != PortOwner::firmwareTool) setPortOwner(PortOwner::deviceSession);
            clearBlankBoardContext();
            refreshFirmwareIdentity();
            profileSyncBootId_.clear();
            resetProfileSync(true);
            prepareTimer_.start();
        } else {
            deviceFirmwareVersion_.clear();
            deviceFirmwareBuildId_.clear();
            profileSyncBootId_.clear();
            resetProfileSync(true);
        }
        reconcile();
    });
    connect(device_, &DeviceController::identificationStateChanged, this, [this] {
        refreshRecoveryOfferFromIdentity();
        reconcile();
    });
    connect(device_, &DeviceController::deviceIdentityChanged, this, [this] {
        if (device_ != nullptr && device_->deviceVerified() &&
            !profileSyncBootId_.isEmpty() && !device_->bootId().isEmpty() &&
            profileSyncBootId_ != device_->bootId()) {
            // A new firmware boot on an unchanged COM is a new authority
            // epoch. Do not carry a READY/profile proof across the reset.
            resetProfileSync(true);
            profileSyncBootId_.clear();
        }
        refreshFirmwareIdentity();
        emit stateChanged();
        reconcile();
    });
    connect(device_, &DeviceController::connectedChanged, this, [this] {
        if (device_ != nullptr && device_->connected() && portOwner_ != PortOwner::firmwareTool) {
            setPortOwner(PortOwner::deviceSession);
        }
        refreshRecoveryOfferFromIdentity();
        reconcile();
    });
    connect(device_, &DeviceController::discoveryChanged, this, [this] {
        refreshRecoveryOfferFromIdentity();
        reconcile();
    });
    connect(device_, &DeviceController::portsChanged, this, [this] {
        refreshRecoveryOfferFromIdentity();
        reconcile();
    });
    connect(device_, &DeviceController::runningChanged, this, [this] {
        if (updateRequested_ && updateStage_ == UpdateStage::stopping &&
            device_ != nullptr && !device_->running()) {
            QTimer::singleShot(0, this, [this] { continueFirmwareUpdate(); });
        }
        reconcile();
    });
    connect(device_, &DeviceController::portReleased, this,
            [this](const quint64 generation, const QString&) {
        if (!updateRequested_ || updateStage_ != UpdateStage::releasingPort ||
            !generationIsCurrent(sessionGeneration_, generation) ||
            generation != pendingReleaseGeneration_) {
            return;
        }
        pendingReleaseGeneration_ = 0;
        setPortOwner(PortOwner::none);
        QTimer::singleShot(0, this, [this] { continueFirmwareUpdate(); });
    });
    connect(device_, &DeviceController::profileStateChanged, this, [this] {
        handleProfileStateChanged();
        reconcile();
    });
    connect(device_, &DeviceController::profileDeploymentProgress, this, [this] {
        if (profileSyncStage_ == ProfileSyncStage::deploying) {
            profileSyncTimer_.start();
        }
    });
}

void SmartSessionController::reconnectProfileSignals() {
    if (profiles_ == nullptr) return;
    connect(profiles_, &SclProfileModel::sourceChanged, this, [this] {
        resetProfileSync(true);
        QTimer::singleShot(0, this, &SmartSessionController::reconcile);
    });
    connect(profiles_, &SclProfileModel::selectedProfileChanged, this, [this] {
        resetProfileSync(true);
        QTimer::singleShot(0, this, &SmartSessionController::reconcile);
    });
}

void SmartSessionController::reconnectFirmwareSignals() {
    if (firmware_ == nullptr) return;

    connect(firmware_, &FirmwareManager::stateChanged, this, [this] {
        if (!updateRequested_) {
            reconcile();
            return;
        }

        if (firmware_->sessionGeneration() != sessionGeneration_ ||
            portOwner_ != PortOwner::firmwareTool) {
            return;
        }

        if (updateStage_ == UpdateStage::probing && !firmware_->busy()) {
            if (firmware_->targetVerified()) {
                updateStage_ = UpdateStage::flashing;
                setPresentation(
                    QStringLiteral("UPDATING FIRMWARE"),
                    QStringLiteral("Installing verified ARStack firmware…"),
                    false,
                    false);
                QTimer::singleShot(0, this, [this] {
                    if (firmware_ == nullptr || device_ == nullptr ||
                        firmware_->sessionGeneration() != sessionGeneration_ ||
                        !firmwareOwnershipValid(portOwner_, device_->connected())) {
                        latchFirmwareFailure(QStringLiteral("Firmware ownership changed before installation could start."));
                        emit firmwareUpdateFinished(false);
                        reconcile();
                        return;
                    }
                    if (!firmware_->installFirmware(updatePort_)) {
                        if (firmware_->bootloaderHelpNeeded()) {
                            updateStage_ = UpdateStage::waitingForBootloader;
                        } else {
                            latchFirmwareFailure(firmware_->status());
                            emit firmwareUpdateFinished(false);
                        }
                        reconcile();
                    }
                });
                return;
            }

            if (firmware_->bootloaderHelpNeeded()) {
                updateStage_ = UpdateStage::waitingForBootloader;
            } else {
                latchFirmwareFailure(firmware_->status());
                emit firmwareUpdateFinished(false);
            }
        } else if (updateStage_ == UpdateStage::flashing && !firmware_->busy() &&
                   firmware_->bootloaderHelpNeeded()) {
            updateStage_ = UpdateStage::waitingForBootloader;
        }
        reconcile();
    });

    connect(firmware_, &FirmwareManager::operationFailed, this,
            [this](const QString& message, const bool bootloaderHelpNeeded) {
        if (!updateRequested_ || firmware_ == nullptr ||
            firmware_->sessionGeneration() != sessionGeneration_ ||
            portOwner_ != PortOwner::firmwareTool) {
            reconcile();
            return;
        }
        if (bootloaderHelpNeeded) {
            updateStage_ = UpdateStage::waitingForBootloader;
        } else {
            latchFirmwareFailure(message);
            emit firmwareUpdateFinished(false);
        }
        reconcile();
    });

    connect(firmware_, &FirmwareManager::installationFinished, this, [this](const bool resetSucceeded) {
        if (!updateRequested_ || firmware_ == nullptr ||
            firmware_->sessionGeneration() != sessionGeneration_ ||
            portOwner_ != PortOwner::firmwareTool) {
            return;
        }

        updateReconnectAttempts_ = 0;
        setPortOwner(PortOwner::none);
        if (resetSucceeded) {
            updateStage_ = UpdateStage::reconnecting;
            setPresentation(
                QStringLiteral("UPDATING FIRMWARE"),
                QStringLiteral("Firmware written. Reconnecting to ESP32-P4…"),
                false,
                false);
            reconnectTimer_.start();
            return;
        }

        if (firmware_->bootloaderHelpNeeded()) {
            setPortOwner(PortOwner::firmwareTool);
            updateStage_ = UpdateStage::waitingForBootloader;
            reconcile();
            return;
        }

        updateStage_ = UpdateStage::reconnecting;
        reconnectTimer_.start();
        reconcile();
    });
}

void SmartSessionController::refreshRecoveryOfferFromIdentity() {
    if (device_ == nullptr || updateRequested_ || setupError_ || device_->deviceVerified()) {
        blankBoardDetected_ = false;
        blankBoardPort_.clear();
        if (device_ == nullptr || device_->deviceVerified()) manualRecoveryArmed_ = false;
        return;
    }

    // A terminal semantic-identification timeout on the *single* high-confidence
    // Espressif/ESP32 candidate is a safe legacy/blank-firmware recovery signal.
    // This does not authorize a write: FirmwareManager still releases the serial
    // session and requires espflash ROM identity + ESP32-P4 pre-v3 verification
    // before write-bin can start. Generic or ambiguous serial ports remain closed.
    if (device_->identificationState() != DeviceController::IdentificationState::Unidentified) {
        blankBoardDetected_ = false;
        blankBoardPort_.clear();
        return;
    }

    // Semantic timeout on an auto-detected port proves *nothing* about
    // flash contents. Present firmware recovery only after the operator
    // explicitly selected this port. ROM chip checks still precede flash.
    if (recoveryPending_ || !manualRecoveryArmed_) {
        blankBoardDetected_ = false;
        blankBoardPort_.clear();
        return;
    }

    QString recoveryPort = device_->recoveryCandidatePort().trimmed();
    if (recoveryPort.isEmpty()) {
        recoveryPort = chooseRecoveryPort(device_->recommendedPort(), device_->ports());
    }
    if (recoveryPort.isEmpty() || !device_->ports().contains(recoveryPort, Qt::CaseInsensitive)) {
        blankBoardDetected_ = false;
        blankBoardPort_.clear();
        return;
    }

    blankBoardPort_ = recoveryPort;
    blankBoardDetected_ = true;
}

void SmartSessionController::clearBlankBoardContext() {
    blankBoardDetected_ = false;
    blankBoardPort_.clear();
    manualRecoveryArmed_ = false;
    unidentifiedDiscoveryTicks_ = 0;
    setupError_ = false;
    setupErrorStatus_.clear();
}

QString SmartSessionController::diagnosticsText() const {
    // Operator-triggered read-only snapshot; does not touch serial ownership.
    QStringList rows;
    auto add = [&rows](const QString& key, const QString& value) {
        rows << key + QStringLiteral(": ") + (value.isEmpty() ? QStringLiteral("-") : value);
    };
    rows << QStringLiteral("ARStack Studio field diagnostics")
         << QStringLiteral("Device telemetry is reported, not independently verified on wire.");
    add(QStringLiteral("Studio version"), expectedFirmwareVersion());
    add(QStringLiteral("Session state"), state_);
    add(QStringLiteral("Session status"), statusText_);
    add(QStringLiteral("Session generation"), QString::number(sessionGeneration_));
    add(QStringLiteral("Serial owner"), portOwner_ == PortOwner::deviceSession
        ? QStringLiteral("device session") : portOwner_ == PortOwner::firmwareTool
        ? QStringLiteral("firmware tool") : QStringLiteral("none"));
    add(QStringLiteral("Firmware update stage"), firmwareUpdateStage());
    add(QStringLiteral("Last firmware update result"), lastFirmwareUpdateResult_);
    add(QStringLiteral("Setup error"), setupErrorStatus_);
    if (firmware_ != nullptr) {
        add(QStringLiteral("Bundled firmware version"), firmware_->firmwareVersion());
        add(QStringLiteral("Bundled build ID"), firmware_->firmwareBuildId());
        add(QStringLiteral("Bundled firmware SHA256"), firmware_->firmwareSha256());
        add(QStringLiteral("Firmware service status"), firmware_->status());
        add(QStringLiteral("Firmware target"), firmware_->targetChip());
        add(QStringLiteral("Firmware operation busy"), firmware_->busy() ? QStringLiteral("yes") : QStringLiteral("no"));
    }
    if (profiles_ != nullptr && profiles_->hasProfiles()) {
        const QVariantMap profile = profiles_->selectedProfile();
        add(QStringLiteral("Configured SV ID"), profile.value(QStringLiteral("svId")).toString());
        add(QStringLiteral("Configured APPID"), profile.value(QStringLiteral("appId")).toString());
        add(QStringLiteral("Configured publisher fps"), profile.value(QStringLiteral("publisherRate")).toString());
        add(QStringLiteral("Configured counter wrap"), profile.value(QStringLiteral("counterModulus")).toString());
        add(QStringLiteral("Configured payload bytes"), profile.value(QStringLiteral("payloadBytes")).toString());
    }
    if (device_ != nullptr) {
        add(QStringLiteral("Device verified"), device_->deviceVerified() ? QStringLiteral("yes") : QStringLiteral("no"));
        add(QStringLiteral("COM port"), device_->portName());
        add(QStringLiteral("Device product"), device_->deviceProduct());
        add(QStringLiteral("Device target"), device_->deviceTarget());
        add(QStringLiteral("Device ID"), device_->deviceId());
        add(QStringLiteral("Device firmware version"), device_->firmwareVersion());
        add(QStringLiteral("Device firmware build ID"), device_->firmwareBuildId());
        add(QStringLiteral("Device protocol"), device_->protocolVersion());
        add(QStringLiteral("Device capabilities"), device_->capabilities().join(QStringLiteral(", ")));
        add(QStringLiteral("Exact bundled build match"), firmwareIsCurrent() ? QStringLiteral("yes") : QStringLiteral("NOT VERIFIED"));
        add(QStringLiteral("Firmware protocol compatible"), !device_->deviceVerified()
            ? QStringLiteral("UNKNOWN (identity not verified)")
            : firmwareIsCompatible() ? QStringLiteral("yes") : QStringLiteral("no"));
        add(QStringLiteral("Profile generation"), device_->profileGeneration());
        add(QStringLiteral("Profile armed"), device_->profileArmed() ? QStringLiteral("yes") : QStringLiteral("no"));
        add(QStringLiteral("SMV running"), device_->running() ? QStringLiteral("yes") : QStringLiteral("no"));
        add(QStringLiteral("SMV FPS reported"), device_->fps());
        add(QStringLiteral("SMV missed reported"), device_->missed());
        add(QStringLiteral("SMV TX failures reported"), device_->txFailures());
        add(QStringLiteral("PTP status reported"), device_->ptpStatus());
        add(QStringLiteral("SV sync internal flight recorder (not physical proof)"),
            device_->syncDiagnostics());
        add(QStringLiteral("PTP role reported"), device_->ptpRole());
        add(QStringLiteral("PTP discipline reported"), device_->ptpDiscipline());
        add(QStringLiteral("SMPSYNCH value reported"), device_->smpSynchValue());
        add(QStringLiteral("Device last error"), device_->lastError());
        rows << QStringLiteral("--- Device serial log, last 12000 chars ---")
             << device_->logText().right(12000);
    }
    if (firmware_ != nullptr) {
        rows << QStringLiteral("--- Firmware service log, last 12000 chars ---")
             << firmware_->logText().right(12000);
    }
    rows << QStringLiteral("Review and redact site identifiers or addresses before sharing.");
    return rows.join(QLatin1Char('\n'));
}

void SmartSessionController::latchFirmwareFailure(QString message) {
    reconnectTimer_.stop();
    const bool optionalOperation = updateWasOptional_;
    updateRequested_ = false;
    updateWasOptional_ = false;
    updateStage_ = UpdateStage::idle;
    updateReconnectAttempts_ = 0;
    pendingReleaseGeneration_ = 0;
    blankBoardDetected_ = false;
    if (portOwner_ == PortOwner::firmwareTool) setPortOwner(PortOwner::none);
    message = message.trimmed();
    lastFirmwareUpdateResult_ = message.isEmpty()
        ? QStringLiteral("Firmware verification failed; inspect the firmware-service log.")
        : message;
    setupError_ = !optionalOperation;
    setupErrorStatus_ = optionalOperation ? QString{} : (message.isEmpty()
        ? QStringLiteral("Firmware setup did not complete. Retry explicitly when the board is ready.")
        : std::move(message));
    if (optionalOperation && started_ && device_ != nullptr && !device_->connected() && !device_->discovering()) {
        QTimer::singleShot(0, this, [this] {
            if (!started_ || updateRequested_ || device_ == nullptr || device_->connected() || device_->discovering()) return;
            static_cast<void>(startDeviceDiscovery());
            reconcile();
        });
    }
}

void SmartSessionController::resetProfileSync(const bool requireSync) {
    profileSyncTimer_.stop();
    profileRetryTimer_.stop();
    profileSyncTotalTimer_.stop();
    profileSyncStage_ = ProfileSyncStage::idle;
    profileSyncAttempts_ = 0;
    profileSyncBaselineGeneration_.clear();
    profileSyncError_.clear();
    needsProfileSync_ = requireSync;
}

bool SmartSessionController::beginProfileSync(const QVariantMap& profile) {
    if (device_ == nullptr || !device_->deviceVerified() || device_->running() ||
        portOwner_ != PortOwner::deviceSession ||
        profileSyncStage_ == ProfileSyncStage::failed ||
        !profileSyncRetryAllowed(profileSyncAttempts_)) {
        return false;
    }

    const QString currentBootId = device_->bootId().trimmed();
    if (profileSyncBootId_ == currentBootId && !currentBootId.isEmpty()) {
        profileSyncBaselineGeneration_ = device_->profileGeneration().trimmed();
    } else {
        profileSyncBaselineGeneration_.clear();
        profileSyncBootId_ = currentBootId;
    }

    ++profileSyncAttempts_;
    profileSyncStage_ = ProfileSyncStage::deploying;
    profileSyncError_.clear();
    profileRetryTimer_.stop();
    profileSyncTotalTimer_.start();

    const bool accepted = device_->deployProfile(profile);
    if (!accepted) {
        if (profileSyncStage_ == ProfileSyncStage::deploying) {
            handleProfileSyncAttemptFailure(
                device_->lastError().isEmpty()
                    ? QStringLiteral("Studio could not send the profile transaction to the ESP32-P4.")
                    : device_->lastError());
        }
        return false;
    }

    if (profileSyncStage_ == ProfileSyncStage::deploying) profileSyncTimer_.start();
    return true;
}

void SmartSessionController::handleProfileStateChanged() {
    if (device_ == nullptr || profileSyncStage_ != ProfileSyncStage::deploying) return;
    if (device_->profileDeploying()) return;

    if (device_->profileArmed()) {
        const QString observedGeneration = device_->profileGeneration().trimmed();
        // For a fresh BINCOMMIT require generation advance. For a read-only
        // canonical-content reuse the generation intentionally stays identical:
        // the device already had exactly the requested profile.
        if (!device_->profileWasReused() &&
            !profileGenerationAdvanced(profileSyncBaselineGeneration_, observedGeneration)) return;

        profileSyncTimer_.stop();
        profileSyncTotalTimer_.stop();
        profileRetryTimer_.stop();
        profileSyncStage_ = ProfileSyncStage::idle;
        profileSyncAttempts_ = 0;
        profileSyncBaselineGeneration_ = observedGeneration;
        profileSyncBootId_ = device_->bootId().trimmed();
        profileSyncError_.clear();
        needsProfileSync_ = false;
        return;
    }

    handleProfileSyncAttemptFailure(
        device_->lastError().isEmpty()
            ? QStringLiteral("The ESP32-P4 rejected the profile transaction.")
            : device_->lastError());
}

void SmartSessionController::handleProfileSyncAttemptFailure(QString reason) {
    profileSyncTimer_.stop();
    profileSyncTotalTimer_.stop();
    if (profileSyncStage_ == ProfileSyncStage::failed) return;

    reason = reason.trimmed();
    if (reason.isEmpty()) reason = QStringLiteral("Profile synchronization did not complete.");

    if (profileSyncRetryAllowed(profileSyncAttempts_)) {
        profileSyncStage_ = ProfileSyncStage::idle;
        profileSyncError_ = reason;
        // Start cool-down BEFORE notifying the device: profileStateChanged is
        // synchronous and could otherwise immediately launch another attempt.
        profileRetryTimer_.start(profileSyncBackoffMs(profileSyncAttempts_));
        if (device_ != nullptr && device_->profileDeploying()) device_->abandonProfileDeployment();
        reconcile();
        return;
    }

    latchProfileSyncFailure(reason);
    if (device_ != nullptr && device_->profileDeploying()) device_->abandonProfileDeployment();
}

void SmartSessionController::latchProfileSyncFailure(QString reason) {
    profileSyncTimer_.stop();
    profileSyncTotalTimer_.stop();
    profileRetryTimer_.stop();
    profileSyncStage_ = ProfileSyncStage::failed;
    needsProfileSync_ = true;
    reason = reason.trimmed();
    if (reason.isEmpty()) reason = QStringLiteral("Profile synchronization did not complete.");
    profileSyncError_ = QStringLiteral(
        "%1 Studio stopped after %2 bounded attempts; Start remains inhibited. Retry profile synchronization or reconnect the device.")
        .arg(reason)
        .arg(profileSyncMaxAttempts());
}

bool SmartSessionController::ensureDefaultProfile() {
    if (profiles_ == nullptr) return false;
    if (profiles_->hasProfiles()) return true;
    return profiles_->loadReferenceTemplate();
}

void SmartSessionController::setPresentation(
    QString state,
    QString status,
    const bool startReady,
    const bool firmwareUpdateRequired) {
    const bool readyNow = startReady;
    const bool changed = state_ != state || statusText_ != status ||
        startReady_ != startReady || firmwareUpdateRequired_ != firmwareUpdateRequired;

    state_ = std::move(state);
    statusText_ = std::move(status);
    startReady_ = startReady;
    firmwareUpdateRequired_ = firmwareUpdateRequired;

    if (changed) emit stateChanged();
    if (readyNow && !wasReady_) emit readyForLiveApply();
    wasReady_ = readyNow;
}

void SmartSessionController::refreshFirmwareIdentity() {
    const bool verified = device_ != nullptr && device_->deviceVerified();
    deviceFirmwareVersion_ = verified ? device_->firmwareVersion() : QString{};
    deviceFirmwareBuildId_ = verified ? device_->firmwareBuildId() : QString{};
}

bool SmartSessionController::firmwareIsCurrent() const {
    return device_ != nullptr && device_->deviceVerified() &&
        DeviceController::identitySupportsCurrentContract(
            device_->deviceIdentity(), expectedFirmwareVersion(), expectedFirmwareBuildId());
}

bool SmartSessionController::firmwareIsCompatible() const {
    return device_ != nullptr && device_->deviceVerified() &&
        DeviceController::identitySupportsCurrentContract(
            device_->deviceIdentity(), expectedFirmwareVersion(), QString{});
}

bool SmartSessionController::deviceControlAvailable() const noexcept {
    return device_ != nullptr && device_->deviceVerified() && firmwareIsCompatible() &&
        portOwner_ == PortOwner::deviceSession && !updateRequested_ &&
        (firmware_ == nullptr || !firmware_->busy());
}

void SmartSessionController::reconcile() {
    if (shuttingDown_) return;
    if (device_ == nullptr || profiles_ == nullptr || firmware_ == nullptr) {
        setPresentation(
            QStringLiteral("INITIALIZING"),
            QStringLiteral("Preparing ARStack Studio…"),
            false,
            false);
        return;
    }

    if (!profiles_->hasProfiles() && !ensureDefaultProfile()) {
        setPresentation(
            QStringLiteral("SETUP ERROR"),
            profiles_->fatalError().isEmpty()
                ? QStringLiteral("The built-in 4I+4V profile could not be loaded.")
                : profiles_->fatalError(),
            false,
            false);
        return;
    }

    if (updateRequested_) {
        if (updateStage_ == UpdateStage::waitingForBootloader) {
            setPresentation(QStringLiteral("UPDATE NEEDS BOOT"), updateStatus(), false, false);
            return;
        }
        if (updateStage_ == UpdateStage::stopping || updateStage_ == UpdateStage::releasingPort ||
            updateStage_ == UpdateStage::probing || updateStage_ == UpdateStage::flashing ||
            (updateStage_ == UpdateStage::reconnecting && !device_->deviceVerified())) {
            setPresentation(
                QStringLiteral("UPDATING FIRMWARE"),
                updateStatus().isEmpty() ? QStringLiteral("Installing firmware…") : updateStatus(),
                false,
                false);
            return;
        }
    }

    // Fail closed immediately. In particular, a wrong-device recovery must not
    // briefly fall through to READY while the asynchronous port close is still
    // being acknowledged by DeviceIoWorker.
    if (setupError_) {
        setPresentation(
            QStringLiteral("SETUP ERROR"),
            setupErrorStatus_.isEmpty()
                ? QStringLiteral("Studio could not identify a supported ESP32-P4 on the connected serial device.")
                : setupErrorStatus_,
            false,
            false);
        return;
    }

    if (device_->discovering() || (device_->connected() && !device_->deviceVerified())) {
        setPresentation(QStringLiteral("CONNECTING"), device_->discoveryStatus(), false, false);
        return;
    }

    if (!device_->deviceVerified()) {
        refreshRecoveryOfferFromIdentity();

        if (blankBoardDetected_) {
            setPresentation(
                QStringLiteral("FIRMWARE RECOVERY"),
                QStringLiteral("Manually selected port %1 did not answer ARStack IDENTIFY. Firmware status is UNKNOWN. Retry connection first; optional recovery requires ROM chip/revision verification.")
                    .arg(blankBoardPort_),
                false,
                false);
            return;
        }

        if (device_->identificationState() == DeviceController::IdentificationState::Unidentified) {
            setPresentation(
                QStringLiteral("UNIDENTIFIED"),
                QStringLiteral("No ARStack semantic identity was received after %1 bounded attempts and the visible serial devices are ambiguous. Disconnect unrelated serial devices or select the intended ESP32-P4 port, then retry.")
                    .arg(device_->identifyAttempts()),
                false,
                false);
            return;
        }

        setPresentation(
            device_->ports().isEmpty() ? QStringLiteral("WAITING FOR DEVICE") : QStringLiteral("DEVICE FOUND"),
            device_->ports().isEmpty()
                ? QStringLiteral("Connect ESP32-P4; ARStack Studio will detect it automatically.")
                : QStringLiteral("USB device found. ARStack Studio is identifying it automatically."),
            false,
            false);
        return;
    }

    refreshFirmwareIdentity();

    // A completed write must verify the exact bundled build. This remains
    // fail-closed even though a pre-existing compatible build may be used.
    if (updateRequested_ && updateStage_ == UpdateStage::reconnecting) {
        if (!firmwareIsCurrent()) {
            const QString observed = deviceFirmwareVersion_.isEmpty()
                ? QStringLiteral("legacy/unknown firmware")
                : QStringLiteral("firmware v%1").arg(deviceFirmwareVersion_);
            const QString installedBuild = deviceFirmwareBuildId_.isEmpty()
                ? QStringLiteral("missing/unknown") : deviceFirmwareBuildId_;
            const QString expectedBuild = expectedFirmwareBuildId().isEmpty()
                ? QStringLiteral("missing/unknown") : expectedFirmwareBuildId();
            latchFirmwareFailure(QStringLiteral(
                "Firmware write/reset completed and ESP32-P4 reconnected, but exact build verification failed: "
                "%1, installed build %2; package expects v%3, build %4. "
                "A compatible existing firmware may still run. Copy diagnostics before retrying.")
                .arg(observed, installedBuild, expectedFirmwareVersion(), expectedBuild));
            emit firmwareUpdateFinished(false);
            reconcile();
            return;
        }
        updateRequested_ = false;
        updateWasOptional_ = false;
        updateStage_ = UpdateStage::idle;
        lastFirmwareUpdateResult_ = QStringLiteral("Exact bundled firmware build verified after reconnect.");
        clearBlankBoardContext();
        emit firmwareUpdateFinished(true);
    }

    // Runtime compatibility and package freshness are intentionally separate.
    // Same-version firmware with the required protocol/capabilities remains
    // usable; build provenance mismatch is an advisory update, not a lockout.
    if (!firmwareIsCompatible()) {
        const QString versionText = deviceFirmwareVersion_.isEmpty()
            ? QStringLiteral("legacy firmware")
            : QStringLiteral("firmware v%1").arg(deviceFirmwareVersion_);
        setPresentation(
            QStringLiteral("FIRMWARE UPDATE"),
            QStringLiteral("%1 does not satisfy the current protocol/capability contract. Update is required before injection.")
                .arg(versionText),
            false,
            true);
        return;
    }

    if (device_->running()) {
        setPresentation(
            QStringLiteral("RUNNING"),
            firmwareUpdateAvailable()
                ? QStringLiteral("4I + 4V · 4000 samples/s · live value apply · firmware update available")
                : QStringLiteral("4I + 4V · 4000 samples/s · live value apply"),
            false,
            false);
        return;
    }

    const QVariantMap profile = profiles_->selectedProfile();
    const bool deployable = profile.value(QStringLiteral("compatibilityClass")).toString() == QStringLiteral("A") &&
        profile.value(QStringLiteral("deviceSupport")).toString() == QStringLiteral("ready");
    if (!deployable) {
        setPresentation(
            QStringLiteral("PROFILE BLOCKED"),
            QStringLiteral("The selected profile is outside the supported 4I+4V runtime."),
            false,
            false);
        return;
    }

    if (profileSyncStage_ == ProfileSyncStage::failed) {
        setPresentation(
            QStringLiteral("PROFILE SYNC ERROR"),
            profileSyncError_.isEmpty()
                ? QStringLiteral("Profile synchronization failed after bounded retries. Retry profile synchronization or reconnect the device.")
                : profileSyncError_,
            false,
            false);
        return;
    }

    if (profileRetryTimer_.isActive()) {
        setPresentation(
            QStringLiteral("RECOVERING PROFILE"),
            QStringLiteral("Profile attempt %1/%2 did not complete: %3. "
                           "Checking session and retrying in %4 ms (no auto-START).")
                .arg(profileSyncAttempts_).arg(profileSyncMaxAttempts())
                .arg(profileSyncError_.left(160))
                .arg(profileRetryTimer_.remainingTime()),
            false, false);
        return;
    }

    if (profileSyncStage_ == ProfileSyncStage::deploying ||
        device_->profileDeploying() || prepareTimer_.isActive()) {
        setPresentation(
            QStringLiteral("PREPARING 4I+4V"),
            profileSyncStage_ == ProfileSyncStage::deploying
                ? QStringLiteral("Synchronizing the default 4I+4V profile · attempt %1/%2…")
                    .arg(profileSyncAttempts_)
                    .arg(profileSyncMaxAttempts())
                : QStringLiteral("Preparing the default 4I+4V injection profile…"),
            false,
            false);
        return;
    }

    if (needsProfileSync_) {
        setPresentation(
            QStringLiteral("PREPARING 4I+4V"),
            QStringLiteral("Synchronizing the default 4I+4V profile…"),
            false,
            false);
        static_cast<void>(beginProfileSync(profile));
        return;
    }

    if (!device_->profileArmed()) {
        resetProfileSync(true);
        setPresentation(
            QStringLiteral("PREPARING 4I+4V"),
            QStringLiteral("Restoring the default 4I+4V profile…"),
            false,
            false);
        QTimer::singleShot(0, this, &SmartSessionController::reconcile);
        return;
    }

    setPresentation(
        QStringLiteral("READY"),
        firmwareUpdateAvailable()
            ? QStringLiteral("4I + 4V · 4000 samples/s · ready · firmware update available")
            : QStringLiteral("4I + 4V · 4000 samples/s · ready to start"),
        true,
        false);
}