docs: document sandbox ssh tests

steipete · steipete · commit 3d168074b473 · 2026-06-04T16:41:43.000-04:00
diff --git a/src/agents/sandbox/context.user-fallback.test.ts b/src/agents/sandbox/context.user-fallback.test.ts
@@ -1,3 +1,5 @@
+// Sandbox user fallback tests cover docker.user resolution from explicit config
+// or workspace ownership.
 import { describe, expect, it } from "vitest";
 import { resolveSandboxDockerUser } from "./context.js";
 import type { SandboxDockerConfig } from "./types.js";
diff --git a/src/agents/sandbox/fs-bridge.backend.e2e.test.ts b/src/agents/sandbox/fs-bridge.backend.e2e.test.ts
@@ -1,3 +1,5 @@
+// Local backend fs bridge E2E tests run generated backend shell scripts against
+// a real temp workspace without Docker.
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -12,6 +14,8 @@ import type {
 async function runLocalShellCommand(
   params: SandboxBackendCommandParams,
 ): Promise<SandboxBackendCommandResult> {
+  // This backend shim executes the exact shell script the fs bridge emits, so
+  // failures prove the generated POSIX script rather than a mocked Docker call.
   return await new Promise<SandboxBackendCommandResult>((resolve, reject) => {
     const child = spawn(
       "sh",
diff --git a/src/agents/sandbox/fs-bridge.shell.test.ts b/src/agents/sandbox/fs-bridge.shell.test.ts
@@ -1,3 +1,5 @@
+// Sandbox fs bridge shell tests cover POSIX shell compatibility, path
+// canonicalization, bind reads, and pinned mutation helpers.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
@@ -144,6 +146,8 @@ describe("sandbox fs bridge shell compatibility", () => {
   });
 
   it("writes via temp file + atomic rename (never direct truncation)", async () => {
+    // Writes must go through the Python mutation helper so validation and
+    // atomic replacement happen together inside the sandbox.
     const bridge = createSandboxFsBridge({ sandbox: createSandbox() });
 
     await bridge.writeFile({ filePath: "b.txt", data: "hello" });
diff --git a/src/agents/sandbox/fs-bridge.test-helpers.ts b/src/agents/sandbox/fs-bridge.test-helpers.ts
@@ -1,3 +1,5 @@
+// Shared fs bridge test helpers install Docker/path-safety mocks and provide
+// seeded sandbox fixtures for boundary and shell tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -77,6 +79,8 @@ const DOCKER_SCRIPT_INDEX = 5;
 const DOCKER_FIRST_SCRIPT_ARG_INDEX = 7;
 
 export function getDockerScript(args: string[]): string {
+  // docker exec argv positions are stable in fs bridge tests; helpers keep
+  // script assertions readable across many call sites.
   return args[DOCKER_SCRIPT_INDEX] ?? "";
 }
 
diff --git a/src/agents/sandbox/ssh-backend.test.ts b/src/agents/sandbox/ssh-backend.test.ts
@@ -1,3 +1,5 @@
+// SSH sandbox backend tests cover runtime description/removal, remote seeding,
+// command execution, bind validation, and backend config plumbing.
 import os from "node:os";
 import path from "node:path";
 import {
@@ -73,6 +75,8 @@ function requireMockRecordArg(mock: ReturnType<typeof vi.fn>, callIndex: number,
 }
 
 function requireSshRunCommandParams(callIndex = 0) {
+  // Backend assertions inspect the normalized remote command params before the
+  // ssh helper turns them into argv.
   return requireMockRecordArg(sshMocks.runSshSandboxCommand, callIndex, "ssh run command params");
 }
 
diff --git a/src/agents/sandbox/ssh.spawn-env.test.ts b/src/agents/sandbox/ssh.spawn-env.test.ts
@@ -1,3 +1,5 @@
+// SSH spawn-env tests ensure subprocesses inherit only safe environment values
+// while command execution and uploads run through ssh.
 import type { ChildProcess, SpawnOptions } from "node:child_process";
 import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
@@ -48,6 +50,8 @@ function mockSuccessfulSpawnCalls(times = 1) {
 }
 
 function spawnOptionsAt(index: number): SpawnOptions {
+  // Secret filtering happens at the child_process.spawn boundary, so tests read
+  // the captured SpawnOptions env directly.
   const options = spawnMock.mock.calls[index]?.[2] as SpawnOptions | undefined;
   if (!options) {
     throw new Error(`expected spawn options for call ${index}`);
diff --git a/src/agents/sandbox/ssh.test.ts b/src/agents/sandbox/ssh.test.ts
@@ -1,3 +1,5 @@
+// SSH sandbox helper tests cover temp auth materialization, remote command
+// validation, shell quoting, and upload symlink safety.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -29,6 +31,8 @@ afterEach(async () => {
 
 describe("sandbox ssh helpers", () => {
   it("materializes inline ssh auth data into a temp config", async () => {
+    // Inline key/cert/known-host material is written to private temp files and
+    // referenced from the generated ssh config.
     const session = await createSshSandboxSessionFromSettings({
       command: "ssh",
       target: "peter@example.com:2222",
diff --git a/src/agents/test-helpers/agent-tools-sandbox-context.test.ts b/src/agents/test-helpers/agent-tools-sandbox-context.test.ts
@@ -1,3 +1,5 @@
+// Agent-tools sandbox context tests keep shared sandbox fixture defaults and
+// override behavior stable for tool tests.
 import { describe, expect, it } from "vitest";
 import { createAgentToolsSandboxContext } from "./agent-tools-sandbox-context.js";
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Sandbox user fallback tests cover docker.user resolution from explicit config`
	`2`	`+// or workspace ownership.`
`1`	`3`	`import { describe, expect, it } from "vitest";`
`2`	`4`	`import { resolveSandboxDockerUser } from "./context.js";`
`3`	`5`	`import type { SandboxDockerConfig } from "./types.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// SSH sandbox backend tests cover runtime description/removal, remote seeding,`
	`2`	`+// command execution, bind validation, and backend config plumbing.`
`1`	`3`	`import os from "node:os";`
`2`	`4`	`import path from "node:path";`
`3`	`5`	`import {`
`@@ -73,6 +75,8 @@ function requireMockRecordArg(mock: ReturnType<typeof vi.fn>, callIndex: number,`
`73`	`75`	`}`
`74`	`76`
`75`	`77`	`function requireSshRunCommandParams(callIndex = 0) {`
	`78`	`+ // Backend assertions inspect the normalized remote command params before the`
	`79`	`+ // ssh helper turns them into argv.`
`76`	`80`	`return requireMockRecordArg(sshMocks.runSshSandboxCommand, callIndex, "ssh run command params");`
`77`	`81`	`}`
`78`	`82`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Agent-tools sandbox context tests keep shared sandbox fixture defaults and`
	`2`	`+// override behavior stable for tool tests.`
`1`	`3`	`import { describe, expect, it } from "vitest";`
`2`	`4`	`import { createAgentToolsSandboxContext } from "./agent-tools-sandbox-context.js";`
`3`	`5`