fix(release): bundle vendored runner ACPX runtime (#12582)

## Thinking Path

> - Paperclip is the open source app that people use to manage AI agents
for work.
> - The npm release includes the Paperclip server and a vendored runner.
> - The vendored runner imports ACPX when it starts a Codex agent.
> - The server package did not include the ACPX version that the runner
needs.
> - A fresh canary install therefore stopped with `ERR_MODULE_NOT_FOUND`
after onboarding.
> - This pull request bundles the patched ACPX runtime with the server
package.
> - The benefit is that a fresh npm install can load the vendored
runner.

## Linked Issues or Issue Description

No public issue exists for this bug. A GitHub search found no duplicate
or related pull request.

**What happened?**

A fresh `npx paperclipai@canary onboard` command completed onboarding.
The server then failed to start. Node could not resolve `acpx` from the
vendored Paperclip runner.

**Expected behavior**

The server should start after onboarding from a fresh npm cache and a
temporary data directory.

**Steps to reproduce**

1. Run `npx paperclipai@canary onboard --data-dir "$(mktemp -d
/tmp/paperclip-canary.XXXXXX)"`.
2. Select Quickstart.
3. Start Paperclip.
4. Observe `ERR_MODULE_NOT_FOUND` for `acpx`.

**Paperclip version or commit**

`paperclipai@2026.831.0-canary.6`

**Deployment mode**

Other: local trusted Quickstart through `npx`.

**Installation method**

npm through `npx`.

**Agent adapter(s) involved**

Codex.

**Database mode**

Embedded PGlite.

**Access context**

Board operator during onboarding.

**Node.js version**

Node.js 26.4.0.

**Operating system**

macOS.

**Relevant logs or output**

```shell
Cannot find package 'acpx' imported from .../node_modules/@paperclipai/server/dist/vendor/paperclip-runner/drivers/acpx/codex-runtime-adapter.js
```

**Relevant config (if applicable)**

No custom configuration was required.

**Additional context**

The published adapter utilities contain a nested `acpx@0.12.0`. Node
cannot resolve that nested package from the sibling vendored runner.
Installing `acpx@0.13.1` at the clean package root makes the failing
runner import succeed.

**Privacy checklist**

The log excerpt contains no user path, token, company name, or other
private value.

## What Changed

- Added `acpx@0.13.1` as a bundled server runtime dependency.
- Added a version-specific patch check for the ACPX versions used by the
server and adapter utilities.
- Added release-package coverage for the server ACPX bundle.

## Verification

- `pnpm test:release-registry` passed 98 tests.
- `node --test scripts/acpx-patch-packaging.test.mjs` passed 12 tests.
- `pnpm exec vitest run
server/src/__tests__/server-package-build-script.test.ts` passed 4
tests.
- `node --test scripts/release-package-map.test.mjs` passed 12 tests.
- `pnpm -r typecheck` passed.
- A clean extracted server tarball contained the patched `acpx@0.13.1`
runtime.
- The previously failing vendored runner module imported from that clean
tarball.
- The repository-wide test suite was stopped before completion at the
maintainer's request because it takes too long for this urgent packaging
fix.

## Risks

- Risk is low.
- The server tarball grows because it now contains ACPX and its
production dependencies.
- The release stager now uses a version-specific marker to verify the
ACPX patch.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex with `gpt-5.6-sol`.
- The model used reasoning mode, tool use, and code execution.
- The context window size was not disclosed.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>

scripts/acpx-patch-packaging.test.mjs

@@ -26,6 +26,9 @@ const rootPackage = JSON.parse(await readFile(new URL("../package.json", import.
 const adapterUtilsPackage = JSON.parse(
   await readFile(new URL("../packages/adapter-utils/package.json", import.meta.url), "utf8"),
 );
+const serverPackage = JSON.parse(
+  await readFile(new URL("../server/package.json", import.meta.url), "utf8"),
+);
 const dbPackage = JSON.parse(
   await readFile(new URL("../packages/db/package.json", import.meta.url), "utf8"),
 );
@@ -38,8 +41,14 @@ test("published packages preserve the patched ACPX runtime", () => {
     rootPackage.pnpm.patchedDependencies["acpx@0.12.0"],
     "patches/acpx@0.12.0.patch",
   );
+  assert.equal(
+    rootPackage.pnpm.patchedDependencies["acpx@0.13.1"],
+    "patches/acpx@0.13.1.patch",
+  );
   assert.equal(adapterUtilsPackage.dependencies.acpx, "0.12.0");
   assert.deepEqual(adapterUtilsPackage.bundleDependencies, ["acpx"]);
+  assert.equal(serverPackage.dependencies.acpx, "0.13.1");
+  assert.deepEqual(serverPackage.bundleDependencies, ["acpx"]);
   assert.equal(bundledCliNpmDependencies.has("acpx"), true);
   assert.equal(cliEsbuildConfig.external.includes("acpx"), false);
 });
@@ -181,7 +190,7 @@ test("bundled package patch selection rejects an unpatched installed version", (
   );
 });
 
-test("bundled package staging rebuilds npm dependencies and applies the acpx patch", (t) => {
+test("server package staging bundles and patches the vendored runner's acpx runtime", (t) => {
   const fixtureDir = mkdtempSync(join(tmpdir(), "paperclip-bundled-stage-"));
   const sourceDir = join(fixtureDir, "source");
   const destinationDir = join(fixtureDir, "destination");
@@ -192,7 +201,10 @@ test("bundled package staging rebuilds npm dependencies and applies the acpx pat
   writeFileSync(join(sourceDir, "dist", "index.js"), "export {};\n");
   mkdirSync(destinationDir);
   mkdirSync(binDir);
-  writeFileSync(join(sourceDir, "package.json"), JSON.stringify(adapterUtilsPackage));
+  writeFileSync(
+    join(sourceDir, "package.json"),
+    JSON.stringify({ ...serverPackage, files: ["dist"] }),
+  );
   writeFileSync(callLog, "");
   t.after(() => rmSync(fixtureDir, { recursive: true, force: true }));
 
@@ -217,7 +229,7 @@ printf 'npm %s\\n' "$*" >> "$FAKE_CALL_LOG"
 [ "$*" = "install --omit=dev --ignore-scripts --no-audit --no-fund" ]
 mkdir -p node_modules/acpx/dist
 printf 'unpatched runtime\\n' > node_modules/acpx/dist/runtime.js
-printf '{"name":"acpx","version":"0.12.0"}\\n' > node_modules/acpx/package.json
+printf '{"name":"acpx","version":"0.13.1"}\\n' > node_modules/acpx/package.json
 `,
   );
   writeExecutable(
@@ -235,9 +247,9 @@ while [ "$#" -gt 0 ]; do
   fi
 done
 patch_input="$(cat)"
-grep -q onAgentStderr <<< "$patch_input"
-! grep -q spawnEnvironment <<< "$patch_input"
-printf 'patched onAgentStderr runtime\\n' > "$target/dist/runtime.js"
+grep -q spawnEnvironment <<< "$patch_input"
+! grep -q onAgentStderr <<< "$patch_input"
+printf 'patched spawnEnvironment runtime\\n' > "$target/dist/runtime.js"
 `,
   );
 
@@ -259,7 +271,10 @@ printf 'patched onAgentStderr runtime\\n' > "$target/dist/runtime.js"
   assert.equal(lstatSync(stagedAcpxDir).isDirectory(), true);
   assert.equal(lstatSync(stagedAcpxDir).isSymbolicLink(), false);
   assert.equal(existsSync(join(destinationDir, "node_modules/.pnpm")), false);
-  assert.match(readFileSync(join(stagedAcpxDir, "dist/runtime.js"), "utf8"), /onAgentStderr/);
+  assert.match(
+    readFileSync(join(stagedAcpxDir, "dist/runtime.js"), "utf8"),
+    /spawnEnvironment/,
+  );
   assert.match(
     readFileSync(callLog, "utf8"),
     /patch -p1 --forward -d .*node_modules\/acpx/,

scripts/prepare-bundled-package.mjs

@@ -166,13 +166,23 @@ export function prepareBundledPackage(sourceDir, destinationDir) {
   writeFileSync(deployedPackagePath, `${JSON.stringify(publishManifest, null, 2)}\n`);
   applyBundledDependencyPatches(destinationDir, bundledDependencies);
 
-  if (
-    bundledDependencies.includes("acpx") &&
-    !readFileSync(resolve(destinationDir, "node_modules/acpx/dist/runtime.js"), "utf8").includes(
-      "onAgentStderr",
-    )
-  ) {
-    throw new Error("staged acpx runtime is missing the repository patch");
+  if (bundledDependencies.includes("acpx")) {
+    const acpxPackage = JSON.parse(
+      readFileSync(resolve(destinationDir, "node_modules/acpx/package.json"), "utf8"),
+    );
+    const expectedPatchMarker = {
+      "0.12.0": "onAgentStderr",
+      "0.13.1": "spawnEnvironment",
+    }[acpxPackage.version];
+    const acpxRuntime = readFileSync(
+      resolve(destinationDir, "node_modules/acpx/dist/runtime.js"),
+      "utf8",
+    );
+    if (!expectedPatchMarker || !acpxRuntime.includes(expectedPatchMarker)) {
+      throw new Error(
+        `staged acpx@${acpxPackage.version} runtime is missing the repository patch`,
+      );
+    }
   }
 
   if (bundledDependencies.includes("embedded-postgres")) {

server/package.json

@@ -63,6 +63,7 @@
     "@paperclipai/shared": "workspace:*",
     "@paperclipai/skills-catalog": "workspace:*",
     "@vercel/connect": "0.6.1",
+    "acpx": "0.13.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "better-auth": "1.7.0",
@@ -84,6 +85,9 @@
     "ws": "^8.21.3",
     "zod": "^4.4.3"
   },
+  "bundleDependencies": [
+    "acpx"
+  ],
   "devDependencies": {
     "@paperclipai/paperclip-runner": "workspace:*",
     "@types/express": "^5.0.0",