openyida 2026.10.13 → 2026.10.14

package/lib/agent/command-receipt.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { managedError } = require('./managed-context');
+const { readManagedContext } = require('./managed-context');
+const { beginManagedMutationCapture, classifyManagedMutation } = require('./mutation-receipt');
+
+const MAX_RECEIPT_BYTES = 16 * 1024;
+
+function retryReceiptFileOperation(operation) {
+  const delays = [20, 40, 80, 160, 320];
+  for (let attempt = 0; ; attempt++) {
+    try {return operation();} catch (error) {
+      if (process.platform !== 'win32' || attempt === delays.length ||
+          !['EBUSY', 'EPERM', 'EACCES'].includes(error.code)) {throw error;}
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delays[attempt]);
+    }
+  }
+}
+
+function writeReceipt(directory, receipt) {
+  const bytes = JSON.stringify(receipt);
+  if (Buffer.byteLength(bytes) > MAX_RECEIPT_BYTES) {throw managedError('MANAGED_RECEIPT_INVALID', 'managed_receipt_invalid');}
+  const temporary = path.join(directory, `.pending-${crypto.randomUUID()}`);
+  let fd;
+  let failure;
+  try {
+    fd = fs.openSync(temporary, 'wx', 0o600);
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    retryReceiptFileOperation(() => fs.renameSync(temporary, path.join(directory, `${receipt.id}.json`)));
+    if (process.platform !== 'win32') {
+      const parent = fs.openSync(directory, 'r');
+      try {fs.fsyncSync(parent);} finally {fs.closeSync(parent);}
+    }
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    if (fd !== undefined) {fs.closeSync(fd);}
+    if (fs.existsSync(temporary)) {retryReceiptFileOperation(() => fs.unlinkSync(temporary));}
+  } catch (error) {
+    // Preserve the publish error if cleanup also encounters a Windows lock.
+    if (!failure) {failure = error;}
+  }
+  if (failure) {throw failure;}
+}
+
+// One bounded receipt only for an explicit successful Yida write. No argv,
+// stdout, source, credentials, or crash-time intent record is persisted.
+function beginCommandReceipt({ command, args = [], env = process.env, consoleObject = console } = {}) {
+  if (env.OPENYIDA_MANAGED_RUN !== '1') {return { finish() {} };}
+  // Only an allowlisted Yida write gets a durable receipt. Reads, help and
+  // ordinary CLI bookkeeping must not create files in the attempt directory.
+  if (!classifyManagedMutation(command, args)) {return { finish() {} };}
+  const context = readManagedContext(env);
+  const directory = env.OPENYIDA_AGENT_RECEIPTS_DIR;
+  if (!directory || !path.isAbsolute(directory) || fs.realpathSync(directory) !== path.resolve(directory)) {
+    throw managedError('MANAGED_RECEIPT_INVALID', 'managed_receipt_invalid');
+  }
+  const info = fs.lstatSync(directory);
+  if (!info.isDirectory() || info.isSymbolicLink() || process.platform !== 'win32' && (info.mode & 0o077)) {
+    throw managedError('MANAGED_RECEIPT_INVALID', 'managed_receipt_invalid');
+  }
+  if (fs.readdirSync(directory).length >= 4000) {throw managedError('MANAGED_RECEIPT_INVALID', 'managed_receipt_invalid');}
+  const receipt = { schemaVersion: 1, id: crypto.randomUUID(), runId: context.runId,
+    attemptId: context.attemptId };
+  const capture = beginManagedMutationCapture({ command, args, env, consoleObject, eventId: receipt.id });
+  let finished = false;
+  return {
+    finish(exitCode = 0) {
+      if (finished) {return;}
+      finished = true;
+      const mutation = exitCode === 0 ? capture.commit() : (capture.discard(), null);
+      if (mutation) {writeReceipt(directory, { ...receipt, mutation });}
+    },
+  };
+}
+
+module.exports = { beginCommandReceipt, writeReceipt, MAX_RECEIPT_BYTES };

package/lib/agent/connection-store.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { CliError } = require('../core/cli-error');
+const { t } = require('../core/i18n');
+const { mkdirPrivate } = require('./private-directory');
+
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+function failure(code = 'AGENT_CONNECTION_STATE_INVALID') {
+  return new CliError(t('agent.identity_invalid'), { code });
+}
+
+function privateDirectory(directory) {
+  mkdirPrivate(directory);
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {throw failure();}
+  if (process.platform !== 'win32') {
+    fs.chmodSync(directory, 0o700);
+    if ((fs.statSync(directory).mode & 0o077) !== 0) {throw failure();}
+  }
+  return directory;
+}
+
+function readJson(file, allowedKeys) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 32 * 1024) {throw failure();}
+  if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {throw failure();}
+  let value;
+  try {value = JSON.parse(fs.readFileSync(file, 'utf8'));} catch {throw failure();}
+  if (!value || Array.isArray(value) || typeof value !== 'object' || Object.keys(value).some(key => !allowedKeys.includes(key))) {throw failure();}
+  return value;
+}
+
+function atomicJson(file, value) {
+  const directory = privateDirectory(path.dirname(file));
+  const temporary = path.join(directory, `.pending-${process.pid}-${crypto.randomBytes(12).toString('hex')}`);
+  fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' });
+  fs.renameSync(temporary, file);
+  if (process.platform !== 'win32') {fs.chmodSync(file, 0o600);}
+}
+
+function storedEndpoint(value) {
+  let endpoint;
+  try {endpoint = new URL(value);} catch {throw failure();}
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(endpoint.hostname);
+  if ((endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && loopback)) ||
+      endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {throw failure();}
+  return endpoint.toString().replace(/\/+$/, '');
+}
+
+function installation(root) {
+  privateDirectory(root);
+  const file = path.join(root, 'installation.json');
+  if (fs.existsSync(file)) {
+    const value = readJson(file, ['schemaVersion', 'installationId']);
+    if (value.schemaVersion !== 1 || !ID.test(value.installationId || '')) {throw failure();}
+    return value.installationId;
+  }
+  const installationId = crypto.randomUUID();
+  try {
+    fs.writeFileSync(file, `${JSON.stringify({ schemaVersion: 1, installationId })}\n`, { mode: 0o600, flag: 'wx' });
+    return installationId;
+  } catch (error) {
+    if (error && error.code === 'EEXIST') {return installation(root);}
+    throw error;
+  }
+}
+
+function enrollmentSlot(token) {
+  const enrollmentId = typeof token === 'string' ? token.split('.', 1)[0] : '';
+  return ID.test(enrollmentId) ? enrollmentId : crypto.randomUUID();
+}
+
+function prepareConnection(root, enrollmentToken) {
+  const installationId = installation(root);
+  const connections = privateDirectory(path.join(root, 'connections'));
+  const stateDir = privateDirectory(path.join(connections, enrollmentSlot(enrollmentToken)));
+  const publicState = path.join(stateDir, 'device.json');
+  if (fs.existsSync(publicState)) {
+    const existing = readJson(publicState, [
+      'installationId', 'endpoint', 'endpointId', 'deviceId', 'devicePublicKey',
+      'expiresAt', 'refreshExpiresAt', 'credentialVersion', 'refreshActionId',
+    ]);
+    if (existing.installationId !== installationId) {throw failure();}
+  } else {
+    atomicJson(publicState, { installationId });
+  }
+  return { installationId, stateDir };
+}
+
+function listConnections(root) {
+  if (!fs.existsSync(root)) {return [];}
+  const rootStat = fs.lstatSync(root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || (process.platform !== 'win32' && (rootStat.mode & 0o077) !== 0)) {throw failure();}
+  const installationFile = path.join(root, 'installation.json');
+  const connections = path.join(root, 'connections');
+  if (!fs.existsSync(installationFile) || !fs.existsSync(connections)) {return [];}
+  const installationState = readJson(installationFile, ['schemaVersion', 'installationId']);
+  if (installationState.schemaVersion !== 1 || !ID.test(installationState.installationId || '')) {throw failure();}
+  const installId = installationState.installationId;
+  const connectionsStat = fs.lstatSync(connections);
+  if (!connectionsStat.isDirectory() || connectionsStat.isSymbolicLink() || (process.platform !== 'win32' && (connectionsStat.mode & 0o077) !== 0)) {throw failure();}
+  const byConnection = new Map();
+  for (const name of fs.readdirSync(connections).sort()) {
+    if (!ID.test(name)) {continue;}
+    const stateDir = path.join(connections, name);
+    let stat;
+    try {stat = fs.lstatSync(stateDir);} catch {continue;}
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {throw failure();}
+    const file = path.join(stateDir, 'device.json');
+    if (!fs.existsSync(file)) {continue;}
+    const value = readJson(file, [
+      'installationId', 'endpoint', 'endpointId', 'deviceId', 'devicePublicKey',
+      'expiresAt', 'refreshExpiresAt', 'credentialVersion', 'refreshActionId',
+    ]);
+    if (value.installationId !== installId) {throw failure();}
+    if (!value.deviceId) {continue;}
+    if (!ID.test(value.deviceId) || !ID.test(value.endpointId || '')) {throw failure();}
+    const candidate = {
+      installationId: installId,
+      stateDir,
+      endpoint: storedEndpoint(value.endpoint),
+      endpointId: value.endpointId,
+      connectionId: value.deviceId,
+      credentialVersion: Number.isSafeInteger(value.credentialVersion) ? value.credentialVersion : 0,
+      modifiedAt: fs.statSync(file).mtimeMs,
+    };
+    const previous = byConnection.get(candidate.connectionId);
+    if (!previous || candidate.credentialVersion > previous.credentialVersion ||
+        (candidate.credentialVersion === previous.credentialVersion && candidate.modifiedAt > previous.modifiedAt)) {
+      byConnection.set(candidate.connectionId, candidate);
+    }
+  }
+  return [...byConnection.values()]
+    .sort((a, b) => a.connectionId.localeCompare(b.connectionId))
+    .map(connection => ({
+      installationId: connection.installationId,
+      stateDir: connection.stateDir,
+      endpoint: connection.endpoint,
+      endpointId: connection.endpointId,
+      connectionId: connection.connectionId,
+    }));
+}
+
+module.exports = { installation, prepareConnection, listConnections };

package/lib/agent/diagnostic-log.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { redactString } = require('../core/redact');
+const { mkdirPrivate } = require('./private-directory');
+
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 100 * 1024 * 1024;
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_FILES = 256;
+const FIELDS = new Set([
+  'command', 'component', 'errorCode', 'statusCode', 'closeCode', 'endpointId',
+  'provider', 'runtimeId', 'sessionId', 'runId', 'attemptId', 'phase', 'status',
+  'runtimeVersion', 'providerVersion',
+]);
+
+function isProductLog(name) {
+  return /^openyida-local-agent-[a-z0-9_-]+-\d{8}T\d{6}Z-\d+(?:\.\d+)?\.jsonl$/.test(name);
+}
+
+function cleanup(dir, current) {
+  const now = Date.now();
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !isProductLog(entry.name)) {continue;}
+    const target = path.join(dir, entry.name);
+    const stat = fs.statSync(target);
+    if (now - stat.mtimeMs > MAX_AGE_MS) {
+      try {fs.unlinkSync(target);} catch { /* best-effort diagnostic cleanup */ }
+      continue;
+    }
+    files.push({ target, size: stat.size, mtimeMs: stat.mtimeMs });
+  }
+  files.sort((a, b) => a.mtimeMs - b.mtimeMs);
+  let total = files.reduce((sum, file) => sum + file.size, 0);
+  let remaining = files.length;
+  for (const file of files) {
+    if (remaining <= MAX_FILES && total <= MAX_TOTAL_BYTES) {break;}
+    if (file.target === current) {continue;}
+    try {fs.unlinkSync(file.target); total -= file.size; remaining--;} catch { /* retry next launch */ }
+  }
+}
+
+function createDiagnosticLog(dir) {
+  try {
+    mkdirPrivate(dir);
+    if (!fs.lstatSync(dir).isDirectory()) {return () => {};}
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+    const file = path.join(dir, `openyida-local-agent-launcher-${stamp}-${process.pid}.jsonl`);
+    fs.closeSync(fs.openSync(file, 'a', 0o600));
+    cleanup(dir, file);
+    return (level, event, values = {}) => {
+      try {
+        if (!/^[a-z0-9_]{1,100}$/.test(event)) {return;}
+        const record = { schema: 'openyida.local_agent.diagnostic.v1', timestamp: new Date().toISOString(), level, event, os: process.platform, arch: process.arch };
+        for (const [key, value] of Object.entries(values)) {
+          if (!FIELDS.has(key)) {continue;}
+          if (typeof value === 'string') {record[key] = redactString(value.slice(0, 512));}
+          else if (typeof value === 'boolean' || typeof value === 'number') {record[key] = value;}
+        }
+        const line = `${JSON.stringify(record)}\n`;
+        const currentSize = fs.existsSync(file) ? fs.statSync(file).size : 0;
+        if (Buffer.byteLength(line) <= 8192 && currentSize + Buffer.byteLength(line) <= MAX_FILE_BYTES) {
+          fs.appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+        }
+      } catch { /* diagnostics must never affect the product path */ }
+    };
+  } catch {
+    return () => {};
+  }
+}
+
+function defaultDiagnosticDir(homedir = os.homedir()) {
+  return path.join(homedir, '.openyida', 'local-agent', 'logs');
+}
+
+// Read only product diagnostic JSONL, not device state, journals or credentials.
+// Failed enrollment has no completed Connection, so read the installation log
+// directory rather than depending on listConnections finding a paired device.
+function readRecentCredentialFailures(dir, now = Date.now()) {
+  const reasons = new Set(['protocol_invalid', 'device_invalid', 'access_format_invalid',
+    'refresh_format_invalid', 'version_invalid', 'access_expired', 'refresh_expired', 'rotation_binding_invalid']);
+  const results = [];
+  try {
+    const directory = fs.lstatSync(dir);
+    if (!directory.isDirectory() || directory.isSymbolicLink()) {return results;}
+    const files = fs.readdirSync(dir, { withFileTypes: true })
+      .filter(entry => entry.isFile() && entry.name.startsWith('openyida-local-agent-runtime-') && isProductLog(entry.name))
+      .flatMap(entry => {
+        try {return [{ file: path.join(dir, entry.name), stat: fs.lstatSync(path.join(dir, entry.name)) }];}
+        catch {return [];}
+      })
+      .filter(item => item.stat.isFile() && !item.stat.isSymbolicLink() &&
+        item.stat.size <= MAX_FILE_BYTES && item.stat.mtimeMs >= now - 2 * 60 * 60 * 1000)
+      .sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs).slice(0, 8);
+    for (const { file, stat: snapshot } of files) {
+      let raw;
+      let fd;
+      try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES || stat.ino !== snapshot.ino || stat.dev !== snapshot.dev) {continue;}
+        const data = Buffer.alloc(stat.size);
+        const bytes = fs.readSync(fd, data, 0, data.length, 0);
+        raw = data.subarray(0, bytes).toString('utf8');
+      } catch {continue;} finally {if (fd !== undefined) {fs.closeSync(fd);}}
+      for (const line of raw.split('\n')) {
+        if (!line || Buffer.byteLength(line) > 8192) {continue;}
+        let record;
+        try {record = JSON.parse(line);} catch {continue;}
+        if (!record || record.schema !== 'openyida.local_agent.diagnostic.v1' ||
+          !['runtime_failed', 'connection_error'].includes(record.event) || record.errorCode !== 'DEVICE_CREDENTIAL_RESPONSE_INVALID') {continue;}
+        const timestamp = Date.parse(record.timestamp);
+        if (!Number.isFinite(timestamp) || timestamp < now - 2 * 60 * 60 * 1000 || timestamp > now + 5 * 60 * 1000) {continue;}
+        const safe = { timestamp: new Date(timestamp).toISOString(), errorCode: 'DEVICE_CREDENTIAL_RESPONSE_INVALID', historical: true };
+        if (reasons.has(record.credentialReason)) {safe.credentialReason = record.credentialReason;}
+        if (['connect', 'run', 'reauthenticate'].includes(record.phase)) {safe.phase = record.phase;}
+        if (typeof record.endpointId === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(record.endpointId)) {safe.endpointId = redactString(record.endpointId);}
+        for (const key of ['accessRemainingSeconds', 'refreshRemainingSeconds']) {
+          if (Number.isSafeInteger(record[key])) {safe[key] = record[key];}
+        }
+        results.push(safe);
+        results.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        if (results.length > 5) {results.length = 5;}
+      }
+    }
+  } catch { /* Log diagnostics are optional, including while files rotate. */ }
+  return results.sort((a, b) => b.timestamp.localeCompare(a.timestamp)).slice(0, 5);
+}
+
+module.exports = { createDiagnosticLog, defaultDiagnosticDir, isProductLog, readRecentCredentialFailures };

package/lib/agent/frozen-bundle.js

@@ -0,0 +1,298 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CliError } = require('../core/cli-error');
+const { t } = require('../core/i18n');
+const { digest, readRegularFile, platformPackageName } = require('./runtime-package');
+const { parseStrictJson, PRODUCTION_RUNTIME_PLATFORMS } = require('./runtime-manifest');
+
+const MAX_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 1024 * 1024 * 1024;
+const MAX_FILES = 30000;
+const MAX_BUNDLE_MANIFEST_BYTES = 16 * 1024 * 1024;
+const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i;
+
+// Retry only transient Windows publication locks; never remove a winner.
+function publishBundle(stage, root) {
+  const delays = [20, 40, 80, 160, 320];
+  for (let attempt = 0; ; attempt++) {
+    try {fs.renameSync(stage, root); return;} catch (error) {
+      if (process.platform !== 'win32' || attempt === delays.length ||
+          !['EBUSY', 'EPERM', 'EACCES'].includes(error.code) || fs.existsSync(root)) {throw error;}
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delays[attempt]);
+    }
+  }
+}
+
+function bundleError(code = 'AGENT_BUNDLE_INVALID') {return new CliError(t('agent.bundle_invalid'), { code });}
+function slash(value) {return value.split(path.sep).join('/');}
+
+function privateDirectory(directory) {
+  if (!path.isAbsolute(directory)) {throw bundleError();}
+  // Canonicalize an existing ancestor before creating anything. Verify every
+  // canonical parent against replacement by other OS users. A root-owned
+  // sticky temp directory is acceptable; our descendants must be private.
+  const suffix = [];
+  let ancestor = directory;
+  while (!fs.existsSync(ancestor)) {suffix.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor);}
+  if (fs.lstatSync(ancestor).isSymbolicLink()) {throw bundleError();}
+  let current = fs.realpathSync(ancestor);
+  const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+  for (let parent = current; ; parent = path.dirname(parent)) {
+    const stat = fs.lstatSync(parent);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {throw bundleError();}
+    if (process.platform !== 'win32' && ((stat.uid !== uid && stat.uid !== 0) ||
+        (stat.mode & 0o022) && !(stat.uid === 0 && stat.mode & 0o1000))) {throw bundleError('AGENT_BUNDLE_UNSAFE_DIRECTORY');}
+    if (parent === path.dirname(parent)) {break;}
+  }
+  for (const component of suffix) {
+    current = path.join(current, component);
+    try {fs.mkdirSync(current, { mode: 0o700 });} catch (error) {if (error.code !== 'EEXIST') {throw error;}}
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || process.platform !== 'win32' && (stat.uid !== uid || stat.mode & 0o077)) {throw bundleError('AGENT_BUNDLE_UNSAFE_DIRECTORY');}
+  }
+  const final = fs.lstatSync(current);
+  if (process.platform !== 'win32' && (final.uid !== uid || final.mode & 0o077)) {throw bundleError('AGENT_BUNDLE_UNSAFE_DIRECTORY');}
+  return current;
+}
+
+function packageMetadata(root) {
+  return parseStrictJson(readRegularFile(path.join(root, 'package.json'), 1024 * 1024).bytes, 1024 * 1024);
+}
+
+function findDependency(root, name) {
+  if (!PACKAGE_NAME.test(name) || name.startsWith('.') || name.includes('..')) {throw bundleError();}
+  // Match normal node_modules ancestor resolution, without NODE_PATH, cwd, an
+  // npm subprocess, or an install hook. Preserve each package's own resolution.
+  for (let current = root; ; current = path.dirname(current)) {
+    const candidate = path.join(current, 'node_modules', name);
+    if (fs.existsSync(path.join(candidate, 'package.json'))) {return fs.realpathSync(candidate);}
+    if (current === path.dirname(current)) {return null;}
+  }
+}
+
+function walkFiles(root, visit, relative = '') {
+  const entries = fs.readdirSync(path.join(root, relative), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, 'en'));
+  for (const entry of entries) {
+    const next = path.join(relative, entry.name);
+    const stat = fs.lstatSync(path.join(root, next));
+    if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()) {throw bundleError();}
+    if (stat.isDirectory()) {walkFiles(root, visit, next);} else {visit(slash(next), stat);}
+  }
+}
+
+function makeWritable(directory) {
+  if (!fs.existsSync(directory)) {return;}
+  fs.chmodSync(directory, 0o700);
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory() && !entry.isSymbolicLink()) {makeWritable(path.join(directory, entry.name));}
+  }
+}
+
+function sealDirectories(directory, sealRoot = true) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {sealDirectories(path.join(directory, entry.name));}
+  }
+  if (sealRoot) {fs.chmodSync(directory, 0o500);}
+}
+
+function verifyBundle(root, expectedId) {
+  try {
+    if (fs.lstatSync(root).isSymbolicLink()) {throw bundleError();}
+    const raw = readRegularFile(path.join(root, 'bundle-manifest.json'), MAX_BUNDLE_MANIFEST_BYTES).bytes;
+    if (digest(raw) !== expectedId) {throw bundleError();}
+    const manifest = parseStrictJson(raw, MAX_BUNDLE_MANIFEST_BYTES);
+    if (manifest.schemaVersion !== 1 || manifest.product !== 'openyida-local-agent-bundle' || !Array.isArray(manifest.files) || manifest.files.length > MAX_FILES) {throw bundleError();}
+    const files = new Map();
+    for (const file of manifest.files) {
+      if (typeof file.path !== 'string' || file.path.startsWith('/') || file.path.includes('\\') ||
+          file.path.split('/').some((part) => !part || part === '.' || part === '..') || files.has(file.path) ||
+          !Number.isSafeInteger(file.size) || file.size < 0 || file.size > MAX_FILE_BYTES || !/^[a-f0-9]{64}$/.test(file.sha256) ||
+          ![0o444, 0o555].includes(file.mode)) {throw bundleError();}
+      files.set(file.path, file);
+    }
+    const actual = new Set();
+    walkFiles(root, (relative, stat) => {
+      if (relative === 'bundle-manifest.json') {return;}
+      const file = files.get(relative);
+      if (!file || stat.size !== file.size || process.platform !== 'win32' && (stat.mode & 0o777) !== file.mode ||
+          digest(readRegularFile(path.join(root, relative), MAX_FILE_BYTES).bytes) !== file.sha256) {throw bundleError();}
+      actual.add(relative);
+    });
+    if (actual.size !== files.size) {throw bundleError();}
+    return manifest;
+  } catch {throw bundleError();}
+}
+
+function materializeBundle(runtime, config, options = {}) {
+  const sourceRoot = fs.realpathSync(config.node.packageRoot);
+  const cache = privateDirectory(options.bundleCache || path.join(config.stateDir, 'bundles'));
+  let stage;
+  const pendingFiles = [];
+  const files = [];
+  const sources = [];
+  const sourceTrees = [];
+  const destinations = new Set();
+  let totalBytes = 0;
+  let published = false;
+  let runtimePackage;
+  const nodeBytes = readRegularFile(config.node.executable, MAX_FILE_BYTES).bytes;
+  const nodeIdentity = { version: process.version, sha256: digest(nodeBytes) };
+  function writeFile(relative, bytes, executable = false, source) {
+    if (destinations.has(relative) || files.length >= MAX_FILES || (totalBytes += bytes.length) > MAX_BUNDLE_BYTES) {throw bundleError();}
+    destinations.add(relative);
+    const mode = executable ? 0o555 : 0o444;
+    const sha256 = digest(bytes);
+    files.push({ path: relative, size: bytes.length, sha256, mode });
+    // Inventory first. Reconnecting to the same content needs no staging copy.
+    // Retain paths instead of whole dependency trees in memory; new bundles
+    // reread and check each file against this snapshot before writing it.
+    pendingFiles.push({ relative, source, bytes: source ? undefined : bytes, mode, sha256 });
+  }
+  function copyFile(source, target) {
+    const file = readRegularFile(source, MAX_FILE_BYTES);
+    writeFile(target, file.bytes, Boolean(file.stat.mode & 0o111), source);
+    sources.push({ path: source, sha256: digest(file.bytes), mode: file.stat.mode & 0o111 });
+  }
+  function copyTree(source, target, skip = () => false) {
+    const stat = fs.lstatSync(source);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {throw bundleError();}
+    const treeFiles = [];
+    function copy(relative = '') {
+      for (const entry of fs.readdirSync(path.join(source, relative), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+        const next = path.join(relative, entry.name);
+        if (skip(slash(next), entry)) {continue;}
+        const filename = path.join(source, next);
+        const child = fs.lstatSync(filename);
+        if (child.isSymbolicLink() || !child.isFile() && !child.isDirectory()) {throw bundleError();}
+        if (child.isDirectory()) {copy(next);} else {treeFiles.push(slash(next)); copyFile(filename, `${target}/${slash(next)}`);}
+      }
+    }
+    copy();
+    sourceTrees.push({ source, skip, files: treeFiles.sort() });
+  }
+  function copyDependencies(source, target, ancestors = []) {
+    if (ancestors.length > 50) {throw bundleError();}
+    const metadata = packageMetadata(source);
+    const optional = metadata.optionalDependencies || {};
+    const peers = metadata.peerDependencies || {};
+    const dependencies = { ...peers, ...metadata.dependencies, ...optional };
+    for (const name of Object.keys(dependencies).sort()) {
+      // Runtime is copied from the verified bytes, never from optional node_modules.
+      if (source === sourceRoot && name === runtimePackage) {continue;}
+      const resolved = findDependency(source, name);
+      if (!resolved) {
+        if (Object.hasOwn(optional, name) || metadata.peerDependenciesMeta?.[name]?.optional) {continue;}
+        throw bundleError('AGENT_BUNDLE_DEPENDENCY_MISSING');
+      }
+      if (packageMetadata(resolved).name !== name) {throw bundleError();}
+      // An ancestor copy already satisfies cycles using normal Node resolution.
+      if (ancestors.includes(resolved)) {continue;}
+      const destination = `${target}/node_modules/${name}`;
+      copyTree(resolved, destination, (relative) => ['node_modules', '.git', '.cache'].includes(relative.split('/')[0]));
+      copyDependencies(resolved, destination, [...ancestors, resolved]);
+    }
+  }
+  try {
+    const metadata = packageMetadata(sourceRoot);
+    if (metadata.name !== 'openyida' || typeof metadata.version !== 'string') {throw bundleError();}
+    // Explicit development runtimes may run on CI platforms without a public
+    // runtime package. Keep the production gate and supported-package exclusion.
+    runtimePackage = runtime.development === true && !PRODUCTION_RUNTIME_PLATFORMS.includes(process.platform)
+      ? undefined : platformPackageName(process.platform, process.arch);
+    // Deliberate installed CLI allowlist: no checkout, private state, user
+    // project, devDependencies, postinstall execution, or global Skills links.
+    for (const directory of ['bin', 'lib', 'yida-skills']) {
+      copyTree(path.join(sourceRoot, directory), `openyida/${directory}`, (relative) => directory === 'lib' && /^samples\/.+\/assets(?:\/|$)/.test(relative));
+    }
+    for (const filename of ['package.json', 'LICENSE', 'README.md', 'project/config.json']) {
+      if (fs.existsSync(path.join(sourceRoot, filename))) {copyFile(path.join(sourceRoot, filename), `openyida/${filename}`);}
+    }
+    const prd = path.join(sourceRoot, 'project', 'prd');
+    if (fs.existsSync(prd)) {
+      for (const name of fs.readdirSync(prd).sort()) {if (/^demo-.*\.md$/.test(name)) {copyFile(path.join(prd, name), `openyida/project/prd/${name}`);}}
+    }
+    copyDependencies(sourceRoot, 'openyida', [sourceRoot]);
+    // An npm replacement during copying must not produce an internally mixed
+    // CLI/skills snapshot. Recheck source content and tree membership before
+    // publishing. Once published, execution never consults these source paths.
+    const verifySources = () => {
+      for (const source of sources) {
+        const current = readRegularFile(source.path, MAX_FILE_BYTES);
+        if (digest(current.bytes) !== source.sha256 || (current.stat.mode & 0o111) !== source.mode) {throw bundleError('AGENT_BUNDLE_SOURCE_CHANGED');}
+      }
+      for (const tree of sourceTrees) {
+        const actual = [];
+        const inspect = (relative = '') => {
+          for (const entry of fs.readdirSync(path.join(tree.source, relative), { withFileTypes: true })) {
+            const next = slash(path.join(relative, entry.name));
+            if (tree.skip(next, entry)) {continue;}
+            if (entry.isSymbolicLink() || !entry.isDirectory() && !entry.isFile()) {throw bundleError();}
+            if (entry.isDirectory()) {inspect(next);} else {actual.push(next);}
+            if (actual.length > MAX_FILES) {throw bundleError();}
+          }
+        };
+        inspect();
+        if (JSON.stringify(actual.sort()) !== JSON.stringify(tree.files)) {throw bundleError('AGENT_BUNDLE_SOURCE_CHANGED');}
+      }
+      if (JSON.stringify(packageMetadata(sourceRoot)) !== JSON.stringify(metadata)) {throw bundleError('AGENT_BUNDLE_SOURCE_CHANGED');}
+    };
+    const runtimeFile = `runtime/bin/openyida-agent-runtime${process.platform === 'win32' ? '.exe' : ''}`;
+    if (digest(runtime.binaryBytes) !== runtime.sha256) {throw bundleError();}
+    writeFile(runtimeFile, runtime.binaryBytes, true);
+    writeFile('runtime/runtime-manifest.json', runtime.manifestBytes);
+    if (runtime.signatureBytes) {writeFile('runtime/runtime-manifest.sig', runtime.signatureBytes);}
+    const manifest = {
+      schemaVersion: 1, product: 'openyida-local-agent-bundle', openyidaVersion: metadata.version,
+      runtimeVersion: runtime.runtimeVersion, launcherProtocol: 1, wireProtocol: 1, node: nodeIdentity,
+      runtime: { executable: runtimeFile, manifest: 'runtime/runtime-manifest.json', signature: runtime.signatureBytes ? 'runtime/runtime-manifest.sig' : null, development: runtime.development === true },
+      cliEntry: 'openyida/bin/yida.js', skillsDir: 'openyida/yida-skills',
+      files: files.sort((a, b) => Buffer.compare(Buffer.from(a.path, 'utf8'), Buffer.from(b.path, 'utf8'))),
+    };
+    if (!destinations.has(manifest.cliEntry) || !files.some((file) => file.path.startsWith(`${manifest.skillsDir}/`))) {throw bundleError();}
+    const raw = Buffer.from(`${JSON.stringify(manifest)}\n`);
+    if (raw.length > MAX_BUNDLE_MANIFEST_BYTES) {throw bundleError();}
+    const id = digest(raw);
+    const root = path.join(cache, id);
+    if (!fs.existsSync(root)) {
+      stage = fs.mkdtempSync(path.join(cache, '.staging-'));
+      fs.chmodSync(stage, 0o700);
+      for (const file of pendingFiles) {
+        const bytes = file.source ? readRegularFile(file.source, MAX_FILE_BYTES).bytes : file.bytes;
+        if (digest(bytes) !== file.sha256) {throw bundleError('AGENT_BUNDLE_SOURCE_CHANGED');}
+        const target = path.join(stage, file.relative);
+        fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(target, bytes, { flag: 'wx', mode: file.mode });
+        fs.chmodSync(target, file.mode);
+      }
+      verifySources();
+      fs.writeFileSync(path.join(stage, 'bundle-manifest.json'), raw, { flag: 'wx', mode: 0o444 });
+      fs.chmodSync(path.join(stage, 'bundle-manifest.json'), 0o444);
+      verifyBundle(stage, id);
+      sealDirectories(stage, false);
+      try {publishBundle(stage, root); published = true;}
+      catch (error) {
+        if (!['EEXIST', 'ENOTEMPTY', 'EACCES', 'EPERM'].includes(error.code) || !fs.existsSync(root)) {throw error;}
+      }
+    } else {
+      // Never trust a version or mtime cache. Check source stability and every
+      // byte of the existing bundle, including unexpected entries, on reuse.
+      verifySources();
+    }
+    if (published) {fs.chmodSync(root, 0o500);}
+    verifyBundle(root, id);
+    const bundle = { schemaVersion: 1, id, root, manifestPath: path.join(root, 'bundle-manifest.json'), manifestSha256: id,
+      runtimeVersion: runtime.runtimeVersion, skillsDir: path.join(root, manifest.skillsDir) };
+    return { runtime: { ...runtime, executable: path.join(root, runtimeFile), manifestPath: path.join(root, 'runtime/runtime-manifest.json') },
+      config: { ...config, bundle, node: { ...config.node, packageRoot: path.join(root, 'openyida'), cliEntry: path.join(root, manifest.cliEntry),
+        version: metadata.version, nodeVersion: nodeIdentity.version, sha256: nodeIdentity.sha256 } } };
+  } catch (error) {
+    if (error instanceof CliError) {throw error;}
+    throw bundleError();
+  } finally {
+    if (stage && !published) {makeWritable(stage); fs.rmSync(stage, { recursive: true, force: true });}
+  }
+}
+
+module.exports = { materializeBundle, verifyBundle, privateDirectory };