{"record":{"id":"50e1d3c7e7d37808","repo":"paperclipai/paperclip","slug":"acpx-provider-requires-verified-package-snapshots","errorCode":null,"errorMessage":"ACPX provider requires verified package snapshots","messagePattern":"ACPX provider requires verified package snapshots","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts","lineNumber":1679,"sourceCode":"function snapshotBootstrap(format: AcpxCommandFormat, guarded = false): string {\n  return [\n    'const fs = require(\"node:fs\");',\n    'const { isBuiltin, registerHooks } = require(\"node:module\");',\n    'const { dirname, extname, join, normalize, relative, resolve } = require(\"node:path\");',\n    'const { fileURLToPath, pathToFileURL } = require(\"node:url\");',\n    \"const commandDirectory = process.argv[1];\",\n    \"const commandName = process.argv[2];\",\n    \"const dependencyAncestorCount = Number.parseInt(process.argv[3], 10);\",\n    \"const serverDependencyAncestorCount = Number.parseInt(process.argv[4], 10);\",\n    \"const serverPackageFormat = process.argv[5];\",\n    \"const dependencyAncestorFormats = JSON.parse(process.argv[6]);\",\n    \"const providerRuntimeExecutableCount = Number.parseInt(process.argv[7], 10);\",\n    `const providerRuntimeEnvironmentVariable = process.env.${VERIFIED_PROVIDER_RUNTIME_TARGET_ENV};`,\n    `delete process.env.${VERIFIED_PROVIDER_RUNTIME_TARGET_ENV};`,\n    `const snapshotHandoff = process.platform === \"darwin\" ? JSON.parse(process.env.${ACPX_PRIVATE_SNAPSHOT_ENV} || \"null\") : null;`,\n    'let privateSnapshot = null; if (snapshotHandoff) { const manifest = fs.readFileSync(snapshotHandoff.path); if (require(\"node:crypto\").createHash(\"sha256\").update(manifest).digest(\"hex\") !== snapshotHandoff.digest) throw new Error(\"ACPX snapshot manifest digest mismatch\"); privateSnapshot = JSON.parse(manifest); }',\n    `delete process.env.${ACPX_PRIVATE_SNAPSHOT_ENV};`,\n    'if (process.platform !== \"linux\" && !(process.platform === \"darwin\" && privateSnapshot && Array.isArray(privateSnapshot.roots) && privateSnapshot.roots.length === dependencyAncestorCount + 1)) throw new Error(\"ACPX provider requires verified package snapshots\");',\n    'const verifySnapshotBytes = (path, bytes) => { if (privateSnapshot && require(\"node:crypto\").createHash(\"sha256\").update(bytes).digest(\"hex\") !== privateSnapshot.digests[path]) throw new Error(\"ACPX private snapshot digest mismatch\"); };',\n    'if (privateSnapshot && providerRuntimeExecutableCount === 1) verifySnapshotBytes(privateSnapshot.executable, fs.readFileSync(privateSnapshot.executable));',\n    `if (!Number.isSafeInteger(dependencyAncestorCount) || dependencyAncestorCount < 0 || dependencyAncestorCount > ${MAX_DEPENDENCY_ANCESTORS}) throw new Error(\"ACPX provider dependency ancestry is invalid\");`,\n    'if (!Number.isSafeInteger(serverDependencyAncestorCount) || serverDependencyAncestorCount < 0 || serverDependencyAncestorCount > dependencyAncestorCount) throw new Error(\"ACPX provider package ancestry is invalid\");',\n    'if ((serverPackageFormat !== \"module\" && serverPackageFormat !== \"commonjs\") || !Array.isArray(dependencyAncestorFormats) || dependencyAncestorFormats.length !== dependencyAncestorCount || dependencyAncestorFormats.some((value) => value !== \"module\" && value !== \"commonjs\")) throw new Error(\"ACPX provider package formats are invalid\");',\n    'if (providerRuntimeExecutableCount !== 0 && providerRuntimeExecutableCount !== 1) throw new Error(\"ACPX provider runtime executable count is invalid\");',\n    `const providerRuntimeExecutableFd = ${DEPENDENCY_ANCESTOR_FD_START} + dependencyAncestorCount;`,\n    'if (providerRuntimeExecutableCount === 1) { if (providerRuntimeEnvironmentVariable !== \"CODEX_PATH\" && providerRuntimeEnvironmentVariable !== \"CLAUDE_CODE_EXECUTABLE\") throw new Error(\"ACPX provider runtime environment target is invalid\"); fs.fstatSync(providerRuntimeExecutableFd); process.env[providerRuntimeEnvironmentVariable] = privateSnapshot ? privateSnapshot.executable : \"/proc/\" + process.pid + \"/fd/\" + providerRuntimeExecutableFd; } else if (providerRuntimeEnvironmentVariable !== undefined) throw new Error(\"ACPX provider runtime environment target is unexpected\");',\n    ...(guarded\n      ? [\n          `const guardianFd = ${DEPENDENCY_ANCESTOR_FD_START} + dependencyAncestorCount + providerRuntimeExecutableCount;`,\n          'const guardian = fs.createReadStream(\"\", { fd: guardianFd, autoClose: false });',\n          `const reapCurrentProviderProcessGroup = ${reapCurrentProviderProcessGroup.toString()};`,\n          \"const killProviderProcess = process.kill.bind(process);\",\n          \"const providerProcessId = process.pid;\",\n          \"const exitProviderProcess = process.exit.bind(process);\",\n          \"let guardianLost = false;\",\n          \"const reapOnGuardianLoss = () => { if (guardianLost) return; guardianLost = true; reapCurrentProviderProcessGroup(killProviderProcess, providerProcessId, exitProviderProcess); };\",","sourceCodeStart":1661,"sourceCodeEnd":1697,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts#L1661-L1697","documentation":"Thrown by the generated provider bootstrap in the child process. On Linux the provider is allowed to run from descriptor-pinned paths without a private snapshot, but on any other platform (notably macOS) it must be handed a verified private snapshot whose roots array has exactly dependencyAncestorCount + 1 entries. If neither condition holds, the child refuses to start because the provider would load unverified package code.","triggerScenarios":"Spawning the guarded ACPX provider with process.platform neither 'linux' nor darwin-with-a-valid-privateSnapshot (null handoff, non-array roots, or roots.length !== dependencyAncestorCount + 1).","commonSituations":"Running the runner on macOS without the darwin private-snapshot path set up; the snapshot handoff env var was stripped (e.g. by a sanitized environment) before the child started; dependency ancestor count changed after the snapshot was built.","solutions":["Run the guarded provider on Linux (fully supported without private snapshots) or on macOS with the private snapshot correctly provisioned.","Verify ACPX_PRIVATE_SNAPSHOT_ENV is present in the child environment and not removed by env sanitization in spawn options.","Rebuild the private snapshot so its roots match the current dependencyAncestorCount (+1 for the server root).","If spawning manually with a custom env, preserve the snapshot handoff variables rather than passing a minimal env."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const snapshotSupported = process.platform === \"linux\" || (process.platform === \"darwin\" && privateSnapshot?.roots?.length === dependencyAncestors.length + 1);\nif (!snapshotSupported) throw new Error(\"provision a private snapshot or run on Linux before spawning the guarded provider\");","typeGuard":"const hasValidSnapshot = (s): s is PrivateSnapshot =>\n  !!s && Array.isArray(s.roots) && s.roots.length > 0;","tryCatchPattern":null,"preventionTips":["Check assertVerifiedAcpxProviderPlatform(process.platform) before guarded spawns","On macOS always provision the private snapshot handoff","Do not strip ACPX_PRIVATE_SNAPSHOT_ENV from the child environment"],"tags":["unsupported-platform","integrity","process-spawn","security"],"backgroundTag":"unsupported-platform","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}