fix: strip systemd service-manager env vars from spawned agent processes (#11584)

<!-- Write all pull request text in Simplified Technical English
(ASD-STE100): short sentences, one instruction per sentence, simple
approved vocabulary, and the active voice. -->

## 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 <dzianisv@gmail.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: commitperclip-bot <305974387+commitperclip-bot@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-12 20:37:17 -06:00
1 parent 1c33275ada
commit 2e795628eb
2 files changed
+59

No files matched your search

@@ -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<string, string | undefined> = {};
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<string, string | undefined>;
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 () => {
@@ -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;