@mikrojs/firmware 0.17.0-pr-276.20260721233726 → 0.17.0

package/components/mikrojs/CMakeLists.txt

@@ -134,6 +134,26 @@ target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_PACKAGE_NAME=\"mikro\""
 set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
     "${CMAKE_CURRENT_LIST_DIR}/../../package.json")
 
+# Firmware identity: the consuming project's package.json name, reported in
+# MSG_READY as `fw`. The CLI only auto-flashes its bundled prebuilt over a
+# device whose identity matches the prebuilt's own recorded name, so custom
+# firmware is protected from the auto-reflash without any project marker.
+# Absent (no package.json, e.g. on-device test apps) the field is omitted.
+execute_process(
+    COMMAND node ${_MIK_RESOLVE} projectName ${CMAKE_SOURCE_DIR}
+    OUTPUT_VARIABLE _MIK_FW_NAME
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+# STREQUAL, not if(_MIK_FW_NAME): a project named "0", "off", or "false"
+# would read as a false constant and silently lose its identity.
+if(NOT _MIK_FW_NAME STREQUAL "")
+    target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_FW_NAME=\"${_MIK_FW_NAME}\"")
+endif()
+if(EXISTS "${CMAKE_SOURCE_DIR}/package.json")
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
+        "${CMAKE_SOURCE_DIR}/package.json")
+endif()
+
 # UTC build timestamp. `string(TIMESTAMP ... UTC)` honors SOURCE_DATE_EPOCH
 # when set. Refreshes on re-configure only (idf.py triggers this on each
 # build via its own reconfigure step, so in practice it's close to
@@ -151,7 +171,7 @@ include("${MIK_BYTECODE_CMAKE}")
 
 # Force linker to include self-registering native modules
 set(_MIK_MODULES cbor pin i2c i2s spi http http_server wifi rtc nvs_kv sntp sleep neopixel pwm uart ota)
-set(_MIK_BYTECODE_MODULES abort cbor env result schema fs http/helpers http/request http/server i2c i2s kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi)
+set(_MIK_BYTECODE_MODULES abort cbor env result schema fs http/helpers http/request http/server i2c i2s kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi)
 if(CONFIG_BT_ENABLED)
     list(APPEND _MIK_MODULES ble)
     list(APPEND _MIK_BYTECODE_MODULES ble)

package/components/mikrojs/include/mikrojs_esp32.h

@@ -25,13 +25,28 @@ void MIK_DeployRecover(void);
  * (may esp_restart). Call right after MIK_DeployRecover(). */
 void mik__ota_boot_reconcile(void);
 
-/* Adopt a streamed .tgz as the live app with no trial, recording it as the OTA
- * rollback baseline (.ota-last-good.tgz). Backs MIK_CMD_DEPLOY_BUILD: a deploy
- * (not an OTA download) becomes the known-good build. Verifies the build
- * against `checksum` (lowercase hex, may be empty to skip), installs it, sets
- * state GOOD with no trial, and clears any pending build. Returns false with
+/* Stage a streamed .tgz for install at the next boot with adopt semantics:
+ * no trial, no rollback baseline, one install attempt. Backs
+ * MIK_CMD_DEPLOY_BUILD. Verifies the build against `checksum` (lowercase hex,
+ * may be empty to skip) so a corrupt upload still fails synchronously over
+ * serial, then arms the boot reconcile's adopt install. Returns false with
  * *err pointing at a static reason string on failure. */
-bool mik__ota_adopt_build(const char* tgz_path, const char* checksum, const char** err);
+bool mik__ota_stage_adopt(const char* tgz_path, const char* checksum, const char** err);
+
+/* Outcome of the last adopt-mode boot install, for MIK_CMD_DEPLOY_RESULT.
+ * Kept separate from the reconcile record on purpose: that record reaches the
+ * registry as `lastInstall` and would blacklist a checksum a developer is
+ * about to legitimately re-push over the cable. */
+typedef struct MIKDeployResult {
+    uint8_t status; /* 0 none, 1 ok, 2 fail */
+    char checksum[96];
+    char reason[32];
+    char detail[160];
+} MIKDeployResult;
+
+/* Read and clear the recorded adopt-install outcome (mik_ota.cpp). status 0
+ * with empty strings when nothing is recorded. */
+void mik__ota_take_deploy_result(MIKDeployResult* out);
 
 /* True while the running build is an unconfirmed OTA trial (mik_ota.cpp). Lets
  * the boot path treat a JS-level fatal during a trial as a failed trial. */

package/components/mikrojs/mik_deploy.cpp

@@ -20,7 +20,7 @@ static const char* DEPLOY_TMP = "/appfs/.deploy-tmp";
 static const char* APP_DIR = "/appfs/app";
 static const char* CHECKSUMS_PATH = "/appfs/app/.checksums";
 /* Where DEPLOY_PUT("/.build.tgz", ...) streams the OTA build (DEPLOY_TMP +
- * "/.build.tgz"). Adopted by MIK_CMD_DEPLOY_BUILD. */
+ * "/.build.tgz"). Staged for boot install by MIK_CMD_DEPLOY_BUILD. */
 static const char* BUILD_TGZ_PATH = "/appfs/.deploy-tmp/.build.tgz";
 
 /* ── Checksums manifest ─────────────────────────────────────────── */
@@ -550,9 +550,12 @@ bool mik__handle_deploy_command(MIKReplTransport* transport, uint8_t cmd_type,
         }
 
         case MIK_CMD_DEPLOY_BUILD: {
-            /* Adopt a streamed .tgz as the live app via the OTA install path,
-             * establishing the rollback baseline. The build was streamed via
-             * PUT("/.build.tgz") + chunks into BUILD_TGZ_PATH.
+            /* Stage a streamed .tgz for install at the next boot. The install
+             * runs from the boot reconcile on a clean heap; installing here
+             * with the app live needs a 32 KB contiguous inflate window a
+             * fragmented heap cannot provide. The checksum is verified now so
+             * a corrupt upload still fails synchronously. The build was
+             * streamed via PUT("/.build.tgz") + chunks into BUILD_TGZ_PATH.
              * Payload: u16le checksum_len | checksum. */
             if (payload_len < 2) {
                 mik__proto_drain(transport, payload_len);
@@ -576,14 +579,14 @@ bool mik__handle_deploy_command(MIKReplTransport* transport, uint8_t cmd_type,
             uint32_t consumed = 2 + (uint32_t)chk_len;
             if (payload_len > consumed) mik__proto_drain(transport, payload_len - consumed);
 
-            /* Flush the staged .tgz to disk before adopt reads it back. */
+            /* Flush the staged .tgz to disk before staging verifies it. */
             put_close_and_clear();
 
             const char* err = nullptr;
-            if (mik__ota_adopt_build(BUILD_TGZ_PATH, checksum, &err)) {
+            if (mik__ota_stage_adopt(BUILD_TGZ_PATH, checksum, &err)) {
                 mik__proto_send_ok(transport);
             } else {
-                mik__proto_send_err(transport, err ? err : "build install failed");
+                mik__proto_send_err(transport, err ? err : "build stage failed");
             }
             deploy_cleanup();
             return true;

package/components/mikrojs/mik_main.cpp

@@ -198,12 +198,35 @@ static bool platform_command_handler(MIKReplTransport* transport, uint8_t cmd_ty
         return true;
     }
 
-    /* Deploy commands (0x20-0x27) plus the build-install command (0x2D) */
+    /* Deploy commands (0x20-0x27) plus the build-stage command (0x2D) */
     if ((cmd_type >= MIK_CMD_DEPLOY_PUT && cmd_type <= MIK_CMD_DEPLOY_CHECKSUM) ||
         cmd_type == MIK_CMD_DEPLOY_BUILD) {
         return mik__handle_deploy_command(transport, cmd_type, payload_len);
     }
 
+    /* Install outcome (0x2E): report + clear the result of the last staged
+     * build install. Handled here, not in the deploy handler: it is a
+     * standalone read after the post-deploy reboot and must not start a
+     * deploy session (pause the runtime, clear the staging dir). */
+    if (cmd_type == MIK_CMD_DEPLOY_RESULT) {
+        mik__proto_drain(transport, payload_len);
+        MIKDeployResult res;
+        mik__ota_take_deploy_result(&res);
+        uint8_t buf[1 + 3 * 2 + sizeof(res.checksum) + sizeof(res.reason) + sizeof(res.detail)];
+        size_t n = 0;
+        buf[n++] = res.status;
+        const char* fields[] = {res.checksum, res.reason, res.detail};
+        for (const char* s : fields) {
+            size_t len = strlen(s);
+            buf[n++] = (uint8_t)(len & 0xFF);
+            buf[n++] = (uint8_t)((len >> 8) & 0xFF);
+            memcpy(buf + n, s, len);
+            n += len;
+        }
+        mik__proto_send(transport, MIK_MSG_OK, buf, n);
+        return true;
+    }
+
     /* File pull (0x2B) */
     if (cmd_type == MIK_CMD_FS_GET) {
         return mik__handle_fs_get(transport, payload_len);

package/components/mikrojs/mik_ota.cpp

@@ -696,6 +696,7 @@ constexpr const char* kKeyTrialLeft = "trialLeft"; // u8
 constexpr const char* kKeyTrialN = "trialN";      // u8: trial budget for a pending install
 constexpr const char* kKeyConfirm = "confirm";    // u8: trial requires markValid() to promote
 constexpr const char* kKeyPending = "pending";    // u8: 1 = .ota-pending.tgz awaits clean-heap install
+constexpr const char* kKeyPendMode = "pendMode";  // u8: how to install the pending build (see below)
 constexpr const char* kKeyInstLeft = "instLeft";  // u8: install-attempt budget
 constexpr const char* kKeyPromLeft = "promLeft";  // u8: promote-attempt budget
 constexpr const char* kKeyRbLeft = "rbLeft";      // u8: rollback-attempt budget
@@ -712,9 +713,22 @@ constexpr const char* kKeyOInst = "oInst";        // str: checksum just installe
 constexpr const char* kKeyORevert = "oRevert";    // u8
 constexpr const char* kKeyORsn = "oRsn";          // str: diagnostic reason
 constexpr const char* kKeyODetail = "oDetail";    // str: diagnostic detail
+// Adopt-install outcome, read once by MIK_CMD_DEPLOY_RESULT and then cleared.
+// Separate from the reconcile record above: that one reaches the registry as
+// `lastInstall` and would blacklist a checksum the developer is re-pushing.
+constexpr const char* kKeyDRes = "dRes";          // u8: 1 ok, 2 fail
+constexpr const char* kKeyDChk = "dChk";          // str: staged checksum
+constexpr const char* kKeyDRsn = "dRsn";          // str: failure reason
+constexpr const char* kKeyDDetail = "dDetail";    // str: failure detail
 
 constexpr uint8_t kStateGood = 0;
 constexpr uint8_t kStateTrial = 1;
+// kKeyPendMode values. Trial is the OTA path (trialBoots, rollback, abandon
+// policy); adopt is the cable-deploy path (straight to GOOD, no trial, no
+// rollback baseline, one install attempt). Absent defaults to trial so a
+// pending build staged by older firmware keeps its semantics.
+constexpr uint8_t kPendModeTrial = 0;
+constexpr uint8_t kPendModeAdopt = 1;
 constexpr uint8_t kInstallBudget = 3;  // boot install attempts before abandoning a pending build
 // Boot attempts to make a survived trial the revert target before giving up on
 // the revert target rather than on the device: a trial that cannot promote and
@@ -867,37 +881,6 @@ bool nvs_str(nvs_handle_t h, const char* key, char* buf, size_t cap) {
     return buf[0] != 0;
 }
 
-// Copy src to dst (truncating dst). Used to move the staged build to the
-// rollback slot before install_build rmtrees the staging tree it lives under.
-bool copy_file(const char* src, const char* dst) {
-    FILE* in = fopen(src, "rb");
-    if (!in) return false;
-    FILE* out = fopen(dst, "wb");
-    if (!out) {
-        fclose(in);
-        return false;
-    }
-    unsigned char* buf = (unsigned char*)malloc(kChunk);
-    if (!buf) {
-        fclose(in);
-        fclose(out);
-        return false;
-    }
-    bool ok = true;
-    size_t n;
-    while ((n = fread(buf, 1, kChunk, in)) > 0) {
-        if (fwrite(buf, 1, n, out) != n) {
-            ok = false;
-            break;
-        }
-    }
-    if (ok && ferror(in)) ok = false;
-    free(buf);
-    if (fclose(out) != 0) ok = false;
-    fclose(in);
-    return ok;
-}
-
 // ── install (gunzip -> untar -> atomic swap) ─────────────────────────────────
 // Unpacks `tgz` into <base>/.deploy-tmp/app and promotes it to /app via the
 // shared app-store engine (crash-safe: an interrupted swap is rolled back by
@@ -1197,6 +1180,9 @@ JSValue js_stage_finish(JSContext* ctx, JSValueConst, int argc, JSValueConst* ar
     nvs_erase_key(h, kKeyStgChk);
     nvs_erase_key(h, kKeyStgSize);
     nvs_set_str(h, kKeyPendChk, want_chk);
+    // Explicit even though trial is the default: a leftover adopt marker from
+    // an earlier cable deploy must not turn this OTA build into an adopt.
+    nvs_set_u8(h, kKeyPendMode, kPendModeTrial);
     nvs_set_u8(h, kKeyTrialN, (uint8_t)trial_boots);
     nvs_set_u8(h, kKeyConfirm, require_confirm ? 1 : 0);
 
@@ -1477,21 +1463,37 @@ bool attempt_rollback(nvs_handle_t h, const char* reason, const char* detail) {
     return true;
 }
 
+// Resolve a failed adopt install: drop the pending build, record the outcome
+// for MIK_CMD_DEPLOY_RESULT, and leave the previous /app running. No rollback
+// and no retry -- the developer is on the serial cable and re-pushes. Never
+// touches the reconcile record (oRsn/oDetail), which reaches the registry.
+void adopt_fail(nvs_handle_t h, const char* chk, const char* reason, const char* detail) {
+    nvs_set_u8(h, kKeyPending, 0);
+    nvs_erase_key(h, kKeyPendChk);
+    nvs_erase_key(h, kKeyPendMode);
+    nvs_erase_key(h, kKeyInstLeft);
+    unlink(kPending);
+    nvs_set_u8(h, kKeyDRes, 2);
+    nvs_set_str(h, kKeyDChk, chk);
+    nvs_set_str(h, kKeyDRsn, reason);
+    nvs_set_str(h, kKeyDDetail, detail);
+    nvs_commit(h);
+}
+
 }  // namespace
 
-// Adopt a streamed .tgz as the live app with NO trial (the deploy / baseline
-// path, distinct from an OTA download which runs a trial). Verifies the build
-// against `checksum`, copies it to the rollback slot first so it survives the
-// commit (install_build rmtrees the staging tree the source lives under),
-// installs it, then records it as the running good build. NOT JS-exposed —
-// called from the serial DEPLOY_BUILD handler.
-bool mik__ota_adopt_build(const char* tgz_path, const char* checksum, const char** err) {
+// Stage a streamed .tgz for adopt install at the next boot (the cable-deploy
+// path, distinct from an OTA download which runs a trial). The install itself
+// runs from mik__ota_boot_reconcile() on a clean heap: doing it here, with the
+// app live, needs a 32 KB contiguous inflate window a fragmented heap cannot
+// provide. Verification stays synchronous so a corrupt upload still fails over
+// serial; empty checksum skips the check. NOT JS-exposed — called from the
+// serial DEPLOY_BUILD handler.
+bool mik__ota_stage_adopt(const char* tgz_path, const char* checksum, const char** err) {
     if (!path_exists(tgz_path)) {
         *err = "build not staged";
         return false;
     }
-    // Verify SHA-256 before install so a corrupt upload can't become the
-    // rollback baseline. Empty checksum skips the check.
     if (checksum && checksum[0]) {
         char got[65];
         if (!sha256_file(tgz_path, got)) {
@@ -1503,43 +1505,74 @@ bool mik__ota_adopt_build(const char* tgz_path, const char* checksum, const char
             return false;
         }
     }
-    // Install from a copy outside the staging tree: install_build commits by
-    // rmtree-ing that tree, and the staged .tgz lives under it. Promote the copy
-    // to the rollback slot only once the install succeeded -- overwriting
-    // kLastGood up front would, on a failed install, leave the revert target
-    // naming a build that is not installed and never was, so a later revert()
-    // would roll *forward* onto it while reporting the old checksum.
-    unlink(kLastGoodTmp);
-    if (!copy_file(tgz_path, kLastGoodTmp)) {
-        *err = "stage rollback baseline";
+    nvs_handle_t h;
+    if (nvs_open(kNs, NVS_READWRITE, &h) != ESP_OK) {
+        *err = "nvs open failed";
         return false;
     }
-    OtaErr kind = OtaErr::kTransient;
-    if (!install_build(kLastGoodTmp, err, &kind)) {
-        unlink(kLastGoodTmp);
+    // Move the .tgz out of the deploy tmp tree before acking: MIK_DeployRecover
+    // cleans that tree at boot, before the reconcile would read it. Rename
+    // before anything else mutates: a failed rename (e.g. littlefs metadata
+    // ENOSPC) must error back over serial having left trial state untouched.
+    unlink(kPending);
+    if (rename(tgz_path, kPending) != 0) {
+        nvs_close(h);
+        *err = "stage pending build";
         return false;
     }
-    unlink(kLastGood);
-    if (rename(kLastGoodTmp, kLastGood) != 0) {
-        // Installed and live, but with no revert target until the next adopt or
-        // promote. Not worth failing the deploy over.
-        unlink(kLastGoodTmp);
-    }
-    nvs_handle_t h;
-    if (nvs_open(kNs, NVS_READWRITE, &h) == ESP_OK) {
-        nvs_set_str(h, kKeyInstChk, checksum ? checksum : "");
+    // A cable deploy supersedes an in-flight trial. Resolve it to GOOD now,
+    // while the trial's checksum is still in pendChk (overwritten below): the
+    // trial build is what /app holds, so it becomes the installed build, the
+    // same accounting the reflash guard does. Without this, the next boot's
+    // trial verdict would roll back or promote against the pending slot this
+    // deploy just replaced.
+    if (nvs_u8(h, kKeyState, kStateGood) == kStateTrial) {
+        char trial_chk[96];
+        if (nvs_str(h, kKeyPendChk, trial_chk, sizeof(trial_chk))) {
+            nvs_set_str(h, kKeyInstChk, trial_chk);
+        }
         nvs_set_u8(h, kKeyState, kStateGood);
         nvs_set_u8(h, kKeyTrialLeft, 0);
-        nvs_set_u8(h, kKeyPending, 0);
+        nvs_erase_key(h, kKeyPromLeft);
+        nvs_erase_key(h, kKeyRbLeft);
+        nvs_erase_key(h, kKeyNeutLeft);
         clear_trial_failure(h);
-        unlink(kPending);
-        nvs_erase_key(h, kKeyPendChk);
-        nvs_commit(h);
-        nvs_close(h);
     }
+    nvs_set_str(h, kKeyPendChk, checksum ? checksum : "");
+    nvs_set_u8(h, kKeyPendMode, kPendModeAdopt);
+    nvs_set_u8(h, kKeyPending, 1);
+    nvs_set_u8(h, kKeyInstLeft, 1);  // one attempt: the developer is on the cable
+    // Drop any unread outcome from an earlier adopt (e.g. a --no-restart deploy
+    // that installed at a natural boot), so the post-restart result read can
+    // only ever see this deploy's outcome.
+    nvs_erase_key(h, kKeyDRes);
+    nvs_erase_key(h, kKeyDChk);
+    nvs_erase_key(h, kKeyDRsn);
+    nvs_erase_key(h, kKeyDDetail);
+    nvs_commit(h);
+    nvs_close(h);
     return true;
 }
 
+// Read and clear the adopt-install outcome for MIK_CMD_DEPLOY_RESULT.
+void mik__ota_take_deploy_result(MIKDeployResult* out) {
+    memset(out, 0, sizeof(*out));
+    nvs_handle_t h;
+    if (nvs_open(kNs, NVS_READWRITE, &h) != ESP_OK) return;
+    out->status = nvs_u8(h, kKeyDRes, 0);
+    nvs_str(h, kKeyDChk, out->checksum, sizeof(out->checksum));
+    nvs_str(h, kKeyDRsn, out->reason, sizeof(out->reason));
+    nvs_str(h, kKeyDDetail, out->detail, sizeof(out->detail));
+    if (out->status != 0) {
+        nvs_erase_key(h, kKeyDRes);
+        nvs_erase_key(h, kKeyDChk);
+        nvs_erase_key(h, kKeyDRsn);
+        nvs_erase_key(h, kKeyDDetail);
+        nvs_commit(h);
+    }
+    nvs_close(h);
+}
+
 // True while an unconfirmed OTA trial is the running build.
 bool mik__ota_in_trial(void) {
     nvs_handle_t h;
@@ -1564,15 +1597,16 @@ void mik__ota_note_trial_failure(const char* detail) {
 }
 
 // Boot reconcile: NOT JS-exposed. Called from MIK_Main() before the JS app
-// loads, after MIK_DeployRecover(). Runs the reflash guard, the trial verdict,
-// and a deferred install in that order.
+// loads, after MIK_DeployRecover(). Runs the reflash guard, an adopt install
+// (cable deploy), the trial verdict, and a deferred trial install in that
+// order.
 void mik__ota_boot_reconcile(void) {
     nvs_handle_t h;
     if (nvs_open(kNs, NVS_READWRITE, &h) != ESP_OK) return;
 
-    // An adopt that died between copying its install source and promoting it to
-    // the rollback slot leaves this behind. It is never valid across a boot, and
-    // it is a whole build's worth of flash.
+    // Legacy leftover: firmware that installed cable deploys synchronously
+    // staged its install source here and could die before promoting it. Never
+    // valid across a boot, and a whole build's worth of flash.
     unlink(kLastGoodTmp);
 
     // 1. Reflash guard. An out-of-band `idf.py flash` swaps the firmware without
@@ -1602,6 +1636,7 @@ void mik__ota_boot_reconcile(void) {
             }
         }
         nvs_erase_key(h, kKeyPendChk);
+        nvs_erase_key(h, kKeyPendMode);
         nvs_set_u8(h, kKeyState, kStateGood);
         nvs_set_u8(h, kKeyTrialLeft, 0);
         nvs_set_u8(h, kKeyPending, 0);
@@ -1613,7 +1648,65 @@ void mik__ota_boot_reconcile(void) {
         nvs_commit(h);
     }
 
-    // 2. Trial verdict. Evaluate why we just reset while a trial was in flight.
+    // 2. Adopt install: a cable deploy staged by MIK_CMD_DEPLOY_BUILD. No
+    //    trial, no rollback baseline, one attempt (charged before the attempt,
+    //    same crash reasoning as the deferred install below). Runs before the
+    //    trial verdict as a backstop: stage_adopt resolves an in-flight trial
+    //    at stage time, but stale trial state must never roll back or promote
+    //    against the pending slot the deploy overwrote.
+    if (nvs_u8(h, kKeyPending, 0) == 1 &&
+        nvs_u8(h, kKeyPendMode, kPendModeTrial) == kPendModeAdopt) {
+        char chk[96] = {0};
+        nvs_str(h, kKeyPendChk, chk, sizeof(chk));
+        if (!path_exists(kPending)) {
+            adopt_fail(h, chk, "install-failed", "staged build missing");
+            nvs_close(h);
+            return;
+        }
+        uint8_t left = nvs_u8(h, kKeyInstLeft, 1);
+        if (left == 0) {
+            // The charged attempt never came back: the install panicked.
+            adopt_fail(h, chk, "install-failed", "install did not complete (device restarted)");
+            nvs_close(h);
+            return;
+        }
+        nvs_set_u8(h, kKeyInstLeft, (uint8_t)(left - 1));
+        nvs_commit(h);
+
+        const char* err = nullptr;
+        OtaErr kind = OtaErr::kTransient;
+        if (!install_build(kPending, &err, &kind)) {
+            adopt_fail(h, chk, kind == OtaErr::kCorrupt ? "install-corrupt" : "install-failed",
+                       err != nullptr ? err : "install failed");
+            nvs_close(h);
+            return;
+        }
+        // Installed. A cable deploy resets the OTA safety story like a reflash
+        // does: nothing to roll back to until the next OTA trial promotes.
+        unlink(kPending);
+        unlink(kLastGood);
+        nvs_set_str(h, kKeyInstChk, chk);
+        nvs_set_u8(h, kKeyState, kStateGood);
+        nvs_set_u8(h, kKeyTrialLeft, 0);
+        nvs_set_u8(h, kKeyPending, 0);
+        nvs_erase_key(h, kKeyPendChk);
+        nvs_erase_key(h, kKeyPendMode);
+        nvs_erase_key(h, kKeyInstLeft);
+        nvs_erase_key(h, kKeyPromLeft);
+        nvs_erase_key(h, kKeyRbLeft);
+        nvs_erase_key(h, kKeyNeutLeft);
+        clear_trial_failure(h);
+        nvs_set_u8(h, kKeyDRes, 1);
+        nvs_set_str(h, kKeyDChk, chk);
+        nvs_erase_key(h, kKeyDRsn);
+        nvs_erase_key(h, kKeyDDetail);
+        nvs_commit(h);
+        nvs_close(h);
+        esp_restart();  // boot into the deployed app on a clean heap
+        return;
+    }
+
+    // 3. Trial verdict. Evaluate why we just reset while a trial was in flight.
     if (nvs_u8(h, kKeyState, kStateGood) == kStateTrial) {
         esp_reset_reason_t reason = esp_reset_reason();
         TrialVerdict verdict = classify_reset(reason);
@@ -1715,8 +1808,10 @@ void mik__ota_boot_reconcile(void) {
         // kNeutral: don't penalize — leave the trial untouched and proceed.
     }
 
-    // 3. Deferred install. A build verified by stageFinish(installNow=false) is
-    //    installed here, on a clean heap, then we restart into its trial.
+    // 4. Deferred trial install. A build verified by stageFinish(installNow=
+    //    false) is installed here, on a clean heap, then we restart into its
+    //    trial. (An adopt-mode pending build never reaches this: step 2
+    //    returns.)
     if (nvs_u8(h, kKeyPending, 0) == 1 && nvs_u8(h, kKeyState, kStateGood) == kStateGood) {
         if (!path_exists(kPending)) {
             nvs_set_u8(h, kKeyPending, 0);

package/index.d.ts

@@ -5,3 +5,4 @@ export const projectCmakePath: string
 
 export function prebuiltFirmwareDir(chip: string): string
 export function hasPrebuiltFirmware(chip: string): boolean
+export function prebuiltFirmwareName(chip: string): string | undefined

package/index.js

@@ -1,4 +1,4 @@
-import {existsSync} from 'node:fs'
+import {existsSync, readFileSync} from 'node:fs'
 import {dirname, join} from 'node:path'
 import {fileURLToPath} from 'node:url'
 
@@ -18,3 +18,15 @@ export function prebuiltFirmwareDir(chip) {
 export function hasPrebuiltFirmware(chip) {
   return existsSync(join(prebuildsRoot, chip, 'flasher_args.json'))
 }
+
+/** Identity of the bundled prebuilt for `chip` (the package name of the
+ *  firmware project it was built from), or undefined when no prebuilt or no
+ *  recorded identity exists. */
+export function prebuiltFirmwareName(chip) {
+  try {
+    const {name} = JSON.parse(readFileSync(join(prebuildsRoot, chip, 'firmware.json'), 'utf8'))
+    return typeof name === 'string' ? name : undefined
+  } catch {
+    return undefined
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/firmware",
-  "version": "0.17.0-pr-276.20260721233726",
+  "version": "0.17.0",
   "description": "Mikro.js ESP32 firmware: ESP-IDF component, build tools, and project template",
   "keywords": [
     "esp-idf",
@@ -47,8 +47,8 @@
   },
   "dependencies": {
     "esbuild": "^0.28.0",
-    "@mikrojs/native": "0.17.0-pr-276.20260721233726+1bcc126",
-    "@mikrojs/quickjs": "0.17.0-pr-276.20260721233726+1bcc126"
+    "@mikrojs/quickjs": "0.17.0",
+    "@mikrojs/native": "0.17.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/prebuilds/esp32/firmware.json

@@ -0,0 +1 @@
+{"name":"@mikrojs/firmware-dev"}

package/prebuilds/esp32c3/firmware.json

@@ -0,0 +1 @@
+{"name":"@mikrojs/firmware-dev"}

package/prebuilds/esp32c5/firmware.json

@@ -0,0 +1 @@
+{"name":"@mikrojs/firmware-dev"}

package/prebuilds/esp32c6/firmware.json

@@ -0,0 +1 @@
+{"name":"@mikrojs/firmware-dev"}

package/prebuilds/esp32s3/firmware.json

@@ -0,0 +1 @@
+{"name":"@mikrojs/firmware-dev"}

package/project.cmake

@@ -81,16 +81,58 @@ if(EXISTS "${CMAKE_SOURCE_DIR}/sdkconfig.defaults.${IDF_TARGET}")
     list(APPEND _SDKCONFIG_LIST "${CMAKE_SOURCE_DIR}/sdkconfig.defaults.${IDF_TARGET}")
 endif()
 
-# Partition table: generate a sdkconfig fragment with the absolute path
+# Partition table: copy the source csv into the build dir and point the
+# config at it, project-relative when possible (ESP-IDF resolves a relative
+# value against the project dir). Writing the resolved package path directly
+# would freeze an absolute node_modules/store path into sdkconfig — sdkconfig
+# wins over defaults files, so every @mikrojs/firmware upgrade would then
+# break the build with a missing-partitions.csv error pointing at a version
+# that is no longer installed.
 if(EXISTS "${CMAKE_SOURCE_DIR}/partitions.csv")
-    set(_PARTITION_CSV "${CMAKE_SOURCE_DIR}/partitions.csv")
+    set(_PARTITION_SRC "${CMAKE_SOURCE_DIR}/partitions.csv")
 else()
-    set(_PARTITION_CSV "${_MIK_CONFIG_DIR}/partitions.csv")
+    set(_PARTITION_SRC "${_MIK_CONFIG_DIR}/partitions.csv")
 endif()
-set(_PARTITION_FRAGMENT "${CMAKE_SOURCE_DIR}/build/sdkconfig.partitions")
+configure_file("${_PARTITION_SRC}" "${CMAKE_BINARY_DIR}/partitions.csv" COPYONLY)
+file(RELATIVE_PATH _PARTITION_CSV "${CMAKE_SOURCE_DIR}" "${CMAKE_BINARY_DIR}/partitions.csv")
+if(_PARTITION_CSV MATCHES "^\\.\\.")
+    # Build dir outside the project (idf.py -B): absolute path, still stable
+    # across package upgrades, and the heal below re-points it if it moves.
+    set(_PARTITION_CSV "${CMAKE_BINARY_DIR}/partitions.csv")
+endif()
+set(_PARTITION_FRAGMENT "${CMAKE_BINARY_DIR}/sdkconfig.partitions")
 file(WRITE "${_PARTITION_FRAGMENT}" "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"${_PARTITION_CSV}\"\n")
 list(APPEND _SDKCONFIG_LIST "${_PARTITION_FRAGMENT}")
 
+# Heal an sdkconfig whose frozen path points outside the project: a stale
+# resolved package path, or a build dir that moved. Must fire even when the
+# frozen file still exists — an older package version often is still in the
+# store, and its old partition table would be built silently. Paths inside
+# the project are deliberate menuconfig overrides and are left alone.
+if(EXISTS "${CMAKE_SOURCE_DIR}/sdkconfig")
+    file(READ "${CMAKE_SOURCE_DIR}/sdkconfig" _SDKCONFIG_CONTENT)
+    string(REGEX MATCH "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"([^\"]*)\"" _PARTITION_MATCH "${_SDKCONFIG_CONTENT}")
+    if(_PARTITION_MATCH AND NOT CMAKE_MATCH_1 STREQUAL "${_PARTITION_CSV}")
+        set(_PARTITION_FROZEN "${CMAKE_MATCH_1}")
+        get_filename_component(_PARTITION_FROZEN_ABS "${_PARTITION_FROZEN}" ABSOLUTE BASE_DIR "${CMAKE_SOURCE_DIR}")
+        string(FIND "${_PARTITION_FROZEN_ABS}" "${CMAKE_SOURCE_DIR}/" _PARTITION_INSIDE)
+        if(NOT _PARTITION_INSIDE EQUAL 0)
+            string(REGEX REPLACE "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"[^\"]*\""
+                   "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"${_PARTITION_CSV}\""
+                   _SDKCONFIG_CONTENT "${_SDKCONFIG_CONTENT}")
+            # The derived twin should be recomputed by kconfgen, but rewrite it
+            # too: if it kept the saved value the build breaks the same way.
+            string(REGEX REPLACE "CONFIG_PARTITION_TABLE_FILENAME=\"[^\"]*\""
+                   "CONFIG_PARTITION_TABLE_FILENAME=\"${_PARTITION_CSV}\""
+                   _SDKCONFIG_CONTENT "${_SDKCONFIG_CONTENT}")
+            file(WRITE "${CMAKE_SOURCE_DIR}/sdkconfig" "${_SDKCONFIG_CONTENT}")
+            message(WARNING
+                "mikrojs: sdkconfig CONFIG_PARTITION_TABLE_CUSTOM_FILENAME pointed outside "
+                "the project (\"${_PARTITION_FROZEN}\"); repointed at \"${_PARTITION_CSV}\"")
+        endif()
+    endif()
+endif()
+
 if(_BOARD_JSON)
     string(JSON _BOARD_COMPONENT_DIRS GET "${_BOARD_JSON}" "components")
     string(JSON _BOARD_SDKCONFIG_DEFAULTS GET "${_BOARD_JSON}" "sdkconfigs")

package/resolve.js

@@ -12,6 +12,7 @@
  *   quickjs          — path to quickjs.cmake
  *   native           — JSON with native package paths
  *   version          — firmware package version
+ *   projectName <dir> — package.json name of the consuming project (empty if none)
  *   discover <dir>   — discover board/driver components from project dir
  */
 import {componentDir, projectCmakePath} from './cmake.js'
@@ -44,6 +45,15 @@ if (query === 'componentDir') {
 } else if (query === 'version') {
   const {default: pkg} = await import('./package.json', {with: {type: 'json'}})
   process.stdout.write(pkg.version)
+} else if (query === 'projectName') {
+  const {readFileSync} = await import('node:fs')
+  const {join} = await import('node:path')
+  try {
+    const pkg = JSON.parse(readFileSync(join(process.argv[3], 'package.json'), 'utf8'))
+    if (typeof pkg.name === 'string') process.stdout.write(pkg.name)
+  } catch {
+    // No package.json (e.g. on-device test apps): no identity, empty output.
+  }
 } else if (query === 'discover') {
   const projectDir = process.argv[3]
   const {discover} = await import('./discover.js')