Files
PaperClipAI/server/src/services/native-runtime/runner-bridge-tools.test.ts
T
DottaandClaude Opus 5.5 10ddb26dbb test(server): accept dash's exit code for a sandbox-denied shell write (#21792)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Runner workspace bridge runs agent commands in a `bwrap` sandbox
that binds only `/usr`, `/bin`, `/lib` and the task workspace
> - A server test checks that a sandboxed command cannot read or write a
file outside the workspace
> - The test only runs where `/usr/bin/bwrap` exists. CI jobs that the
gate sends to GitHub's `ubuntu-latest` now get the `ubuntu-26.04` image,
which has `bwrap`, so the test runs on CI for the first time
> - There it fails on every run, because it expects the write attempt to
exit with 1, but Ubuntu's `/bin/sh` (dash) exits with 2 when a
redirection fails
> - This pull request checks that the write fails and that the file is
unchanged, without depending on the shell's exit code
> - The benefit is that the "General tests (server (7/12))" job passes
again on the new image, and the test still proves the sandbox denial

## Linked Issues or Issue Description

**What happened?**
`server/src/services/native-runtime/runner-bridge-tools.test.ts` ›
`Runner workspace bridge > runs useful commands but denies files outside
the workspace and injected credentials` fails in "ci / General tests
(server (7/12))" on unrelated branches, on the first run and the retry:
- PR #21765, head `98197c87e9`
- branch `feat/run-loop-detector`, run 43732047843, head `b8c6e27429`,
job 132866487949, image `ubuntu-26.04` version 20261111.196.1

```
AssertionError: expected { exitCode: 2, signal: null, …(3) } to match object { exitCode: 1 }
 ❯ src/services/native-runtime/runner-bridge-tools.test.ts:180:19
```

On jobs that ran on the RunsOn `ubuntu24` image there is no
`/usr/bin/bwrap`, so the test is skipped (7 skipped instead of 6).

**Expected behavior**
The test passes wherever the command sandbox is available, and it fails
if the sandboxed command can read or change the outside file.

**Steps to reproduce**
1. In a Debian or Ubuntu container, run `/bin/sh -c 'printf stolen >
"$1"' sh /nonexistent/dir/private.txt`.
2. dash prints `cannot create /nonexistent/dir/private.txt: Directory
nonexistent` and exits with 2. bash exits with 1. `cat` of the same path
exits with 1.
3. In the sandbox, the outside temporary directory is not bound, so the
path does not exist. This is the same case.

**Root cause**
A stale test expectation, exposed by a CI image change. No commit on
`master` changed the bridge, the sandbox or this test today (the last
change to the test is from 2026-11-08). The test expected the shell
write to exit with 1. That is bash behavior. On Ubuntu, `/bin/sh` is
dash, which exits with 2 for a failed redirection. Until today no CI
image had `bwrap`, so the test never ran on CI.

**Production impact**
None. The sandbox denies the access as intended: the `cat` step on the
same run exits with 1 and its output does not contain the secret, and
the write fails with `Directory nonexistent` because the outside
directory is not visible in the sandbox. This is not a sandbox
regression.

## What Changed

- The write step now checks that the outside file still contains
`PRIVATE` first, then that the command was not stopped and exited with a
non-zero code. It no longer requires exit code 1 from the shell.
- The read step and the success step are unchanged.

## Verification

- Linux container (`node:24-bookworm-slim`, `/bin/sh -> dash`): the
write command exits with 2 under dash and 1 under bash, and both are
failures, as the test now accepts.
- `npx vitest run
src/services/native-runtime/runner-bridge-tools.test.ts` in `server/` on
macOS: 11 passed, 6 skipped (the sandbox tests need Linux with `bwrap`).
- I cannot run the sandbox test on this Mac. It runs in this pull
request's CI only when the job lands on an `ubuntu-26.04` runner.

## Risks

- Low risk. Only one test assertion changes. The test still fails if the
write succeeds, because the file content check runs first and the exit
code must be non-zero.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edit, GitHub CLI, Docker).

## Checklist

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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 10:47:19 -06:00

214 lines
16 KiB
TypeScript

import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
import { createHash } from "node:crypto";
import { materializeAsset } from "./runtime-context.js";
import { taskBridgeApiRequest } from "./paperclip-runner-tool-authority.js";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { afterEach, describe, expect, it } from "vitest";
import { executeWorkspaceTool, readAssignedSkill, readWorkspaceUploadFile, runnerBridgeDefinitions, workspaceCommandSandboxAvailable, settleRunnerBridgeRead } from "./runner-bridge-tools.js";
const roots: string[] = [];
afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); });
const root = async () => { const directory = await mkdtemp(join(tmpdir(), "dot-bridge-")); roots.push(directory); return directory; };
const authorize = async () => {};
describe("Runner workspace bridge", () => {
it("guards new writes, existing content, traversal and symlinks", async () => {
const directory = await root(), outside = await root();
const result = await executeWorkspaceTool(directory, "workspace_write", { path: "hello.txt", text: "hello 🌍", expectedSha256: null }, authorize) as any;
expect(result.byteSize).toBe(Buffer.byteLength("hello 🌍"));
expect(await executeWorkspaceTool(directory, "workspace_read", { path: "hello.txt" }, authorize)).toMatchObject({ text: "hello 🌍", sha256: result.sha256 });
await expect(executeWorkspaceTool(directory, "workspace_write", { path: "hello.txt", text: "overwrite", expectedSha256: null }, authorize)).rejects.toThrow();
await expect(executeWorkspaceTool(directory, "workspace_write", { path: "hello.txt", text: "overwrite", expectedSha256: "0".repeat(64) }, authorize)).rejects.toThrow("conflict");
await executeWorkspaceTool(directory, "workspace_write", { path: "hello.txt", text: "updated", expectedSha256: result.sha256 }, authorize);
await expect(executeWorkspaceTool(directory, "workspace_read", { path: "../hello.txt" }, authorize)).rejects.toThrow();
await writeFile(join(outside, "private.txt"), "PRIVATE");
await symlink(outside, join(directory, "outside"));
await expect(readWorkspaceUploadFile(directory, "../private.txt")).rejects.toThrow();
await expect(readWorkspaceUploadFile(directory, "outside/private.txt")).rejects.toThrow("symlink_denied");
expect((await readWorkspaceUploadFile(directory, "hello.txt")).toString()).toBe("updated");
await expect(executeWorkspaceTool(directory, "workspace_read", { path: "outside/private.txt" }, authorize)).rejects.toThrow("symlink");
});
it.each(["workspace", "skill"])("preserves Unicode characters across %s text pages", async mode => {
const text = "a".repeat(5999) + "🌍" + "z".repeat(6000) + "🚀";
const directory = await root();
await writeFile(join(directory, "unicode.txt"), text);
const bundle = await materializeAsset([{ path: "SKILL.md", content: Buffer.from(text), mode: 0o444 }]);
const context = { skills: [{ key: "unicode", runtimeName: "unicode", versionId: "version-1", bundle }] } as any;
const read = async (offset: number) => (mode === "workspace"
? executeWorkspaceTool(directory, "workspace_read", { path: "unicode.txt", offset }, authorize)
: readAssignedSkill(context, { skill: "unicode", offset })) as Promise<{ text: string; nextOffset: number | null; sha256: string; byteSize: number }>;
const first = await read(0);
expect(first.nextOffset).toBe(5999);
expect(first.text).toBe("a".repeat(5999));
let combined = first.text, next = first.nextOffset;
while (next !== null) {
const page = await read(next);
expect(page.sha256).toBe(first.sha256);
expect(page.byteSize).toBe(Buffer.byteLength(text));
expect(page.text).not.toMatch(/^[\uDC00-\uDFFF]|[\uD800-\uDBFF]$/u);
combined += page.text;
next = page.nextOffset;
}
expect(combined).toBe(text);
await expect(read(6000)).rejects.toThrow("offset_splits_character");
});
it("excludes instance state from workspace reads, writes, listings and upload reads", async () => {
const directory = await root();
await mkdir(join(directory, ".paperclip"));
await writeFile(join(directory, ".paperclip", ".env"), "SYNTHETIC_INSTANCE_SECRET");
await mkdir(join(directory, "nested", ".PaPeRcLiP"), { recursive: true });
for (const path of [".paperclip/.env", "nested/.PaPeRcLiP/config.json"]) {
await expect(executeWorkspaceTool(directory, "workspace_read", { path }, authorize)).rejects.toThrow("instance_state_denied");
await expect(executeWorkspaceTool(directory, "workspace_write", { path, text: "overwrite", expectedSha256: null }, authorize)).rejects.toThrow("instance_state_denied");
await expect(readWorkspaceUploadFile(directory, path)).rejects.toThrow("instance_state_denied");
}
await expect(executeWorkspaceTool(directory, "workspace_list", { path: ".paperclip" }, authorize)).rejects.toThrow("instance_state_denied");
expect(await executeWorkspaceTool(directory, "workspace_list", { path: "" }, authorize)).toMatchObject({ entries: [{ name: "nested" }] });
expect(await readFile(join(directory, ".paperclip", ".env"), "utf8")).toBe("SYNTHETIC_INSTANCE_SECRET");
});
it.skipIf(!workspaceCommandSandboxAvailable())("denies command access to instance keys while preserving ordinary workspace work", async () => {
const directory = join(await root(), "project.[safe]");
await mkdir(directory);
await mkdir(join(directory, ".paperclip"));
await mkdir(join(directory, "nested", ".PaPeRcLiP"), { recursive: true });
const keys = [".paperclip/.env", "nested/.PaPeRcLiP/config.json"];
for (const key of keys) await writeFile(join(directory, key), "SYNTHETIC_INSTANCE_SECRET");
for (const key of keys) {
const read = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/cat", args: [key] }, authorize) as any;
expect(read.exitCode).not.toBe(0);
expect(read.output).not.toContain("SYNTHETIC_INSTANCE_SECRET");
const write = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/sh", args: ["-c", 'printf overwrite > "$1"', "sh", key] }, authorize) as any;
expect(write.exitCode).not.toBe(0);
expect(await readFile(join(directory, key), "utf8")).toBe("SYNTHETIC_INSTANCE_SECRET");
}
const ordinary = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/sh", args: ["-c", "printf hello > result.txt"] }, authorize) as any;
expect(ordinary.exitCode).toBe(0);
expect(await readFile(join(directory, "result.txt"), "utf8")).toBe("hello");
});
it("tells agents that a comment on a running task waits for the assignee's next turn", () => {
// A chat lead routing a requirement change to busy work otherwise reads "without interrupting"
// as "never delivered" and reaches for the assignee's workspace or a duplicate task instead.
const comment = runnerBridgeDefinitions({ workspace: false, skills: false, api: true, mode: "standard" }).find(tool => tool.name === "comment_on_task");
expect(comment?.description).toContain("existing task's assignee a new or changed requirement");
expect(comment?.description).toContain("rather than creating a duplicate task or editing that task's workspace files");
expect(comment?.description).toContain("delivers it at the start of the assignee's next turn on that task");
expect(comment?.description).toContain("set resume: true for such a requirement");
expect(comment?.description).toContain("delivery still happens if the assignee completes the task first");
expect(comment?.description).toContain("not as already applied");
expect((comment?.inputSchema as { properties?: Record<string, unknown> }).properties?.resume).toEqual({ type: "boolean" });
});
it("forwards a comment's explicit resume intent to the comment API and omits it otherwise", () => {
const taskId = "8ba8b5a2-066a-4bb2-b591-e396942ecdf5";
expect(taskBridgeApiRequest("comment_on_task", { taskId, body: "Set the headline to Launch sooner.", resume: true }).body)
.toEqual({ body: "Set the headline to Launch sooner.", resume: true });
expect(taskBridgeApiRequest("comment_on_task", { taskId, body: "FYI only." }).body).toEqual({ body: "FYI only." });
expect(taskBridgeApiRequest("comment_on_task", { taskId, body: "FYI only.", resume: false }).body).toEqual({ body: "FYI only." });
});
it.skipIf(process.platform === "linux")("does not expose or execute commands without descendant containment", async () => {
const directory = await root();
expect(workspaceCommandSandboxAvailable()).toBe(false);
const tools = runnerBridgeDefinitions({ workspace: true, skills: false, api: false, mode: "standard" }).map(tool => tool.name);
expect(tools).toEqual(expect.arrayContaining(["workspace_list", "workspace_read", "workspace_write"]));
expect(tools).not.toContain("workspace_run");
await expect(executeWorkspaceTool(directory, "workspace_run", {
program: "/bin/sh", args: ["-c", "printf escaped > unexpected.txt"],
}, authorize)).rejects.toThrow("command_sandbox_unavailable");
await expect(readFile(join(directory, "unexpected.txt"))).rejects.toThrow();
});
it.skipIf(!workspaceCommandSandboxAvailable()).each(["completion", "timeout", "revocation"])("terminates detached descendants on %s", async mode => {
const directory = await root();
await writeFile(join(directory, "detach.py"), `import os, time, sys
if os.fork() == 0:
os.setsid()
for fd in (0, 1, 2):
os.close(fd)
for tick in range(500):
with open("ticks.txt", "w") as out:
out.write(str(tick))
time.sleep(0.02)
os._exit(0)
while not os.path.exists("ticks.txt"):
time.sleep(0.01)
if sys.argv[1] != "completion":
time.sleep(20)
`);
let revoked = false;
const result = await executeWorkspaceTool(directory, "workspace_run", {
program: "/usr/bin/python3", args: ["detach.py", mode], timeoutMs: mode === "timeout" ? 1000 : 5000,
}, async () => {
if (revoked) throw new Error("revoked");
if (mode === "revocation") revoked = await readFile(join(directory, "ticks.txt")).then(() => true, () => false);
}) as any;
expect(result.stopped).toBe(mode === "timeout" ? "timeout" : mode === "revocation" ? "authority_revoked" : null);
const final = await readFile(join(directory, "ticks.txt"), "utf8");
await new Promise(resolve => setTimeout(resolve, 150));
expect(await readFile(join(directory, "ticks.txt"), "utf8")).toBe(final);
});
it("serializes overlapping writes so only one observed hash can commit", async () => {
const directory = await root();
const initial = await executeWorkspaceTool(directory, "workspace_write", { path: "shared.txt", text: "initial", expectedSha256: null }, authorize) as any;
let entered!: () => void, release!: () => void, authorizations = 0;
const waiting = new Promise<void>(resolve => { entered = resolve; });
const gate = new Promise<void>(resolve => { release = resolve; });
const first = executeWorkspaceTool(directory, "workspace_write", { path: "shared.txt", text: "first", expectedSha256: initial.sha256 }, async () => {
if (++authorizations === 2) { entered(); await gate; }
});
await waiting;
const second = executeWorkspaceTool(directory, "workspace_write", { path: "shared.txt", text: "second", expectedSha256: initial.sha256 }, authorize);
const observed = Promise.allSettled([first, second]);
release();
const results = await observed;
expect(results[0].status).toBe("fulfilled");
expect(results[1]).toMatchObject({ status: "rejected", reason: expect.objectContaining({ message: "runner_workspace_write_conflict" }) });
expect(await readFile(join(directory, "shared.txt"), "utf8")).toBe("first");
});
it.skipIf(!workspaceCommandSandboxAvailable())("runs useful commands but denies files outside the workspace and injected credentials", async () => {
const directory = await root(), outside = await root();
const secret = join(outside, "private.txt"); await writeFile(secret, "PRIVATE");
const success = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/sh", args: ["-c", "printf hello > output.txt; printf '%s' \"${PAPERCLIP_SECRETS_MASTER_KEY-unset}\"" ] }, authorize);
expect(success).toMatchObject({ exitCode: 0, output: "unset", stopped: null });
expect(await readFile(join(directory, "output.txt"), "utf8")).toBe("hello");
const read = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/cat", args: [secret] }, authorize);
expect(read).toMatchObject({ exitCode: 1 }); expect(String((read as any).output)).not.toContain("PRIVATE");
const write = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/sh", args: ["-c", 'printf stolen > "$1"', "sh", secret] }, authorize);
expect(await readFile(secret, "utf8")).toBe("PRIVATE");
expect(write).toMatchObject({ stopped: null, exitCode: expect.any(Number) }); expect((write as { exitCode: number }).exitCode).not.toBe(0);
});
it.skipIf(!workspaceCommandSandboxAvailable())("stops its owned process on authority loss and bounds output", async () => {
const directory = await root(); let calls = 0;
const result = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/sleep", args: ["20"] }, async () => { if (++calls > 2) throw new Error("revoked"); });
expect(result).toMatchObject({ stopped: "authority_revoked" });
const large = await executeWorkspaceTool(directory, "workspace_run", { program: "/bin/sh", args: ["-c", "yes x | head -c 50000"] }, authorize) as any;
expect(large.truncated).toBe(true); expect(Buffer.byteLength(large.output)).toBeLessThanOrEqual(24000);
});
it("reads only a pinned skill file and detects tampering", async () => {
const bundle = await materializeAsset([{ path: "SKILL.md", content: Buffer.from("# Assigned skill\nUse the pinned instructions."), mode: 0o444 }]);
const context = { skills: [{ key: "assigned", runtimeName: "assigned", versionId: "version-1", bundle }] } as any;
expect(await readAssignedSkill(context, { skill: "assigned" })).toMatchObject({ versionId: "version-1", text: "# Assigned skill\nUse the pinned instructions." });
await expect(readAssignedSkill(context, { skill: "not-assigned" })).rejects.toThrow("not_assigned");
await expect(readAssignedSkill(context, { skill: "assigned", path: "../private" })).rejects.toThrow();
await expect(readAssignedSkill(context, { skill: "assigned", path: "not-pinned.txt" })).rejects.toThrow("not_pinned");
await expect(readAssignedSkill({ ...context, skills: [{ ...context.skills[0], bundle: { ...bundle, manifestDigest: createHash("sha256").update("different").digest("hex") } }] }, { skill: "assigned" })).rejects.toThrow("manifest_digest");
});
it("settles missing-file reads without disclosing host paths or leaving an unknown effect", async () => {
const directory = await root();
const result = await settleRunnerBridgeRead(() => executeWorkspaceTool(directory, "workspace_read", { path: "missing.txt" }, authorize));
expect(result).toMatchObject({ outcome: "failed", code: "runner_bridge_file_not_found" });
expect(JSON.stringify(result)).not.toContain(directory);
expect(await settleRunnerBridgeRead(async () => { throw new Error("runner_skill_file_not_pinned"); })).toMatchObject({ outcome: "failed", code: "runner_skill_file_not_pinned" });
});
it("advertises only available tools in the current work mode", () => {
const tools = runnerBridgeDefinitions({ workspace: false, skills: false, api: false, mode: "ask" }).map(tool => tool.name);
expect(tools).toEqual(["get_identity", "list_people"]);
expect(runnerBridgeDefinitions({ workspace: true, skills: true, api: true, mode: "planning" }).map(tool => tool.name)).not.toContain("workspace_run");
});
});