contextecf-codeledger 0.10.80 → 0.10.82

package/bin/codeledger.js

@@ -1,25 +1,39 @@
 #!/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 launcher and its installation helpers ship 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 { dirname, join, resolve } = require('node:path');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { resolveRuntimePin, compareRuntimeVersions, isRuntimePinTrusted } = require('../scripts/runtime-pin.js');
+const { existsSync, realpathSync, statSync } = require('node:fs');
+const { basename, dirname, join, resolve } = require('node:path');
 const { homedir, platform } = require('node:os');
 
-const { version } = require('../package.json');
+const { name: packageName, version } = require('../package.json');
+
+// `codeledger-mcp` bin alias (same file, no extra JS): for MCP registries
+// that cannot pass arguments, it always runs `mcp start` + the user's args.
+// Every other invocation forwards argv unchanged, including a bare launch,
+// so the CLI's own bare-launch MCP detection applies.
+const MCP_ALIAS = /^codeledger-mcp(\.c?js)?$/i.test(basename(process.argv[1] || ''));
+const ARGS = MCP_ALIAS ? ['mcp', 'start', ...process.argv.slice(2)] : process.argv.slice(2);
 
 const CACHE_DIR =
   process.env.CODELEDGER_CACHE_DIR ||
@@ -37,14 +51,51 @@ function die(msg, code = 1) {
   process.exit(code);
 }
 
+// Repair commands use the installed version, so an old pin cannot trap an upgrade.
+function repairing() {
+  const commands = [];
+  for (let i = 0; i < ARGS.length && ARGS[i] !== '--'; i++) {
+    if (ARGS[i] === '--cwd') { i++; continue; }
+    if (!ARGS[i].startsWith('-')) commands.push(ARGS[i]);
+  }
+  return ['vendor', 'upgrade', 'update', 'init'].includes(commands[0]);
+}
+
+function findPinnedRuntime(startDir) {
+  if (process.env.CODELEDGER_GLOBAL_VERSION_PROBE === '1' || repairing()) return null;
+  let root = resolve(startDir);
+  while (true) {
+    const pin = resolveRuntimePin(join(root, '.codeledger'), { fs, path, crypto }, compareRuntimeVersions);
+    if (pin) {
+      const trustDir = process.env.CODELEDGER_RUNTIME_TRUST_DIR || join(homedir(), '.cache', 'codeledger', 'runtime-trust');
+      if (isRuntimePinTrusted(root, pin.manifest, { fs, path, crypto }, trustDir)) return { kind: 'standalone', path: pin.path, repoRoot: root };
+      process.stderr.write('codeledger: repository runtime has no installed trust receipt; using the global installation. Run the installed codeledger vendor command to install and trust its verified runtime.\n');
+      return null;
+    }
+    if (existsSync(join(root, '.git'))) return null;
+    const parent = dirname(root);
+    if (parent === root) return null;
+    root = parent;
+  }
+}
+
+// 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);
   while (true) {
+    if (existsSync(join(current, '.codeledger', 'runtime.json'))) return null;
+    // Legacy scripts require an explicit environment-level repository trust decision.
+    if (process.env.CODELEDGER_TRUST_LEGACY_RUNTIME !== '1') return null;
     const wrapper = join(current, '.codeledger', 'bin', 'codeledger');
     const standalone = join(current, '.codeledger', 'bin', 'codeledger-standalone.cjs');
     if (existsSync(wrapper)) return { kind: 'wrapper', path: wrapper, repoRoot: current };
     if (existsSync(standalone)) return { kind: 'standalone', path: standalone, repoRoot: current };
+    if (existsSync(join(current, '.git'))) return null;
     const parent = dirname(current);
     if (parent === current) return null;
     current = parent;
@@ -54,20 +105,19 @@ function findRepoLocalRuntime(startDir) {
 function runRepoLocal(runtime) {
   process.stderr.write(
     [
-      `codeledger: ContextECF CodeLedger hardened binary for v${version} is not installed in the global cache.`,
+      `codeledger: using the repository runtime instead of the global v${version} installation.`,
       `codeledger: using repo-local runtime at ${runtime.path}`,
       '',
     ].join('\n'),
   );
   const command = runtime.kind === 'standalone' ? process.execPath : runtime.path;
   const args = runtime.kind === 'standalone'
-    ? [runtime.path, ...process.argv.slice(2)]
-    : process.argv.slice(2);
+    ? [runtime.path, ...ARGS]
+    : ARGS;
   const result = spawnSync(command, args, {
     stdio: 'inherit',
-    cwd: runtime.repoRoot,
+    cwd: process.cwd(),
     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 +125,106 @@ 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 = ARGS;
+  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' || (args.length === 0 && !process.stdin.isTTY))) 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() {
+  const pinned = findPinnedRuntime(launchDirectory());
+  if (pinned) runRepoLocal(pinned);
+  if (existsSync(BINARY_PATH)) {
+    const problem = require('../scripts/postinstall.js').verifyCachedBinary(BINARY_PATH);
+    if (problem) {
+      process.stderr.write(`codeledger: cached binary at ${BINARY_PATH} failed verification (${problem}); discarding it and downloading a verified copy.\n`);
+      try { fs.unlinkSync(BINARY_PATH); } catch (error) { die(`could not remove the unverified cached binary: ${error.message}. Delete ${BINARY_PATH} and retry.`); }
+    }
+  }
+  if (!existsSync(BINARY_PATH)) {
+    const repoLocal = repairing() ? null : 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, readInstallFailure, unpublishedAssetsMessage } = 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));
+    }
+
+    const priorFailure = readInstallFailure();
+    if (priorFailure) {
+      process.stderr.write(`codeledger: the install step could not fetch the hardened binary (${priorFailure.at}): ${priorFailure.message}\n`);
+    }
+    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) {
+      const unpublished = unpublishedAssetsMessage(err);
+      die(
+        [
+          `hardened binary for v${version} not found at ${BINARY_PATH}, and the on-demand download just failed: ${err.message}`,
+          ...(unpublished ? ['', unpublished,
+            'Retrying or reinstalling this version will not help until they are published.',
+            'To use a published version instead, list them with: npm view @codeledger/cli versions'] : [
+            '',
+            '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 this version: npm install -g ${packageName}@${version}`,
+          `  3. node "${installerPath}"`,
+          '  4. Re-run the install without --ignore-scripts',
+          '  5. In an initialized repo, use: ./.codeledger/bin/codeledger ready',
+          '',
+          `Release page for v${version} (it exists only once that release is published):`,
+          `  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, ARGS, {
+    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().catch((error) => die(error.message));

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "contextecf-codeledger",
-  "version": "0.10.80",
+  "version": "0.10.82",
   "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",
   "bin": {
-    "codeledger": "./bin/codeledger.js"
+    "codeledger": "./bin/codeledger.js",
+    "codeledger-mcp": "./bin/codeledger.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js"

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.
@@ -31,113 +42,157 @@ const {
   chmodSync,
   existsSync,
   unlinkSync,
+  readFileSync,
+  statSync,
 } = require('node:fs');
 const { join } = require('node:path');
 const { homedir, platform, arch } = require('node:os');
 
 const { version } = require('../package.json');
 
-// ─── config ──────────────────────────────────────────────────────────────────
+// ─── platform / path resolution (pure — no I/O, no process.exit) ──────────
+
+// Only these native asset names are wired into this installer.
+const PLATFORM_MAP = {
+  'darwin-arm64': 'darwin-arm64',
+  'linux-x64': 'linux-x64',
+};
+
+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()}`;
+}
 
-if (process.env.CODELEDGER_SKIP_POSTINSTALL === '1') {
-  console.log(
-    'codeledger: CODELEDGER_SKIP_POSTINSTALL=1 set, skipping ContextECF CodeLedger hardened binary download.',
+function getCacheDir() {
+  return (
+    process.env.CODELEDGER_CACHE_DIR || join(homedir(), '.cache', 'codeledger', 'bin')
   );
-  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);
+// Binaries are hosted on the public CodeLedger GitHub Releases page so
+// `npm install -g @codeledger/cli` can fetch them without authentication.
+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();
+
+  return {
+    binaryUrl: `${releaseBase}/${binaryRemoteName}`,
+    checksumsUrl: `${releaseBase}/SHA256SUMS-v${version}.txt`,
+    binaryRemoteName,
+    cacheDir,
+    binaryLocalPath: join(cacheDir, `codeledger-hardened-v${version}`),
+  };
+}
+
+// The verified SHA-256 is recorded beside the cached binary so every launch can
+// reject a truncated, replaced, or tampered cache before executing it.
+function receiptPath(binaryPath) {
+  return `${binaryPath}.sha256.json`;
+}
+
+function writeVerifiedReceipt(binaryPath, sha256) {
+  const stat = statSync(binaryPath);
+  writeFileSync(receiptPath(binaryPath), JSON.stringify({ schema: 1, version, sha256, size: stat.size }) + '\n');
+}
+
+/** Returns null when the cached binary matches its install receipt, else the reason it does not. */
+function verifyCachedBinary(binaryPath) {
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync(receiptPath(binaryPath), 'utf8'));
+  } catch {
+    return 'no install receipt';
   }
-} catch {
-  // fall through to normal install
+  if (!receipt || receipt.schema !== 1 || receipt.version !== version || !/^[a-f0-9]{64}$/.test(String(receipt.sha256))) return 'invalid install receipt';
+  let stat;
+  try {
+    stat = statSync(binaryPath);
+  } catch {
+    return 'binary missing';
+  }
+  if (!stat.isFile() || stat.size === 0) return 'binary is empty or not a file';
+  if (stat.size !== receipt.size) return 'binary size changed since install';
+  // Hashed on every launch: size or timestamps can be preserved by a same-size replacement.
+  const actual = createHash('sha256').update(readFileSync(binaryPath)).digest('hex');
+  return actual === receipt.sha256 ? null : 'SHA256 mismatch with install receipt';
 }
 
-// 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.
-const PLATFORM_MAP = {
-  'darwin-arm64': 'darwin-arm64',
-  'linux-x64': 'linux-x64',
-};
+// npm hides postinstall output by default, so a soft failure is recorded where
+// the first `codeledger` run can report it.
+function installFailurePath() {
+  return join(getCacheDir(), `install-failure-v${version}.json`);
+}
 
-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.',
-    );
+function recordInstallFailure(err) {
+  try {
+    mkdirSync(getCacheDir(), { recursive: true });
+    writeFileSync(installFailurePath(), JSON.stringify({
+      schema: 1, version, at: new Date().toISOString(),
+      status: typeof err.statusCode === 'number' ? err.statusCode : null,
+      message: String(err.message).split('\n')[0].slice(0, 300),
+    }) + '\n');
+  } catch { /* Reporting is best effort; the install stays a soft failure. */ }
+}
+
+function readInstallFailure() {
+  try {
+    const record = JSON.parse(readFileSync(installFailurePath(), 'utf8'));
+    return record && record.schema === 1 && record.version === version ? record : null;
+  } catch {
+    return null;
   }
-  // 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);
 }
 
-// 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 clearInstallFailure() {
+  try { unlinkSync(installFailurePath()); } catch { /* Nothing recorded. */ }
+}
 
-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`;
+/** A 404 after the propagation window means this version's release assets are not published. */
+function unpublishedAssetsMessage(err) {
+  return err && err.statusCode === 404
+    ? `The v${version} release assets were not found (HTTP 404): this version's hardened binaries are not published yet, or were withdrawn.`
+    : null;
+}
 
-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) && verifyCachedBinary(paths.binaryLocalPath) === null);
+}
 
 // ─── 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 +208,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 +224,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 +293,171 @@ 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);
+  writeVerifiedReceipt(paths.binaryLocalPath, actualSha);
+  clearInstallFailure();
+
+  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.
+    recordInstallFailure(err);
+    console.error(`codeledger: could not pre-fetch the hardened binary — ${err.message}`);
+    const unpublished = unpublishedAssetsMessage(err);
+    if (unpublished) console.error(`codeledger: ${unpublished}`);
+    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');
+  }
 }
 
-module.exports = { findExpectedSha, PLATFORM_MAP };
+// 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,
+  downloadAndVerifyBinary,
+  getPlatformKey,
+  getBinaryPaths,
+  isBinaryCached,
+  unsupportedPlatformMessage,
+  verifyCachedBinary,
+  writeVerifiedReceipt,
+  readInstallFailure,
+  recordInstallFailure,
+  unpublishedAssetsMessage,
+};

package/scripts/runtime-pin.js

@@ -0,0 +1,125 @@
+/* Generated by scripts/generate-runtime-resolver.mjs. Public installation contract only. */
+'use strict';
+module.exports = (() => {
+/** Strict SemVer 2.0, shared by pin validation and explicit installation. */
+function parseRuntimeVersion(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(value);
+  if (!match || match[0] !== value) throw new Error(`Invalid runtime version: ${value}. Use an exact semantic version.`);
+  const core = match.slice(1, 4).map(Number);
+  const prerelease = match[4]?.split('.') ?? [];
+  if (core.some((n) => !Number.isSafeInteger(n)) || prerelease.some((p) => /^\d+$/.test(p) && (p.length > 1 && p.startsWith('0')))) {
+    throw new Error(`Invalid runtime version: ${value}`);
+  }
+  return { core, prerelease };
+}
+
+function compareRuntimeVersions(left, right) {
+  const a = parseRuntimeVersion(left);
+  const b = parseRuntimeVersion(right);
+  for (let i = 0; i < 3; i++) {
+    if (a.core[i] !== b.core[i]) return a.core[i] < b.core[i] ? -1 : 1;
+  }
+  if (!a.prerelease.length || !b.prerelease.length) {
+    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length ? -1 : 1;
+  }
+  for (let i = 0; i < Math.max(a.prerelease.length, b.prerelease.length); i++) {
+    const x = a.prerelease[i];
+    const y = b.prerelease[i];
+    if (x === y) continue;
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) return x.length !== y.length ? (x.length < y.length ? -1 : 1) : x < y ? -1 : 1;
+    if (xn !== yn) return xn ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function runtimeGenerationSha256(bytes, notices, crypto) {
+  return crypto.createHash('sha256').update(String(bytes.length) + ':').update(bytes).update(notices === null ? '-1:' : String(notices.length) + ':').update(notices || Buffer.alloc(0)).digest('hex');
+}
+
+function resolveRuntimePin(
+  codeledgerDir,
+  io,
+  compare,
+) {
+  const manifestPath = io.path.join(codeledgerDir, 'runtime.json');
+  if (!io.fs.existsSync(manifestPath)) return null;
+  if (io.fs.lstatSync(codeledgerDir).isSymbolicLink() || io.fs.lstatSync(manifestPath).isSymbolicLink()) throw new Error('Runtime state must not be symlinked. Run codeledger vendor from the owning repository.');
+  if (io.fs.statSync(manifestPath).size > 65536) throw new Error('runtime.json exceeds its 64 KiB contract bound. Repair with codeledger vendor.');
+  let raw;
+  try { raw = JSON.parse(io.fs.readFileSync(manifestPath, 'utf8')); } catch (error) { throw new Error('.codeledger/runtime.json is not valid JSON (' + error.message + '). Restore it from version control, or repair with codeledger vendor.'); }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Invalid runtime.json: expected an object. Repair with codeledger vendor.');
+  const m = raw;
+  if (m.schema_version !== 'codeledger/runtime/v1' || typeof m.installation_id !== 'string' || typeof m.version !== 'string' || typeof m.min_runtime !== 'string'
+    || typeof m.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(m.sha256)
+    || (m.distribution !== 'full' && m.distribution !== 'open') || !['fail-open-v1', 'legacy'].includes(m.hook_contract)
+    || !m.source || typeof m.source.kind !== 'string' || typeof m.source.location !== 'string'
+    || !m.build || m.build.content_sha256 !== m.sha256 || (m.build.revision !== null && typeof m.build.revision !== 'string')
+    || (m.build.source_dirty !== undefined && m.build.source_dirty !== null && typeof m.build.source_dirty !== 'boolean')
+    || (m.build.generation_sha256 === undefined && m.build.legal_sha256 !== undefined)
+    || (m.build.generation_sha256 !== undefined && (typeof m.build.generation_sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(m.build.generation_sha256) || (m.build.legal_sha256 !== null && !/^[a-f0-9]{64}$/.test(m.build.legal_sha256))))
+    || typeof m.entrypoint !== 'string' || m.entrypoint !== `bin/runtime/${m.version}-${m.build.generation_sha256 || m.sha256}/codeledger-standalone.cjs`) {
+    throw new Error('Invalid runtime.json contract. Repair with codeledger vendor.');
+  }
+  for (const reference of [m.previous, m.migration_fallback]) {
+    if (reference === undefined) continue;
+    if (!reference || typeof reference !== 'object' || !/^[a-f0-9]{64}$/.test(reference.sha256) || typeof reference.entrypoint !== 'string') throw new Error('Invalid previous runtime reference. Repair with codeledger vendor.');
+    if (reference.version !== null) compare(reference.version, reference.version);
+    const generation = reference.generation_sha256 || reference.sha256;
+    if (!/^[a-f0-9]{64}$/.test(generation) || (reference.entrypoint !== `bin/runtime/legacy-${reference.sha256}/codeledger-standalone.cjs` && (reference.version === null || reference.entrypoint !== `bin/runtime/${reference.version}-${generation}/codeledger-standalone.cjs`))) throw new Error('Invalid previous runtime path. Repair with codeledger vendor.');
+  }
+  if (compare(m.version, m.min_runtime) < 0) throw new Error('Pinned runtime is older than its configuration contract. Run codeledger upgrade.');
+  if (compare(m.version, '0.10.82-0') >= 0 && m.build.generation_sha256 === undefined) throw new Error('Runtime generation identity is missing. Repair with codeledger vendor.');
+  const root = io.fs.realpathSync(codeledgerDir);
+  if (!io.fs.existsSync(io.path.resolve(root, m.entrypoint))) throw new Error('Pinned runtime is missing: .codeledger/' + m.entrypoint + '. Restore it from version control (git checkout -- .codeledger/bin), or repair with codeledger vendor.');
+  const runtimePath = io.fs.realpathSync(io.path.resolve(root, m.entrypoint));
+  const rel = io.path.relative(root, runtimePath);
+  if (rel.startsWith('..') || io.path.isAbsolute(rel) || runtimePath !== io.path.resolve(root, m.entrypoint) || !io.fs.statSync(runtimePath).isFile()) {
+    throw new Error('Pinned runtime escapes the repository. Repair with codeledger vendor.');
+  }
+  const bytes = io.fs.readFileSync(runtimePath);
+  if (io.crypto.createHash('sha256').update(bytes).digest('hex') !== m.sha256) {
+    throw new Error('Pinned runtime checksum mismatch. Repair with codeledger vendor; do not execute the modified artifact.');
+  }
+  if (m.build.generation_sha256 !== undefined) {
+    let notices = null;
+    if (m.build.legal_sha256 !== null) {
+      const legal = runtimePath + '.LEGAL.txt';
+      if (!io.fs.existsSync(legal)) throw new Error('Pinned notices are missing: ' + legal + '. Restore them from version control, or repair with codeledger vendor.');
+      if (io.fs.lstatSync(legal).isSymbolicLink()) throw new Error('Pinned notices must not be symlinked. Repair with codeledger vendor.');
+      notices = io.fs.readFileSync(legal);
+      if (io.crypto.createHash('sha256').update(notices).digest('hex') !== m.build.legal_sha256) throw new Error('Pinned notices checksum mismatch. Repair with codeledger vendor.');
+    }
+    if (runtimeGenerationSha256(bytes, notices, io.crypto) !== m.build.generation_sha256) throw new Error('Pinned generation checksum mismatch. Repair with codeledger vendor.');
+  }
+  const header = bytes.subarray(0, 65536).toString('utf8');
+  const version = /^\/\* CODELEDGER_STANDALONE_VERSION:([^\s*]+) \*\//m.exec(header)?.[1];
+  const flavor = header.includes('/* CodeLedger Open CLI') ? 'open' : header.includes('/* CodeLedger Standalone CLI') ? 'full' : null;
+  if (version !== m.version || flavor !== m.distribution) throw new Error('Pinned runtime version or distribution does not match runtime.json.');
+  return { manifest: m, path: runtimePath };
+}
+
+
+function runtimeTrustKey(root, manifest, io) {
+  return io.crypto.createHash('sha256').update(JSON.stringify([io.fs.realpathSync(root), manifest])).digest('hex');
+}
+function isRuntimePinTrusted(root, manifest, io, trustDir) {
+  if (!trustDir || trustDir === 'disabled') return false;
+  try {
+    const directory = io.fs.realpathSync(trustDir);
+    const repo = io.fs.realpathSync(root);
+    const relative = io.path.relative(repo, directory);
+    if (!relative || (!relative.startsWith('..' + io.path.sep) && relative !== '..' && !io.path.isAbsolute(relative))) return false;
+    const key = runtimeTrustKey(root, manifest, io);
+    const file = io.path.join(directory, key + '.json');
+    const stat = io.fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) return false;
+    const receipt = JSON.parse(io.fs.readFileSync(file, 'utf8'));
+    return receipt.schema === 1 && receipt.key === key;
+  } catch { return false; }
+}
+return {parseRuntimeVersion, compareRuntimeVersions, resolveRuntimePin, runtimeGenerationSha256, runtimeTrustKey, isRuntimePinTrusted};
+})();