mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
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:
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;
|
||||
|
||||
Reference in new issue
Block a user