contextecf-codeledger 0.10.79 → 0.10.81

package/bin/codeledger.js

@@ -1,21 +1,24 @@
 #!/usr/bin/env node
 /*
- * ContextECF CodeLedger npm launcher — thin shim (safe unscoped alias).
+ * CodeLedger npm launcher — thin shim.
  *
- * This is the safe unscoped alias of @codeledger/cli. Both packages install
- * the exact same hardened binary. You can install either:
+ * This file is the ONLY JavaScript that ships to npm under @codeledger/cli.
+ * It contains no engine code, no scoring logic, no formulas. All CodeLedger
+ * functionality lives inside the hardened binary that is downloaded during
+ * `postinstall` from the GitHub Release for this exact version, verified
+ * via SHA256, and cached under ~/.cache/codeledger/bin/.
  *
- *   npm install -g contextecf-codeledger@latest   (this package)
- *   npm install -g @codeledger/cli@latest          (scoped original)
- *
- * This file contains no engine code. All CodeLedger functionality lives
- * inside the hardened binary downloaded during postinstall.
+ * postinstall soft-fails (see scripts/postinstall.js) rather than blocking
+ * `npm install`, so the binary may not be cached yet the first time this
+ * shim runs. When that happens, this shim first looks for a repo-local
+ * runtime (an already-initialized repo's `.codeledger/bin/`) before making
+ * one synchronous, on-demand download attempt itself.
  */
 
 'use strict';
 
 const { spawnSync } = require('node:child_process');
-const { existsSync } = require('node:fs');
+const { existsSync, realpathSync, statSync } = require('node:fs');
 const { dirname, join, resolve } = require('node:path');
 const { homedir, platform } = require('node:os');
 
@@ -37,6 +40,11 @@ function die(msg, code = 1) {
   process.exit(code);
 }
 
+// Repo-local fallback: an already-`codeledger init`'d repo vendors its own
+// runtime under .codeledger/bin/. Checked before attempting a network
+// download since it's instant and needs no connectivity — the global cache
+// miss just means this particular machine hasn't installed globally yet,
+// not that the user has no working CodeLedger available to them.
 function findRepoLocalRuntime(startDir) {
   if (process.env.CODELEDGER_GLOBAL_VERSION_PROBE === '1') return null;
   let current = resolve(startDir);
@@ -67,7 +75,6 @@ function runRepoLocal(runtime) {
     stdio: 'inherit',
     cwd: runtime.repoRoot,
     env: { ...process.env, CODELEDGER_DELEGATED: '1' },
-    shell: runtime.kind === 'wrapper',
   });
   if (result.error) {
     die(`failed to spawn repo-local runtime: ${result.error.message}`);
@@ -75,64 +82,89 @@ function runRepoLocal(runtime) {
   process.exit(result.status ?? 1);
 }
 
-if (!existsSync(BINARY_PATH)) {
-  const repoLocal = findRepoLocalRuntime(process.cwd());
-  if (repoLocal) {
-    runRepoLocal(repoLocal);
+// One-shot, on-demand fetch, used only when the binary isn't cached yet and
+// no repo-local runtime was found. Bounded well below postinstall's own
+// window since a live invocation is blocked on this, not a background
+// install step.
+const ON_DEMAND_DEADLINE_MS = 30_000;
+
+function launchDirectory() {
+  const args = process.argv.slice(2);
+  let target;
+  for (let i = 0; i < args.length && args[i] !== '--'; i++) {
+    if (args[i].startsWith('--cwd=')) target = args[i].slice(6);
+    else if (args[i] === '--cwd') {
+      target = args[++i];
+      if (!target || target.startsWith('--')) die('--cwd requires a repository directory.', 2);
+    }
   }
+  if (target === undefined && args[0] === 'mcp') target = process.env.CODELEDGER_REPO_ROOT;
+  if (target !== undefined && !target.trim()) die('Repository target cannot be empty.', 2);
+  try {
+    const root = realpathSync(resolve(target ?? process.cwd()));
+    if (!statSync(root).isDirectory()) throw new Error('Not a directory');
+    return root;
+  } catch { die('Repository target must be an existing directory. Check --cwd or CODELEDGER_REPO_ROOT.', 2); }
+}
 
-  const { arch } = require('node:os');
-  const platformKey = `${platform()}-${arch()}`;
-  const installerPath = join(__dirname, '..', 'scripts', 'postinstall.js');
-
-  if (platformKey === 'darwin-x64') {
-    die(
-      [
-        `ContextECF CodeLedger hardened binary for v${version} not found at ${BINARY_PATH}.`,
-        '',
-        'You are on an Intel Mac (darwin-x64). Pre-built binaries are',
-        'available for Apple Silicon (darwin-arm64) only.',
-        '',
-        'Options:',
-        '  1. Use Rosetta 2 (recommended):',
-        '       arch -arm64 npm install -g contextecf-codeledger@latest',
-        '  2. If this repo was already initialized, use the vendored CLI:',
-        '       npm install -g contextecf-codeledger@latest',
-        '       ./.codeledger/bin/codeledger ready',
-        '       node .codeledger/bin/codeledger-standalone.cjs ready',
-        '  3. Download a binary manually from:',
-        `       https://github.com/codeledgerECF/codeledger/releases/tag/v${version}`,
-      ].join('\n'),
-    );
-  } else {
-    die(
-      [
-        `ContextECF CodeLedger hardened binary for v${version} not found at ${BINARY_PATH}.`,
-        '',
-        'The postinstall step may have been skipped (e.g. --ignore-scripts).',
-        'This safe alias installs ContextECF CodeLedger. Avoid: npm install -g codeledger.',
-        '',
-        'Recover with one of:',
-        `  1. Upgrade: npm install -g contextecf-codeledger@latest`,
-        `  2. Retry this install: npm rebuild contextecf-codeledger`,
-        `  3. node "${installerPath}"`,
-        `  4. Re-run the install without --ignore-scripts`,
-        `  5. In an initialized repo, use: ./.codeledger/bin/codeledger ready`,
-        '',
-        'Or download the binary manually from:',
-        `  https://github.com/codeledgerECF/codeledger/releases/tag/v${version}`,
-      ].join('\n'),
+async function main() {
+  if (!existsSync(BINARY_PATH)) {
+    const repoLocal = findRepoLocalRuntime(launchDirectory());
+    if (repoLocal) {
+      runRepoLocal(repoLocal);
+    }
+
+    const { arch } = require('node:os');
+    const platformKey = `${platform()}-${arch()}`;
+    const installerPath = join(__dirname, '..', 'scripts', 'postinstall.js');
+
+    const { PLATFORM_MAP, downloadAndVerifyBinary, unsupportedPlatformMessage } = require('../scripts/postinstall.js');
+    if (!PLATFORM_MAP[platformKey]) {
+      // Don't waste time on a download attempt that can only ever fail —
+      // getBinaryPaths() would reject this platformKey immediately anyway.
+      // See postinstall.js's matching message for why this is "no
+      // committed timeline", not "try again later".
+      die(unsupportedPlatformMessage(platformKey));
+    }
+
+    process.stderr.write(
+      `codeledger: hardened binary for v${version} not cached locally — downloading now (one-time)...\n`,
     );
+    try {
+      await downloadAndVerifyBinary({ deadlineMs: ON_DEMAND_DEADLINE_MS });
+    } catch (err) {
+      die(
+        [
+          `hardened binary for v${version} not found at ${BINARY_PATH}, and the on-demand download just failed: ${err.message}`,
+          '',
+          'The postinstall step may have been skipped (e.g. --ignore-scripts).',
+          'Confirm the official scoped package is installed: @codeledger/cli.',
+          'Avoid the unrelated unscoped npm package: codeledger.',
+          '',
+          'Recover with one of:',
+          '  1. Retry: codeledger --version',
+          '  2. Reinstall: npm install -g @codeledger/cli@latest',
+          `  3. node "${installerPath}"`,
+          '  4. Re-run the install without --ignore-scripts',
+          '  5. In an initialized repo, use: ./.codeledger/bin/codeledger ready',
+          '',
+          'Or download the binary manually from:',
+          `  https://github.com/codeledgerECF/codeledger/releases/tag/v${version}`,
+        ].join('\n'),
+      );
+    }
   }
-}
 
-const result = spawnSync(BINARY_PATH, process.argv.slice(2), {
-  stdio: 'inherit',
-  env: process.env,
-});
+  const result = spawnSync(BINARY_PATH, process.argv.slice(2), {
+    stdio: 'inherit',
+    env: process.env,
+  });
 
-if (result.error) {
-  die(`failed to spawn binary: ${result.error.message}`);
+  if (result.error) {
+    die(`failed to spawn binary: ${result.error.message}`);
+  }
+
+  process.exit(result.status ?? 1);
 }
 
-process.exit(result.status ?? 1);
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextecf-codeledger",
-  "version": "0.10.79",
+  "version": "0.10.81",
   "mcpName": "io.github.codeledgerECF/codeledger",
   "description": "ContextECF CodeLedger — deterministic context selection for AI coding agents. Safe unscoped alias for @codeledger/cli; avoid the unrelated codeledger package.",
   "type": "commonjs",

package/scripts/postinstall.js

@@ -1,20 +1,31 @@
 #!/usr/bin/env node
 /*
- * ContextECF CodeLedger postinstall — download + verify the hardened binary.
+ * CodeLedger postinstall — download + verify the hardened binary.
  *
- * Runs automatically on `npm install -g contextecf-codeledger`. Downloads the
+ * Runs automatically on `npm install -g @codeledger/cli`. Downloads the
  * platform-specific hardened binary from the GitHub Release for this
  * exact version, verifies its SHA256 against SHA256SUMS-v<version>.txt
  * (also downloaded from the release), and writes it to the cache dir.
  *
+ * This is best-effort and always exits 0: if the download can't complete
+ * within the propagation window (e.g. installing a version whose release
+ * assets haven't landed yet, or aren't going to), npm must NOT treat the
+ * install as failed — a failed postinstall can roll back an existing
+ * working install. bin/codeledger.js retries the same download on-demand,
+ * synchronously, the first time the binary is actually needed.
+ *
  * Environment variables (all optional):
  *   CODELEDGER_SKIP_POSTINSTALL=1   — skip entirely (air-gapped installs)
+ *   CODELEDGER_RUN_UPGRADE=1        — after the binary download succeeds,
+ *                                     also run `codeledger upgrade`
  *   CODELEDGER_BINARY_URL=<url>     — override the release download base URL
  *                                     (for corporate mirrors / internal CDNs).
  *                                     Must serve the same filenames and a
  *                                     SHA256SUMS-v<version>.txt sibling file.
  *   CODELEDGER_CACHE_DIR=<path>     — override the cache directory
  *                                     (default: ~/.cache/codeledger/bin)
+ *   CODELEDGER_INSTALL_DEADLINE_MS=<ms> — override the download propagation
+ *                                     window (default: 150000 = 2.5 min)
  *
  * This file contains no engine logic. It only fetches, verifies, and writes
  * bytes. Safe to inspect, safe to mirror, safe to audit.
@@ -37,107 +48,79 @@ const { homedir, platform, arch } = require('node:os');
 
 const { version } = require('../package.json');
 
-// ─── config ──────────────────────────────────────────────────────────────────
-
-if (process.env.CODELEDGER_SKIP_POSTINSTALL === '1') {
-  console.log(
-    'codeledger: CODELEDGER_SKIP_POSTINSTALL=1 set, skipping ContextECF CodeLedger hardened binary download.',
-  );
-  process.exit(0);
-}
-
-// Skip when running inside this source workspace (dev mode). The presence of
-// pnpm-workspace.yaml two directories up is a reliable signal that this is not
-// a real end-user install, and the release binary for this version may not
-// exist yet.
-try {
-  const path = require('node:path');
-  const fs = require('node:fs');
-  const workspaceRoot = path.resolve(__dirname, '..', '..', '..');
-  if (fs.existsSync(path.join(workspaceRoot, 'pnpm-workspace.yaml'))) {
-    console.log(
-      'codeledger: in-workspace dev install detected, skipping ContextECF CodeLedger hardened binary download.',
-    );
-    process.exit(0);
-  }
-} catch {
-  // fall through to normal install
-}
+// ─── platform / path resolution (pure — no I/O, no process.exit) ──────────
 
-// darwin-x64 is temporarily absent from v0.10.6 — no working Intel
-// Mac runner on the release CI plan as of 2026-04-09. Intel Mac
-// users hit the "unsupported platform" soft-fail below, which tells
-// them to download manually from the GitHub Release. Re-add when a
-// working Intel Mac binary is available.
+// Only these native asset names are wired into this installer.
 const PLATFORM_MAP = {
   'darwin-arm64': 'darwin-arm64',
   'linux-x64': 'linux-x64',
 };
 
-const platformKey = `${platform()}-${arch()}`;
-const platformSuffix = PLATFORM_MAP[platformKey];
-
-if (!platformSuffix) {
-  if (platformKey === 'darwin-x64') {
-    console.log('');
-    console.log('codeledger: ContextECF CodeLedger Intel Mac (darwin-x64) detected.');
-    console.log('codeledger: Pre-built binaries are available for Apple Silicon (darwin-arm64) only.');
-    console.log('');
-    console.log('Options:');
-    console.log('  Safe alias: contextecf-codeledger. Official package: @codeledger/cli. Avoid: codeledger.');
-    console.log('  1. Use Rosetta 2 (recommended):');
-    console.log('       arch -arm64 npm install -g contextecf-codeledger@latest');
-    console.log('  2. If this repo was already initialized, use the vendored CLI:');
-    console.log('       ./.codeledger/bin/codeledger ready');
-    console.log('       node .codeledger/bin/codeledger-standalone.cjs ready');
-    console.log('  3. For a new repo without a vendored CLI, use a supported platform or Docker.');
-    console.log('  4. Download a binary manually from:');
-    console.log(`       https://github.com/codeledgerECF/codeledger/releases/tag/v${version}`);
-    console.log('');
-  } else {
-    console.error(
-      `codeledger: unsupported platform ${platformKey}. Supported: ${Object.keys(
-        PLATFORM_MAP,
-      ).join(', ')}`,
-    );
-    console.error(
-      `codeledger: v${version} does not provide a hardened binary for ${platformKey}.`,
-    );
-    console.error(
-      'codeledger: this installer is for ContextECF CodeLedger; you can still use the published source package or a supported release asset.',
-    );
-  }
-  // Fail softly: don't block `npm install` for unsupported platforms. The
-  // bin shim will tell the user what happened when they first run `codeledger`.
-  process.exit(0);
+function unsupportedPlatformMessage(platformKey) {
+  return [
+    `${platformKey} has no pre-built CodeLedger hardened binary.`,
+    `Supported native routes: ${Object.keys(PLATFORM_MAP).join(', ')}.`,
+    'A successful npm install does not establish a working runtime or MCP connection.',
+    'For an already initialized repository with a trusted vendored runtime:',
+    '  node .codeledger/bin/codeledger-standalone.cjs ready',
+    'For a fresh repository, use a supported host or a supported linux-x64 environment.',
+    'Skipping postinstall does not bootstrap a missing runtime; codeledger init cannot fix that loop.',
+    'Intel Macs cannot run an Apple Silicon binary through Rosetta.',
+    'Source-build prerequisites and limitations: https://github.com/codeledgerECF/codeledger/blob/main/docs/security/ENTERPRISE_ASSURANCE.md',
+  ].join('\n');
+}
+
+function getPlatformKey() {
+  return `${platform()}-${arch()}`;
+}
+
+function getCacheDir() {
+  return (
+    process.env.CODELEDGER_CACHE_DIR || join(homedir(), '.cache', 'codeledger', 'bin')
+  );
 }
 
 // Binaries are hosted on the public CodeLedger GitHub Releases page so
 // `npm install -g @codeledger/cli` can fetch them without authentication.
-const RELEASE_BASE =
-  process.env.CODELEDGER_BINARY_URL ||
-  `https://github.com/codeledgerECF/codeledger/releases/download/v${version}`;
+function getBinaryPaths(platformKey) {
+  const platformSuffix = PLATFORM_MAP[platformKey];
+  if (!platformSuffix) return null;
+
+  const releaseBase =
+    process.env.CODELEDGER_BINARY_URL ||
+    `https://github.com/codeledgerECF/codeledger/releases/download/v${version}`;
+  const binaryRemoteName = `codeledger-hardened-${platformSuffix}-v${version}`;
+  const cacheDir = getCacheDir();
 
-const BINARY_REMOTE_NAME = `codeledger-hardened-${platformSuffix}-v${version}`;
-const BINARY_URL = `${RELEASE_BASE}/${BINARY_REMOTE_NAME}`;
-const CHECKSUMS_URL = `${RELEASE_BASE}/SHA256SUMS-v${version}.txt`;
+  return {
+    binaryUrl: `${releaseBase}/${binaryRemoteName}`,
+    checksumsUrl: `${releaseBase}/SHA256SUMS-v${version}.txt`,
+    binaryRemoteName,
+    cacheDir,
+    binaryLocalPath: join(cacheDir, `codeledger-hardened-v${version}`),
+  };
+}
 
-const CACHE_DIR =
-  process.env.CODELEDGER_CACHE_DIR ||
-  join(homedir(), '.cache', 'codeledger', 'bin');
-const BINARY_LOCAL_NAME = `codeledger-hardened-v${version}`;
-const BINARY_LOCAL_PATH = join(CACHE_DIR, BINARY_LOCAL_NAME);
+function isBinaryCached() {
+  const paths = getBinaryPaths(getPlatformKey());
+  return Boolean(paths && existsSync(paths.binaryLocalPath));
+}
 
 // ─── http ────────────────────────────────────────────────────────────────────
 
-function fetchBufferOnce(url, redirectDepth = 0) {
+const FETCH_TIMEOUT_MS = 60_000;
+
+function fetchBufferOnce(url, redirectDepth = 0, expiresAt = Date.now() + FETCH_TIMEOUT_MS) {
   if (redirectDepth > 5) {
     return Promise.reject(new Error(`too many redirects fetching ${url}`));
   }
   return new Promise((resolve, reject) => {
+    const remaining = Math.min(FETCH_TIMEOUT_MS, expiresAt - Date.now());
+    if (remaining <= 0) { reject(new Error('Binary download deadline exceeded.')); return; }
     const req = https.get(
       url,
       {
+        timeout: FETCH_TIMEOUT_MS,
         headers: {
           'User-Agent': `codeledger-installer/${version}`,
           Accept: 'application/octet-stream',
@@ -153,7 +136,7 @@ function fetchBufferOnce(url, redirectDepth = 0) {
         ) {
           res.resume();
           const next = new URL(res.headers.location, url).toString();
-          fetchBufferOnce(next, redirectDepth + 1).then(resolve, reject);
+          fetchBufferOnce(next, redirectDepth + 1, expiresAt).then(resolve, reject);
           return;
         }
         if (res.statusCode !== 200) {
@@ -169,34 +152,51 @@ function fetchBufferOnce(url, redirectDepth = 0) {
         res.on('error', reject);
       },
     );
+    const timer = setTimeout(() => {
+      const error = new Error('Binary download deadline exceeded.');
+      req.destroy(error);
+      reject(error);
+    }, remaining);
     req.on('error', reject);
-    req.setTimeout(60_000, () => {
-      req.destroy(new Error(`timeout fetching ${url}`));
-    });
+    req.once('close', () => clearTimeout(timer));
   });
 }
 
+// Default propagation window for the postinstall-time attempt. Deliberately
+// a wall-clock deadline, not a fixed attempt count: the question is "how
+// long is it plausible for a just-published release's assets to still be
+// propagating," not "how many times did we try." A version whose GitHub
+// Release will never exist (npm published ahead of a working release — the
+// actual incident this retry policy is designed around) now fails within
+// this window instead of retrying for ~8 minutes that were never going to
+// succeed.
+const DEFAULT_DEADLINE_MS = Number(process.env.CODELEDGER_INSTALL_DEADLINE_MS) || 150_000; // 2.5 minutes
+
 // Retry wrapper that tolerates the short propagation window where a freshly
 // published package may be visible before all release assets are available.
-// A 404 is retried with exponential backoff; non-404 errors fail fast.
-async function fetchBuffer(url) {
-  const backoffs = [10, 20, 40, 60, 60, 60, 60, 60, 60, 60]; // seconds
+// A 404 is retried with exponential backoff bounded by deadlineMs;
+// non-404 errors fail fast.
+async function fetchBuffer(url, deadlineMs = DEFAULT_DEADLINE_MS) {
+  const start = Date.now();
+  let attempt = 0;
   let lastErr;
-  for (let i = 0; i <= backoffs.length; i++) {
+  for (;;) {
     try {
-      return await fetchBufferOnce(url);
+      return await fetchBufferOnce(url, 0, start + deadlineMs);
     } catch (err) {
       lastErr = err;
-      // Only retry on 404 — everything else is a hard failure
+      // Only retry on 404 — everything else is a hard failure.
       if (err.statusCode !== 404) throw err;
-      if (i === backoffs.length) break;
-      const wait = backoffs[i];
-      console.log(
-        `codeledger:   Binary pending — new release detected, retrying in ${wait}s ` +
-          `(attempt ${i + 1}/${backoffs.length + 1}). ` +
-          `This is normal for the first ~10 minutes after a release.`,
+      const elapsed = Date.now() - start;
+      const wait = Math.min(20_000, 5_000 * 2 ** attempt);
+      if (elapsed + wait >= deadlineMs) break;
+      attempt += 1;
+      const remainingSec = Math.round((deadlineMs - elapsed) / 1000);
+      console.error(
+        `codeledger:   Binary pending — retrying in ${Math.round(wait / 1000)}s ` +
+          `(${remainingSec}s left in propagation window).`,
       );
-      await new Promise((r) => setTimeout(r, wait * 1000));
+      await new Promise((r) => setTimeout(r, wait));
     }
   }
   throw lastErr;
@@ -221,72 +221,161 @@ function findExpectedSha(checksumsText, filename) {
   return null;
 }
 
-// ─── main ────────────────────────────────────────────────────────────────────
+// ─── download + verify (the reusable, side-effect-scoped core) ────────────
+
+// Downloads, verifies, and caches the hardened binary for the current
+// platform + this package's version. Throws on failure — does not exit the
+// process. Callers decide what "failure" means for them: postinstall.js
+// soft-fails (exit 0, retry later); bin/codeledger.js's on-demand path
+// falls through to a hard failure message since the user is blocked right
+// now.
+async function downloadAndVerifyBinary({ deadlineMs = DEFAULT_DEADLINE_MS } = {}) {
+  const platformKey = getPlatformKey();
+  const paths = getBinaryPaths(platformKey);
+  if (!paths) {
+    throw new Error(`unsupported platform ${platformKey}`);
+  }
 
-async function main() {
-  console.log(`codeledger: installing v${version} hardened binary for ${platformKey}`);
-  console.log(`  source:   ${BINARY_URL}`);
+  console.error(`codeledger: installing v${version} hardened binary for ${platformKey}`);
+  console.error(`  source:   ${paths.binaryUrl}`);
 
   const [checksumsBuf, binary] = await Promise.all([
-    fetchBuffer(CHECKSUMS_URL),
-    fetchBuffer(BINARY_URL),
+    fetchBuffer(paths.checksumsUrl, deadlineMs),
+    fetchBuffer(paths.binaryUrl, deadlineMs),
   ]);
   const checksums = checksumsBuf.toString('utf8');
 
-  const expectedSha = findExpectedSha(checksums, BINARY_REMOTE_NAME);
+  const expectedSha = findExpectedSha(checksums, paths.binaryRemoteName);
   if (!expectedSha) {
     throw new Error(
-      `${BINARY_REMOTE_NAME} not listed in SHA256SUMS-v${version}.txt — cannot verify binary integrity`,
+      `${paths.binaryRemoteName} not listed in SHA256SUMS-v${version}.txt — cannot verify binary integrity`,
     );
   }
 
   const actualSha = createHash('sha256').update(binary).digest('hex');
   if (actualSha !== expectedSha) {
     throw new Error(
-      `SHA256 mismatch for ${BINARY_REMOTE_NAME}:\n  expected ${expectedSha}\n  got      ${actualSha}`,
+      `SHA256 mismatch for ${paths.binaryRemoteName}:\n  expected ${expectedSha}\n  got      ${actualSha}`,
     );
   }
 
-  mkdirSync(CACHE_DIR, { recursive: true });
+  mkdirSync(paths.cacheDir, { recursive: true });
 
   // Atomic-ish write: write to tmp, rename
-  const tmpPath = `${BINARY_LOCAL_PATH}.tmp`;
+  const tmpPath = `${paths.binaryLocalPath}.tmp`;
   if (existsSync(tmpPath)) unlinkSync(tmpPath);
   writeFileSync(tmpPath, binary);
   chmodSync(tmpPath, 0o755);
-  if (existsSync(BINARY_LOCAL_PATH)) unlinkSync(BINARY_LOCAL_PATH);
-  // rename via fs for portability
-  require('node:fs').renameSync(tmpPath, BINARY_LOCAL_PATH);
-
-  console.log(`codeledger: installed ${BINARY_LOCAL_PATH}`);
-  console.log(`  sha256:   ${actualSha}`);
-  console.log('');
-  console.log('codeledger: next step inside your repo:');
-  console.log('  codeledger ready');
-  console.log('codeledger: ready initializes, scans, and prepares ambient task context.');
+  if (existsSync(paths.binaryLocalPath)) unlinkSync(paths.binaryLocalPath);
+  require('node:fs').renameSync(tmpPath, paths.binaryLocalPath);
+
+  console.error(`codeledger: installed ${paths.binaryLocalPath}`);
+  console.error(`  sha256:   ${actualSha}`);
+
+  return paths.binaryLocalPath;
 }
 
-// Only run main() when invoked directly (npm postinstall, node scripts/postinstall.js).
-// When require()'d from tests, just export the helper functions.
-if (require.main === module) {
-  main().catch((err) => {
-    console.error(`codeledger: postinstall failed — ${err.message}`);
-    console.error('');
-    console.error('Recovery options:');
-    console.error('  1. Upgrade: npm install -g contextecf-codeledger@latest');
-    console.error('  2. Retry this install: npm rebuild contextecf-codeledger');
-    console.error('  3. Air-gapped install:');
-    console.error('       CODELEDGER_SKIP_POSTINSTALL=1 npm install -g contextecf-codeledger@latest');
-    console.error('     then manually place the binary at:');
-    console.error(`       ${BINARY_LOCAL_PATH}`);
-    console.error('  4. Use a mirror:');
-    console.error('       CODELEDGER_BINARY_URL=https://your-mirror/path npm install -g contextecf-codeledger@latest');
-    console.error('');
+// Optional post-download step: run `codeledger upgrade` in the most likely
+// target repo so existing repos pick up refreshed ambient hooks/runtime
+// without a second manual command. Opt-in only — never runs by default.
+function maybeRunUpgrade() {
+  if (process.env.CODELEDGER_RUN_UPGRADE === '1') {
+    const { spawnSync } = require('node:child_process');
+    const path = require('node:path');
+    const fs = require('node:fs');
+    const codeledgerBin = path.join(__dirname, '..', 'bin', 'codeledger.js');
+    const initCwd = process.env['INIT_CWD'];
+    const homeCwd = process.env['HOME'] ?? process.env['USERPROFILE'] ?? process.cwd();
+    const upgradeCwd =
+      initCwd && fs.existsSync(path.join(initCwd, '.codeledger')) ? initCwd : homeCwd;
+    console.error('codeledger: CODELEDGER_RUN_UPGRADE=1 set, running upgrade...');
+    const upgradeResult = spawnSync(process.execPath, [codeledgerBin, 'upgrade'], {
+      stdio: 'inherit',
+      cwd: upgradeCwd,
+      env: { ...process.env, CODELEDGER_SKIP_AMBIENT_ACTIVATION: '1' },
+    });
+    if ((upgradeResult.status ?? 0) !== 0) {
+      console.error('');
+      console.error('codeledger: upgrade step encountered an issue. Run manually:');
+      console.error('  codeledger upgrade');
+    }
+  }
+}
+
+// ─── postinstall entry point ───────────────────────────────────────────────
+// All side-effecting decisions (env skip, dev-workspace skip, platform
+// gating, process.exit) live here, gated behind `require.main === module`
+// below — so requiring this file as a library (from bin/codeledger.js, or
+// from tests) never has side effects.
+
+async function runPostinstall() {
+  if (process.env.CODELEDGER_SKIP_POSTINSTALL === '1') {
     console.error(
-      `Manual download: https://github.com/codeledgerECF/codeledger/releases/tag/v${version}`,
+      'codeledger: CODELEDGER_SKIP_POSTINSTALL=1 set, skipping ContextECF CodeLedger hardened binary download.',
     );
-    process.exit(1);
-  });
+    return;
+  }
+
+  // Skip when running inside this source workspace (dev mode). The presence
+  // of pnpm-workspace.yaml two directories up is a reliable signal that
+  // this is not a real end-user install, and the release binary for this
+  // version may not exist yet.
+  try {
+    const path = require('node:path');
+    const fs = require('node:fs');
+    const workspaceRoot = path.resolve(__dirname, '..', '..', '..');
+    if (fs.existsSync(path.join(workspaceRoot, 'pnpm-workspace.yaml'))) {
+      console.error(
+        'codeledger: in-workspace dev install detected, skipping ContextECF CodeLedger hardened binary download.',
+      );
+      return;
+    }
+  } catch {
+    // fall through to normal install
+  }
+
+  const platformKey = getPlatformKey();
+
+  if (!PLATFORM_MAP[platformKey]) {
+    // Soft install failure does not create a fresh runtime on this platform.
+    console.error(`codeledger: ${unsupportedPlatformMessage(platformKey)}`);
+    return;
+  }
+
+  try {
+    await downloadAndVerifyBinary();
+    console.error('');
+    console.error('codeledger: install complete.');
+    console.error('  Next: cd your-repo && codeledger ready');
+    console.error('  Existing repos can refresh ambient hooks/runtime with: codeledger upgrade');
+    console.error('codeledger: ready initializes, scans, and prepares ambient task context.');
+    maybeRunUpgrade();
+  } catch (err) {
+    // Soft-fail, deliberately: exit 0 either way. A failed postinstall
+    // makes npm treat the whole install as failed, which can roll back an
+    // existing working install (the exact incident this is designed
+    // around). bin/codeledger.js retries this same download on-demand,
+    // synchronously, the first time it's actually needed.
+    console.error(`codeledger: could not pre-fetch the hardened binary — ${err.message}`);
+    console.error('codeledger: not fatal — it will download automatically on first "codeledger" invocation.');
+    console.error('codeledger: or, in an initialized repo, use: ./.codeledger/bin/codeledger ready');
+  }
+}
+
+// Only run the postinstall entry point when invoked directly (npm
+// postinstall, node scripts/postinstall.js). When required — from
+// bin/codeledger.js's on-demand download path, or from tests — this file
+// has no side effects; only the exported pure/reusable functions are used.
+if (require.main === module) {
+  runPostinstall().then(() => process.exit(0));
 }
 
-module.exports = { findExpectedSha, PLATFORM_MAP };
+module.exports = {
+  findExpectedSha,
+  PLATFORM_MAP,
+  downloadAndVerifyBinary,
+  getPlatformKey,
+  getBinaryPaths,
+  isBinaryCached,
+  unsupportedPlatformMessage,
+};