blun-king-cli 9.1.624 → 9.1.626

package/bin/managed-node.js

@@ -1,186 +1,186 @@
-'use strict';
-
-const crypto = require('node:crypto');
-const fs = require('node:fs');
-const https = require('node:https');
-const os = require('node:os');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-
-const NODE_VERSION = '24.15.0';
-const MAX_ARCHIVE_BYTES = 100 * 1024 * 1024;
-const DISTRIBUTIONS = {
-  'darwin-arm64': {
-    archive: `node-v${NODE_VERSION}-darwin-arm64.tar.gz`,
-    binary: path.join('bin', 'node'),
-    format: 'tar.gz',
-    sha256: '372331b969779ab5d15b949884fc6eaf88d5afe87bde8ba881d6400b9100ffc4',
-  },
-  'darwin-x64': {
-    archive: `node-v${NODE_VERSION}-darwin-x64.tar.gz`,
-    binary: path.join('bin', 'node'),
-    format: 'tar.gz',
-    sha256: 'ffd5ee293467927f3ee731a553eb88fd1f48cf74eebc2d74a6babe4af228673b',
-  },
-  'win32-arm64': {
-    archive: `node-v${NODE_VERSION}-win-arm64.zip`,
-    binary: 'node.exe',
-    format: 'zip',
-    sha256: 'c9eb7402eda26e2ba7e44b6727fc85a8de56c5095b1f71ebd3062892211aa116',
-  },
-  'win32-x64': {
-    archive: `node-v${NODE_VERSION}-win-x64.zip`,
-    binary: 'node.exe',
-    format: 'zip',
-    sha256: 'cc5149eabd53779ce1e7bdc5401643622d0c7e6800ade18928a767e940bb0e62',
-  },
-};
-
-function distributionFor(platform, arch) {
-  return DISTRIBUTIONS[`${platform}-${arch}`] || null;
-}
-
-function sha256File(file) {
-  const hash = crypto.createHash('sha256');
-  hash.update(fs.readFileSync(file));
-  return hash.digest('hex');
-}
-
-function downloadFile(url, destination, redirectsLeft = 3) {
-  return new Promise((resolve, reject) => {
-    const request = https.get(url, { timeout: 30_000 }, (response) => {
-      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-        response.resume();
-        if (redirectsLeft <= 0) {
-          reject(new Error('Zu viele Weiterleitungen beim Node.js-Download.'));
-          return;
-        }
-        const redirect = new URL(response.headers.location, url);
-        if (redirect.protocol !== 'https:') {
-          reject(new Error('Unsichere Weiterleitung beim Node.js-Download abgelehnt.'));
-          return;
-        }
-        downloadFile(redirect.href, destination, redirectsLeft - 1).then(resolve, reject);
-        return;
-      }
-
-      if (response.statusCode !== 200) {
-        response.resume();
-        reject(new Error(`Node.js-Download antwortete mit HTTP ${response.statusCode}.`));
-        return;
-      }
-
-      const contentLength = Number(response.headers['content-length'] || 0);
-      if (contentLength > MAX_ARCHIVE_BYTES) {
-        response.destroy();
-        reject(new Error('Node.js-Download ist groesser als erwartet.'));
-        return;
-      }
-
-      let received = 0;
-      const output = fs.createWriteStream(destination, { flags: 'wx' });
-      response.on('data', (chunk) => {
-        received += chunk.length;
-        if (received > MAX_ARCHIVE_BYTES) {
-          response.destroy(new Error('Node.js-Download ist groesser als erwartet.'));
-        }
-      });
-      response.on('error', reject);
-      output.on('error', reject);
-      output.on('finish', () => output.close(resolve));
-      response.pipe(output);
-    });
-    request.on('error', reject);
-    request.on('timeout', () => request.destroy(new Error('Zeitlimit beim Node.js-Download erreicht.')));
-  });
-}
-
-function usableNode(binary) {
-  if (!fs.existsSync(binary)) return false;
-  const result = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 5_000 });
-  return result.status === 0 && result.stdout.trim() === `v${NODE_VERSION}`;
-}
-
-function archiveRootName(distribution) {
-  const suffix = distribution.format === 'zip' ? '.zip' : '.tar.gz';
-  if (!distribution.archive.endsWith(suffix)) {
-    throw new Error('Unbekanntes Format der Node.js-Laufzeit.');
-  }
-  return distribution.archive.slice(0, -suffix.length);
-}
-
-function unpackArchive(archive, destination, distribution, platform) {
-  const command = platform === 'win32'
-    ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe')
-    : '/usr/bin/tar';
-  const args = distribution.format === 'zip'
-    ? ['-xf', archive, '-C', destination]
-    : ['-xzf', archive, '-C', destination];
-  return spawnSync(command, args, {
-    encoding: 'utf8',
-    timeout: 120_000,
-  });
-}
-
-async function ensureManagedNode(blunHome, platform, arch) {
-  const distribution = distributionFor(platform, arch);
-  if (!distribution) {
-    throw new Error(
-      `Automatische Node.js-Einrichtung wird fuer ${platform}-${arch} noch nicht unterstuetzt.`,
-    );
-  }
-
-  const installDir = path.join(
-    blunHome,
-    'runtime',
-    'node',
-    `v${NODE_VERSION}-${platform}-${arch}`,
-  );
-  const binary = path.join(installDir, distribution.binary);
-  if (usableNode(binary)) return binary;
-
-  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'blun-node-runtime-'));
-  try {
-    const archive = path.join(staging, distribution.archive);
-    await downloadFile(
-      `https://nodejs.org/dist/v${NODE_VERSION}/${distribution.archive}`,
-      archive,
-    );
-
-    const actualSha = sha256File(archive);
-    if (actualSha !== distribution.sha256) {
-      throw new Error('Die SHA-256-Pruefsumme der Node.js-Laufzeit stimmt nicht.');
-    }
-
-    const extractedName = archiveRootName(distribution);
-    const extractedDir = path.join(staging, extractedName);
-    const unpacked = unpackArchive(archive, staging, distribution, platform);
-    if (unpacked.status !== 0 || !usableNode(path.join(extractedDir, distribution.binary))) {
-      const detail = (unpacked.stderr || '').trim();
-      throw new Error(
-        `Die Node.js-Laufzeit konnte nicht entpackt werden${detail ? `: ${detail}` : '.'}`,
-      );
-    }
-
-    fs.mkdirSync(path.dirname(installDir), { recursive: true });
-    if (usableNode(binary)) return binary;
-    fs.rmSync(installDir, { recursive: true, force: true });
-    fs.renameSync(extractedDir, installDir);
-    if (!usableNode(binary)) throw new Error('Die installierte Node.js-Laufzeit startet nicht.');
-    return binary;
-  } finally {
-    fs.rmSync(staging, { recursive: true, force: true });
-  }
-}
-
-module.exports = {
-  DISTRIBUTIONS,
-  MAX_ARCHIVE_BYTES,
-  NODE_VERSION,
-  distributionFor,
-  ensureManagedNode,
-  archiveRootName,
-  sha256File,
-  unpackArchive,
-  usableNode,
-};
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const NODE_VERSION = '24.15.0';
+const MAX_ARCHIVE_BYTES = 100 * 1024 * 1024;
+const DISTRIBUTIONS = {
+  'darwin-arm64': {
+    archive: `node-v${NODE_VERSION}-darwin-arm64.tar.gz`,
+    binary: path.join('bin', 'node'),
+    format: 'tar.gz',
+    sha256: '372331b969779ab5d15b949884fc6eaf88d5afe87bde8ba881d6400b9100ffc4',
+  },
+  'darwin-x64': {
+    archive: `node-v${NODE_VERSION}-darwin-x64.tar.gz`,
+    binary: path.join('bin', 'node'),
+    format: 'tar.gz',
+    sha256: 'ffd5ee293467927f3ee731a553eb88fd1f48cf74eebc2d74a6babe4af228673b',
+  },
+  'win32-arm64': {
+    archive: `node-v${NODE_VERSION}-win-arm64.zip`,
+    binary: 'node.exe',
+    format: 'zip',
+    sha256: 'c9eb7402eda26e2ba7e44b6727fc85a8de56c5095b1f71ebd3062892211aa116',
+  },
+  'win32-x64': {
+    archive: `node-v${NODE_VERSION}-win-x64.zip`,
+    binary: 'node.exe',
+    format: 'zip',
+    sha256: 'cc5149eabd53779ce1e7bdc5401643622d0c7e6800ade18928a767e940bb0e62',
+  },
+};
+
+function distributionFor(platform, arch) {
+  return DISTRIBUTIONS[`${platform}-${arch}`] || null;
+}
+
+function sha256File(file) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(file));
+  return hash.digest('hex');
+}
+
+function downloadFile(url, destination, redirectsLeft = 3) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { timeout: 30_000 }, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        if (redirectsLeft <= 0) {
+          reject(new Error('Zu viele Weiterleitungen beim Node.js-Download.'));
+          return;
+        }
+        const redirect = new URL(response.headers.location, url);
+        if (redirect.protocol !== 'https:') {
+          reject(new Error('Unsichere Weiterleitung beim Node.js-Download abgelehnt.'));
+          return;
+        }
+        downloadFile(redirect.href, destination, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Node.js-Download antwortete mit HTTP ${response.statusCode}.`));
+        return;
+      }
+
+      const contentLength = Number(response.headers['content-length'] || 0);
+      if (contentLength > MAX_ARCHIVE_BYTES) {
+        response.destroy();
+        reject(new Error('Node.js-Download ist groesser als erwartet.'));
+        return;
+      }
+
+      let received = 0;
+      const output = fs.createWriteStream(destination, { flags: 'wx' });
+      response.on('data', (chunk) => {
+        received += chunk.length;
+        if (received > MAX_ARCHIVE_BYTES) {
+          response.destroy(new Error('Node.js-Download ist groesser als erwartet.'));
+        }
+      });
+      response.on('error', reject);
+      output.on('error', reject);
+      output.on('finish', () => output.close(resolve));
+      response.pipe(output);
+    });
+    request.on('error', reject);
+    request.on('timeout', () => request.destroy(new Error('Zeitlimit beim Node.js-Download erreicht.')));
+  });
+}
+
+function usableNode(binary) {
+  if (!fs.existsSync(binary)) return false;
+  const result = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 5_000 });
+  return result.status === 0 && result.stdout.trim() === `v${NODE_VERSION}`;
+}
+
+function archiveRootName(distribution) {
+  const suffix = distribution.format === 'zip' ? '.zip' : '.tar.gz';
+  if (!distribution.archive.endsWith(suffix)) {
+    throw new Error('Unbekanntes Format der Node.js-Laufzeit.');
+  }
+  return distribution.archive.slice(0, -suffix.length);
+}
+
+function unpackArchive(archive, destination, distribution, platform) {
+  const command = platform === 'win32'
+    ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe')
+    : '/usr/bin/tar';
+  const args = distribution.format === 'zip'
+    ? ['-xf', archive, '-C', destination]
+    : ['-xzf', archive, '-C', destination];
+  return spawnSync(command, args, {
+    encoding: 'utf8',
+    timeout: 120_000,
+  });
+}
+
+async function ensureManagedNode(blunHome, platform, arch) {
+  const distribution = distributionFor(platform, arch);
+  if (!distribution) {
+    throw new Error(
+      `Automatische Node.js-Einrichtung wird fuer ${platform}-${arch} noch nicht unterstuetzt.`,
+    );
+  }
+
+  const installDir = path.join(
+    blunHome,
+    'runtime',
+    'node',
+    `v${NODE_VERSION}-${platform}-${arch}`,
+  );
+  const binary = path.join(installDir, distribution.binary);
+  if (usableNode(binary)) return binary;
+
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'blun-node-runtime-'));
+  try {
+    const archive = path.join(staging, distribution.archive);
+    await downloadFile(
+      `https://nodejs.org/dist/v${NODE_VERSION}/${distribution.archive}`,
+      archive,
+    );
+
+    const actualSha = sha256File(archive);
+    if (actualSha !== distribution.sha256) {
+      throw new Error('Die SHA-256-Pruefsumme der Node.js-Laufzeit stimmt nicht.');
+    }
+
+    const extractedName = archiveRootName(distribution);
+    const extractedDir = path.join(staging, extractedName);
+    const unpacked = unpackArchive(archive, staging, distribution, platform);
+    if (unpacked.status !== 0 || !usableNode(path.join(extractedDir, distribution.binary))) {
+      const detail = (unpacked.stderr || '').trim();
+      throw new Error(
+        `Die Node.js-Laufzeit konnte nicht entpackt werden${detail ? `: ${detail}` : '.'}`,
+      );
+    }
+
+    fs.mkdirSync(path.dirname(installDir), { recursive: true });
+    if (usableNode(binary)) return binary;
+    fs.rmSync(installDir, { recursive: true, force: true });
+    fs.renameSync(extractedDir, installDir);
+    if (!usableNode(binary)) throw new Error('Die installierte Node.js-Laufzeit startet nicht.');
+    return binary;
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  DISTRIBUTIONS,
+  MAX_ARCHIVE_BYTES,
+  NODE_VERSION,
+  distributionFor,
+  ensureManagedNode,
+  archiveRootName,
+  sha256File,
+  unpackArchive,
+  usableNode,
+};

package/bin/managed-plugin-selection.cjs

@@ -1,122 +1,115 @@
-'use strict';
-const { createHash, randomUUID } = require('node:crypto');
-const fs = require('node:fs');
-const path = require('node:path');
-const { ensurePrivateDirectory, securePrivateTree } = require('./private-paths');
-const SCHEMA = 'blun.managed-plugin-selection/v1';
-
-function snapshotPluginTree(root, expectedEntries = null) {
+'use strict';
+const { createHash, randomUUID } = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { ensurePrivateDirectory, securePrivateTree } = require('./private-paths');
+const SCHEMA = 'blun.managed-plugin-selection/v1';
+
+function snapshotPluginTree(root) {
   const entries = [];
-  const expectedByPath = expectedEntries === null ? null
-    : new Map(expectedEntries.map(entry => [entry.path, entry]));
-  const rootStat = fs.lstatSync(root);
-  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) return null;
-  const visit = (directory, relativeDirectory = '') => {
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })
-      .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
-      const relativePath = path.join(relativeDirectory, entry.name);
-      const absolutePath = path.join(directory, entry.name);
+  const rootStat = fs.lstatSync(root);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) return null;
+  const visit = (directory, relativeDirectory = '') => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })
+      .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
+      const relativePath = path.join(relativeDirectory, entry.name);
+      const absolutePath = path.join(directory, entry.name);
       const stat = fs.lstatSync(absolutePath);
       if (stat.isSymbolicLink()) return false;
-      const expected = expectedByPath?.get(relativePath);
-      if (expectedByPath && !expected) return false;
       if (stat.isDirectory()) {
-        if (expected && expected.kind !== 'directory') return false;
-        entries.push({ kind: 'directory', path: relativePath });
-        if (!visit(absolutePath, relativePath)) return false;
+        entries.push({ kind: 'directory', path: relativePath });
+        if (!visit(absolutePath, relativePath)) return false;
       } else if (stat.isFile()) {
-        if (expected && (expected.kind !== 'file' || stat.size !== expected.content.length)) return false;
-        entries.push({ kind: 'file', path: relativePath, content: fs.readFileSync(absolutePath) });
-      } else return false;
-    }
-    return true;
-  };
-  if (!visit(root) || (expectedByPath && entries.length !== expectedByPath.size)) return null;
-  return entries;
+        entries.push({ kind: 'file', path: relativePath, content: fs.readFileSync(absolutePath) });
+      } else return false;
+    }
+    return true;
+  };
+  return visit(root) ? entries : null;
 }
-
-function digestPluginEntries(entries) {
-  if (entries === null) throw new Error('Invalid managed plugin tree');
-  const hash = createHash('sha256');
-  for (const entry of entries) {
-    hash.update(Buffer.from(`${entry.kind}\0${entry.path}\0`, 'utf8'));
-    if (entry.kind === 'file') {
-      const length = Buffer.allocUnsafe(8);
-      length.writeBigUInt64BE(BigInt(entry.content.length));
-      hash.update(length);
-      hash.update(entry.content);
-    }
-  }
-  return hash.digest('hex');
-}
-
-function samePath(left, right) {
-  const normalize = value => process.platform === 'win32' ? path.resolve(value).toLowerCase() : path.resolve(value);
-  return normalize(left) === normalize(right);
-}
-
-function scopedPluginRoot(blunDir, pluginRoot) {
-  const managed = path.resolve(blunDir, 'plugins', 'managed');
-  const root = path.resolve(pluginRoot);
-  if (!samePath(path.dirname(root), managed)) throw new Error('Selected AgentSpine root is outside this profile');
-  for (const directory of [blunDir, path.dirname(managed), managed, root]) {
-    const stat = fs.lstatSync(directory);
-    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('Selected AgentSpine root contains a linked directory');
-  }
-  if (!samePath(path.dirname(fs.realpathSync(root)), fs.realpathSync(managed))) {
-    throw new Error('Selected AgentSpine root resolves outside this profile');
-  }
-  return root;
-}
-
-function describeAgentSpineSelection({ blunDir, pluginRoot }) {
-  const root = scopedPluginRoot(blunDir, pluginRoot);
-  const digest = digestPluginEntries(snapshotPluginTree(root));
-  if (path.basename(root) !== `agent-spine-${digest}`) throw new Error('Selected AgentSpine digest mismatch');
-  return { schema: SCHEMA, digest };
-}
-
-function selectedAgentSpineRoot({ installed, blunDir }) {
-  const records = installed.plugins.filter(record => record.id === 'agent-spine');
-  if (!records.some(record => Object.hasOwn(record, 'managedSelection'))) return null;
-  if (records.length !== 1) throw new Error('Ambiguous AgentSpine selection');
-  const [record] = records;
-  const selection = record.managedSelection;
-  if (!selection || selection.schema !== SCHEMA || !/^[a-f0-9]{64}$/.test(selection.digest || '')
-    || Object.keys(selection).sort().join(',') !== 'digest,schema' || typeof record.root !== 'string') {
-    throw new Error('Invalid AgentSpine selection');
-  }
-  const actual = describeAgentSpineSelection({ blunDir, pluginRoot: record.root });
-  if (actual.digest !== selection.digest) throw new Error('Selected AgentSpine digest mismatch');
-  return record.root;
-}
-
-function copySelectedAgentSpinePlugin({ blunDir, sourceRoot }) {
-  const plugins = path.resolve(blunDir, 'plugins');
-  const managed = path.join(plugins, 'managed');
-  ensurePrivateDirectory(plugins);
-  ensurePrivateDirectory(managed);
-  const digest = digestPluginEntries(snapshotPluginTree(sourceRoot));
-  const pluginRoot = path.join(managed, `agent-spine-${digest}`);
-  if (fs.existsSync(pluginRoot)) {
-    describeAgentSpineSelection({ blunDir, pluginRoot });
-    return pluginRoot;
-  }
-  const staging = path.join(managed, `.agent-spine-selected-${process.pid}-${randomUUID()}.tmp`);
-  try {
-    fs.cpSync(sourceRoot, staging, { recursive: true, errorOnExist: true, force: false });
-    securePrivateTree(staging);
-    if (digestPluginEntries(snapshotPluginTree(staging)) !== digest) throw new Error('AgentSpine source changed during installation');
-    fs.renameSync(staging, pluginRoot);
-    describeAgentSpineSelection({ blunDir, pluginRoot });
-    return pluginRoot;
-  } finally {
-    if (!samePath(path.dirname(staging), managed) || !path.basename(staging).startsWith('.agent-spine-selected-')) {
-      throw new Error('Invalid AgentSpine staging cleanup path');
-    }
-    fs.rmSync(staging, { recursive: true, force: true });
-  }
-}
-
-module.exports = { snapshotPluginTree, digestPluginEntries, describeAgentSpineSelection,
-  selectedAgentSpineRoot, copySelectedAgentSpinePlugin };
+
+function digestPluginEntries(entries) {
+  if (entries === null) throw new Error('Invalid managed plugin tree');
+  const hash = createHash('sha256');
+  for (const entry of entries) {
+    hash.update(Buffer.from(`${entry.kind}\0${entry.path}\0`, 'utf8'));
+    if (entry.kind === 'file') {
+      const length = Buffer.allocUnsafe(8);
+      length.writeBigUInt64BE(BigInt(entry.content.length));
+      hash.update(length);
+      hash.update(entry.content);
+    }
+  }
+  return hash.digest('hex');
+}
+
+function samePath(left, right) {
+  const normalize = value => process.platform === 'win32' ? path.resolve(value).toLowerCase() : path.resolve(value);
+  return normalize(left) === normalize(right);
+}
+
+function scopedPluginRoot(blunDir, pluginRoot) {
+  const managed = path.resolve(blunDir, 'plugins', 'managed');
+  const root = path.resolve(pluginRoot);
+  if (!samePath(path.dirname(root), managed)) throw new Error('Selected AgentSpine root is outside this profile');
+  for (const directory of [blunDir, path.dirname(managed), managed, root]) {
+    const stat = fs.lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('Selected AgentSpine root contains a linked directory');
+  }
+  if (!samePath(path.dirname(fs.realpathSync(root)), fs.realpathSync(managed))) {
+    throw new Error('Selected AgentSpine root resolves outside this profile');
+  }
+  return root;
+}
+
+function describeAgentSpineSelection({ blunDir, pluginRoot }) {
+  const root = scopedPluginRoot(blunDir, pluginRoot);
+  const digest = digestPluginEntries(snapshotPluginTree(root));
+  if (path.basename(root) !== `agent-spine-${digest}`) throw new Error('Selected AgentSpine digest mismatch');
+  return { schema: SCHEMA, digest };
+}
+
+function selectedAgentSpineRoot({ installed, blunDir }) {
+  const records = installed.plugins.filter(record => record.id === 'agent-spine');
+  if (!records.some(record => Object.hasOwn(record, 'managedSelection'))) return null;
+  if (records.length !== 1) throw new Error('Ambiguous AgentSpine selection');
+  const [record] = records;
+  const selection = record.managedSelection;
+  if (!selection || selection.schema !== SCHEMA || !/^[a-f0-9]{64}$/.test(selection.digest || '')
+    || Object.keys(selection).sort().join(',') !== 'digest,schema' || typeof record.root !== 'string') {
+    throw new Error('Invalid AgentSpine selection');
+  }
+  const actual = describeAgentSpineSelection({ blunDir, pluginRoot: record.root });
+  if (actual.digest !== selection.digest) throw new Error('Selected AgentSpine digest mismatch');
+  return record.root;
+}
+
+function copySelectedAgentSpinePlugin({ blunDir, sourceRoot }) {
+  const plugins = path.resolve(blunDir, 'plugins');
+  const managed = path.join(plugins, 'managed');
+  ensurePrivateDirectory(plugins);
+  ensurePrivateDirectory(managed);
+  const digest = digestPluginEntries(snapshotPluginTree(sourceRoot));
+  const pluginRoot = path.join(managed, `agent-spine-${digest}`);
+  if (fs.existsSync(pluginRoot)) {
+    describeAgentSpineSelection({ blunDir, pluginRoot });
+    return pluginRoot;
+  }
+  const staging = path.join(managed, `.agent-spine-selected-${process.pid}-${randomUUID()}.tmp`);
+  try {
+    fs.cpSync(sourceRoot, staging, { recursive: true, errorOnExist: true, force: false });
+    securePrivateTree(staging);
+    if (digestPluginEntries(snapshotPluginTree(staging)) !== digest) throw new Error('AgentSpine source changed during installation');
+    fs.renameSync(staging, pluginRoot);
+    describeAgentSpineSelection({ blunDir, pluginRoot });
+    return pluginRoot;
+  } finally {
+    if (!samePath(path.dirname(staging), managed) || !path.basename(staging).startsWith('.agent-spine-selected-')) {
+      throw new Error('Invalid AgentSpine staging cleanup path');
+    }
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+module.exports = { snapshotPluginTree, digestPluginEntries, describeAgentSpineSelection,
+  selectedAgentSpineRoot, copySelectedAgentSpinePlugin };