capiumbrowser 1.0.4 → 1.1.0

package/README.md

@@ -253,7 +253,7 @@ The spoofing lives in the compiled binary — not injected via JavaScript, not s
 aligned to a single coherent story.
 
 **Download mechanics.** The binary is fetched from the license service with a signed, path-based GET
-(`/download/distro/chromium-v<version>/capiumbrowser-<os>-<arch>.tar.gz`): the key travels in the
+(`/download/distro/chromium-v<version>.<revision>/capiumbrowser-<os>-<arch>.tar.gz`): the key travels in the
 `X-Capzy-License` header (never the URL) and the request path is HMAC-signed. The response's
 `X-Capzy-SHA256` is verified against the streamed bytes before extraction, so a corrupted or tampered
 archive is rejected. Env overrides: `CAPIUM_LICENSE_KEY` (or `~/.capium/license`), `CAPIUM_VERSION` (target

package/lib/channels.json

@@ -1,29 +1,31 @@
 {
-  "_comment": "SINGLE SOURCE OF TRUTH for the current stable Capium browser build per OS/arch. Each OS reaches stable independently -- edit one entry without touching the others. This file ships inside the wheel (the SDK reads it to pick each host's stable build) AND is published to the download server by the release pipeline. `version` is the Chromium base; `revision` is the re-spin counter -- the served R2 folder is chromium-v<version>/ for revision 1 (the base build) and chromium-v<version>-r<N>/ for a re-spin (N>=2), so publishing a re-spin never overwrites the base artifact older SDKs still fetch. `published: false` means the tag is declared but no artifact exists yet -- the SDK raises a clear 'not published yet' error instead of a raw 404.",
+  "_comment": "SINGLE SOURCE OF TRUTH for the current stable Capium browser build per OS/arch. Each OS reaches stable independently -- edit one entry without touching the others. This file ships inside the wheel (the SDK reads it to pick each host's stable build) AND is published to the download server by the release pipeline. `version` is the Chromium version (what the browser reports to the customer -- unchanged by the revision); `revision` is our packaging counter -- the served R2 folder is chromium-v<version>.<revision>/, ALWAYS dotted-suffixed starting at 1 (chromium-v<version>.1/ is the first build, .2/ a same-engine re-spin), so publishing a re-spin never overwrites the artifact older SDKs still fetch. `published: false` means the tag is declared but no artifact exists yet -- the SDK raises a clear 'not published yet' error instead of a raw 404.",
   "schema": 1,
-  "updated": "2026-09-24",
+  "updated": "2026-09-28",
   "channels": {
     "stable": {
       "windows-x64": {
-        "version": "152.0.7977.82",
-        "revision": 3,
-        "sha256": "7172b2fdd62cbbfa2619428eca44a2c2fc614b859ce3e51bafef95ad759d4ef0",
+        "version": "153.0.8010.53",
+        "engine_version": "153.0.8010.52",
+        "revision": 1,
+        "sha256": "6eaea779c665335ffa8585f437527bb5124b72fc730b373bb53d23145fa33026",
         "published": true
       },
       "macos-arm64": {
-        "version": "152.0.7977.82",
-        "revision": 3,
-        "sha256": "4196dcc7687f11390a095b5f3c5aae091a7480306f63cdd9df86ad1267b421d8",
+        "version": "153.0.8010.53",
+        "engine_version": "153.0.8010.52",
+        "revision": 1,
+        "sha256": "a8901553c8c7eabf3b08106bc3784dd270280c82be8484cac800838c41dca40d",
         "published": true
       },
       "linux-x64": {
-        "version": "152.0.7977.82",
-        "revision": 3,
-        "sha256": "cd95ced9f03f571d9b3af419cd46949ca850968daa29c3bebdeaabeb9a412972",
+        "version": "153.0.8010.52",
+        "revision": 1,
+        "sha256": "69f512f01c2bfe202181847e10a76c36f0d1736170fd5bfe861f9ea6bdf5cc02",
         "published": true
       },
       "linux-arm64": {
-        "version": "152.0.7977.82",
+        "version": "153.0.8010.52",
         "revision": 1,
         "sha256": null,
         "published": false

package/lib/download.js

@@ -7,7 +7,7 @@
  * overrides).
  *
  * Download scheme (signed, path-based):
- *     GET {server}/download/distro/chromium-v{version}/capiumbrowser-{os}-{arch}.tar.gz
+ *     GET {server}/download/distro/chromium-v{version}.{revision}/capiumbrowser-{os}-{arch}.tar.gz
  *
  * The license key travels in the X-Capzy-License header (over TLS), NEVER in the URL; the
  * request PATH is HMAC-signed (X-Capzy-Timestamp + X-Capzy-Signature =
@@ -15,7 +15,7 @@
  * X-Capzy-SHA256 is verified against the downloaded bytes before anything is extracted.
  *
  * The archive FILENAME is version-independent -- `capiumbrowser-<os>-<arch>.tar.gz` is always
- * the same; only the `chromium-v<version>/` folder changes.
+ * the same; only the `chromium-v<version>.<revision>/` folder changes.
  *
  * Source resolution (first that works):
  *     CAPIUM_BINARY            -> use this exact launch target, no download
@@ -87,15 +87,15 @@ function downloadTag(system = null, machine = null) {
 }
 
 /**
- * The signed request path for a build: version in the folder, tag in the filename
- * (`/download/distro/chromium-v<version>/capiumbrowser-<tag>.tar.gz`). Per-OS versions work
- * because each tag lives under its own chromium-v<version>/ folder (win/mac .65 while linux
- * is .64). Key travels in the X-Capzy-License header, the path is HMAC-signed, and the bytes
+ * The signed request path for a build: version.revision in the folder, tag in the filename
+ * (`/download/distro/chromium-v<version>.<revision>/capiumbrowser-<tag>.tar.gz`). Per-OS versions
+ * work because each tag lives under its own chromium-v<version>.<revision>/ folder (win/mac .65
+ * while linux .64). Key travels in the X-Capzy-License header, the path is HMAC-signed, and the bytes
  * are verified against the response's X-Capzy-SHA256.
  */
 function distroPath(version, tag, revision = 1) {
-  // A same-engine re-spin (revision>=2) lands in its own immutable folder
-  // chromium-v<version>-r<N>/, so publishing it never overwrites the base artifact older SDKs fetch.
+  // Each packaging revision lands in its own immutable folder chromium-v<version>.<N>/
+  // (N>=1), so publishing a re-spin never overwrites the artifact older SDKs fetch.
   return `/download/distro/chromium-v${buildId(version, revision)}/capiumbrowser-${tag}.tar.gz`;
 }
 
@@ -192,6 +192,38 @@ function stampVersion(binPath, version) {
   } catch {}
 }
 
+/**
+ * The buildId (`<version>.<N>`) this host SHOULD run, honoring CAPIUM_* env, or
+ * null if it can't be determined (CAPIUM_BINARY override / unsupported platform / bad manifest).
+ * Lets the launch path detect+reject a stale binary from an earlier install instead of running it.
+ */
+function expectedBuildId() {
+  if (process.env.CAPIUM_BINARY) return null;
+  try {
+    const tag = downloadTag();
+    const envVer = process.env.CAPIUM_VERSION;
+    const version = envVer || binaryVersionFor(tag);
+    let revision;
+    if (process.env.CAPIUM_REVISION) revision = parseInt(process.env.CAPIUM_REVISION, 10);
+    else if (envVer) revision = 1;
+    else revision = binaryRevisionFor(tag);
+    return buildId(version, revision);
+  } catch {
+    return null;
+  }
+}
+
+/** The launch wrapper inside a just-extracted distro dir, or null (scoped, never a global search). */
+function wrapperIn(distroDir) {
+  for (const nm of config._wrapperNames()) {
+    const p = path.join(distroDir, nm);
+    try {
+      if (fs.statSync(p).isFile()) return p;
+    } catch {}
+  }
+  return null;
+}
+
 /**
  * Delete previously-extracted capium distros under `root`. A host only ever holds its own
  * platform's build, so on a version change we drop the stale one before installing the new
@@ -294,8 +326,8 @@ async function ensureBinary({ version = null, licenseKey = null, server = null }
   const envVer = process.env.CAPIUM_VERSION;
   version = version || envVer || binaryVersionFor(tag);
   // A same Chromium version can be re-spun (r2, r3, ...). CAPIUM_REVISION overrides; an explicit
-  // CAPIUM_VERSION pin defaults to the base (r1) unless a revision is given; otherwise the per-OS
-  // revision comes from channels.json.
+  // CAPIUM_VERSION pin defaults to revision 1 (<version>.1) unless a revision is given;
+  // otherwise the per-OS revision comes from channels.json.
   let revision;
   if (process.env.CAPIUM_REVISION) revision = parseInt(process.env.CAPIUM_REVISION, 10);
   else if (envVer) revision = 1;
@@ -328,12 +360,13 @@ async function ensureBinary({ version = null, licenseKey = null, server = null }
   const subdir = `capium-${String(version).split('.')[0]}-${tag}`; // FLAT-archive wrapper name
   const tmp = path.join(os.tmpdir(),
     `capium-dl-${crypto.randomBytes(6).toString('hex')}.tar.gz`);
+  let distroDir = null;
   try {
     await download(url, headers, tmp, version, tag);
     // Only drop the stale install once the new bytes are in hand (a failed download must
     // never leave the host with no binary), then extract the new version.
     removeInstalls(root);
-    const distroDir = await extract(tmp, root, subdir);
+    distroDir = await extract(tmp, root, subdir);
     // Stamp the version marker BEFORE discovery: the FLAT Windows tar carries no capium
     // marker files, and findBinary only accepts a bare chrome.exe next to one -- the
     // downloader vouches for the directory it just extracted.
@@ -346,13 +379,17 @@ async function ensureBinary({ version = null, licenseKey = null, server = null }
     } catch {}
   }
 
-  let binPath;
-  try {
-    binPath = config.findBinary();
-  } catch {
-    throw new CapiumError(
-      `downloaded and extracted the ${tag} build but no launch target was found afterwards ` +
-        `(unexpected archive layout under ${root}).`);
+  // Return the binary we JUST extracted (scoped to distroDir), never a global findBinary here --
+  // a stale binary in another base could otherwise be returned instead of the fresh build.
+  let binPath = wrapperIn(distroDir);
+  if (!binPath) {
+    try {
+      binPath = config.findBinary();
+    } catch {
+      throw new CapiumError(
+        `downloaded and extracted the ${tag} build but no launch target was found afterwards ` +
+          `(unexpected archive layout under ${root}).`);
+    }
   }
   stampVersion(binPath, bid); // so a later version/revision bump knows to re-download
   // Re-apply exec bits the wrapper + engine binaries need (zip drops unix perms).
@@ -372,6 +409,7 @@ module.exports = {
   destRoot,
   ensureBinary,
   installedVersion,
+  expectedBuildId,
   _SUPPORTED: SUPPORTED,
   _normOs: normOs,
   _normArch: normArch,

package/lib/version.js

@@ -1,135 +1,139 @@
-/**
- * Version of the capium Node SDK (independent of the browser binary version).
- *
- * The SDK version and the Capium/Chromium binary version move on separate cadences: you update
- * the SDK with `npm install -U capiumbrowser`, and the SDK fetches the *default* binary build to
- * match. Crucially that default is **per platform** -- each OS/arch reaches a stable Capium build
- * independently (Windows can sit on 150 while macOS is on 151).
- *
- * The stable build for each OS is not hardcoded here; it comes from `channels.json`, which ships
- * inside the package and is the single source of truth (the release pipeline edits that file to
- * promote an OS to a new stable, and the same file is published to the download server). This
- * module just loads it; FALLBACK_VERSIONS is used only if the bundled manifest is missing or
- * corrupt in an install.
- *
- * Override order at download time: CAPIUM_VERSION env > per-OS stable from channels.json.
- */
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const SDK_VERSION = require('../package.json').version;
-
-// Used only if channels.json can't be read (corrupt/removed install). ensureBinary() raises a
-// clear error long before the "unsupported platform" case matters; this keeps lookups total.
-const FALLBACK_VERSIONS = {
-  'windows-x64': '152.0.7977.65', // real Chrome 152 stable per OS (win/mac .65, linux .64)
-  'macos-arm64': '152.0.7977.65',
-  'linux-x64': '152.0.7977.64',
-  'linux-arm64': '152.0.7977.64', // declared; not yet published (see channels.json)
-};
-const DEFAULT_BINARY_VERSION = '152.0.7977.65';
-
-function loadStable() {
-  // The `channels.stable` map from the bundled manifest, or null if unreadable.
-  try {
-    const raw = fs.readFileSync(path.join(__dirname, 'channels.json'), 'utf8');
-    const stable = JSON.parse(raw).channels.stable;
-    return stable && typeof stable === 'object' ? stable : null;
-  } catch {
-    return null;
-  }
-}
-
-const STABLE = loadStable();
-
-function versionsFromManifest() {
-  if (!STABLE) return { ...FALLBACK_VERSIONS };
-  const out = {};
-  for (const [tag, entry] of Object.entries(STABLE)) {
-    if (entry && typeof entry === 'object' && entry.version) out[tag] = entry.version;
-  }
-  return Object.keys(out).length ? out : { ...FALLBACK_VERSIONS };
-}
-
-// Default stable Capium binary build per distro tag, resolved from channels.json.
-const CAPIUM_BINARY_VERSIONS = versionsFromManifest();
-
-/** The current stable Capium binary version for a distro tag (e.g. 'windows-x64'). */
-function binaryVersionFor(tag) {
-  return CAPIUM_BINARY_VERSIONS[tag] || DEFAULT_BINARY_VERSION;
-}
-
-function revisionsFromManifest() {
-  if (!STABLE) return {};
-  const out = {};
-  for (const [tag, entry] of Object.entries(STABLE)) {
-    if (entry && typeof entry === 'object' && Number.isInteger(entry.revision)) out[tag] = entry.revision;
-  }
-  return out;
-}
-
-// Re-spin variant per tag (>=1). Same Chromium version can be rebuilt (a stealth/fingerprint
-// change with no engine bump); each re-spin increments this. 1 = the base build.
-const CAPIUM_BINARY_REVISIONS = revisionsFromManifest();
-
-/**
- * The re-spin variant (>=1) for a distro tag. 1 = the base build (suffix-less folder); 2,3,...
- * are re-spins of the SAME Chromium version served from chromium-v<version>-r<N>/ (so a re-spin
- * never overwrites the base artifact older SDKs still fetch). A version bump resets this to 1.
- */
-function binaryRevisionFor(tag) {
-  return CAPIUM_BINARY_REVISIONS[tag] || 1;
-}
-
-/**
- * Stable identity of one specific build = the R2 folder discriminator AND the install-cache key.
- * revision 1 -> the version itself (chromium-v<version>/, the base build); N>=2 -> '<version>-r<N>'
- * (chromium-v<version>-r<N>/). So a revision bump on an unchanged engine still re-downloads.
- */
-function buildId(version, revision) {
-  const n = parseInt(revision, 10);
-  return !n || n < 2 ? version : `${version}-r${n}`;
-}
-
-/**
- * False only when the manifest declares the tag but marks it not-yet-published. Unknown
- * tags / missing manifest return true so the download layer's own error/404 speaks instead.
- */
-function isPublished(tag) {
-  if (!STABLE) return true;
-  const entry = STABLE[tag];
-  if (!entry || typeof entry !== 'object') return true;
-  return entry.published !== false;
-}
-
-/**
- * Best-effort distro tag for the current host, mirroring download.js's mapping. Kept
- * dependency-free (no require of download.js) so version.js stays loadable in isolation.
- */
-function hostTag() {
-  const p = process.platform;
-  const osName = p === 'darwin' ? 'macos' : p === 'win32' ? 'windows' : 'linux';
-  const m = os.arch();
-  const arch = m === 'x64' || m === 'ia32' ? 'x64' : m === 'arm64' ? 'arm64' : m;
-  return `${osName}-${arch}`;
-}
-
-// The stable build this SDK targets for THIS host (CLI display, examples). Code that fetches a
-// build should prefer binaryVersionFor(tag) with the tag it already resolved.
-const CAPIUM_BINARY_VERSION = binaryVersionFor(hostTag());
-
-module.exports = {
-  SDK_VERSION,
-  CAPIUM_BINARY_VERSION,
-  CAPIUM_BINARY_VERSIONS,
-  CAPIUM_BINARY_REVISIONS,
-  binaryVersionFor,
-  binaryRevisionFor,
-  buildId,
-  isPublished,
-  hostTag,
-  _FALLBACK_VERSIONS: FALLBACK_VERSIONS,
-};
+/**
+ * Version of the capium Node SDK (independent of the browser binary version).
+ *
+ * The SDK version and the Capium/Chromium binary version move on separate cadences: you update
+ * the SDK with `npm install -U capiumbrowser`, and the SDK fetches the *default* binary build to
+ * match. Crucially that default is **per platform** -- each OS/arch reaches a stable Capium build
+ * independently (Windows can sit on 150 while macOS is on 151).
+ *
+ * The stable build for each OS is not hardcoded here; it comes from `channels.json`, which ships
+ * inside the package and is the single source of truth (the release pipeline edits that file to
+ * promote an OS to a new stable, and the same file is published to the download server). This
+ * module just loads it; FALLBACK_VERSIONS is used only if the bundled manifest is missing or
+ * corrupt in an install.
+ *
+ * Override order at download time: CAPIUM_VERSION env > per-OS stable from channels.json.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SDK_VERSION = require('../package.json').version;
+
+// Used only if channels.json can't be read (corrupt/removed install). ensureBinary() raises a
+// clear error long before the "unsupported platform" case matters; this keeps lookups total.
+const FALLBACK_VERSIONS = {
+  'windows-x64': '153.0.8010.52', // real Chrome 152 stable per OS (win/mac .65, linux .64)
+  'macos-arm64': '153.0.8010.52',
+  'linux-x64': '153.0.8010.52',
+  'linux-arm64': '153.0.8010.52', // declared; not yet published (see channels.json)
+};
+const DEFAULT_BINARY_VERSION = '153.0.8010.52';
+
+function loadStable() {
+  // The `channels.stable` map from the bundled manifest, or null if unreadable.
+  try {
+    const raw = fs.readFileSync(path.join(__dirname, 'channels.json'), 'utf8');
+    const stable = JSON.parse(raw).channels.stable;
+    return stable && typeof stable === 'object' ? stable : null;
+  } catch {
+    return null;
+  }
+}
+
+const STABLE = loadStable();
+
+function versionsFromManifest() {
+  if (!STABLE) return { ...FALLBACK_VERSIONS };
+  const out = {};
+  for (const [tag, entry] of Object.entries(STABLE)) {
+    if (entry && typeof entry === 'object' && entry.version) out[tag] = entry.version;
+  }
+  return Object.keys(out).length ? out : { ...FALLBACK_VERSIONS };
+}
+
+// Default stable Capium binary build per distro tag, resolved from channels.json.
+const CAPIUM_BINARY_VERSIONS = versionsFromManifest();
+
+/** The current stable Capium binary version for a distro tag (e.g. 'windows-x64'). */
+function binaryVersionFor(tag) {
+  return CAPIUM_BINARY_VERSIONS[tag] || DEFAULT_BINARY_VERSION;
+}
+
+function revisionsFromManifest() {
+  if (!STABLE) return {};
+  const out = {};
+  for (const [tag, entry] of Object.entries(STABLE)) {
+    if (entry && typeof entry === 'object' && Number.isInteger(entry.revision)) out[tag] = entry.revision;
+  }
+  return out;
+}
+
+// Re-spin variant per tag (>=1). Same Chromium version can be rebuilt (a stealth/fingerprint
+// change with no engine bump); each re-spin increments this. 1 = the base build.
+const CAPIUM_BINARY_REVISIONS = revisionsFromManifest();
+
+/**
+ * The packaging revision (>=1) for a distro tag. 1 = the first build (chromium-v<version>.1/);
+ * 2,3,... are re-spins of the SAME Chromium version served from chromium-v<version>.<N>/ (so a
+ * re-spin never overwrites the artifact older SDKs still fetch). A version bump resets this to 1.
+ */
+function binaryRevisionFor(tag) {
+  return CAPIUM_BINARY_REVISIONS[tag] || 1;
+}
+
+/**
+ * Stable identity of one specific build = the R2 folder discriminator AND the install-cache key.
+ * The packaging revision is ALWAYS a dotted suffix starting at 1: chromium-v<version>.<N>/
+ * (revision 1 -> <version>.1, the first build; 2,3,... -> <version>.2 etc., a same-engine
+ * re-spin). Each revision is its own immutable folder, so a re-spin never overwrites the
+ * artifact an older SDK still fetches, and a revision bump re-downloads. NOTE: the customer's
+ * reported Chrome version is unchanged -- this suffix only names our distro/upload/download
+ * artifact, not the browser version.
+ */
+function buildId(version, revision) {
+  const n = parseInt(revision, 10);
+  return `${version}.${!n || n < 1 ? 1 : n}`;
+}
+
+/**
+ * False only when the manifest declares the tag but marks it not-yet-published. Unknown
+ * tags / missing manifest return true so the download layer's own error/404 speaks instead.
+ */
+function isPublished(tag) {
+  if (!STABLE) return true;
+  const entry = STABLE[tag];
+  if (!entry || typeof entry !== 'object') return true;
+  return entry.published !== false;
+}
+
+/**
+ * Best-effort distro tag for the current host, mirroring download.js's mapping. Kept
+ * dependency-free (no require of download.js) so version.js stays loadable in isolation.
+ */
+function hostTag() {
+  const p = process.platform;
+  const osName = p === 'darwin' ? 'macos' : p === 'win32' ? 'windows' : 'linux';
+  const m = os.arch();
+  const arch = m === 'x64' || m === 'ia32' ? 'x64' : m === 'arm64' ? 'arm64' : m;
+  return `${osName}-${arch}`;
+}
+
+// The stable build this SDK targets for THIS host (CLI display, examples). Code that fetches a
+// build should prefer binaryVersionFor(tag) with the tag it already resolved.
+const CAPIUM_BINARY_VERSION = binaryVersionFor(hostTag());
+
+module.exports = {
+  SDK_VERSION,
+  CAPIUM_BINARY_VERSION,
+  CAPIUM_BINARY_VERSIONS,
+  CAPIUM_BINARY_REVISIONS,
+  binaryVersionFor,
+  binaryRevisionFor,
+  buildId,
+  isPublished,
+  hostTag,
+  _FALLBACK_VERSIONS: FALLBACK_VERSIONS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capiumbrowser",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Drop-in stealth browser SDK on top of Playwright or Puppeteer (Capium Chromium).",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Capzy (https://capzy.ai)",

package/playwright.js

@@ -42,12 +42,23 @@ function requireDriver() {
 
 /** Find the capium wrapper; if absent, try to download it (see lib/download). */
 async function resolveBinary(binary, licenseKey) {
+  // Explicit override (arg or CAPIUM_BINARY) wins with no version check -- the caller's choice.
+  if (binary || process.env.CAPIUM_BINARY) return config.findBinary(binary);
+  // Otherwise the discovered binary must be the CURRENT target build. A stale binary left by an
+  // earlier install (older revision -> older device pool / pre-fix fingerprint) must never be
+  // launched silently even after `npm i -U` -- it still trips detection. Re-fetch on a mismatch.
+  const want = download.expectedBuildId();
   try {
-    return config.findBinary(binary);
+    const found = config.findBinary();
+    const have = download.installedVersion(found);
+    if (want === null || have === want) return found;
+    process.stderr.write(
+      `capium: ignoring stale binary at ${found} (build ${have}; current target ${want}) and ` +
+        `fetching the current build. Delete it or set CAPIUM_BINARY to silence this.\n`);
   } catch (e) {
     if (e.code !== 'ENOENT') throw e;
-    return download.ensureBinary({ licenseKey });
   }
+  return download.ensureBinary({ licenseKey });
 }
 
 /**

package/puppeteer.js

@@ -45,12 +45,23 @@ function requireDriver() {
 }
 
 async function resolveBinary(binary, licenseKey) {
+  // Explicit override (arg or CAPIUM_BINARY) wins with no version check -- the caller's choice.
+  if (binary || process.env.CAPIUM_BINARY) return config.findBinary(binary);
+  // Otherwise the discovered binary must be the CURRENT target build. A stale binary left by an
+  // earlier install (older revision -> older device pool / pre-fix fingerprint) must never be
+  // launched silently even after `npm i -U` -- it still trips detection. Re-fetch on a mismatch.
+  const want = download.expectedBuildId();
   try {
-    return config.findBinary(binary);
+    const found = config.findBinary();
+    const have = download.installedVersion(found);
+    if (want === null || have === want) return found;
+    process.stderr.write(
+      `capium: ignoring stale binary at ${found} (build ${have}; current target ${want}) and ` +
+        `fetching the current build. Delete it or set CAPIUM_BINARY to silence this.\n`);
   } catch (e) {
     if (e.code !== 'ENOENT') throw e;
-    return download.ensureBinary({ licenseKey });
   }
+  return download.ensureBinary({ licenseKey });
 }
 
 async function prepare(opts) {