{"record":{"id":"314716d68412b7a9","repo":"paperclipai/paperclip","slug":"acpx-provider-relative-module-loading-requires-lin","errorCode":null,"errorMessage":"ACPX provider relative module loading requires Linux descriptor-pinned paths","messagePattern":"ACPX provider relative module loading requires Linux descriptor-pinned paths","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts","lineNumber":1814,"sourceCode":"    \"const metadataAfter = fs.fstatSync(moduleFd, { bigint: true });\",\n    \"verifySnapshotBytes(fileURLToPath(url), moduleSource);\",\n    `if (moduleSource.length > ${MAX_AGENT_COMMAND_BYTES} || moduleSource.length !== admittedModuleBytes || BigInt(moduleSource.length) !== metadataAfter.size || metadataBefore.dev !== metadataAfter.dev || metadataBefore.ino !== metadataAfter.ino || metadataBefore.size !== metadataAfter.size || metadataBefore.mtimeNs !== metadataAfter.mtimeNs || metadataBefore.ctimeNs !== metadataAfter.ctimeNs) { const error = new Error(\"ACPX provider module changed while it was read\"); error.code = \"ERR_ACPX_UNVERIFIED_MODULE\"; throw error; }`,\n    \"return { format: moduleFormat, source: moduleSource, shortCircuit: true };\",\n    \"} finally { fs.closeSync(moduleFd); }\",\n    \"});\",\n    \"} });\",\n    \"import(target).catch((error) => { console.error(error); process.exitCode = 1; });\",\n  ].join(\"\");\n}\n\nexport function guardSnapshotModuleLookup<T>(\n  platform: NodeJS.Platform,\n  filesystemLookup: boolean,\n  lookup: () => T,\n  privateSnapshot = false,\n): T {\n  if (platform !== \"linux\" && !(platform === \"darwin\" && privateSnapshot) && filesystemLookup) {\n    throw new Error(\n      \"ACPX provider relative module loading requires Linux descriptor-pinned paths\",\n    );\n  }\n  return lookup();\n}\n\n/** Refuse filesystem modules that are not reached through a retained directory. */\nexport function guardSnapshotModuleResolution(\n  builtin: boolean,\n  resolvedUrl: unknown,\n  descriptorAuthorized: boolean,\n): void {\n  if (\n    !builtin &&\n    typeof resolvedUrl === \"string\" &&\n    resolvedUrl.startsWith(\"file:\") &&\n    !descriptorAuthorized\n  ) {","sourceCodeStart":1796,"sourceCodeEnd":1832,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts#L1796-L1832","documentation":"Guard around relative module loading used by the ACPX provider setup. Descriptor-pinned (/proc/<pid>/fd/N) paths only work on Linux; on darwin they work only when a private snapshot provides real filesystem paths. If the caller requests a filesystem lookup (filesystemLookup === true) with relative module loading on an unsupported platform combination, this throw prevents resolving modules through paths that cannot exist.","triggerScenarios":"Calling the guarded relative-module lookup helper with platform neither 'linux' nor 'darwin'+privateSnapshot while filesystemLookup is true.","commonSituations":"Running the ACPX verified provider on macOS without private snapshots enabled; a custom integration forcing filesystemLookup=true; platform-dependent code paths exercised on Windows/other OS during development or tests.","solutions":["Run on Linux, where /proc fd-pinned relative module loading is natively supported.","On macOS, enable/provision the private snapshot (privateSnapshot = true) so lookups use snapshot paths instead of fd paths.","Pass filesystemLookup = false on unsupported platforms to use non-filesystem resolution.","Guard platform-specific setup with assertVerifiedAcpxProviderPlatform before attempting lookups."],"exampleFix":"// before\nresolveRelativeModule(process.platform, true, () => require(rel));\n// after\nconst fsLookup = process.platform === \"linux\" || (process.platform === \"darwin\" && privateSnapshot);\nresolveRelativeModule(process.platform, fsLookup, () => require(rel));","handlingStrategy":"validation","validationCode":"const useFsLookup = platform === \"linux\" || (platform === \"darwin\" && privateSnapshot);\nif (!useFsLookup) {\n  // fall back to non-filesystem resolution or fail before attempting lookup\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Call assertVerifiedAcpxProviderPlatform before relative module loading","On macOS enable private snapshots; on other platforms avoid fd-pinned lookups entirely","Gate platform-specific resolution behind explicit platform checks in tests and dev setups"],"tags":["unsupported-platform","module-resolution","process-spawn"],"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"}