@blamejs/core 0.17.11 → 0.17.13

package/lib/self-update.js

@@ -57,7 +57,6 @@ var nodeCrypto = require("node:crypto");
 var numericBounds = require("./numeric-bounds");
 var atomicFile = require("./atomic-file");
 var validateOpts = require("./validate-opts");
-var bCrypto = require("./crypto");
 var guardRegex = require("./guard-regex");
 var httpClient = require("./http-client");
 var safeJson = require("./safe-json");
@@ -301,6 +300,60 @@ function _matchAsset(name, pattern, fallback) {
   return fallback ? fallback.test(name) : false;
 }
 
+// Detached-signature suffixes. A release's detached signature is conventionally
+// the asset name plus one of these (asset.tar.gz.sig / .asc / .sig.bin).
+var _SIG_SUFFIXES = [".sig", ".asc", ".sig.bin"];
+var _SIG_SHAPE    = /\.sig$|\.asc$|\.sig\.bin$/i;
+
+function _assetObj(a) {
+  return {
+    name:   a.name,
+    url:    a.browser_download_url,
+    size:   a.size || null,
+    digest: typeof a.digest === "string" ? a.digest : null,
+  };
+}
+
+function _findEntryByName(entries, name) {
+  for (var i = 0; i < entries.length; i++) {
+    if (entries[i].name === name) return entries[i];
+  }
+  return null;
+}
+
+// _selectSignatureFor — pick the detached signature OF `assetName`, not a
+// first-match-wins signature that may sign a DIFFERENT sidecar. Selecting the
+// asset first and DERIVING the expected signature name from it is the pairing
+// contract: a returned { asset, signature } is guaranteed to be an asset and
+// the signature over exactly that asset. Falls back to a lone signature-shaped
+// asset only when the release ships exactly one (the common one-asset-one-sig
+// case); anything ambiguous fails closed (null) rather than pairing a signature
+// that may not sign the returned asset.
+function _selectSignatureFor(assetName, entries, signaturePattern) {
+  // (a) Strong pairing: the asset name plus a signature suffix.
+  for (var s = 0; s < _SIG_SUFFIXES.length; s++) {
+    var hit = _findEntryByName(entries, assetName + _SIG_SUFFIXES[s]);
+    // When the operator constrained signaturePattern, the derived name must
+    // also satisfy it; otherwise the derived name is authoritative.
+    if (hit && (signaturePattern === undefined || _matchAsset(hit.name, signaturePattern, null))) {
+      return _assetObj(hit);
+    }
+  }
+  // (b) Operator signaturePattern, no derived hit: accept only a pattern match
+  // that ALSO references the asset stem, and only when unambiguous — else fail
+  // closed (never pair a pattern hit that may sign a different asset).
+  if (signaturePattern !== undefined) {
+    var stemMatches = entries.filter(function (e) {
+      return e.name.indexOf(assetName) === 0 && _matchAsset(e.name, signaturePattern, null);
+    });
+    return stemMatches.length === 1 ? _assetObj(stemMatches[0]) : null;
+  }
+  // (c) No operator pattern, no derived hit: accept a lone signature-shaped
+  // asset (single-sig release), else null.
+  var sigShaped = entries.filter(function (e) { return _SIG_SHAPE.test(e.name); });
+  return sigShaped.length === 1 ? _assetObj(sigShaped[0]) : null;
+}
+
 /**
  * @primitive b.selfUpdate.poll
  * @signature b.selfUpdate.poll(opts)
@@ -474,21 +527,27 @@ async function poll(opts) {
   }
 
   var assets = Array.isArray(latest.assets) ? latest.assets : [];
-  var assetMatch     = null;
-  var signatureMatch = null;
+  // Collect the well-formed asset entries once, preserving feed order.
+  var entries = [];
   for (var i = 0; i < assets.length; i++) {
     var a = assets[i] || {};
     if (typeof a.name !== "string" || typeof a.browser_download_url !== "string") continue;
-    if (signatureMatch === null && _matchAsset(a.name, opts.signaturePattern, /\.sig$|\.asc$|\.sig\.bin$/i)) {
-      signatureMatch = { name: a.name, url: a.browser_download_url, size: a.size || null,
-                         digest: typeof a.digest === "string" ? a.digest : null };
-      continue;
-    }
-    if (assetMatch === null && _matchAsset(a.name, opts.assetPattern, /\.(tar\.gz|tgz|zip|node|exe|bin)$/i)) {
-      assetMatch = { name: a.name, url: a.browser_download_url, size: a.size || null,
-                     digest: typeof a.digest === "string" ? a.digest : null };
+    entries.push(a);
+  }
+  // Select the runtime asset FIRST, then derive its detached signature — so the
+  // returned signature is the sig OF the returned asset, never a first-match-wins
+  // sig that may belong to a different sidecar (#497).
+  var assetMatch     = null;
+  var signatureMatch = null;
+  for (var j = 0; j < entries.length; j++) {
+    if (_matchAsset(entries[j].name, opts.assetPattern, /\.(tar\.gz|tgz|zip|node|exe|bin)$/i)) {
+      assetMatch = _assetObj(entries[j]);
+      break;
     }
   }
+  if (assetMatch) {
+    signatureMatch = _selectSignatureFor(assetMatch.name, entries, opts.signaturePattern);
+  }
 
   _safeAuditEmit("selfupdate.poll.checked", "success", {
     releasesUrl:    opts.releasesUrl,
@@ -539,13 +598,20 @@ function _validateVerifyOpts(opts) {
  * @since     0.6.0
  * @related   b.selfUpdate.poll, b.selfUpdate.swap, b.crypto.verify
  *
- * Verify a detached signature over the asset bytes. The algorithm is
- * auto-detected from `opts.pubkeyPem` (ML-DSA-87 / Ed25519 / ECDSA
- * P-384) by `b.crypto.verify`. Reports the asset's hash alongside the
- * verified flag for SBOM / audit correlation; the supported digest
- * algorithms are sha3-512 (default), sha-256, sha-512, and shake256.
- * Throws SelfUpdateError on a missing file, a verify-time exception,
- * or a signature that does not verify.
+ * Verify a detached signature over the asset bytes. The signature
+ * algorithm is auto-detected from `opts.pubkeyPem` (ML-DSA-87 / Ed25519
+ * / ECDSA P-384). Verification routes through the framework's own
+ * `standaloneVerifier`, which streams the asset (no whole-file buffer),
+ * commits to a SHA3-512 digest, and dispatches the ECDSA signature
+ * encoding by structure (DER SEQUENCE vs raw IEEE-P1363) — so a release
+ * sidecar signed SHA3-512-then-sign with either encoding verifies, and
+ * the accept set is identical to `b.selfUpdate.standaloneVerifier.verify`
+ * (no verifier divergence between the install-pipeline and installed
+ * paths). Reports the asset's hash alongside the verified flag for SBOM /
+ * audit correlation; the supported digest algorithms are sha3-512
+ * (default), sha-256, sha-512, and shake256. Throws SelfUpdateError on a
+ * missing file, a verify-time exception, or a signature that does not
+ * verify.
  *
  * @opts
  *   assetPath:     string,   // required — path to the downloaded asset
@@ -565,56 +631,67 @@ function _validateVerifyOpts(opts) {
  *     e.code;                 // → "selfupdate/read-failed"
  *   }
  */
+// _mapStandaloneKind — translate a standaloneVerifier `.kind` into this
+// module's typed selfupdate/* code. File-availability / size-cap failures are
+// read-failed; a cryptographic non-verification is signature-mismatch; a
+// structural / key / encoding problem is verify-failed. Keeping the mapping
+// structural (off `.kind`, not English message text) means a message reword in
+// the zero-dep verifier never silently reclassifies a failure here.
+function _mapStandaloneKind(kind) {
+  switch (kind) {
+    case "asset-not-found":
+    case "sig-not-found":
+    case "sig-too-large":
+    case "asset-too-large":
+    case "size-race":
+      return "selfupdate/read-failed";
+    case "verify-failed":
+      return "selfupdate/signature-mismatch";
+    default:   // bad-input / bad-pubkey / unsupported-key / sig-empty / bad-sig-encoding
+      return "selfupdate/verify-failed";
+  }
+}
+
 async function verify(opts) {
   _validateVerifyOpts(opts);
   var alg = opts.hashAlgo || DEFAULT_HASH_ALG;
+  var maxBytes = typeof opts.maxBytes === "number" ? opts.maxBytes : C.BYTES.gib(1);
+  // The default sha3-512 / sha-256 reported digests are already produced by the
+  // standalone verifier's single pass; only a non-default reported alg needs an
+  // extra digest folded into that same stream (no second read of the asset).
+  var extraDigests = (alg === "sha3-512" || alg === "sha-256") ? [] : [alg];
 
-  var assetBytes;
-  var sigBytes;
+  var result;
   try {
-    assetBytes = await atomicFile.read(opts.assetPath, {
-      maxBytes: typeof opts.maxBytes === "number" ? opts.maxBytes : C.BYTES.gib(1),
-    });
-    sigBytes = await atomicFile.read(opts.signaturePath, {
-      maxBytes: C.BYTES.kib(64),
+    // Route the signature verification through the framework's own
+    // standaloneVerifier so the installed path and the copy-into-install-pipeline
+    // path share ONE verifier — SHA3-512 digest, DER/IEEE-P1363 structural
+    // dispatch, streamed (no whole-asset in-memory buffer). It fails closed on a
+    // wrong key, truncated / empty signature, or size-cap breach.
+    result = standaloneVerifier.verify(opts.assetPath, opts.signaturePath, opts.pubkeyPem, {
+      maxAssetBytes: maxBytes,
+      extraDigests:  extraDigests,
     });
   } catch (e) {
+    var code = _mapStandaloneKind(e && e.kind);
     _safeAuditEmit("selfupdate.verify.failed", "denied", {
       assetPath: opts.assetPath, signaturePath: opts.signaturePath,
-      reason: "read-failed", message: (e && e.message) || String(e),
-    });
-    throw new SelfUpdateError("selfupdate/read-failed",
-      "selfUpdate.verify: read failed: " + ((e && e.message) || String(e)));
-  }
-
-  var ok = false;
-  try { ok = bCrypto.verify(assetBytes, sigBytes, opts.pubkeyPem); }
-  catch (e) {
-    _safeAuditEmit("selfupdate.verify.failed", "denied", {
-      assetPath: opts.assetPath, signaturePath: opts.signaturePath,
-      reason: "verify-threw", message: (e && e.message) || String(e),
+      reason: (e && e.kind) || "verify-error", message: (e && e.message) || String(e),
     });
-    throw new SelfUpdateError("selfupdate/verify-failed",
-      "selfUpdate.verify: signature verify threw: " + ((e && e.message) || String(e)));
+    throw new SelfUpdateError(code,
+      "selfUpdate.verify: " + ((e && e.message) || String(e)));
   }
 
-  var hashHex = nodeCrypto.createHash(alg).update(assetBytes).digest("hex");
-
-  if (!ok) {
-    _safeAuditEmit("selfupdate.verify.failed", "denied", {
-      assetPath: opts.assetPath, signaturePath: opts.signaturePath,
-      alg: alg, hash: hashHex, reason: "signature-mismatch",
-    });
-    throw new SelfUpdateError("selfupdate/signature-mismatch",
-      "selfUpdate.verify: signature did not verify against the supplied public key");
-  }
+  var hashHex = alg === "sha3-512" ? result.sha3_512
+              : alg === "sha-256"  ? result.sha256
+              : result.digests[alg];
 
   _safeAuditEmit("selfupdate.verify.passed", "success", {
     assetPath: opts.assetPath, signaturePath: opts.signaturePath,
-    alg: alg, hash: hashHex, bytes: assetBytes.length,
+    alg: alg, hash: hashHex, bytes: result.bytes,
   });
   log("selfUpdate.verify passed asset=" + opts.assetPath + " alg=" + alg);
-  return { verified: true, hash: hashHex, alg: alg, bytes: assetBytes.length };
+  return { verified: true, hash: hashHex, alg: alg, bytes: result.bytes };
 }
 
 // ---- swap ----
@@ -656,25 +733,47 @@ function _validateSwapOpts(opts, label) {
   validateOpts.shape(opts, schema, "selfUpdate." + label, SelfUpdateError, "selfupdate/bad-opts");
 }
 
-// _safeRollback — best-effort restore of `to` from `backupTo` during
-// the swap failure paths. Returns null on success (or when no backup
-// existed); returns the rollback Error otherwise so the caller can
-// throw a distinct `selfupdate/swap-rollback-failed`. Emits the
-// `selfupdate.swap.rollback_failed` audit event when rollback fails
-// (the prior best-effort catch dropped this signal silently —
-// operators with no audit row for `rollback_failed` couldn't tell a
-// successful swap-with-rollback from a failed both-binaries-lost
-// scenario). SSDF RV.1.
+// _relocateFile — move `src` -> `dst`, preferring an atomic rename. A rename
+// moves even a locked, RUNNING image on Windows (which refuses an in-place
+// replace of a mapped executable but allows a rename/move) and needs no second
+// copy; on EXDEV (cross-volume) it falls back to copy + unlink. This one
+// primitive backs BOTH "move the outgoing `to` aside to its backup before an
+// install" and "restore the backup over `to` on rollback", so the locked-image
+// path is handled identically in the install and rollback directions.
+async function _relocateFile(src, dst, fileMode) {
+  try {
+    atomicFile.renameWithRetry(src, dst);
+    return;
+  } catch (e) {
+    if (!e || e.code !== "EXDEV") throw e;
+    // Cross-volume: a rename can't cross the device boundary. Preserve the
+    // bytes by copy, then remove the source (best-effort — a locked cross-volume
+    // source is the documented limitation of this rare fallback).
+    await atomicFile.copy(src, dst, { fileMode: fileMode });
+    try { nodeFs.unlinkSync(src); } catch (_u) { /* cross-vol source cleanup — operator-cleanable */ }
+  }
+}
+
+// _safeRollback — best-effort restore of `to` from `backupTo` during the swap
+// failure paths. Routes through _relocateFile so the moved-aside backup is
+// renamed back over the (now-absent) `to` — a rename that succeeds even where an
+// in-place copy-replace would be blocked by a lock. Returns null on success (or
+// when no backup existed); returns the rollback Error otherwise so the caller
+// can throw a distinct `selfupdate/swap-rollback-failed`. Emits the
+// `selfupdate.swap.rollback_failed` audit event when rollback fails (the prior
+// best-effort catch dropped this signal silently — operators with no audit row
+// for `rollback_failed` couldn't tell a successful swap-with-rollback from a
+// failed both-binaries-lost scenario). SSDF RV.1.
 async function _safeRollback(backupTo, to, hadOriginal) {
   if (!hadOriginal) return null;
   try {
-    await atomicFile.copy(backupTo, to, { fileMode: 0o600 });
+    await _relocateFile(backupTo, to, 0o600);
     return null;
   } catch (re) {
     var err = re instanceof Error ? re : new Error(String(re));
     _safeAuditEmit("selfupdate.swap.rollback_failed", "denied", {
       to: to, backupTo: backupTo,
-      reason: "rollback-copy-failed",
+      reason: "rollback-restore-failed",
       message: err.message,
     });
     return err;
@@ -684,29 +783,33 @@ async function _safeRollback(backupTo, to, hadOriginal) {
 // Atomic swap of `from` -> `to` with rollback on failure. Steps:
 //
 //   1. ensure `to` and `backupTo` parents exist
-//   2. if `to` exists — copy bytes to `backupTo` (atomic write of the
-//      backup, preserving the original on `to` until step 3)
-//   3. rename `from` -> `to` (atomic on the same FS; cross-device is
-//      detected and surfaced as selfupdate/cross-device)
+//   2. if `to` exists — MOVE it aside to `backupTo` via a rename (this both
+//      frees `to` and IS the backup). A rename moves even a locked, running
+//      image on Windows, where an in-place replace of a mapped exe is refused;
+//      cross-volume (EXDEV) falls back to copy + unlink.
+//   3. write the verified in-memory bytes to the now-free `to` (a create, not
+//      a replace of a locked file)
 //   4. fsync both directories (best-effort across platforms)
 //
-// If step 3 fails the backup remains; if step 4 fails the swap is
-// considered complete (operator can audit) but a warning is logged.
+// If step 2 fails the original `to` is intact (surfaced as backup-failed); if
+// step 3 fails the moved-aside backup is renamed back over `to` (rollback); if
+// step 4 fails the swap is considered complete (operator can audit).
 /**
  * @primitive b.selfUpdate.swap
  * @signature b.selfUpdate.swap(opts)
  * @since     0.6.0
- * @related   b.selfUpdate.verify, b.selfUpdate.rollback, b.atomicFile.copy
+ * @related   b.selfUpdate.verify, b.selfUpdate.rollback, b.atomicFile.write
  *
  * Atomic install: re-hash `from` and refuse unless it matches `expectedHash`
  * (the hash selfUpdate.verify returned — this binds the installed bytes to the
- * signature-verified bytes and closes the verify→swap window), copy the
- * existing `to` to `backupTo`, rename `from` → `to`, then fsync both
- * directories. Cross-device renames fall back to copy + unlink on the
- * destination filesystem. On any failure the original `to` is restored from
- * `backupTo`. Throws SelfUpdateError on a missing `from`, an
- * expectedHash mismatch, backup-copy failure, cross-device install failure,
- * or rename failure.
+ * signature-verified bytes and closes the verify→swap window), MOVE the existing
+ * `to` aside to `backupTo` with a rename (which succeeds on a locked, running
+ * image where an in-place replace is refused, and IS the backup), write the
+ * verified bytes to the now-free `to`, then fsync both directories. `backupTo`
+ * must be on the same volume as `to`; a cross-volume backup (EXDEV) falls back to
+ * copy + replace. On an install-write failure after the move-aside, the backup is
+ * restored over `to`. Throws SelfUpdateError on a missing `from`, an expectedHash
+ * mismatch, a move-aside/backup failure, or an install-write failure.
  *
  * @opts
  *   from:         string,   // required — newly-installed asset path
@@ -777,26 +880,31 @@ async function swap(opts) {
   atomicFile.ensureDir(toDir);
   atomicFile.ensureDir(backupDir);
 
-  // Step 2 — backup if `to` exists. Use atomicFile.copy so the backup
-  // hits disk via temp+fsync+rename.
+  // Step 2 — move the outgoing `to` ASIDE to `backupTo` via a rename. A rename
+  // frees the path even when `to` is a locked, running image (Windows refuses an
+  // in-place replace of a mapped executable but allows the move), and the moved
+  // file IS the backup — so no separate copy of the old bytes is needed. The
+  // move-aside failing leaves the original `to` intact (surfaced as backup-failed).
   var hadOriginal = nodeFs.existsSync(to);
   if (hadOriginal) {
     try {
-      await atomicFile.copy(to, backupTo, { fileMode: 0o600 });
+      await _relocateFile(to, backupTo, 0o600);
     } catch (e) {
       throw new SelfUpdateError("selfupdate/backup-failed",
-        "selfUpdate.swap: failed to copy " + to + " -> " + backupTo + ": " +
+        "selfUpdate.swap: failed to move " + to + " aside to " + backupTo + ": " +
         ((e && e.message) || String(e)));
     }
   }
 
-  // Step 3 — install the verified in-memory bytes via an atomic temp+fsync+
-  // rename on the DESTINATION filesystem (atomicFile.write), so the installed
-  // object is exactly the bytes just hashed: cross-device is handled (the temp
-  // is created on the dest FS), there is no by-path re-read to race, and a
-  // symlinked source can't be moved into place. Roll back from the backup on
-  // failure; a rollback failure surfaces as a DISTINCT error class + audit
-  // event so operators don't silently lose both binaries (SSDF RV.1).
+  // Step 3 — install the verified in-memory bytes at the now-free `to` via an
+  // atomic temp+fsync+rename (atomicFile.write). With `to` moved aside (or never
+  // present), this rename is a CREATE at a free path, not a replace of a locked
+  // file — so it succeeds on a running Windows image. The installed object is
+  // exactly the bytes just hashed (installed from memory), so there is no by-path
+  // re-read to race and no symlinked source to move into place. On failure the
+  // moved-aside backup is renamed back over `to`; a rollback failure surfaces as
+  // a DISTINCT error class + audit event so operators don't silently lose both
+  // binaries (SSDF RV.1).
   try {
     await atomicFile.write(to, fromBytes, { fileMode: fromMode, overwrite: true });
   } catch (e) {
@@ -882,11 +990,313 @@ async function rollback(opts) {
   return { ok: true, restoredAt: Date.now(), to: to, backupTo: backupTo };
 }
 
+// ---- probation / auto-rollback orchestration ----
+//
+// A swap installs the new binary; probation gives it a bounded window to prove
+// itself before the install is considered final. The new binary (or the
+// operator's shutdown hook) calls confirmHealthy() once it is up + healthy,
+// which clears the marker — the "clean / healthy" signal. On the next boot
+// evaluateOnBoot() reads the marker: still inside the window means a clean stop /
+// restart (NOT a crash) so it keeps; past the window with no confirmHealthy means
+// the binary never became healthy so it rolls the known-good backup back over the
+// target. Rollback re-verifies first (the installed bytes must still hash to the
+// probationary expectedHash and the backup must exist) so a marker left behind by
+// a swap that FAILED — where the new binary was never installed — never triggers
+// a phantom rollback.
+
+var PROBATION_MARKER_SUFFIX = ".blamejs-probation.json";
+var PROBATION_MARKER_MAX    = C.BYTES.kib(64);   // marker is a small JSON record
+
+function _resolveMarkerPath(opts) {
+  if (typeof opts.markerPath === "string" && opts.markerPath.length > 0) return opts.markerPath;
+  return opts.to + PROBATION_MARKER_SUFFIX;
+}
+
+function _probationHashAlgo(value, method) {
+  if (value !== undefined && (typeof value !== "string" || ALLOWED_HASH_ALGS.indexOf(value) === -1)) {
+    throw new SelfUpdateError("selfupdate/bad-hash-algo",
+      "selfUpdate." + method + ": opts.hashAlgo must be one of " + ALLOWED_HASH_ALGS.join(", "));
+  }
+}
+
+// Field-descriptor builders for the probation validators — the required/optional
+// string field shape composes from one definition instead of repeating an inline
+// `{ rule, code, label }` object per field across the three validators.
+function _reqStr(code, label) { return { rule: "required-string", code: code, label: label }; }
+function _optStr(code, label) { return { rule: "optional-string", code: code, label: label }; }
+function _probationLabel(method, field) { return "selfUpdate." + method + ": opts." + field; }
+
+function _validateProbationBeginOpts(opts) {
+  validateOpts.shape(opts, {
+    to:           _reqStr("selfupdate/bad-to",            _probationLabel("beginProbation", "to")),
+    backupTo:     _reqStr("selfupdate/bad-backup",        _probationLabel("beginProbation", "backupTo")),
+    expectedHash: _reqStr("selfupdate/bad-expected-hash", _probationLabel("beginProbation", "expectedHash")),
+    windowMs: function (value) {
+      numericBounds.requirePositiveFiniteIntIfPresent(value,
+        _probationLabel("beginProbation", "windowMs"), SelfUpdateError, "selfupdate/bad-window");
+    },
+    hashAlgo:   function (value) { _probationHashAlgo(value, "beginProbation"); },
+    markerPath: _optStr("selfupdate/bad-marker-path", _probationLabel("beginProbation", "markerPath")),
+  }, "selfUpdate.beginProbation", SelfUpdateError, "selfupdate/bad-opts");
+}
+
+function _validateConfirmOpts(opts) {
+  validateOpts.shape(opts, {
+    to:         _reqStr("selfupdate/bad-to",          _probationLabel("confirmHealthy", "to")),
+    markerPath: _optStr("selfupdate/bad-marker-path", _probationLabel("confirmHealthy", "markerPath")),
+  }, "selfUpdate.confirmHealthy", SelfUpdateError, "selfupdate/bad-opts");
+}
+
+function _validateEvaluateOpts(opts) {
+  validateOpts.shape(opts, {
+    to:         _reqStr("selfupdate/bad-to",          _probationLabel("evaluateOnBoot", "to")),
+    backupTo:   _optStr("selfupdate/bad-backup",      _probationLabel("evaluateOnBoot", "backupTo")),
+    markerPath: _optStr("selfupdate/bad-marker-path", _probationLabel("evaluateOnBoot", "markerPath")),
+    now: function (value) {
+      numericBounds.requirePositiveFiniteIntIfPresent(value,
+        _probationLabel("evaluateOnBoot", "now"), SelfUpdateError, "selfupdate/bad-now");
+    },
+  }, "selfUpdate.evaluateOnBoot", SelfUpdateError, "selfupdate/bad-opts");
+}
+
+function _probationKeep(reason, to, markerPath) {
+  // A boot with no probation marker is the steady-state no-op — don't audit it
+  // every boot. Every other keep reason is a real probation transition.
+  if (reason !== "no-probation-active") {
+    _safeAuditEmit("selfupdate.probation.kept", "success", {
+      to: to, markerPath: markerPath, reason: reason,
+    });
+  }
+  return { action: "keep", reason: reason };
+}
+
+/**
+ * @primitive b.selfUpdate.beginProbation
+ * @signature b.selfUpdate.beginProbation(opts)
+ * @since     0.17.13
+ * @status    stable
+ * @related   b.selfUpdate.confirmHealthy, b.selfUpdate.evaluateOnBoot, b.selfUpdate.swap
+ *
+ * Arm a bounded post-install probation for a freshly-swapped binary. Writes an
+ * atomic marker (`to` + `.blamejs-probation.json`, or `opts.markerPath`)
+ * recording the target, the known-good backup, the installed bytes' hash, and an
+ * `expiresAt` = now + `windowMs`. The new binary calls `confirmHealthy` once it
+ * is up and healthy (clearing the marker); if the window elapses with no such
+ * confirmation, the next `evaluateOnBoot` rolls the backup back over the target.
+ *
+ * The marker is written via `b.atomicFile.writeJson` (temp + fsync + rename), so
+ * a process that dies mid-write leaves either the previous complete marker or
+ * none — never a half-written record a boot could misread.
+ *
+ * @opts
+ *   to:           string,   // required — installed binary path (the probationary target)
+ *   backupTo:     string,   // required — known-good backup restored on a failed probation
+ *   expectedHash: string,   // required — hash of the installed bytes (selfUpdate.verify/swap's hash)
+ *   windowMs:     number,   // probation window in ms; default 10 minutes
+ *   hashAlgo:     string,   // sha3-512 (default) | sha-256 | sha-512 | shake256
+ *   markerPath:   string,   // override marker path (default: `to` + ".blamejs-probation.json")
+ *
+ * @example
+ *   var v = await b.selfUpdate.verify({ assetPath, signaturePath, pubkeyPem });
+ *   await b.selfUpdate.swap({ from, to, backupTo, expectedHash: v.hash });
+ *   var p = await b.selfUpdate.beginProbation({ to, backupTo, expectedHash: v.hash });
+ *   p.expiresAt;   // → epoch ms the probation window closes
+ */
+async function beginProbation(opts) {
+  _validateProbationBeginOpts(opts);
+  var markerPath  = _resolveMarkerPath(opts);
+  var windowMs    = typeof opts.windowMs === "number" ? opts.windowMs : C.TIME.minutes(10);
+  var hashAlgo    = opts.hashAlgo || DEFAULT_HASH_ALG;
+  var installedAt = Date.now();
+  var expiresAt   = installedAt + windowMs;
+
+  // Carry a monotonically increasing generation across successive probations of
+  // the same target — each install supersedes the prior probation record.
+  var generation = 1;
+  try {
+    var prior = await atomicFile.readJson(markerPath, { maxBytes: PROBATION_MARKER_MAX });
+    if (prior && typeof prior.generation === "number" && isFinite(prior.generation)) {
+      generation = prior.generation + 1;
+    }
+  } catch (_p) { /* no prior marker (or unreadable) — first generation */ }
+
+  var marker = {
+    schema:       1,
+    installedAt:  installedAt,
+    expiresAt:    expiresAt,
+    windowMs:     windowMs,
+    to:           opts.to,
+    backupTo:     opts.backupTo,
+    expectedHash: opts.expectedHash,
+    hashAlgo:     hashAlgo,
+    generation:   generation,
+  };
+  var written = await atomicFile.writeJson(markerPath, marker, { computeHash: true, fileMode: 0o600 });
+
+  _safeAuditEmit("selfupdate.probation.begin", "success", {
+    to: opts.to, backupTo: opts.backupTo, markerPath: markerPath,
+    expiresAt: expiresAt, generation: generation, markerHash: written.hash,
+  });
+  log("selfUpdate.beginProbation to=" + opts.to + " expiresAt=" + expiresAt + " gen=" + generation);
+  return { markerPath: markerPath, installedAt: installedAt, expiresAt: expiresAt, generation: generation };
+}
+
+/**
+ * @primitive b.selfUpdate.confirmHealthy
+ * @signature b.selfUpdate.confirmHealthy(opts)
+ * @since     0.17.13
+ * @status    stable
+ * @related   b.selfUpdate.beginProbation, b.selfUpdate.evaluateOnBoot
+ *
+ * Clear the probation marker — the explicit clean / healthy signal. The new
+ * binary calls this once its own startup health checks pass (and an operator's
+ * graceful-shutdown hook may call it too, marking a clean stop). With the marker
+ * gone, a later `evaluateOnBoot` finds no probation and keeps the binary. Absence
+ * of this signal at the next boot past the window is what `evaluateOnBoot` reads
+ * as a failed probation. Idempotent: a missing marker returns `cleared: false`.
+ *
+ * @opts
+ *   to:         string,   // required — the probationary target (locates the marker)
+ *   markerPath: string,   // override marker path (must match beginProbation)
+ *
+ * @example
+ *   // in the new binary, after startup health checks pass:
+ *   var r = await b.selfUpdate.confirmHealthy({ to: "/opt/app/app.bin" });
+ *   r.cleared;   // → true (marker removed)
+ */
+async function confirmHealthy(opts) {
+  _validateConfirmOpts(opts);
+  var markerPath = _resolveMarkerPath(opts);
+  var cleared = false;
+  if (nodeFs.existsSync(markerPath)) {
+    try {
+      nodeFs.unlinkSync(markerPath);
+      cleared = true;
+    } catch (e) {
+      throw new SelfUpdateError("selfupdate/probation-confirm-failed",
+        "selfUpdate.confirmHealthy: failed to clear probation marker " + markerPath + ": " +
+        ((e && e.message) || String(e)));
+    }
+  }
+  _safeAuditEmit("selfupdate.probation.confirmed", "success", {
+    to: opts.to, markerPath: markerPath, cleared: cleared,
+  });
+  log("selfUpdate.confirmHealthy to=" + opts.to + " cleared=" + cleared);
+  return { ok: true, cleared: cleared, markerPath: markerPath };
+}
+
+/**
+ * @primitive b.selfUpdate.evaluateOnBoot
+ * @signature b.selfUpdate.evaluateOnBoot(opts)
+ * @since     0.17.13
+ * @status    stable
+ * @related   b.selfUpdate.beginProbation, b.selfUpdate.confirmHealthy, b.selfUpdate.rollback
+ *
+ * Decide, at process start, whether a probationary install should be kept or
+ * rolled back. Returns `{ action: "keep" | "rollback", reason }`. No marker, or a
+ * marker still inside its window, keeps (a clean stop / restart within the window
+ * is not a crash). A marker past its window with no `confirmHealthy` means the
+ * binary never became healthy → the known-good backup is restored over the
+ * target and the marker cleared.
+ *
+ * Before restoring, it RE-VERIFIES: the bytes currently at `to` must still hash
+ * to the marker's `expectedHash` (so a marker left by a swap that FAILED — where
+ * the probationary binary was never installed — never triggers a phantom
+ * rollback), and the backup must exist (otherwise it keeps and defers to the
+ * operator rather than destroying the only present binary). A corrupt / malformed
+ * marker keeps, never rolls back.
+ *
+ * @opts
+ *   to:         string,   // required — the probationary target
+ *   backupTo:   string,   // override the marker's backup path
+ *   markerPath: string,   // override marker path (must match beginProbation)
+ *   now:        number,   // override the wall clock (epoch ms) for deterministic evaluation
+ *
+ * @example
+ *   // at process start, before serving traffic:
+ *   var d = await b.selfUpdate.evaluateOnBoot({ to: "/opt/app/app.bin" });
+ *   if (d.action === "rollback") process.exit(1);   // restart onto the restored binary
+ */
+async function evaluateOnBoot(opts) {
+  _validateEvaluateOpts(opts);
+  var markerPath = _resolveMarkerPath(opts);
+  var to  = opts.to;
+  var now = typeof opts.now === "number" ? opts.now : Date.now();
+
+  if (!nodeFs.existsSync(markerPath)) {
+    return _probationKeep("no-probation-active", to, markerPath);
+  }
+  var marker;
+  try {
+    marker = await atomicFile.readJson(markerPath, { maxBytes: PROBATION_MARKER_MAX });
+  } catch (_e) {
+    // A corrupt / unreadable marker must not phantom-rollback.
+    return _probationKeep("marker-unreadable", to, markerPath);
+  }
+  if (!marker || typeof marker.expiresAt !== "number" || typeof marker.expectedHash !== "string") {
+    return _probationKeep("marker-malformed", to, markerPath);
+  }
+  // Inside the window — a clean stop / restart is not a crash.
+  if (now < marker.expiresAt) {
+    return _probationKeep("within-probation-window", to, markerPath);
+  }
+
+  // Expired with no confirmHealthy. Re-verify before restoring.
+  var backupTo = typeof opts.backupTo === "string" ? opts.backupTo : marker.backupTo;
+  var alg = ALLOWED_HASH_ALGS.indexOf(marker.hashAlgo) !== -1 ? marker.hashAlgo : DEFAULT_HASH_ALG;
+
+  // The probationary binary must actually be the one installed at `to`; if `to`
+  // is absent or holds different bytes (a swap that failed and left the old
+  // binary), rolling back would be a phantom.
+  var currentHash = null;
+  try {
+    var curBytes = atomicFile.fdSafeReadSync(to, { maxBytes: C.BYTES.gib(1) });
+    currentHash = nodeCrypto.createHash(alg).update(curBytes).digest("hex");
+  } catch (_r) { currentHash = null; }
+  if (currentHash !== marker.expectedHash) {
+    return _probationKeep("installed-binary-not-probationary", to, markerPath);
+  }
+  if (typeof backupTo !== "string" || !nodeFs.existsSync(backupTo)) {
+    // No backup to restore — keep the current binary and defer to the operator
+    // rather than leaving the target with nothing.
+    return _probationKeep("backup-unavailable", to, markerPath);
+  }
+
+  // Restore the known-good backup over the failed probationary binary. On boot
+  // the target is not yet running, so an atomic write-replace is safe.
+  try {
+    var backupBytes = atomicFile.fdSafeReadSync(backupTo, { maxBytes: C.BYTES.gib(1) });
+    var restoreMode;
+    try { restoreMode = (nodeFs.statSync(to).mode & 0o777); } catch (_sm) { restoreMode = 0o600; }
+    await atomicFile.write(to, backupBytes, { fileMode: restoreMode, overwrite: true });
+  } catch (e) {
+    _safeAuditEmit("selfupdate.probation.rollback_failed", "denied", {
+      to: to, backupTo: backupTo, markerPath: markerPath,
+      reason: "restore-failed", message: (e && e.message) || String(e),
+    });
+    throw new SelfUpdateError("selfupdate/probation-rollback-failed",
+      "selfUpdate.evaluateOnBoot: probation rollback restore of " + to + " failed: " +
+      ((e && e.message) || String(e)));
+  }
+  atomicFile.fsyncDir(nodePath.dirname(to));
+  try { nodeFs.unlinkSync(markerPath); } catch (_u) { /* marker cleanup best-effort */ }
+
+  _safeAuditEmit("selfupdate.probation.rolled_back", "success", {
+    to: to, backupTo: backupTo, markerPath: markerPath, generation: marker.generation,
+  });
+  log("selfUpdate.evaluateOnBoot rolled back to=" + to + " from=" + backupTo);
+  return { action: "rollback", reason: "probation-window-elapsed-without-confirmation",
+           to: to, backupTo: backupTo, generation: marker.generation };
+}
+
 module.exports = {
   poll:                  poll,
   verify:                verify,
   swap:                  swap,
   rollback:              rollback,
+  beginProbation:        beginProbation,
+  confirmHealthy:        confirmHealthy,
+  evaluateOnBoot:        evaluateOnBoot,
   // Standalone verifier — zero-dep companion for install-pipeline
   // contexts that run BEFORE the framework is installed (Dockerfile
   // build stages, install.sh, update.sh). See the module's intro for