From 2e795628eb3a5ff8da4139745251f81661b0d9b7 Mon Sep 17 00:00:00 2001 From: Den <2119348+dzianisv@users.noreply.github.com> Date: Fri, 13 Nov 2026 10:37:17 +0800 Subject: [PATCH] fix: strip systemd service-manager env vars from spawned agent processes (#11584) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The server runs under systemd on many self-hosted installs. Systemd gives the server process a readiness socket (`NOTIFY_SOCKET`) and socket-activation variables (`LISTEN_FDS`, `LISTEN_PID`, `LISTEN_FDNAMES`). > - Paperclip spawns agent child processes with `runChildProcess`. That function merges `process.env` with caller-supplied `opts.env`. > - The systemd variables leak into the merged environment and reach the spawned agent process. The agent process can then write to the server's own readiness socket. > - Every service start then logs `Got notification message from PID N, but reception only permitted for main PID M`, and a spawned process gets access to a channel it has no reason to touch. > - This pull request strips the four systemd variables from the merged environment, in the same place that already strips other unwanted inherited variables. > - The benefit is a clean systemd log and one less inherited channel between the server process and any process it spawns. ## Linked Issues or Issue Description No public GitHub issue exists yet for this specific leak. Following the bug report template inline: **What happened?** `runChildProcess` (`packages/adapter-utils/src/server-utils.ts`) merges `process.env` with `opts.env` to build the child process environment. The merge does not strip `NOTIFY_SOCKET`, `LISTEN_FDS`, `LISTEN_PID`, or `LISTEN_FDNAMES`. When the server runs under systemd, those four variables end up in every spawned agent child process. **Expected behavior** A spawned agent child process should not receive the server's own systemd readiness socket or socket-activation variables. Only the server's main process should be able to notify systemd of readiness. **Steps to reproduce** 1. Run the Paperclip server under systemd with `NOTIFY_SOCKET` (and, if socket-activated, `LISTEN_FDS`/`LISTEN_PID`/`LISTEN_FDNAMES`) set in the server's environment. 2. Let the server spawn an agent child process through any local adapter (pi-local, claude-local, codex-local, cursor-local, gemini-local, opencode-local, copilot-local, acpx-local). 3. Inspect the child process environment (for example by having it print `process.env`). 4. Observe that the four systemd variables are present in the child, and that systemd logs a stray notification warning once the child process happens to write to that socket path. **Paperclip version or commit** Current `master` at the time of this change. **Deployment mode** Self-hosted server, systemd-managed. This change is scoped to the environment leak only. A related, larger piece of work about sandboxing spawned agent processes more generally (cgroup-level containment) is tracked separately and is out of scope here. ## What Changed - In `runChildProcess` (`packages/adapter-utils/src/server-utils.ts`), strip `NOTIFY_SOCKET`, `LISTEN_FDS`, `LISTEN_PID`, and `LISTEN_FDNAMES` from the environment. - The strip happens after the `process.env` + `opts.env` merge, in the same block that already strips the Claude Code nesting-guard variables, so it also covers callers whose `opts.env` is built as `{ ...process.env, ...env }` and would otherwise re-introduce the leak. - This is a single chokepoint fix. It covers every local adapter that goes through `runChildProcess`. Remote/sandbox execution targets do not use `runChildProcess` and are unaffected. ## Verification New unit test in `packages/adapter-utils/src/server-utils.test.ts`: sets `NOTIFY_SOCKET`, `LISTEN_FDS`, `LISTEN_PID`, and `LISTEN_FDNAMES` in both `process.env` and the caller's `opts.env`, spawns a child that echoes its own `process.env` as JSON, and asserts none of the four variables are present. ``` $ npx vitest run --project @paperclipai/adapter-utils src/server-utils.test.ts ✓ |@paperclipai/adapter-utils| src/server-utils.test.ts (93 tests) ``` Confirmed the new test fails on unmodified `master` (red) and passes with this fix (green). `pnpm --filter @paperclipai/adapter-utils typecheck` is clean. (No per-package `test` script exists in `packages/adapter-utils/package.json` or any sibling adapter package. Tests run through the root vitest `projects` config, so `--project @paperclipai/adapter-utils` is equivalent to `pnpm --filter @paperclipai/adapter-utils test`.) ## Risks Low risk. This removes four specific environment variables from a spawned child's environment. No other variables are touched. A child process that legitimately needed one of these four variables for its own purpose would be the only regression case, and no local adapter has such a need today. ## Model Used Claude (Anthropic), model `claude-sonnet-5`, used within a coding-agent harness with tool use (file edit, test execution, local verification). ## 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 - [ ] I have updated relevant documentation to reflect my changes — not applicable; internal environment-hygiene fix with no user-facing or operator-facing documentation surface. - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green — `review` (template/commitperclip gate) passes. Two unrelated jobs (`General tests (server (2/5))`, `verify`) are currently red; not yet triaged. Not a description issue; leaving this box unchecked until those two jobs are green. - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups — confirmed via the Greptile Review comment: "Confidence Score: 5/5", no open P2s or follow-ups listed. - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: dzianisv Co-authored-by: Paperclip Co-authored-by: commitperclip-bot <305974387+commitperclip-bot@users.noreply.github.com> --- .../adapter-utils/src/server-utils.test.ts | 43 +++++++++++++++++++ packages/adapter-utils/src/server-utils.ts | 16 +++++++ 2 files changed, 59 insertions(+) diff --git a/packages/adapter-utils/src/server-utils.test.ts b/packages/adapter-utils/src/server-utils.test.ts index 6ea975407a4..c15bc4923f6 100644 --- a/packages/adapter-utils/src/server-utils.test.ts +++ b/packages/adapter-utils/src/server-utils.test.ts @@ -789,6 +789,49 @@ describe("runChildProcess", () => { expect(finishedAt - startedAt).toBeGreaterThanOrEqual(spawnDelayMs); }); + it("strips systemd service-manager vars (NOTIFY_SOCKET/LISTEN_FDS/LISTEN_PID/LISTEN_FDNAMES) from both inherited and caller-supplied env", async () => { + const SERVICE_MANAGER_VARS = ["NOTIFY_SOCKET", "LISTEN_FDS", "LISTEN_PID", "LISTEN_FDNAMES"] as const; + const originalValues: Record = {}; + for (const key of SERVICE_MANAGER_VARS) { + originalValues[key] = process.env[key]; + process.env[key] = `inherited-${key}`; + } + + try { + const result = await runChildProcess( + randomUUID(), + process.execPath, + ["-e", "process.stdout.write(JSON.stringify(process.env))"], + { + cwd: process.cwd(), + env: { + NOTIFY_SOCKET: "/run/caller-supplied.sock", + LISTEN_FDS: "1", + LISTEN_PID: "12345", + LISTEN_FDNAMES: "caller", + }, + timeoutSec: 5, + graceSec: 1, + onLog: async () => {}, + }, + ); + + expect(result.exitCode).toBe(0); + const childEnv = JSON.parse(result.stdout) as Record; + for (const key of SERVICE_MANAGER_VARS) { + expect(childEnv[key]).toBeUndefined(); + } + } finally { + for (const key of SERVICE_MANAGER_VARS) { + if (originalValues[key] === undefined) { + delete process.env[key]; + } else { + process.env[key] = originalValues[key]; + } + } + } + }); + it.skipIf(process.platform === "win32")( "kills descendant processes on timeout via the process group", async () => { diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts index 8538a710687..78217c44904 100644 --- a/packages/adapter-utils/src/server-utils.ts +++ b/packages/adapter-utils/src/server-utils.ts @@ -4829,6 +4829,22 @@ export async function runChildProcess( delete rawMerged[key]; } + // Strip systemd service-manager vars so the spawned agent process can't + // reach the Paperclip server's own readiness/socket-activation channel. + // NOTIFY_SOCKET in particular lets any process with it in its env call + // sd_notify on the server's readiness socket; systemd only accepts + // notifications from the service's registered main PID, so an agent + // subprocess inheriting it just spams "reception only permitted for + // main PID" warnings, but it's still an unintended channel and must not + // be handed to child processes. These vars can arrive either via + // process.env (systemd sets them on the server process) or via + // opts.env (adapters that build their env as `{ ...process.env, ... }`), + // so strip them after the merge, not just from the process.env side. + const SERVICE_MANAGER_VARS = ["NOTIFY_SOCKET", "LISTEN_FDS", "LISTEN_PID", "LISTEN_FDNAMES"] as const; + for (const key of SERVICE_MANAGER_VARS) { + delete rawMerged[key]; + } + const mergedEnv = ensurePathInEnv(rawMerged); if (opts.localProcessSandbox?.homeDir) { mergedEnv.HOME = opts.localProcessSandbox.homeDir;