The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(adapter-utils): terminate the remote process-session wrapper deterministically on bridge stop (#12244)
Nicky Leach4277ecbb2e7b
diff --git a/packages/adapter-utils/src/execution-target-stdin-race.test.ts b/packages/adapter-utils/src/execution-target-stdin-race.test.tsindex 26fb6a0ff9..225adc00cc 100644--- a/packages/adapter-utils/src/execution-target-stdin-race.test.ts+++ b/packages/adapter-utils/src/execution-target-stdin-race.test.ts@@ -1,10 +1,10 @@import { execFile as execFileCallback, spawn } from "node:child_process";-import { mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";+import { chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";import net from "node:net";import os from "node:os";import path from "node:path";import { promisify } from "node:util";-import { afterEach, describe, expect, it } from "vitest";+import { afterAll, afterEach, describe, expect, it } from "vitest";import {getProcessSessionRemoteSource,@@ -480,11 +480,11 @@ describe("stdin file race (parent PAP-4037)", () => {await waitFor(() => finalizeStarted.includes("000000000001.json"), 8_000);// Stop the bridge while file 1's write is still pending. `stop()` awaits- // the chained `stdinEnd` write, so both finalizes are complete when it- // returns, in send order.+ // the chained `stdinEnd` write, then chains a `shutdown` write after it,+ // so all three finalizes are complete when it returns, in send order.await bridge!.stop();stopped = true;- expect(finalizeOrder).toEqual(["000000000001.json", "000000000002.json"]);+ expect(finalizeOrder).toEqual(["000000000001.json", "000000000002.json", "000000000003.json"]);} finally {peer?.destroy();if (!stopped) await bridge?.stop();@@ -621,3 +621,1197 @@ describe("stdin file race (parent PAP-4037)", () => {expect(observedComplete).toBeGreaterThan(0);});});++// Coverage for deterministic wrapper shutdown (parent PAP-5307): a bridge+// stop must leave no remote wrapper process and no direct child process+// alive, the host must send no operating-system signal, and the host must+// store no process identifier. These tests drive the real emitted wrapper as+// a node process and, where noted, the real bridge through a local runner.+describe("deterministic remote process-session wrapper shutdown (PAP-5316)", () => {+ const cleanupDirs: string[] = [];++ afterEach(async () => {+ while (cleanupDirs.length > 0) {+ const dir = cleanupDirs.pop();+ if (dir) await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ function delay(ms: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, ms));+ }++ async function waitFor(check: () => boolean | Promise<boolean>, timeoutMs = 8_000): Promise<void> {+ const deadline = Date.now() + timeoutMs;+ while (Date.now() < deadline) {+ if (await check()) return;+ await delay(20);+ }+ throw new Error("Timed out waiting for condition.");+ }++ function isPidAlive(pid: number): boolean {+ try {+ process.kill(pid, 0);+ return true;+ } catch {+ return false;+ }+ }++ // A read-only, test-only liveness probe over the real OS process table. It+ // never signals anything; it only greps `ps` output to tell the test+ // whether a specific test-authored script (identified by its own temp file+ // path) is still running. Production host code never does this — it never+ // matches or signals a process by name or command line.+ async function findLivePidsByArgvSubstring(substring: string): Promise<number[]> {+ try {+ const { stdout } = await execFile("ps", ["-eo", "pid=,args="]);+ const pids: number[] = [];+ for (const line of stdout.split("\n")) {+ const trimmed = line.trim();+ if (!trimmed) continue;+ const match = /^(\d+)\s+(.*)$/.exec(trimmed);+ if (match && match[2].includes(substring)) {+ const pid = Number.parseInt(match[1], 10);+ if (Number.isFinite(pid)) pids.push(pid);+ }+ }+ return pids;+ } catch {+ return [];+ }+ }++ type WrapperFrame = {+ seq?: number;+ type?: string;+ stream?: string;+ data?: string;+ code?: number | null;+ signal?: string | null;+ message?: string;+ };++ // A test-only preload module for the wrapper's node process (PAP-5338).+ // This sandbox's filesystems all report a real, working birthtime, so a+ // test cannot reach the two known "no usable creation time" fallbacks by+ // using a real filesystem alone. This preload patches fs.promises.lstat+ // inside the wrapper's own process, for one directory the test names+ // through an env var, so the wrapper observes the exact Stats shape each+ // fallback produces. It never runs unless a test opts in, and it never+ // touches this test file's own process.+ // Kept outside cleanupDirs (which afterEach drains after every single test):+ // this preload file is created once and reused by every test in this+ // describe block, so an early test's cleanup must not delete it out from+ // under a later test.+ let fakeBirthtimePreloadDir: string | null = null;+ afterAll(async () => {+ if (fakeBirthtimePreloadDir) await rm(fakeBirthtimePreloadDir, { recursive: true, force: true }).catch(() => undefined);+ });+ let fakeBirthtimePreloadPath: Promise<string> | null = null;+ async function getFakeBirthtimePreloadPath(): Promise<string> {+ if (!fakeBirthtimePreloadPath) {+ fakeBirthtimePreloadPath = (async () => {+ const dir = await mkdtemp(path.join(os.tmpdir(), "paperclip-birthtime-preload-"));+ fakeBirthtimePreloadDir = dir;+ const preloadPath = path.join(dir, "fake-birthtime-preload.cjs");+ await writeFile(+ preloadPath,+ [+ `const fs = require("fs");`,+ `const path = require("path");`,+ `const target = process.env.PAPERCLIP_TEST_FAKE_BIRTHTIME_TARGET;`,+ `const mode = process.env.PAPERCLIP_TEST_FAKE_BIRTHTIME_MODE;`,+ `const sessionDir = process.env.PAPERCLIP_PROCESS_SESSION_DIR;`,+ `if (target && mode && sessionDir) {`,+ ` const resolvedTarget = path.resolve(target === "stdinDir" ? path.join(sessionDir, "stdin") : sessionDir);`,+ ` const originalLstat = fs.promises.lstat.bind(fs.promises);`,+ ` fs.promises.lstat = async (candidatePath, opts) => {`,+ ` const stats = await originalLstat(candidatePath, opts);`,+ ` if (path.resolve(String(candidatePath)) === resolvedTarget) {`,+ ` const fakeValue = mode === "zero" ? 0 : stats.ctimeMs;`,+ ` Object.defineProperty(stats, "birthtimeMs", { value: fakeValue, configurable: true });`,+ ` }`,+ ` return stats;`,+ ` };`,+ `}`,+ ].join("\n"),+ "utf8",+ );+ return preloadPath;+ })();+ }+ return fakeBirthtimePreloadPath;+ }++ // Run the real emitted wrapper (either variant) as a node process, with no+ // sandbox and no bridge in front of it. The test owns the wrapper's node+ // ChildProcess handle directly, so it can observe the wrapper's own exit+ // without storing or signaling any process identifier itself.+ async function startWrapperProcess(options?: {+ outputToStdout?: boolean;+ command?: string;+ args?: string[];+ maxRetries?: number;+ terminateGraceMs?: number;+ // A dedicated parent for this wrapper's session directory, instead of the+ // shared OS temp directory. A test that must chmod sessionDir's own+ // parent (to force EACCES on sessionDir itself) needs a parent it owns,+ // never the shared OS temp directory every other process on the host+ // also uses.+ parentDir?: string;+ // Makes the wrapper's own process observe an unusable birthtimeMs on one+ // control directory, through the preload above. See PAP-5338 AC-1: a+ // real "no usable creation time" filesystem is not reachable in this+ // sandbox, so the test simulates the exact Stats shape instead.+ fakeBirthtime?: { target: "sessionDir" | "stdinDir"; mode: "zero" | "followCtime" };+ }) {+ const sessionDir = await mkdtemp(path.join(options?.parentDir ?? os.tmpdir(), "paperclip-wrapper-lifecycle-"));+ cleanupDirs.push(sessionDir);+ const stdinDir = path.join(sessionDir, "stdin");+ const eventsDir = path.join(sessionDir, "events");+ await mkdir(stdinDir, { recursive: true });+ if (options?.outputToStdout !== true) await mkdir(eventsDir, { recursive: true });++ const wrapperPath = path.join(sessionDir, "wrapper.mjs");+ await writeFile(wrapperPath, getProcessSessionRemoteSource({ outputToStdout: options?.outputToStdout === true }), "utf8");++ const config = { command: options?.command ?? "cat", args: options?.args ?? [], cwd: sessionDir, env: {} };+ const commandPayload = Buffer.from(JSON.stringify(config), "utf8").toString("base64");++ const env: Record<string, string> = {+ ...process.env,+ PAPERCLIP_PROCESS_SESSION_DIR: sessionDir,+ PAPERCLIP_PROCESS_SESSION_COMMAND_B64: commandPayload,+ };+ if (options?.maxRetries != null) env.PAPERCLIP_PROCESS_SESSION_STDIN_MAX_RETRIES = String(options.maxRetries);+ if (options?.terminateGraceMs != null) env.PAPERCLIP_PROCESS_SESSION_TERMINATE_GRACE_MS = String(options.terminateGraceMs);++ const execArgv: string[] = [];+ if (options?.fakeBirthtime) {+ env.PAPERCLIP_TEST_FAKE_BIRTHTIME_TARGET = options.fakeBirthtime.target;+ env.PAPERCLIP_TEST_FAKE_BIRTHTIME_MODE = options.fakeBirthtime.mode;+ execArgv.push("--require", await getFakeBirthtimePreloadPath());+ }++ const child = spawn(process.execPath, [...execArgv, wrapperPath], {+ cwd: sessionDir,+ env,+ stdio: ["ignore", "pipe", "pipe"],+ });++ const frames: WrapperFrame[] = [];+ let stdoutBuffer = "";+ child.stdout.on("data", (chunk: Buffer) => {+ stdoutBuffer += chunk.toString("utf8");+ const lines = stdoutBuffer.split("\n");+ stdoutBuffer = lines.pop() || "";+ for (const line of lines) {+ if (!line.trim()) continue;+ try {+ frames.push(JSON.parse(line) as WrapperFrame);+ } catch {+ // A partial line at a chunk boundary; ignore.+ }+ }+ });+ let stderrText = "";+ child.stderr.on("data", (chunk: Buffer) => {+ stderrText += chunk.toString("utf8");+ });++ let exitCode: number | null = null;+ let exitSignal: NodeJS.Signals | null = null;+ const exited = new Promise<void>((resolve) => {+ child.on("close", (code, signal) => {+ exitCode = code;+ exitSignal = signal;+ resolve();+ });+ });++ async function readEventFiles(): Promise<WrapperFrame[]> {+ const names = (await readdir(eventsDir).catch(() => [])).filter((name) => name.endsWith(".json")).sort();+ const out: WrapperFrame[] = [];+ for (const name of names) {+ const body = await readFile(path.join(eventsDir, name), "utf8").catch(() => "");+ if (!body.trim()) continue;+ try {+ out.push(JSON.parse(body) as WrapperFrame);+ } catch {+ // Not fully written yet; the test polls again.+ }+ }+ return out;+ }++ return {+ sessionDir,+ stdinDir,+ eventsDir,+ wrapperPath,+ frames,+ stderrText: () => stderrText,+ exited,+ exitInfo: () => ({ code: exitCode, signal: exitSignal }),+ readEventFiles,+ };+ }++ // A runner that runs each bridge shell script as a real child process+ // (matches the harness in the stdin-race describe block above), so a test+ // drives the whole legacy-poll bridge for real: the socket handler, the+ // command-managed `writeTextFile`/`remove` scripts, the nohup wrapper+ // launch, and the output poll.+ function createLocalSandboxRunner(onExecute?: (script: string) => Promise<void>) {+ let counter = 0;+ return {+ execute: async (input: {+ command: string;+ args?: string[];+ cwd?: string;+ env?: Record<string, string>;+ stdin?: string;+ timeoutMs?: number;+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;+ }): Promise<RunProcessResult> => {+ counter += 1;+ const script = input.args?.[1] ?? "";+ if (onExecute) await onExecute(script);+ const command =+ input.command === "bash" ? "/bin/bash" : input.command === "sh" ? "/bin/sh" : input.command;+ return runChildProcess(`wrapper-lifecycle-run-${counter}`, command, input.args ?? [], {+ cwd: input.cwd ?? process.cwd(),+ env: input.env ?? {},+ stdin: input.stdin,+ timeoutSec: Math.max(1, Math.ceil((input.timeoutMs ?? 30_000) / 1000)),+ graceSec: 5,+ onLog: input.onLog ?? (async () => {}),+ });+ },+ };+ }++ function trackedChildSource(pidFile: string): string {+ return [+ `import { writeFileSync } from "node:fs";`,+ `writeFileSync(${JSON.stringify(pidFile)}, String(process.pid));`,+ `process.stdin.resume();`,+ ].join("\n");+ }++ // T2's child ignores SIGTERM, so `terminate()` must escalate to SIGKILL+ // after its grace period. Ignoring end-of-file on stdin alone would not+ // prove that: a plain `cat`-like child already dies from the default+ // SIGTERM disposition.+ function stubbornChildSource(pidFile: string): string {+ return [+ `import { writeFileSync } from "node:fs";`,+ `writeFileSync(${JSON.stringify(pidFile)}, String(process.pid));`,+ `process.stdin.resume();`,+ `process.on("SIGTERM", () => {});`,+ `setInterval(() => {}, 1000);`,+ ].join("\n");+ }++ async function startTrackedBridgeSession(input: {+ rootDir: string;+ runId: string;+ childSource: string;+ runner: ReturnType<typeof createLocalSandboxRunner>;+ }) {+ const pidFile = path.join(input.rootDir, `${input.runId}.pid`);+ const childPath = path.join(input.rootDir, `${input.runId}-child.mjs`);+ await writeFile(childPath, input.childSource, "utf8");+ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: input.rootDir,+ timeoutMs: 30_000,+ runner: input.runner,+ };+ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: input.runId,+ target,+ runtimeRootDir: path.posix.join(input.rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: input.rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async () => {},+ });+ expect(bridge).not.toBeNull();+ await waitFor(async () => (await readFile(pidFile, "utf8").catch(() => "")).trim().length > 0, 8_000);+ const pid = Number.parseInt((await readFile(pidFile, "utf8")).trim(), 10);+ return { bridge: bridge!, pid };+ }++ it("T1 exits within a bounded time when its session directory disappears with no message ever sent", async () => {+ const wrapper = await startWrapperProcess({ outputToStdout: false, terminateGraceMs: 200 });+ // Let the poll loop run a few cycles before the directory disappears.+ await delay(150);+ await rm(wrapper.sessionDir, { recursive: true, force: true });+ await Promise.race([+ wrapper.exited,+ delay(4_000).then(() => {+ throw new Error("The wrapper did not exit after its session directory disappeared.");+ }),+ ]);+ });++ it("T2 leaves neither the wrapper nor a stubborn child alive after stop()", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-stubborn-child-"));+ cleanupDirs.push(rootDir);+ const runner = createLocalSandboxRunner();+ const session = await startTrackedBridgeSession({+ rootDir,+ runId: "stubborn",+ childSource: stubbornChildSource(path.join(rootDir, "stubborn.pid")),+ runner,+ });+ // The emitted wrapper script's own path is unique to this test (it lives+ // under this test's fresh temp root), so a `ps` grep on it identifies+ // only this test's wrapper process, not a sibling test's.+ const wrapperScriptSubstring = path.posix.join(rootDir, ".paperclip-runtime", "acpx", "process-sessions");+ try {+ expect(isPidAlive(session.pid)).toBe(true);+ await waitFor(async () => (await findLivePidsByArgvSubstring(wrapperScriptSubstring)).length > 0, 4_000);+ await session.bridge.stop();+ // The child ignores SIGTERM, so `terminate()` needs its own grace+ // period (default 3s) before it escalates to SIGKILL.+ await waitFor(() => !isPidAlive(session.pid), 8_000);+ expect(isPidAlive(session.pid)).toBe(false);+ await waitFor(async () => (await findLivePidsByArgvSubstring(wrapperScriptSubstring)).length === 0, 4_000);+ } finally {+ await session.bridge.stop().catch(() => undefined);+ }+ }, 15_000);++ it("T3 exits on its own when the child exits first and no stdinEnd is ever sent", async () => {+ const wrapper = await startWrapperProcess({+ outputToStdout: false,+ command: process.execPath,+ args: ["-e", "process.exit(0)"],+ });+ await Promise.race([+ wrapper.exited,+ delay(4_000).then(() => {+ throw new Error("The wrapper did not exit on its own after its child exited.");+ }),+ ]);+ const events = await wrapper.readEventFiles();+ expect(events.some((event) => event.type === "exit")).toBe(true);+ });++ it("T4 stopping one session leaves a sibling session's wrapper and child alive", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-session-isolation-"));+ cleanupDirs.push(rootDir);+ const runner = createLocalSandboxRunner();+ const sessionA = await startTrackedBridgeSession({+ rootDir,+ runId: "session-a",+ childSource: trackedChildSource(path.join(rootDir, "session-a.pid")),+ runner,+ });+ const sessionB = await startTrackedBridgeSession({+ rootDir,+ runId: "session-b",+ childSource: trackedChildSource(path.join(rootDir, "session-b.pid")),+ runner,+ });+ try {+ expect(isPidAlive(sessionA.pid)).toBe(true);+ expect(isPidAlive(sessionB.pid)).toBe(true);++ await sessionA.bridge.stop();+ await waitFor(() => !isPidAlive(sessionA.pid), 8_000);++ expect(isPidAlive(sessionA.pid)).toBe(false);+ // Session B never received a stdinEnd or a shutdown message.+ expect(isPidAlive(sessionB.pid)).toBe(true);+ } finally {+ await sessionA.bridge.stop().catch(() => undefined);+ await sessionB.bridge.stop().catch(() => undefined);+ }+ }, 15_000);++ it("T5 still writes both control messages, finishes fast, and warns never after a forged exit event the live poll reads early", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-forged-exit-"));+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "quiet-child.mjs");+ await writeFile(childPath, "process.stdin.resume();\n", "utf8");++ const scripts: string[] = [];+ const runner = createLocalSandboxRunner(async (script) => {+ scripts.push(script);+ });+ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner,+ };+ let warnedCount = 0;+ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-forged-exit",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async (stream, chunk) => {+ if (stream === "stderr" && chunk.includes("did not acknowledge shutdown")) warnedCount += 1;+ },+ });+ expect(bridge).not.toBeNull();++ const mkdirScript = scripts.find((script) => script.startsWith("mkdir -p"));+ const dirsMatch = /mkdir -p '([^']+)' '([^']+)'/.exec(mkdirScript ?? "");+ expect(dirsMatch).not.toBeNull();+ const eventsDir = dirsMatch![2];++ // Forge an exit event from outside the wrapper, before any real shutdown.+ await mkdir(eventsDir, { recursive: true });+ await writeFile(path.join(eventsDir, "999999999999.json"), `${JSON.stringify({ type: "exit", code: 0 })}\n`, "utf8");++ // Give the live 100 ms host poll time to read the forged file well+ // before stop() runs. This closes the gap T5 used to leave open: a+ // forged event `stop()` observes only through its own bounded reader+ // (not through the live poll, which sets `stopping` on its own and+ // stops re-arming) must not shorten the wait either.+ await delay(600);++ scripts.length = 0;+ const start = Date.now();+ await bridge!.stop();+ const elapsedMs = Date.now() - start;++ const finalizeWrites = scripts.filter((script) => script.includes("base64 -d") && script.includes(".paperclip-upload.decoded"));+ // stdinEnd, then shutdown: both control messages still land.+ expect(finalizeWrites.length).toBeGreaterThanOrEqual(2);+ const removeScript = scripts.find((script) => script.trim().startsWith("rm -rf"));+ expect(removeScript).toBeDefined();+ // The child never exits on its own, so the wrapper's own genuine+ // shutdownAck -- not the forged exit event -- is the only thing that can+ // finish this fast with no warning. T14 (below) proves the forged event+ // alone gives no such shortcut when no genuine acknowledgement ever+ // follows it.+ expect(elapsedMs).toBeLessThan(1_000);+ expect(warnedCount).toBe(0);+ }, 10_000);++ it("T14 a forged exit event alone does not shorten the wait when the wrapper never truly runs", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-forged-only-"));+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "quiet-child.mjs");+ await writeFile(childPath, "process.stdin.resume();\n", "utf8");++ const scripts: string[] = [];+ let counter = 0;+ // Run every script for real except the wrapper launch itself, so the+ // wrapper never starts. The forged file below is then the only event+ // that will ever exist under the session's events directory.+ const runner = {+ execute: async (input: {+ command: string;+ args?: string[];+ cwd?: string;+ env?: Record<string, string>;+ stdin?: string;+ timeoutMs?: number;+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;+ }): Promise<RunProcessResult> => {+ const script = input.args?.[1] ?? "";+ scripts.push(script);+ if (script.includes("nohup node")) {+ return { exitCode: 0, signal: null, timedOut: false, stdout: "", stderr: "", pid: null, startedAt: null };+ }+ counter += 1;+ const command =+ input.command === "bash" ? "/bin/bash" : input.command === "sh" ? "/bin/sh" : input.command;+ return runChildProcess(`forged-only-run-${counter}`, command, input.args ?? [], {+ cwd: input.cwd ?? process.cwd(),+ env: input.env ?? {},+ stdin: input.stdin,+ timeoutSec: Math.max(1, Math.ceil((input.timeoutMs ?? 30_000) / 1000)),+ graceSec: 5,+ onLog: input.onLog ?? (async () => {}),+ });+ },+ };+ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner,+ };++ let warnedCount = 0;+ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-forged-only",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async (stream, chunk) => {+ if (stream === "stderr" && chunk.includes("did not acknowledge shutdown")) warnedCount += 1;+ },+ });+ expect(bridge).not.toBeNull();++ const mkdirScript = scripts.find((script) => script.startsWith("mkdir -p"));+ const dirsMatch = /mkdir -p '([^']+)' '([^']+)'/.exec(mkdirScript ?? "");+ expect(dirsMatch).not.toBeNull();+ const eventsDir = dirsMatch![2];++ // Forge a terminal event from outside the wrapper. The wrapper never+ // started, so this is the only event that will ever exist on disk.+ await mkdir(eventsDir, { recursive: true });+ await writeFile(path.join(eventsDir, "999999999999.json"), `${JSON.stringify({ type: "exit", code: 0 })}\n`, "utf8");++ // Give the live 100 ms host poll time to read the forged file well+ // before stop() runs, so this test cannot pass by accident: `stop()`+ // never itself observes this event through its own first-line+ // `stopping` flag.+ await delay(600);++ const start = Date.now();+ await bridge!.stop();+ const elapsedMs = Date.now() - start;++ // An exit event under `sessionDir` is untrusted telemetry. With no+ // genuine wrapper ever running to write a real shutdownAck, the wait+ // still runs its full budget and still warns, exactly as it would with+ // no forged event at all (compare T13).+ expect(elapsedMs).toBeGreaterThanOrEqual(2_900);+ expect(warnedCount).toBe(1);+ const removeScript = scripts.find((script) => script.trim().startsWith("rm -rf"));+ expect(removeScript).toBeDefined();+ }, 10_000);++ it("T6 issues no operating-system signal from the host during stop()", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-no-signal-"));+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "quiet-child.mjs");+ await writeFile(childPath, "process.stdin.resume();\n", "utf8");++ const scripts: string[] = [];+ const runner = createLocalSandboxRunner(async (script) => {+ scripts.push(script);+ });+ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner,+ };+ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-no-signal",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async () => {},+ });+ expect(bridge).not.toBeNull();++ scripts.length = 0;+ await bridge!.stop();++ // stop() only ever writes files and removes a directory. None of the+ // scripts it runs names a signal or a kill command.+ const signalLike = scripts.filter((script) => /\bkill\b|SIGTERM|SIGKILL/i.test(script));+ expect(signalLike).toEqual([]);+ });++ it("T8 running terminate() a second time, after the child already exited, is a safe no-op", async () => {+ const wrapper = await startWrapperProcess({+ outputToStdout: false,+ command: process.execPath,+ args: ["-e", "process.exit(0)"],+ });+ await Promise.race([+ wrapper.exited,+ delay(4_000).then(() => {+ throw new Error("The wrapper did not exit after its child exited on its own.");+ }),+ ]);+ // The wrapper's own child-close handler already ran terminate() once (the+ // child was already gone, so its child.kill() call no-opped). The+ // wrapper did not throw and did not hang.+ expect(wrapper.stderrText()).toBe("");+ expect(wrapper.exitInfo().code).toBe(0);+ const events = await wrapper.readEventFiles();+ expect(events.filter((event) => event.type === "exit").length).toBe(1);+ // No stray signal-triggered event (e.g. a second exit from a SIGKILL)+ // ever landed.+ expect(events.filter((event) => event.type === "error").length).toBe(0);+ });++ it("T9 exits with an error event when sessionDir is a symbolic link", async () => {+ const targetDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-symlink-target-"));+ cleanupDirs.push(targetDir);+ const linkDir = `${targetDir}-link`;+ const { symlink } = await import("node:fs/promises");+ await symlink(targetDir, linkDir, "dir");+ cleanupDirs.push(linkDir);++ const wrapperPath = path.join(targetDir, "wrapper.mjs");+ await writeFile(wrapperPath, getProcessSessionRemoteSource({ outputToStdout: true }), "utf8");+ const config = { command: "cat", args: [] as string[], cwd: targetDir, env: {} };+ const commandPayload = Buffer.from(JSON.stringify(config), "utf8").toString("base64");++ const child = spawn(process.execPath, [wrapperPath], {+ cwd: targetDir,+ env: {+ ...process.env,+ PAPERCLIP_PROCESS_SESSION_DIR: linkDir,+ PAPERCLIP_PROCESS_SESSION_COMMAND_B64: commandPayload,+ },+ stdio: ["ignore", "pipe", "pipe"],+ });+ const frames: WrapperFrame[] = [];+ let stdoutBuffer = "";+ child.stdout.on("data", (chunk: Buffer) => {+ stdoutBuffer += chunk.toString("utf8");+ const lines = stdoutBuffer.split("\n");+ stdoutBuffer = lines.pop() || "";+ for (const line of lines) {+ if (!line.trim()) continue;+ frames.push(JSON.parse(line) as WrapperFrame);+ }+ });+ const exited = new Promise<void>((resolve) => child.on("close", () => resolve()));++ await Promise.race([+ exited,+ delay(4_000).then(() => {+ throw new Error("The wrapper did not exit after sessionDir was a symbolic link.");+ }),+ ]);+ expect(frames.some((frame) => frame.type === "error" && typeof frame.message === "string" && frame.message.includes("symbolic link"))).toBe(+ true,+ );+ });++ it("T10 the emitted wrapper strips its own session env vars from the child", async () => {+ const wrapper = await startWrapperProcess({+ outputToStdout: true,+ command: process.execPath,+ args: [+ "-e",+ "process.stdout.write(JSON.stringify(Object.keys(process.env).filter((k) => k.startsWith('PAPERCLIP_PROCESS_SESSION'))));process.exit(0)",+ ],+ });+ await waitFor(() => wrapper.frames.some((frame) => frame.type === "exit"), 4_000);+ const text = wrapper.frames+ .filter((frame) => frame.type === "data" && frame.stream === "stdout" && typeof frame.data === "string")+ .map((frame) => Buffer.from(frame.data as string, "base64").toString("utf8"))+ .join("");+ const leakedKeys = JSON.parse(text || "[]") as string[];+ expect(leakedKeys).toEqual([]);+ });++ it("T11 each wrapper source has exactly one spawn call site and every kill call is child.kill()", () => {+ for (const outputToStdout of [true, false]) {+ const src = getProcessSessionRemoteSource({ outputToStdout });+ // Strip `//` line comments first, so prose that happens to mention+ // "spawn(" or "kill(" (e.g. explaining `ChildProcess#kill()`) is never+ // mistaken for a call site. This checks the code, not the comments.+ const code = src+ .split("\n")+ .map((line) => line.replace(/\/\/.*$/, ""))+ .join("\n");+ const spawnCallSites = code.match(/\bspawn\(/g) ?? [];+ expect(spawnCallSites.length).toBe(1);+ const killCallSites = [...code.matchAll(/[A-Za-z0-9_.$]*kill\(/g)].map((match) => match[0]);+ expect(killCallSites.length).toBeGreaterThan(0);+ for (const site of killCallSites) {+ expect(site).toBe("child.kill(");+ }++ // Regression coverage for PAP-5336: the shared tail must carry the+ // session-identity latch, not the old counter it replaced. A counter+ // that a successful `readdir` reset to zero let an attacker who+ // recreated a deleted control directory keep the wrapper alive+ // forever. Both wrapper variants append the same shared tail, so this+ // check runs once per variant and fails if a future edit lands the+ // latch in only one of them.+ expect(src).not.toContain("missingSessionDirStreak");+ const identityLatchDeclarations = code.match(/\blet identityLost = false;/g) ?? [];+ expect(identityLatchDeclarations.length).toBe(1);+ const identityCaptureCallSites = code.match(/\bcaptureSessionIdentity\(\)/g) ?? [];+ expect(identityCaptureCallSites.length).toBeGreaterThan(0);+ const identityVerifyCallSites = code.match(/\bverifySessionIdentity\(\)/g) ?? [];+ expect(identityVerifyCallSites.length).toBeGreaterThan(0);+ // The capture must run before the first poll cycle: its call site must+ // precede the `pollStdin()` call site in the emitted source.+ expect(code.indexOf("await captureSessionIdentity();")).toBeGreaterThan(0);+ expect(code.indexOf("await captureSessionIdentity();")).toBeLessThan(code.indexOf("void pollStdin()"));+ }+ });++ // Regression coverage for PAP-5323: the host used to burn the full+ // shutdown budget and log a false warning on every normal run, because+ // the file-poll loop stopped re-arming right after it delivered the+ // `exit` event and so never read the `shutdownAck` file that followed it.+ it("T12 stop() finishes well inside the shutdown budget and logs no warning after a normal child exit", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-normal-exit-"));+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "quick-exit-child.mjs");+ await writeFile(childPath, "process.exit(0);\n", "utf8");++ const runner = createLocalSandboxRunner();+ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner,+ };++ let warnedCount = 0;+ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-normal-exit",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async (stream, chunk) => {+ if (stream === "stderr" && chunk.includes("did not acknowledge shutdown")) warnedCount += 1;+ },+ });+ expect(bridge).not.toBeNull();++ // Let the child exit and the wrapper write its own `exit` event before+ // stop() runs, so this matches a normal run-completion teardown.+ await delay(500);++ const start = Date.now();+ await bridge!.stop();+ const elapsedMs = Date.now() - start;++ expect(elapsedMs).toBeLessThan(1_000);+ expect(warnedCount).toBe(0);+ }, 10_000);++ // Regression coverage for PAP-5323: a genuinely stuck wrapper, one that+ // never writes any event, must still warn after the budget and still+ // remove `sessionDir`. The fix must not turn the bounded wait into an+ // unconditional skip.+ it("T13 warns and still removes sessionDir when the wrapper never acknowledges and never exits", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-never-acks-"));+ cleanupDirs.push(rootDir);+ const childPath = path.join(rootDir, "quiet-child.mjs");+ await writeFile(childPath, "process.stdin.resume();\n", "utf8");++ const scripts: string[] = [];+ let counter = 0;+ // Run every script for real except the wrapper launch itself, so the+ // wrapper never starts and the events directory stays empty on every+ // poll. `stop()` can then never observe a real `shutdownAck` or a real+ // terminal `exit`/`error` event.+ const runner = {+ execute: async (input: {+ command: string;+ args?: string[];+ cwd?: string;+ env?: Record<string, string>;+ stdin?: string;+ timeoutMs?: number;+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;+ }): Promise<RunProcessResult> => {+ const script = input.args?.[1] ?? "";+ scripts.push(script);+ if (script.includes("nohup node")) {+ return { exitCode: 0, signal: null, timedOut: false, stdout: "", stderr: "", pid: null, startedAt: null };+ }+ counter += 1;+ const command =+ input.command === "bash" ? "/bin/bash" : input.command === "sh" ? "/bin/sh" : input.command;+ return runChildProcess(`never-acks-run-${counter}`, command, input.args ?? [], {+ cwd: input.cwd ?? process.cwd(),+ env: input.env ?? {},+ stdin: input.stdin,+ timeoutSec: Math.max(1, Math.ceil((input.timeoutMs ?? 30_000) / 1000)),+ graceSec: 5,+ onLog: input.onLog ?? (async () => {}),+ });+ },+ };+ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner,+ };++ let warnedCount = 0;+ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-never-acks",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async (stream, chunk) => {+ if (stream === "stderr" && chunk.includes("did not acknowledge shutdown")) warnedCount += 1;+ },+ });+ expect(bridge).not.toBeNull();++ const start = Date.now();+ await bridge!.stop();+ const elapsedMs = Date.now() - start;++ // The full shutdown budget elapsed, because nothing ever proved the+ // wrapper stopped.+ expect(elapsedMs).toBeGreaterThanOrEqual(2_900);+ expect(warnedCount).toBe(1);+ const removeScript = scripts.find((script) => script.trim().startsWith("rm -rf"));+ expect(removeScript).toBeDefined();+ }, 10_000);++ // Regression coverage for PAP-5336: the finding this test reproduces is a+ // sandbox control-plane integrity failure, not a timing quirk. During+ // `stop()`, a sandbox peer with access to the session directory can (1)+ // delete the real `shutdown` control file before the wrapper ever reads+ // it, (2) forge a `shutdownAck` event so the host's wait ends early, and+ // (3) recreate `sessionDir/stdin` right after the host removes+ // `sessionDir`. On the parent commit, a successful `readdir` on the+ // recreated directory reset the wrapper's only terminal counter to zero,+ // so the wrapper (and its child) polled forever.+ //+ // The fix replaces the counter with an identity captured at startup: the+ // device number, the inode number, and the inode's own creation time. All+ // three matter for this test to be a real regression check, not a check+ // that passes by luck. Recreating a directory at the same path right after+ // removal, with nothing else on the filesystem in between, can reissue the+ // exact same device and inode numbers on common filesystems (this test's+ // recreate step does exactly that): a device/inode-only identity would+ // then wrongly read as unchanged. The creation time does not have this+ // gap, because it is set fresh on every inode allocation even when the+ // allocator reissues an old inode number.+ it("T15 latches on a lost session identity: a recreated control directory cannot keep the wrapper or its child alive", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-lost-identity-"));+ cleanupDirs.push(rootDir);+ const pidFile = path.join(rootDir, "t15-child.pid");+ const childPath = path.join(rootDir, "t15-child.mjs");+ await writeFile(childPath, trackedChildSource(pidFile), "utf8");++ let sessionDir = "";+ let stdinDir = "";+ let eventsDir = "";+ let shutdownFileDeleted = false;+ let shutdownAckForged = false;+ let stdinDirRecreated = false;+ const scripts: string[] = [];+ let counter = 0;++ const syntheticSuccess: RunProcessResult = {+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: "",+ stderr: "",+ pid: null,+ startedAt: null,+ };++ // Run every script for real on the local filesystem (matching T2/T4/T5's+ // harness), so a real wrapper process and a real child process come up,+ // with two exceptions that make the attack deterministic instead of a+ // race against the wrapper's own 50 ms poll:+ //+ // 1. With no stdin data ever sent, the host's shutdown control message+ // always targets stdin file 000000000002.json (file 1 is stdinEnd).+ // Never let that write's script pipeline actually run: this is+ // equivalent to an attacker who deletes the file before the wrapper+ // ever reads it, but with no window in which the wrapper could win a+ // race and read it first.+ // 2. Perform the sessionDir removal and the sessionDir/stdin,+ // sessionDir/events recreation as direct filesystem calls in this+ // same async step, instead of spawning a real `rm -rf` subprocess.+ // That removes an external process's scheduling latency from the+ // window the wrapper's next poll cycle has to observe the recreated+ // directory.+ const runner = {+ execute: async (input: {+ command: string;+ args?: string[];+ cwd?: string;+ env?: Record<string, string>;+ stdin?: string;+ timeoutMs?: number;+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;+ }): Promise<RunProcessResult> => {+ counter += 1;+ const script = input.args?.[1] ?? "";+ scripts.push(script);++ const shutdownFilePath = stdinDir ? path.posix.join(stdinDir, "000000000002.json") : null;+ if (shutdownFilePath && script.includes(shutdownFilePath)) {+ if (!shutdownFileDeleted) {+ shutdownFileDeleted = true;+ await writeFile(+ path.join(eventsDir, "999999999999.json"),+ `${JSON.stringify({ type: "shutdownAck" })}\n`,+ "utf8",+ ).catch(() => undefined);+ shutdownAckForged = true;+ }+ return syntheticSuccess;+ }++ // Match the removal of sessionDir itself, not the host's own+ // per-file event cleanup (which also runs `rm -rf` on a path that+ // has sessionDir as a substring).+ if (!stdinDirRecreated && sessionDir && script.trim() === `rm -rf '${sessionDir}'`) {+ stdinDirRecreated = true;+ await rm(sessionDir, { recursive: true, force: true }).catch(() => undefined);+ await mkdir(stdinDir, { recursive: true }).catch(() => undefined);+ await mkdir(eventsDir, { recursive: true }).catch(() => undefined);+ return syntheticSuccess;+ }++ const command =+ input.command === "bash" ? "/bin/bash" : input.command === "sh" ? "/bin/sh" : input.command;+ return runChildProcess(`lost-identity-run-${counter}`, command, input.args ?? [], {+ cwd: input.cwd ?? process.cwd(),+ env: input.env ?? {},+ stdin: input.stdin,+ timeoutSec: Math.max(1, Math.ceil((input.timeoutMs ?? 30_000) / 1000)),+ graceSec: 5,+ onLog: input.onLog ?? (async () => {}),+ });+ },+ };++ const target: AdapterSandboxExecutionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "local-test",+ remoteCwd: rootDir,+ timeoutMs: 30_000,+ runner,+ };++ const bridge = await startAdapterExecutionTargetProcessSessionBridge({+ runId: "run-lost-identity",+ target,+ runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),+ adapterKey: "acpx",+ command: process.execPath,+ args: [childPath],+ cwd: rootDir,+ env: {},+ timeoutSec: 5,+ onLog: async () => {},+ });+ expect(bridge).not.toBeNull();++ const mkdirScript = scripts.find((script) => script.startsWith("mkdir -p"));+ const dirsMatch = /mkdir -p '([^']+)' '([^']+)'/.exec(mkdirScript ?? "");+ expect(dirsMatch).not.toBeNull();+ stdinDir = dirsMatch![1];+ eventsDir = dirsMatch![2];+ sessionDir = path.posix.dirname(stdinDir);++ await waitFor(async () => (await readFile(pidFile, "utf8").catch(() => "")).trim().length > 0, 8_000);+ const pid = Number.parseInt((await readFile(pidFile, "utf8")).trim(), 10);+ expect(isPidAlive(pid)).toBe(true);+ const wrapperScriptSubstring = path.posix.join(rootDir, ".paperclip-runtime", "acpx", "process-sessions");+ await waitFor(async () => (await findLivePidsByArgvSubstring(wrapperScriptSubstring)).length > 0, 4_000);++ await bridge!.stop();++ // Both the attacker's forged shutdownAck and its directory recreation+ // ran; this is the full chain the finding describes, not a partial one.+ expect(shutdownFileDeleted).toBe(true);+ expect(shutdownAckForged).toBe(true);+ expect(stdinDirRecreated).toBe(true);++ // The wrapper process and its child process both exit within a bounded+ // time, even though the wrapper never read a real shutdown message and+ // the host's wait ended early on a forged hint. Only the wrapper's own+ // identity latch can explain this: it observes the recreated directory+ // carries a different identity than the one captured at startup.+ await waitFor(() => !isPidAlive(pid), 8_000);+ expect(isPidAlive(pid)).toBe(false);+ await waitFor(async () => (await findLivePidsByArgvSubstring(wrapperScriptSubstring)).length === 0, 8_000);+ }, 15_000);++ // ---- PAP-5338: fail closed on an unusable creation time, and on every+ // lstat error during verification -------------------------------------++ async function waitForTrackedChildPid(pidFile: string): Promise<number> {+ await waitFor(async () => (await readFile(pidFile, "utf8").catch(() => "")).trim().length > 0, 8_000);+ return Number.parseInt((await readFile(pidFile, "utf8")).trim(), 10);+ }++ async function expectWrapperAndTrackedChildToDie(+ wrapper: { exited: Promise<void> },+ pid: number,+ ): Promise<void> {+ await waitFor(() => !isPidAlive(pid), 8_000);+ expect(isPidAlive(pid)).toBe(false);+ await Promise.race([+ wrapper.exited,+ delay(8_000).then(() => {+ throw new Error("The wrapper process did not exit.");+ }),+ ]);+ }++ // A capture failure latches and calls terminate() before the poll loop+ // ever starts, often within a few milliseconds of the child's own spawn()+ // call returning. A freshly spawned Node.js child needs real wall-clock+ // time just to boot before it can run its own code, so it can lose the+ // race to write a pid file before terminate()'s SIGTERM reaches it. This+ // is the correct, intended shape of a fail-fast capture: the child never+ // gets a chance to become a live orphan. So these two tests prove death+ // through the OS process table by the child's own script path (the same+ // technique T15 above uses for the wrapper itself), which needs no+ // cooperation from code inside the child.+ async function expectNoLiveProcessByArgvSubstring(substring: string): Promise<void> {+ await waitFor(async () => (await findLivePidsByArgvSubstring(substring)).length === 0, 8_000);+ expect(await findLivePidsByArgvSubstring(substring)).toEqual([]);+ }++ it("T16 fails closed at capture when the reported creation time is zero, so no orphan wrapper or child ever starts polling", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-birthtime-zero-"));+ cleanupDirs.push(rootDir);+ const pidFile = path.join(rootDir, "t16-child.pid");+ const childPath = path.join(rootDir, "t16-child.mjs");+ await writeFile(childPath, trackedChildSource(pidFile), "utf8");++ const wrapper = await startWrapperProcess({+ outputToStdout: false,+ command: process.execPath,+ args: [childPath],+ fakeBirthtime: { target: "sessionDir", mode: "zero" },+ });++ await Promise.race([+ wrapper.exited,+ delay(8_000).then(() => {+ throw new Error("The wrapper process did not exit.");+ }),+ ]);+ expect(wrapper.stderrText()).toMatch(/not usable/);+ await expectNoLiveProcessByArgvSubstring(childPath);+ }, 15_000);++ it("T17 fails closed at capture when the reported creation time follows the change time, so a change-time copy never passes as a real creation time", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-birthtime-followctime-"));+ cleanupDirs.push(rootDir);+ const pidFile = path.join(rootDir, "t17-child.pid");+ const childPath = path.join(rootDir, "t17-child.mjs");+ await writeFile(childPath, trackedChildSource(pidFile), "utf8");++ const wrapper = await startWrapperProcess({+ outputToStdout: false,+ command: process.execPath,+ args: [childPath],+ fakeBirthtime: { target: "stdinDir", mode: "followCtime" },+ });++ await Promise.race([+ wrapper.exited,+ delay(8_000).then(() => {+ throw new Error("The wrapper process did not exit.");+ }),+ ]);+ await expectNoLiveProcessByArgvSubstring(childPath);+ expect(wrapper.stderrText()).toMatch(/changed after a probe write/);+ }, 15_000);++ it("T18 latches on an EACCES lstat failure on sessionDir during verification, not only on a removed directory", async () => {+ // sessionDir lives inside a parent this test owns, never the shared OS+ // temp directory: the test denies traversal on that parent, and doing+ // that to the shared OS temp directory would break every other process+ // on the host that also uses it.+ const parentDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-eacces-sessiondir-"));+ cleanupDirs.push(parentDir);+ const pidFile = path.join(parentDir, "t18-child.pid");+ const childPath = path.join(parentDir, "t18-child.mjs");+ await writeFile(childPath, trackedChildSource(pidFile), "utf8");++ const wrapper = await startWrapperProcess({+ outputToStdout: false,+ command: process.execPath,+ args: [childPath],+ parentDir,+ terminateGraceMs: 200,+ });++ const pid = await waitForTrackedChildPid(pidFile);+ // Let capture succeed and the poll loop run a clean cycle first, so the+ // termination below proves the verify-time latch, not the capture-time+ // one.+ await delay(150);+ await chmod(parentDir, 0o000);+ try {+ await expectWrapperAndTrackedChildToDie(wrapper, pid);+ } finally {+ // Restore permission so the shared cleanup can remove this directory.+ await chmod(parentDir, 0o700).catch(() => undefined);+ }+ expect(wrapper.stderrText()).toMatch(/Latching on a lost process session identity/);+ }, 15_000);++ it("T19 latches on an EACCES lstat failure on stdinDir during verification, even though sessionDir itself still stats cleanly", async () => {+ const wrapperOptions = { outputToStdout: false as const, terminateGraceMs: 200 };+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-eacces-stdindir-"));+ cleanupDirs.push(rootDir);+ const pidFile = path.join(rootDir, "t19-child.pid");+ const childPath = path.join(rootDir, "t19-child.mjs");+ await writeFile(childPath, trackedChildSource(pidFile), "utf8");++ const wrapper = await startWrapperProcess({ ...wrapperOptions, command: process.execPath, args: [childPath] });++ const pid = await waitForTrackedChildPid(pidFile);+ await delay(150);+ // Deny traversal into sessionDir itself: lstat(stdinDir) fails EACCES+ // while lstat(sessionDir) still succeeds, since a directory's own mode+ // never gates lstat of the directory itself, only lookups inside it.+ await chmod(wrapper.sessionDir, 0o000);+ try {+ await expectWrapperAndTrackedChildToDie(wrapper, pid);+ } finally {+ await chmod(wrapper.sessionDir, 0o700).catch(() => undefined);+ }+ expect(wrapper.stderrText()).toMatch(/Latching on a lost process session identity/);+ }, 15_000);+});diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.tsindex 3f028b3cb6..801af1ab55 100644--- a/packages/adapter-utils/src/execution-target.ts+++ b/packages/adapter-utils/src/execution-target.ts@@ -1596,6 +1596,12 @@ const PROCESS_SESSION_REMOTE_SCRIPT = "paperclip-process-session-remote.mjs";// hash-skip gate thrashing when a run switches output mode.const PROCESS_SESSION_REMOTE_STREAM_SCRIPT = "paperclip-process-session-remote-stream.mjs";const PROCESS_SESSION_AUTH_TIMEOUT_MS = 5_000;+// The bounded budget `stop()` waits for the wrapper's `shutdownAck` event+// before it removes `sessionDir` unconditionally. The wrapper writes the+// acknowledgement right after it arms its own kill timer, well before its+// child actually exits, so this budget only needs to cover message delivery,+// not the child's full shutdown.+const DEFAULT_PROCESS_SESSION_SHUTDOWN_WAIT_MS = 3_000;function jsonLine(value: unknown): string {return `${JSON.stringify(value)}\n`;@@ -1792,10 +1798,11 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {args: shellCommandArgs([`mkdir -p ${shellQuote(stdinDir)} ${shellQuote(eventsDir)}`,+ // I3: no numeric process identifier anywhere. Background the+ // wrapper and let it go; do not capture `$!`.`PAPERCLIP_PROCESS_SESSION_DIR=${shellQuote(sessionDir)} ` +`PAPERCLIP_PROCESS_SESSION_COMMAND_B64=${shellQuote(commandPayload)} ` +`nohup node ${shellQuote(remoteScriptPath)} >/dev/null 2>&1 < /dev/null &`,- "printf '%s\\n' \"$!\"",].join("\n"),),cwd: target.remoteCwd,@@ -1841,6 +1848,19 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {}> = [];const token = createSandboxCallbackBridgeToken(18);const proxyDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-proxy-"));+ // `stop()` waits on this promise, bounded, for the wrapper's `shutdownAck`+ // event. `deliverRemoteEvent` resolves it below and never forwards the+ // event further: it is a host-internal control ack, not part of the ACP+ // output stream. An event under `sessionDir` is untrusted telemetry: an+ // `exit` or `error` event is never treated as proof of shutdown, because+ // any process running under the sandbox can write one. Only `shutdownAck`+ // counts, and `stop()` also gives itself a dedicated reader for it below,+ // so a late `shutdownAck` still lands even after the long-lived poll has+ // stopped re-arming.+ let signalShutdownAcknowledged: () => void = () => {};+ const shutdownAcknowledged = new Promise<void>((resolve) => {+ signalShutdownAcknowledged = resolve;+ });const writeRemoteEventToSocket = (event: (typeof pendingRemoteEvents)[number]) => {if (!socket) return false;@@ -1856,6 +1876,10 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {};const deliverRemoteEvent = (event: (typeof pendingRemoteEvents)[number]) => {+ if (event.type === "shutdownAck") {+ signalShutdownAcknowledged();+ return;+ }if (socket) {writeRemoteEventToSocket(event);return;@@ -1966,6 +1990,10 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {const poll = async () => {if (stopping) return;try {+ // Read every file this tick fetched before this loop decides whether to+ // keep polling. A `shutdownAck` can land in the same batch right after+ // an `exit` event; deliver it too, so this tick never drops an+ // already-fetched (and already-removed-from-disk) event.const events = await readRemoteJsonFiles({ client, dir: eventsDir });for (const event of events) {const parsed = JSON.parse(event.body) as {@@ -1977,7 +2005,6 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {message?: string;};deliverRemoteEvent(parsed);- if (parsed.type === "exit" || parsed.type === "error") return;}} catch (error) {const message = error instanceof Error ? error.message : String(error);@@ -2130,6 +2157,43 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {schedulePoll();}+ // `stop()` cannot rely on the long-lived poll above to observe a late+ // `shutdownAck`: that poll stops re-arming as soon as it forwards a+ // terminal `exit`/`error` event, and `stop()` itself sets `stopping` on+ // its own first line. A normal completion's `shutdownAck` file, written a+ // moment after `exit`, can then land on disk after nobody reads the events+ // directory any more. Give `stop()` its own bounded reader that looks only+ // for `shutdownAck` and ignores every other event type, so the wait below+ // shortens on the wrapper's own proof of shutdown -- never on an `exit` or+ // `error` event, which any process running under `sessionDir` can forge.+ let stopReadingForShutdownAck = false;+ const readShutdownAckUntil = (deadlineEpochMs: number) => {+ if (stopReadingForShutdownAck) return;+ void (async () => {+ try {+ const events = await readRemoteJsonFiles({ client, dir: eventsDir });+ if (stopReadingForShutdownAck) return;+ for (const event of events) {+ try {+ const parsed = JSON.parse(event.body) as { type?: string };+ if (parsed.type === "shutdownAck") {+ signalShutdownAcknowledged();+ return;+ }+ } catch {+ // Not readable JSON yet. It is not a `shutdownAck`; ignore it.+ }+ }+ } catch {+ // Best-effort: a read failure here is not proof of anything.+ }+ if (!stopReadingForShutdownAck && Date.now() < deadlineEpochMs) {+ const timer = setTimeout(() => readShutdownAckUntil(deadlineEpochMs), 100);+ timer.unref?.();+ }+ })();+ };+return {agentCommand,stop: async () => {@@ -2155,6 +2219,53 @@ export async function startAdapterExecutionTargetProcessSessionBridge(input: {);stdinWriteChain = stdinEndWrite.then(() => undefined, () => undefined);await stdinEndWrite.catch(() => undefined);+ // The `shutdown` control message tells the wrapper to terminate itself+ // and its own child (I3: no operating-system signal and no process+ // identifier cross this boundary — only a file-queue message does).+ // Chain it onto the same per-session write order as `stdinEnd`, so its+ // file never lands before the earlier one.+ const shutdownPath = path.posix.join(+ stdinDir,+ `${String(stdinSeq + 2).padStart(12, "0")}.json`,+ );+ const shutdownWrite = stdinWriteChain.then(() =>+ client.writeTextFile(shutdownPath, jsonLine({ type: "shutdown" })),+ );+ stdinWriteChain = shutdownWrite.then(() => undefined, () => undefined);+ await shutdownWrite.catch(() => undefined);+ // Wait a bounded budget for a hint that the wrapper stopped: only the+ // `shutdownAck` event counts; an `exit` or `error` event is untrusted+ // telemetry from inside the sandbox and never shortens this wait or+ // suppresses the warning below. `shutdownAck` itself is ALSO an+ // untrusted hint, not proof: any process that shares the sandbox can+ // write the same event under this session's event directory. It can+ // only shorten this wait and suppress the warning below; it never+ // gates, shortens, or replaces the unconditional removal further down.+ // What actually makes the wrapper's own termination deterministic is+ // the wrapper-side session-identity latch, not this event.+ let acknowledgedInTime = false;+ readShutdownAckUntil(Date.now() + DEFAULT_PROCESS_SESSION_SHUTDOWN_WAIT_MS);+ await Promise.race([+ shutdownAcknowledged.then(() => {+ acknowledgedInTime = true;+ }),+ new Promise<void>((resolve) => {+ const budgetTimer = setTimeout(resolve, DEFAULT_PROCESS_SESSION_SHUTDOWN_WAIT_MS);+ budgetTimer.unref?.();+ }),+ ]);+ stopReadingForShutdownAck = true;+ if (!acknowledgedInTime) {+ await onLog(+ "stderr",+ `[paperclip] ACP process session wrapper did not acknowledge shutdown within ${DEFAULT_PROCESS_SESSION_SHUTDOWN_WAIT_MS}ms; removing the session directory anyway.\n`,+ ).catch(() => undefined);+ }+ // Unconditional: this removal runs whether or not the wrapper+ // acknowledged, and whether or not any event (real or forged) arrived+ // under `sessionDir`. `stop()` runs during run teardown and must stay+ // non-fatal, so every step above is best-effort and this step never+ // throws.await client.remove(sessionDir).catch(() => undefined);await fs.rm(proxyDir, { recursive: true, force: true }).catch(() => undefined);},@@ -2244,11 +2355,274 @@ const stdinParseRetries = new Map();let stdinExpectedSeq = 1;let stdinGapRetries = 0;+// The bounded grace period between the SIGTERM and the SIGKILL a terminate()+// call sends. A test can override it through the environment, so a stubborn+// child does not force a slow test.+const terminateGraceMs = (() => {+ const raw = Number.parseInt(process.env.PAPERCLIP_PROCESS_SESSION_TERMINATE_GRACE_MS || "", 10);+ return Number.isFinite(raw) && raw > 0 ? raw : 3000;+})();++// I2: terminate() is the only function in this wrapper that calls+// child.kill(). No child event handler and no sibling callback calls it.+// terminate() is idempotent: a second call, or a first call after the child+// already exited on its own, does nothing beyond what already ran.+async function terminate() {+ if (terminated) return;+ terminated = true;+ shuttingDown = true;+ stdinClosed = true;+ child.stdin.end();+ // A \`false\` return means the child's process handle is already gone (the+ // child exited before this call ran). ChildProcess#kill() is handle-scoped:+ // once Node clears the handle at reap, the method call above sends no+ // signal and never falls back to a stored process identifier (I3). Treat+ // \`false\` as a no-op and do not retry through a numeric identifier.+ const sentTerm = child.kill("SIGTERM");+ if (sentTerm) {+ killTimer = setTimeout(() => {+ // Escalate on the same handle only (I2): the grace period expired, so+ // send SIGKILL through the same child handle, never a numeric+ // identifier and never a process-group signal.+ child.kill("SIGKILL");+ }, terminateGraceMs);+ killTimer.unref?.();+ }+ // This event is an untrusted latency hint, not proof. Any process that can+ // reach this session's event directory can write the same event type. It+ // can only shorten the host's shutdown wait and suppress the host's+ // timeout warning; it is never evidence that this wrapper's lifecycle+ // completed, and the host's cleanup never depends on it. The identity+ // latch below is what makes this wrapper's own termination deterministic.+ await writeEvent({ type: "shutdownAck" });+}++// A sandbox peer can delete sessionDir and stdinDir, then recreate a+// directory at the same pathname. A pathname does not prove identity: any+// process that shares the sandbox can write it. So this wrapper captures the+// OS-level identity of both paths once at startup, before the first poll+// cycle, and checks it on every later cycle.+//+// The identity is the device number, the inode number, AND the inode's own+// creation time. The device/inode pair alone is not enough: a filesystem can+// reissue the exact inode number a just-removed directory held to the very+// next directory created at the same path, with no attacker action needed+// beyond the recreate the finding already describes. The creation time does+// not have this gap: it is set fresh on every inode allocation, even when the+// allocator reissues an old inode number, so a recreated directory always+// carries a different creation time. The creation time alone is not enough+// either, on a filesystem or kernel too old to report it, so this wrapper+// keeps the device/inode pair as a second signal rather than relying on+// either alone. Ordinary use of stdinDir (the host writing and this wrapper+// deleting individual stdin files) changes that directory's OWN change time,+// but never its creation time, so the creation time is safe to latch on+// without producing a false positive on every stdin message.+//+// A filesystem or kernel that cannot report a real creation time does not+// always report a value of zero. Node fails in one of two ways, and both are+// grounded, not assumed: on Linux, when the statx() call finds no creation+// time support, the kernel leaves the field unset and Node reports 0. On a+// platform whose stat() call has no creation-time field at all, Node copies+// the change time into the creation time instead. A 0 value fails open (any+// recreated directory then matches on birthtimeMs alone), and a change-time+// copy fails closed but far too often (it would move on every stdin file+// this wrapper deletes). captureSessionIdentity() below proves the value is+// usable before it trusts it, and fails closed on both known fallbacks.+let sessionDirIdentity = null;+let stdinDirIdentity = null;+// The latch. Once set, it never clears. This replaces a counter that a+// successful read reset to zero: an attacker who recreated the directory+// before the counter reached its threshold kept the wrapper polling forever.+// A latch has no threshold to race and no reset path.+let identityLost = false;++async function statPathIdentity(candidatePath) {+ const stats = await fs.lstat(candidatePath);+ if (stats.isSymbolicLink()) {+ const error = new Error("Refusing a symbolic link on a process session control path.");+ error.code = "EPAPERCLIP_SYMLINK";+ throw error;+ }+ if (!stats.isDirectory()) {+ const error = new Error("A process session control path is not a directory.");+ error.code = "ENOTDIR";+ throw error;+ }+ return { dev: stats.dev, ino: stats.ino, birthtimeMs: stats.birthtimeMs };+}++function sameIdentity(left, right) {+ return left.dev === right.dev && left.ino === right.ino && left.birthtimeMs === right.birthtimeMs;+}++async function latchAndTerminate() {+ if (identityLost) return;+ identityLost = true;+ await terminate();+}++function isUsableBirthtimeMs(value) {+ return typeof value === "number" && Number.isFinite(value) && value !== 0;+}++let probeSeq = 0;++// A probe file name that pollStdin() can never read as a stdin message: it+// does not end in ".json", so the ".json" filter in pollStdin() skips it if+// a poll cycle ever lists the directory during the probe's short window.+function nextProbeFileName() {+ probeSeq += 1;+ return ".paperclip-birthtime-probe-" + process.pid + "-" + probeSeq;+}++// Proves a directory's reported birthtimeMs is a real creation time, not a+// change-time copy. Creating and removing a file inside a directory changes+// that directory's OWN change time but never its true creation time, so a+// birthtimeMs that moves across the probe is a change-time copy. Returns+// false both on a detected copy and on a probe that cannot run at all (for+// example a permission error): either way the caller must not trust the+// value.+async function birthtimeSurvivesProbe(dirPath) {+ let before;+ try {+ before = (await fs.lstat(dirPath)).birthtimeMs;+ } catch {+ return false;+ }+ const probePath = path.posix.join(dirPath, nextProbeFileName());+ try {+ await fs.writeFile(probePath, "");+ } catch {+ return false;+ } finally {+ await fs.rm(probePath, { force: true }).catch(() => undefined);+ }+ let after;+ try {+ after = (await fs.lstat(dirPath)).birthtimeMs;+ } catch {+ return false;+ }+ return before === after;+}++async function refuseUnusableCreationTime(label, dirPath, reason) {+ process.stderr.write(+ "Refusing to trust the process session control path " + label + " (" + dirPath + "): " + reason ++ ". This filesystem or kernel gives no usable creation time. Terminating.\\n",+ );+ await latchAndTerminate();+}++// Runs once, before the first poll cycle, and before this wrapper captures+// the identities it later checks on every cycle. A failed capture fails+// closed: the wrapper has no verified identity to check on later cycles, so+// it terminates now instead of polling a control path it never verified.+//+// This wrapper cannot assume stats.birthtimeMs is a real creation time. Node+// reports it in one of two unusable shapes on a filesystem or kernel that+// cannot supply one: 0 (the Linux statx() path when the filesystem reports+// no STATX_BTIME), or a copy of the change time (the generic POSIX stat()+// path on a platform with no birthtime field). A 0 value fails open, so this+// wrapper rejects it outright. A change-time copy fails closed but far too+// aggressively (it would move on every stdin file this wrapper deletes), so+// this wrapper proves the value is not a copy with a probe before it trusts+// it, run once here, before either directory's identity is captured.+async function captureSessionIdentity() {+ try {+ if (!(await birthtimeSurvivesProbe(sessionDir))) {+ await refuseUnusableCreationTime("sessionDir", sessionDir, "its reported creation time changed after a probe write");+ return;+ }+ if (!(await birthtimeSurvivesProbe(stdinDir))) {+ await refuseUnusableCreationTime("stdinDir", stdinDir, "its reported creation time changed after a probe write");+ return;+ }+ const session = await statPathIdentity(sessionDir);+ const stdin = await statPathIdentity(stdinDir);+ if (!isUsableBirthtimeMs(session.birthtimeMs)) {+ await refuseUnusableCreationTime("sessionDir", sessionDir, "its reported creation time (" + session.birthtimeMs + ") is not usable");+ return;+ }+ if (!isUsableBirthtimeMs(stdin.birthtimeMs)) {+ await refuseUnusableCreationTime("stdinDir", stdinDir, "its reported creation time (" + stdin.birthtimeMs + ") is not usable");+ return;+ }+ sessionDirIdentity = session;+ stdinDirIdentity = stdin;+ } catch (error) {+ process.stderr.write(+ "Failed to capture the process session identity: " ++ (error instanceof Error ? error.message : String(error)) + ". Terminating.\\n",+ );+ await latchAndTerminate();+ }+}++// Runs on every poll cycle, before the wrapper reads stdinDir. Terminate and+// latch on any proof the control path is no longer the one this wrapper+// captured at startup (a missing path, a path that is no longer a directory,+// a symbolic link, or a directory whose identity changed), AND on every+// other lstat failure. A permission error is not transient here: a sandbox+// peer can deny search permission on the control directory without removing+// it, and treating that as transient would leave the wrapper and its child+// alive forever. The error code below only picks the stderr message, so an+// operator can still tell a removed directory from a permission error; it+// never decides whether to latch.+//+// Contrast readStdinDirNames() right below, whose catch block stays narrow+// on purpose: readdir() opens a directory descriptor, so it can fail with a+// genuinely transient error under descriptor exhaustion, and latching there+// would kill live sessions under load. lstat() opens no descriptor, and this+// function already runs before every call to readStdinDirNames(), so a+// permission error latches here before readdir() is ever reached.+async function verifySessionIdentity() {+ if (identityLost) return false;+ try {+ const session = await statPathIdentity(sessionDir);+ const stdin = await statPathIdentity(stdinDir);+ if (!sameIdentity(session, sessionDirIdentity) || !sameIdentity(stdin, stdinDirIdentity)) {+ await latchAndTerminate();+ return false;+ }+ return true;+ } catch (error) {+ const code = error && typeof error === "object" ? error.code : undefined;+ const reason =+ code === "ENOENT"+ ? "the control path no longer exists"+ : code === "ENOTDIR"+ ? "the control path is no longer a directory"+ : code === "EPAPERCLIP_SYMLINK"+ ? "the control path is now a symbolic link"+ : "lstat failed" + (code ? " with " + code : "");+ process.stderr.write("Latching on a lost process session identity: " + reason + ". Terminating.\\n");+ await latchAndTerminate();+ return false;+ }+}++// This catch block stays narrow on purpose: see the comment above+// verifySessionIdentity() for why a permission error here is treated as+// transient while the same error latches there.+async function readStdinDirNames() {+ if (!(await verifySessionIdentity())) return [];+ try {+ return await fs.readdir(stdinDir);+ } catch (error) {+ const code = error && typeof error === "object" ? error.code : undefined;+ if (code === "ENOENT" || code === "ENOTDIR") {+ await latchAndTerminate();+ }+ return [];+ }+}+async function pollStdin() {- while (!stdinClosed) {- const entries = (await fs.readdir(stdinDir).catch(() => [])).filter((name) => name.endsWith(".json")).sort();+ while (!shuttingDown) {+ const entries = (await readStdinDirNames()).filter((name) => name.endsWith(".json")).sort();for (const name of entries) {- if (stdinClosed) break;+ if (shuttingDown) break;const entrySeq = Number.parseInt(name, 10);// Hold the send order when an earlier file has not appeared. Do not consume// this later file: wait for the missing file on a later cycle, bounded by@@ -2271,7 +2645,12 @@ async function pollStdin() {const file = path.posix.join(stdinDir, name);let message;try {- const raw = await fs.readFile(file, "utf8");+ // Hardening (I3): open with O_NOFOLLOW where the platform defines it,+ // so a control-path symbolic link swapped in after the directory+ // check fails the read instead of following it.+ const readFlag =+ typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW : "r";+ const raw = await fs.readFile(file, { encoding: "utf8", flag: readFlag });// An empty read means the content is not on disk yet. Treat it the same// as a parse failure: keep the file and retry on a later cycle.if (!raw) throw new Error("stdin file is empty");@@ -2317,12 +2696,17 @@ async function pollStdin() {stdinClosed = true;child.stdin.end();break;+ } else if (message.type === "shutdown") {+ await terminate();+ break;}}- if (!stdinClosed) await new Promise((resolve) => setTimeout(resolve, 50));+ if (!shuttingDown) await new Promise((resolve) => setTimeout(resolve, 50));}}+await captureSessionIdentity();+void pollStdin().catch((error) => void writeEvent({ type: "error", message: error instanceof Error ? error.message : String(error) }));`;@@ -2335,7 +2719,7 @@ void pollStdin().catch((error) => void writeEvent({ type: "error", message: erro// command settles and the session shell (the subshell wrap around it) survives.function getProcessSessionRemoteStreamSource(): string {return `import { spawn } from "node:child_process";-import { promises as fs } from "node:fs";+import { promises as fs, constants as fsConstants } from "node:fs";import path from "node:path";const sessionDir = process.env.PAPERCLIP_PROCESS_SESSION_DIR;@@ -2345,6 +2729,9 @@ if (!sessionDir || !commandPayload) throw new Error("Missing process session briconst stdinDir = path.posix.join(sessionDir, "stdin");let seq = 0;let stdinClosed = false;+let shuttingDown = false;+let terminated = false;+let killTimer = null;const config = JSON.parse(Buffer.from(commandPayload, "base64").toString("utf8"));await fs.mkdir(stdinDir, { recursive: true });@@ -2356,9 +2743,36 @@ function writeEvent(event) {process.stdout.write(JSON.stringify({ seq, ...event }) + "\\n");}+// Hardening (I3): refuse a symbolic link on a control path before this+// wrapper reads or writes through it. A symbolic link here could let another+// sandbox process redirect the wrapper's file I/O outside the session tree.+async function isSymbolicLink(candidatePath) {+ try {+ const stats = await fs.lstat(candidatePath);+ return stats.isSymbolicLink();+ } catch {+ return false;+ }+}++if ((await isSymbolicLink(sessionDir)) || (await isSymbolicLink(stdinDir))) {+ await writeEvent({ type: "error", message: "Refusing a symbolic link on a process session control path." });+ process.exitCode = 1;+ process.exit(1);+}++// Hardening (I3, not containment): the wrapper's own launch env carries the+// session dir and the command payload. Scrub both keys before they reach the+// spawned child, so the child never inherits a path to its own control files.+const childEnv = { ...process.env, ...(config.env || {}) };+delete childEnv.PAPERCLIP_PROCESS_SESSION_DIR;+delete childEnv.PAPERCLIP_PROCESS_SESSION_COMMAND_B64;++// I1: exactly one child process per emitted wrapper. Do not add a second+// tracked child handle.const child = spawn(config.command, Array.isArray(config.args) ? config.args : [], {cwd: config.cwd || process.cwd(),- env: { ...process.env, ...(config.env || {}) },+ env: childEnv,stdio: ["pipe", "pipe", "pipe"],});@@ -2366,12 +2780,21 @@ child.stdout.on("data", (chunk) => writeEvent({ type: "data", stream: "stdout",child.stderr.on("data", (chunk) => writeEvent({ type: "data", stream: "stderr", data: Buffer.from(chunk).toString("base64") }));child.on("error", (error) => writeEvent({ type: "error", message: error.message }));// "close" (not "exit") so stdout/stderr fully drain before the exit frame.-// Stop the stdin poll and set the exit code, then let the event loop drain: a-// natural exit flushes the stdout pipe, so the exit frame always lands.+// Queue the exit frame first, then run terminate(), so the exit frame always+// lands even when the child closes on its own, with no stdinEnd and no+// shutdown message ever received. writeEvent() only queues an asynchronous+// write. terminate()'s own synchronous work (ending the child's stdin and+// sending SIGTERM) already runs in this same handler by the time the exit+// frame becomes readable on disk. terminate() is idempotent and its+// child.kill() call here is always a no-op (I2): the child's process handle+// is already gone by the time "close" fires. An error frame carries no such+// guarantee: child.on("error", ...) below does not call terminate(), and+// neither does the poll loop's own error writes, so those fire while the+// wrapper and its child are still fully alive.child.on("close", (code, signal) => {writeEvent({ type: "exit", code, signal });- stdinClosed = true;process.exitCode = typeof code === "number" ? code : 1;+ void terminate();});${PROCESS_SESSION_STDIN_POLL_TAIL}`;@@ -2379,7 +2802,7 @@ ${PROCESS_SESSION_STDIN_POLL_TAIL}`;function getProcessSessionRemoteEventFileSource(): string {return `import { spawn } from "node:child_process";-import { promises as fs } from "node:fs";+import { promises as fs, constants as fsConstants } from "node:fs";import path from "node:path";const sessionDir = process.env.PAPERCLIP_PROCESS_SESSION_DIR;@@ -2390,6 +2813,9 @@ const stdinDir = path.posix.join(sessionDir, "stdin");const eventsDir = path.posix.join(sessionDir, "events");let seq = 0;let stdinClosed = false;+let shuttingDown = false;+let terminated = false;+let killTimer = null;const config = JSON.parse(Buffer.from(commandPayload, "base64").toString("utf8"));await fs.mkdir(stdinDir, { recursive: true });@@ -2408,9 +2834,36 @@ function writeEvent(event) {return write;}+// Hardening (I3): refuse a symbolic link on a control path before this+// wrapper reads or writes through it. A symbolic link here could let another+// sandbox process redirect the wrapper's file I/O outside the session tree.+async function isSymbolicLink(candidatePath) {+ try {+ const stats = await fs.lstat(candidatePath);+ return stats.isSymbolicLink();+ } catch {+ return false;+ }+}++if ((await isSymbolicLink(sessionDir)) || (await isSymbolicLink(stdinDir))) {+ await writeEvent({ type: "error", message: "Refusing a symbolic link on a process session control path." });+ process.exitCode = 1;+ process.exit(1);+}++// Hardening (I3, not containment): the wrapper's own launch env carries the+// session dir and the command payload. Scrub both keys before they reach the+// spawned child, so the child never inherits a path to its own control files.+const childEnv = { ...process.env, ...(config.env || {}) };+delete childEnv.PAPERCLIP_PROCESS_SESSION_DIR;+delete childEnv.PAPERCLIP_PROCESS_SESSION_COMMAND_B64;++// I1: exactly one child process per emitted wrapper. Do not add a second+// tracked child handle.const child = spawn(config.command, Array.isArray(config.args) ? config.args : [], {cwd: config.cwd || process.cwd(),- env: { ...process.env, ...(config.env || {}) },+ env: childEnv,stdio: ["pipe", "pipe", "pipe"],});@@ -2419,7 +2872,22 @@ child.stderr.on("data", (chunk) => void writeEvent({ type: "data", stream: "stdechild.on("error", (error) => void writeEvent({ type: "error", message: error.message }));// "close" (not "exit") so stdout/stderr fully drain before the exit event;// the write chain then guarantees the exit file lands after every data file.-child.on("close", (code, signal) => void writeEvent({ type: "exit", code, signal }));+// Queue the exit event first, then run terminate(), so the poll loop ends+// even when the child closes on its own, with no stdinEnd and no shutdown+// message ever received. writeEvent() only queues an asynchronous write.+// terminate()'s own synchronous work (ending the child's stdin and sending+// SIGTERM) already runs in this same handler by the time the exit file+// becomes readable on disk. terminate() is idempotent and its child.kill()+// call here is always a no-op (I2): the child's process handle is already+// gone by the time "close" fires. An error event carries no such guarantee:+// child.on("error", ...) below does not call terminate(), and neither does+// the poll loop's own error writes, so those fire while the wrapper and its+// child are still fully alive.+child.on("close", (code, signal) => {+ void writeEvent({ type: "exit", code, signal });+ process.exitCode = typeof code === "number" ? code : 1;+ void terminate();+});${PROCESS_SESSION_STDIN_POLL_TAIL}`;}