aether-colony 5.3.2 → 5.4.0

package/bin/cli.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 const { program } = require('commander');
 
 // Error handling imports
@@ -1204,6 +1204,71 @@ function setupHub() {
   }
 }
 
+/**
+ * Refresh the Go binary during update flow.
+ * Downloads if missing or outdated. Non-blocking — failures are logged, never thrown.
+ *
+ * @param {string} version - Target version string
+ * @param {object} [options] - Options
+ * @param {boolean} [options.quiet=false] - Suppress output
+ * @returns {Promise<{refreshed: boolean, reason?: string}>} Result
+ */
+async function refreshBinary(version, options = {}) {
+  const { quiet = false } = options;
+
+  // Binary refresh is non-blocking — update always completes
+  try {
+    const binaryPath = path.join(HOME, '.aether', 'bin',
+      process.platform === 'win32' ? 'aether.exe' : 'aether');
+
+    // Check if binary exists
+    if (!fs.existsSync(binaryPath)) {
+      if (!quiet) log(`  ${c.colony('Binary:')} missing, downloading v${version}...`);
+      const { downloadBinary } = require('./lib/binary-downloader');
+      const result = await downloadBinary(version);
+      if (result.success) {
+        if (!quiet) log(`  ${c.success('Binary:')} installed v${version} -> ${c.dim(result.path)}`);
+        return { refreshed: true };
+      } else {
+        if (!quiet) log(`  ${c.warning('Binary:')} download skipped (${result.reason})`);
+        return { refreshed: false, reason: result.reason };
+      }
+    }
+
+    // Binary exists — check version
+    let installedVersion = null;
+    try {
+      const { execFileSync } = require('child_process');
+      const output = execFileSync(binaryPath, ['version'], { encoding: 'utf8', timeout: 5000 });
+      // Parse version from output like "aether v5.3.3" or just "v5.3.3"
+      const match = output.match(/v?(\d+\.\d+\.\d+)/);
+      if (match) installedVersion = match[1];
+    } catch {
+      // Can't determine version — download fresh
+    }
+
+    if (!installedVersion || installedVersion !== version) {
+      if (!quiet) log(`  ${c.colony('Binary:')} updating ${installedVersion || 'unknown'} -> v${version}...`);
+      const { downloadBinary } = require('./lib/binary-downloader');
+      const result = await downloadBinary(version);
+      if (result.success) {
+        if (!quiet) log(`  ${c.success('Binary:')} updated to v${version}`);
+        return { refreshed: true };
+      } else {
+        if (!quiet) log(`  ${c.warning('Binary:')} update skipped (${result.reason})`);
+        return { refreshed: false, reason: result.reason };
+      }
+    }
+
+    // Binary is up to date
+    if (!quiet) log(`  ${c.dim(`Binary: v${version} (up to date)`)}`);
+    return { refreshed: false, reason: 'up to date' };
+  } catch (err) {
+    if (!quiet) log(`  ${c.warning('Binary:')} refresh failed (${err.message})`);
+    return { refreshed: false, reason: err.message };
+  }
+}
+
 async function updateRepo(repoPath, sourceVersion, opts) {
   opts = opts || {};
   const dryRun = opts.dryRun || false;
@@ -1276,6 +1341,8 @@ async function updateRepo(repoPath, sourceVersion, opts) {
       removed: systemRemoved + commandsRemoved + agentsRemoved + rulesRemoved + agentsClaudeRemoved,
       removedFiles: allRemovedFiles,
       stashCreated: !!transaction.checkpoint?.stashRef,
+      stashRestored: result.stash_restored || false,
+      stashConflict: result.stash_conflict || false,
       checkpoint_id: result.checkpoint_id,
       cleanup: cleanupResult,
     };
@@ -1381,6 +1448,19 @@ async function performGlobalInstall() {
   log(c.colony('Setting up distribution hub...'));
   setupHub();
 
+  // Download Go binary (non-blocking)
+  try {
+    const { downloadBinary } = require('./lib/binary-downloader');
+    const result = await downloadBinary(VERSION);
+    if (result.success) {
+      log(`  ${c.colony('Binary:')} ${c.dim(result.path)}`);
+    } else {
+      log(`  ${c.warning('Binary:')} skipped (${result.reason})`);
+    }
+  } catch (err) {
+    log(`  ${c.warning('Binary:')} download failed (${err.message})`);
+  }
+
   log('');
   log(c.success('Install complete.'));
   log(`  ${c.queen('Claude Code:')} run /ant to get started`);
@@ -1535,7 +1615,13 @@ program
               log(`    Distribution chain: ${c.success('\u2713')} clean`);
             }
             if (result.stashCreated) {
-              log(`  Stash created. Recover with: cd ${repo.path} && git stash pop`);
+              if (result.stashRestored) {
+                log(`  Local changes restored automatically`);
+              } else if (result.stashConflict) {
+                log(`  ${c.warning('Stash restore had conflicts')} — resolve manually: cd ${repo.path} && git stash pop`);
+              } else {
+                log(`  Stash created. Recover with: cd ${repo.path} && git stash pop`);
+              }
             }
             updated++;
           } else {
@@ -1556,6 +1642,11 @@ program
         writeJsonSync(HUB_REGISTRY, registry);
       }
 
+      // Binary refresh is non-blocking — update always completes
+      if (!dryRun) {
+        await refreshBinary(sourceVersion, { quiet: false });
+      }
+
       const label = dryRun ? 'would update' : 'updated';
       let summary = `\nSummary: ${updated} ${label}, ${upToDate} up to date, ${pruned} pruned`;
       if (dirty > 0) summary += `, ${dirty} dirty (skipped)`;
@@ -1639,12 +1730,22 @@ program
         if (result.cleanup && result.cleanup.cleaned.length === 0 && result.cleanup.failed.length === 0) {
           console.log(`  Distribution chain: ${c.success('\u2713')} clean`);
         }
-        if (result.stashCreated) {
+        if (result.stashRestored) {
+          console.log(`  ${c.success('\u2713')} Local changes restored`);
+        } else if (result.stashConflict) {
+          console.log(`  ${c.warning('\u26A0')} Stash restore had conflicts — resolve manually: git stash pop`);
+        } else if (result.stashCreated) {
           console.log('  Git stash created. Recover with: git stash pop');
         }
         if (result.checkpoint_id) {
           console.log(`  Checkpoint: ${result.checkpoint_id}`);
         }
+
+        // Binary refresh is non-blocking — update always completes
+        if (!dryRun) {
+          await refreshBinary(sourceVersion);
+        }
+
         console.log('  Colony data (.aether/data/) untouched.');
       } catch (error) {
         // Handle UpdateError with prominent recovery commands (UPDATE-04)
@@ -2201,6 +2302,7 @@ module.exports = {
   loadCheckpointMetadata,
   saveCheckpointMetadata,
   isUserData,
+  refreshBinary,
   syncDirWithCleanup,
   syncSkillsToHub,
   listFilesRecursive,
@@ -2219,5 +2321,18 @@ function run() {
 
 // Parse command line arguments only when run directly (not when required as a module)
 if (require.main === module) {
+  // Delegation shim: if Go binary is available and version matches, pass through to it.
+  // Commands that must run in Node.js (install, update, setup) are excluded.
+  const { shouldDelegate, getBinaryPath } = require('./lib/version-gate');
+  if (shouldDelegate(process.argv)) {
+    const { spawnSync } = require('child_process');
+    const binaryPath = getBinaryPath();
+    const result = spawnSync(binaryPath, process.argv.slice(2), {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    process.exit(result.status);
+  }
+
   run();
 }

package/bin/lib/binary-downloader.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * Binary Downloader for Aether Colony
+ *
+ * Downloads the correct platform Go binary from GitHub Releases during
+ * `npm install -g aether-colony`. Verifies SHA-256 checksum before
+ * atomic install to ~/.aether/bin/aether.
+ *
+ * Uses ONLY Node.js built-in modules. No external dependencies.
+ */
+
+const https = require('https');
+const http = require('http');
+const crypto = require('crypto');
+const fs = require('fs');
+const fsPromises = require('fs/promises');
+const os = require('os');
+const path = require('path');
+const { execFile } = require('child_process');
+const { pipeline } = require('stream/promises');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+
+// Platform detection maps process.platform + process.arch to goreleaser naming
+const PLATFORM_MAP = {
+  darwin: 'darwin',
+  linux: 'linux',
+  win32: 'windows',
+};
+
+const ARCH_MAP = {
+  x64: 'amd64',
+  arm64: 'arm64',
+};
+
+/**
+ * Detect platform and architecture, mapped to goreleaser naming.
+ * @returns {{os: string, arch: string}|null} Platform info or null if unsupported
+ */
+function getPlatformArch() {
+  const goos = PLATFORM_MAP[process.platform];
+  const goarch = ARCH_MAP[process.arch];
+  if (!goos || !goarch) return null;
+  return { os: goos, arch: goarch };
+}
+
+/**
+ * Download a URL following HTTP redirects (GitHub releases always 302).
+ * Node.js https.get() does NOT follow redirects automatically.
+ *
+ * @param {string} url - URL to download
+ * @param {number} maxRedirects - Maximum redirect hops (default 5)
+ * @returns {Promise<import('http').IncomingMessage>} Response stream on 200
+ */
+function downloadWithRedirects(url, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    function attempt(currentUrl, redirectsLeft) {
+      const client = currentUrl.startsWith('https') ? https : http;
+      client.get(currentUrl, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          if (redirectsLeft <= 0) {
+            res.resume();
+            return reject(new Error('Too many redirects'));
+          }
+          res.resume(); // Drain response body before next request
+          return attempt(res.headers.location, redirectsLeft - 1);
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode}`));
+        }
+        resolve(res);
+      }).on('error', reject);
+    }
+    attempt(url, maxRedirects);
+  });
+}
+
+/**
+ * Download a URL and return the full response body as a string.
+ *
+ * @param {string} url - URL to download
+ * @returns {Promise<string>} Response body text
+ */
+async function downloadText(url) {
+  const response = await downloadWithRedirects(url);
+  return new Promise((resolve, reject) => {
+    let data = '';
+    response.on('data', (chunk) => { data += chunk; });
+    response.on('end', () => resolve(data));
+    response.on('error', reject);
+  });
+}
+
+/**
+ * Parse goreleaser checksums.txt to find the hash for a specific filename.
+ * Format: <sha256_hex>  <filename> (two-space separator)
+ *
+ * @param {string} checksumsContent - Full checksums.txt content
+ * @param {string} filename - Archive filename to find
+ * @returns {string|null} SHA-256 hex digest or null if not found
+ */
+function findChecksum(checksumsContent, filename) {
+  const lines = checksumsContent.split('\n');
+  for (const line of lines) {
+    const parts = line.split('  ');
+    if (parts.length >= 2 && parts[1] === filename) {
+      return parts[0];
+    }
+  }
+  return null;
+}
+
+/**
+ * Download an archive to a temp file while computing SHA-256 hash.
+ * Hashing happens during the stream -- no extra I/O pass.
+ *
+ * @param {string} url - Archive URL
+ * @param {string} tmpPath - Temp file path for the download
+ * @returns {Promise<{hash: string, tmpPath: string}>} Computed hash and temp file path
+ */
+async function downloadAndHash(url, tmpPath) {
+  const hash = crypto.createHash('sha256');
+  const fileStream = fs.createWriteStream(tmpPath);
+
+  const response = await downloadWithRedirects(url);
+
+  // Hash while streaming -- zero extra I/O
+  response.on('data', (chunk) => hash.update(chunk));
+
+  await pipeline(response, fileStream);
+
+  return { hash: hash.digest('hex'), tmpPath };
+}
+
+/**
+ * Extract binary from archive using system tar command.
+ * tar is available on macOS, Linux, and Windows 10+.
+ *
+ * @param {string} archivePath - Path to the archive file
+ * @param {string} destDir - Directory to extract into
+ * @param {string} goos - Goreleaser OS name (darwin, linux, windows)
+ * @returns {Promise<string>} Path to the extracted binary
+ */
+async function extractBinary(archivePath, destDir, goos) {
+  const binaryName = goos === 'windows' ? 'aether.exe' : 'aether';
+
+  await fsPromises.mkdir(destDir, { recursive: true });
+
+  await execFileAsync('tar', [
+    '-xf', archivePath,
+    '-C', destDir,
+    '--strip-components', '1',
+    binaryName,
+  ]);
+
+  return path.join(destDir, binaryName);
+}
+
+/**
+ * Atomically install a binary by renaming from temp to final path.
+ * fs.rename() is atomic on both POSIX and Windows (Node 14+).
+ *
+ * @param {string} extractedBinary - Path to the extracted binary
+ * @param {string} targetPath - Final install path
+ */
+async function atomicInstall(extractedBinary, targetPath) {
+  await fsPromises.mkdir(path.dirname(targetPath), { recursive: true });
+  await fsPromises.rename(extractedBinary, targetPath);
+  // Set executable permission on Unix
+  if (process.platform !== 'win32') {
+    await fsPromises.chmod(targetPath, 0o755);
+  }
+}
+
+/**
+ * Download and install the correct platform Go binary from GitHub Releases.
+ *
+ * This function NEVER throws. On any error it returns {success: false, reason: string}.
+ *
+ * @param {string} version - Version string (e.g. "5.3.3")
+ * @param {object} [options] - Download options
+ * @param {boolean} [options.quiet=false] - Suppress progress output
+ * @param {number} [options.timeout=30000] - Download timeout in milliseconds
+ * @returns {Promise<{success: boolean, reason?: string, path?: string}>} Result
+ */
+async function downloadBinary(version, options = {}) {
+  const { quiet = false, timeout = 30000 } = options;
+
+  try {
+    // 1. Platform detection
+    const platform = getPlatformArch();
+    if (!platform) {
+      return { success: false, reason: `Unsupported platform: ${process.platform}/${process.arch}` };
+    }
+
+    // 2. Construct URLs
+    const archiveExt = platform.os === 'windows' ? '.zip' : '.tar.gz';
+    const archiveFilename = `aether_${version}_${platform.os}_${platform.arch}${archiveExt}`;
+    const baseUrl = `https://github.com/calcosmic/Aether/releases/download/v${version}`;
+    const archiveUrl = `${baseUrl}/${archiveFilename}`;
+    const checksumsUrl = `${baseUrl}/checksums.txt`;
+
+    // 3. Download checksums.txt
+    let checksumsContent;
+    try {
+      checksumsContent = await downloadText(checksumsUrl);
+    } catch (err) {
+      return { success: false, reason: `Failed to download checksums: ${err.message}` };
+    }
+
+    // 4. Parse expected hash
+    const expectedHash = findChecksum(checksumsContent, archiveFilename);
+
+    // 5. Download archive and compute hash
+    const tmpArchive = path.join(os.tmpdir(), `aether-download-${Date.now()}.tmp`);
+
+    // Race download against timeout, clearing timer on success
+    let timeoutId;
+    const downloadPromise = downloadAndHash(archiveUrl, tmpArchive);
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => reject(new Error('Download timed out')), timeout);
+    });
+    const downloadResult = await Promise.race([downloadPromise, timeoutPromise])
+      .finally(() => clearTimeout(timeoutId));
+
+    const { hash: actualHash } = downloadResult;
+
+    // 6. Verify checksum
+    if (expectedHash && actualHash !== expectedHash) {
+      await fsPromises.unlink(tmpArchive).catch(() => {});
+      return { success: false, reason: `Checksum mismatch for ${archiveFilename}` };
+    }
+
+    // 7. Extract binary from archive
+    const tmpBinaryDir = path.join(os.tmpdir(), `aether-extract-${Date.now()}`);
+    const extractedBinary = await extractBinary(tmpArchive, tmpBinaryDir, platform.os);
+
+    // 8. Atomic install
+    const targetPath = path.join(
+      os.homedir(), '.aether', 'bin',
+      process.platform === 'win32' ? 'aether.exe' : 'aether'
+    );
+    await atomicInstall(extractedBinary, targetPath);
+
+    // 9. Cleanup temp files (best effort)
+    await fsPromises.unlink(tmpArchive).catch(() => {});
+    await fsPromises.rm(tmpBinaryDir, { recursive: true }).catch(() => {});
+
+    return { success: true, path: targetPath };
+  } catch (err) {
+    return { success: false, reason: err.message };
+  }
+}
+
+module.exports = {
+  downloadBinary,
+  getPlatformArch,
+  // Internal helpers exported for testing (prefixed with _)
+  _findChecksum: findChecksum,
+  _downloadWithRedirects: downloadWithRedirects,
+  _downloadText: downloadText,
+  _downloadAndHash: downloadAndHash,
+  _extractBinary: extractBinary,
+  _atomicInstall: atomicInstall,
+};

package/bin/lib/update-transaction.js

@@ -172,8 +172,9 @@ class UpdateTransaction {
 
     // Directories to exclude from sync (user data, local state, and separately-synced dirs)
     // v4.0: archive and chambers added — these are private and must not sync to target repos
-    // v6.0: oracle, midden, exchange added for complete user data protection
-    this.EXCLUDE_DIRS = ['data', 'dreams', 'oracle', 'midden', 'checkpoints', 'locks', 'temp', 'agents', 'commands', 'rules', 'archive', 'chambers', 'exchange'];
+    // v6.0: oracle, midden added for complete user data protection
+    // v7.0: exchange removed from exclusion — .sh scripts must distribute; .xml/.json data excluded by file extension
+    this.EXCLUDE_DIRS = ['data', 'dreams', 'oracle', 'midden', 'checkpoints', 'locks', 'temp', 'agents', 'commands', 'rules', 'archive', 'chambers'];
 
     // Files to exclude from sync (user wisdom, protected files)
     this.EXCLUDE_FILES = ['QUEEN.md'];
@@ -192,7 +193,6 @@ class UpdateTransaction {
       'temp',
       'archive',
       'chambers',
-      'exchange',
     ]);
     this.managedPrefixes = [
       '.claude/commands/ant',
@@ -792,6 +792,11 @@ class UpdateTransaction {
     if (this.EXCLUDE_FILES.includes(basename)) {
       return true;
     }
+    // Protect exchange data files — only .sh scripts should distribute
+    // Only filter files (not directories), so the exchange dir itself is traversed
+    if (parts.includes('exchange') && !basename.endsWith('.sh') && !relPath.endsWith('exchange')) {
+      return true;
+    }
     return false;
   }
 
@@ -1664,6 +1669,23 @@ class UpdateTransaction {
                           (this.syncResult?.agents?.removed?.length || 0) +
                           (this.syncResult?.rules?.removed?.length || 0);
 
+      // Restore stashed files on success
+      let stashRestored = false;
+      let stashConflict = false;
+      if (!dryRun && this.checkpoint?.stashRef) {
+        try {
+          execSync(`git stash pop ${this.checkpoint.stashRef}`, {
+            cwd: this.repoPath,
+            stdio: 'pipe',
+          });
+          stashRestored = true;
+          this.log(`  Restored stash ${this.checkpoint.stashRef}`);
+        } catch (err) {
+          stashConflict = true;
+          this.log(`  Warning: stash pop had conflicts — manual merge needed`);
+        }
+      }
+
       return {
         success: true,
         status: dryRun ? 'dry-run' : 'updated',
@@ -1672,6 +1694,8 @@ class UpdateTransaction {
         files_removed: filesRemoved,
         sync_result: this.syncResult,
         cleanup_result: this.cleanupResult || { cleaned: [], failed: [] },
+        stash_restored: stashRestored,
+        stash_conflict: stashConflict,
       };
 
     } catch (error) {

package/bin/lib/version-gate.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Version Gate Module
+ *
+ * Checks whether the Go binary at ~/.aether/bin/aether exists, is executable,
+ * and reports a version matching the npm package version. Provides delegation
+ * logic so that `aether` commands route to the Go binary when the gate passes
+ * and fall back to the Node.js CLI when it does not.
+ *
+ * Requirements: GATE-01, GATE-02, SHM-01, SHM-02
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const HOME = process.env.HOME || process.env.USERPROFILE;
+const BINARY_PATH = HOME ? path.join(HOME, '.aether', 'bin', 'aether') : null;
+
+// Commands that must always run in Node.js regardless of binary availability (SHM-02)
+const NODE_ONLY_COMMANDS = ['install', 'update', 'setup', 'setup-hub'];
+
+/**
+ * Compare two semver version strings.
+ * Handles optional 'v' prefix and compares major.minor.patch numerically.
+ * Pre-release tags are ignored for comparison purposes (treated as the base version).
+ *
+ * @param {string} a - First version string
+ * @param {string} b - Second version string
+ * @returns {number} -1 if a < b, 0 if a === b, 1 if a > b
+ */
+function compareVersions(a, b) {
+  const stripPrefix = (v) => String(v).replace(/^v/, '');
+  const parseParts = (v) => {
+    const cleaned = stripPrefix(v);
+    // Take only the numeric parts (ignore pre-release tags like -alpha.1)
+    const numericPart = cleaned.split('-')[0];
+    return numericPart.split('.').map((n) => {
+      const parsed = parseInt(n, 10);
+      return isNaN(parsed) ? 0 : parsed;
+    });
+  };
+
+  const aParts = parseParts(a);
+  const bParts = parseParts(b);
+  const maxLen = Math.max(aParts.length, bParts.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    const aVal = aParts[i] || 0;
+    const bVal = bParts[i] || 0;
+    if (aVal < bVal) return -1;
+    if (aVal > bVal) return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Get the expected path to the Go binary.
+ * @returns {string|null} Absolute path to the binary, or null if HOME is unset
+ */
+function getBinaryPath() {
+  return BINARY_PATH;
+}
+
+/**
+ * Check whether the Go binary is available and its version matches the npm package.
+ *
+ * Returns an object describing the binary state:
+ * - available: boolean - true if binary exists, is executable, and version matches
+ * - path: string - the expected binary path
+ * - version: string|null - the binary's reported version (null if unavailable)
+ * - reason: string|null - why the gate failed, if it did
+ *
+ * @param {object} [opts] - Options
+ * @param {string} [opts.binaryPath] - Override binary path (for testing)
+ * @param {string} [opts.packageVersion] - Override package version (for testing)
+ * @param {object} [opts.fs] - Override fs module (for testing)
+ * @param {object} [opts.childProcess] - Override child_process (for testing)
+ * @returns {{ available: boolean, path: string, version: string|null, reason: string|null }}
+ */
+function checkBinary(opts) {
+  opts = opts || {};
+  const binaryPath = opts.binaryPath || BINARY_PATH;
+  const pkgVersion = opts.packageVersion || require('../../package.json').version;
+  const fsMod = opts.fs || fs;
+  const cp = opts.childProcess || { execSync };
+
+  if (!binaryPath) {
+    return { available: false, path: binaryPath, version: null, reason: 'HOME not set' };
+  }
+
+  // Check binary exists
+  if (!fsMod.existsSync(binaryPath)) {
+    return { available: false, path: binaryPath, version: null, reason: 'binary not found' };
+  }
+
+  // Check executable
+  try {
+    fsMod.accessSync(binaryPath, fsMod.constants.X_OK);
+  } catch {
+    return { available: false, path: binaryPath, version: null, reason: 'binary not executable' };
+  }
+
+  // Get binary version — call `aether version` and strip "aether v" prefix
+  let binaryVersion;
+  try {
+    const output = cp.execSync(`"${binaryPath}" version`, {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    // Strip "aether " or "aether v" prefix (e.g. "aether v5.3.3" → "5.3.3")
+    binaryVersion = output.replace(/^aether\s+v?/, '');
+  } catch {
+    return { available: false, path: binaryPath, version: null, reason: 'binary version check failed' };
+  }
+
+  // Compare versions (compareVersions handles v-prefix on both sides)
+  if (compareVersions(binaryVersion, pkgVersion) !== 0) {
+    return {
+      available: false,
+      path: binaryPath,
+      version: binaryVersion,
+      reason: `version mismatch: binary=${binaryVersion}, package=${pkgVersion}`,
+    };
+  }
+
+  return { available: true, path: binaryPath, version: binaryVersion, reason: null };
+}
+
+/**
+ * Determine whether the current command should be delegated to the Go binary.
+ *
+ * @param {string[]} argv - process.argv (or equivalent)
+ * @param {object} [opts] - Options (forwarded to checkBinary)
+ * @returns {boolean} True if the command should be delegated to Go
+ */
+function shouldDelegate(argv, opts) {
+  opts = opts || {};
+
+  // Extract command name: skip node and script path
+  // argv[0] = node, argv[1] = script path, argv[2] = command name
+  const args = argv.slice(2);
+  const command = args[0];
+
+  // No command means help/version — still delegate if possible
+  if (!command) {
+    const check = checkBinary(opts);
+    return check.available;
+  }
+
+  // Strip leading dashes
+  const cleanCommand = command.replace(/^--?/, '');
+
+  // Node-only commands never delegate (SHM-02)
+  if (NODE_ONLY_COMMANDS.includes(cleanCommand)) {
+    return false;
+  }
+
+  // Global flags (--help, --version, --no-color, --quiet) — delegate if binary available
+  if (command.startsWith('-')) {
+    const check = checkBinary(opts);
+    return check.available;
+  }
+
+  // All other commands: delegate if version gate passes
+  const check = checkBinary(opts);
+  return check.available;
+}
+
+module.exports = {
+  compareVersions,
+  checkBinary,
+  shouldDelegate,
+  getBinaryPath,
+  NODE_ONLY_COMMANDS,
+};