Skip to content

Commit 99f8d77

Browse files
fix(sandbox): preserve UnixLocal hardlink snapshots and validate before clearing (#5188)
* fix: preserve UnixLocal hardlink snapshots and validate before clearing * fix: access tar inode cache without platform-specific type suppression
1 parent 61e98ab commit 99f8d77

2 files changed

Lines changed: 191 additions & 16 deletions

File tree

‎src/agents/sandbox/sandboxes/unix_local.py‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@
7070
UnsafeTarMemberError,
7171
safe_extract_tarfile,
7272
should_skip_tar_member,
73+
validate_tarfile,
7374
)
7475
from ..workspace_paths import _raise_if_filesystem_root
7576
from . import _unix_local_file_ops
@@ -1148,19 +1149,17 @@ async def persist_workspace(self) -> io.IOBase:
11481149

11491150
def _archive_workspace() -> None:
11501151
with tarfile.open(fileobj=buf, mode="w") as tar:
1151-
tar.add(
1152-
root,
1153-
arcname=".",
1154-
filter=lambda ti: (
1155-
None
1156-
if should_skip_tar_member(
1157-
ti.name,
1158-
skip_rel_paths=skip,
1159-
root_name=None,
1160-
)
1161-
else ti
1162-
),
1163-
)
1152+
1153+
def filter_member(member: tarfile.TarInfo) -> tarfile.TarInfo | None:
1154+
# tarfile records inodes before filtering. Clear even excluded entries so
1155+
# every retained hardlink has its own payload. Unlike dereference=True,
1156+
# this preserves symlinks instead of reading their targets on the host.
1157+
getattr(tar, "inodes").clear() # noqa: B009 - Not exposed by typeshed.
1158+
if should_skip_tar_member(member.name, skip_rel_paths=skip, root_name=None):
1159+
return None
1160+
return member
1161+
1162+
tar.add(root, arcname=".", filter=filter_member)
11641163

11651164
try:
11661165
await run_blocking_workspace_io(_archive_workspace)
@@ -1170,6 +1169,32 @@ def _archive_workspace() -> None:
11701169
buf.seek(0)
11711170
return buf
11721171

1172+
async def _restore_snapshot_into_workspace_on_resume(self) -> None:
1173+
root = Path(self.state.manifest.root)
1174+
archive = await self.state.snapshot.restore(dependencies=self.dependencies)
1175+
1176+
def validate_archive() -> None:
1177+
try:
1178+
with tarfile.open(fileobj=archive, mode="r:*") as tar:
1179+
validate_tarfile(tar, allow_external_symlink_targets=False)
1180+
archive.seek(0)
1181+
except UnsafeTarMemberError as e:
1182+
raise WorkspaceArchiveWriteError(
1183+
path=root, context={"reason": e.reason, "member": e.member}, cause=e
1184+
) from e
1185+
except (tarfile.TarError, OSError) as e:
1186+
raise WorkspaceArchiveWriteError(path=root, cause=e) from e
1187+
1188+
try:
1189+
# Older snapshots may contain unsupported members. Reject them before discarding
1190+
# the live files; keep hydrate_workspace's own validation for direct callers too.
1191+
await run_blocking_workspace_io(validate_archive)
1192+
await self._clear_workspace_root_on_resume()
1193+
await self.hydrate_workspace(archive)
1194+
finally:
1195+
with suppress(Exception):
1196+
archive.close()
1197+
11731198
async def hydrate_workspace(self, data: io.IOBase) -> None:
11741199
root = Path(self.state.manifest.root)
11751200

‎tests/sandbox/test_unix_local.py‎

Lines changed: 153 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import asyncio
44
import contextlib
55
import io
6+
import os
67
import shutil
78
import signal
89
import tarfile
@@ -14,8 +15,8 @@
1415

1516
import pytest
1617

17-
from agents.sandbox import SandboxPathGrant
18-
from agents.sandbox.errors import PtySessionNotFoundError
18+
from agents.sandbox import LocalSnapshotSpec, SandboxPathGrant
19+
from agents.sandbox.errors import PtySessionNotFoundError, WorkspaceArchiveWriteError
1920
from agents.sandbox.manifest import Environment, Manifest
2021
from agents.sandbox.sandboxes import unix_local as unix_local_module
2122
from agents.sandbox.sandboxes.unix_local import (
@@ -24,7 +25,7 @@
2425
UnixLocalSandboxSessionState,
2526
_UnixPtyProcessEntry,
2627
)
27-
from agents.sandbox.snapshot import NoopSnapshot
28+
from agents.sandbox.snapshot import LocalSnapshot, NoopSnapshot
2829
from agents.sandbox.types import ExecResult, User
2930

3031

@@ -48,6 +49,155 @@ async def _exec_internal(
4849
return ExecResult(stdout=b"", stderr=b"", exit_code=0)
4950

5051

52+
@pytest.mark.asyncio
53+
@pytest.mark.parametrize("exclude_first", [False, True])
54+
async def test_unix_local_snapshot_round_trips_hardlinks(
55+
tmp_path: Path, exclude_first: bool
56+
) -> None:
57+
workspace = tmp_path / "workspace"
58+
client = UnixLocalSandboxClient(inherit_host_environment=False)
59+
session = await client.create(
60+
manifest=Manifest(root=str(workspace)),
61+
snapshot=LocalSnapshotSpec(base_path=tmp_path / "snapshots"),
62+
)
63+
await session.start()
64+
first = workspace / "a.py"
65+
second = workspace / "b.py"
66+
first.write_bytes(b"VALUE = 1\n")
67+
first.chmod(0o755)
68+
os.link(first, second)
69+
(workspace / "link.py").symlink_to("b.py")
70+
(workspace / "copy.py").write_bytes(b"independent\n")
71+
if exclude_first:
72+
session.register_persist_workspace_skip_path("a.py")
73+
await session.stop()
74+
archive = await session.state.snapshot.restore()
75+
try:
76+
with tarfile.open(fileobj=archive) as tar:
77+
members = {member.name: member for member in tar.getmembers()}
78+
assert members["./b.py"].isreg()
79+
assert members["./link.py"].issym()
80+
if exclude_first:
81+
assert "./a.py" not in members
82+
else:
83+
assert members["./a.py"].isreg()
84+
finally:
85+
archive.close()
86+
87+
# Prove that resume actually restores the snapshot, not the surviving workspace.
88+
second.write_bytes(b"changed after snapshot\n")
89+
(workspace / "stale.txt").write_bytes(b"remove on resume")
90+
resumed = await client.resume(session.state)
91+
try:
92+
await resumed.start()
93+
assert second.read_bytes() == b"VALUE = 1\n"
94+
assert second.stat().st_mode & 0o777 == 0o755
95+
assert (workspace / "copy.py").read_bytes() == b"independent\n"
96+
assert (workspace / "link.py").is_symlink()
97+
assert (workspace / "link.py").read_bytes() == b"VALUE = 1\n"
98+
assert not (workspace / "stale.txt").exists()
99+
if exclude_first:
100+
assert not first.exists()
101+
else:
102+
assert first.read_bytes() == b"VALUE = 1\n"
103+
assert first.stat().st_ino != second.stat().st_ino
104+
finally:
105+
await resumed.shutdown()
106+
await session.shutdown()
107+
108+
109+
@pytest.mark.asyncio
110+
@pytest.mark.parametrize("invalid_kind", ["hardlink", "external_symlink", "invalid_tar"])
111+
async def test_unix_local_resume_rejects_invalid_snapshot_before_clearing_workspace(
112+
tmp_path: Path, invalid_kind: str
113+
) -> None:
114+
workspace = tmp_path / "workspace"
115+
client = UnixLocalSandboxClient(inherit_host_environment=False)
116+
session = await client.create(
117+
manifest=Manifest(root=str(workspace)),
118+
snapshot=LocalSnapshotSpec(base_path=tmp_path / "snapshots"),
119+
)
120+
await session.start()
121+
(workspace / "keep.txt").write_bytes(b"live workspace")
122+
archive = io.BytesIO()
123+
if invalid_kind == "invalid_tar":
124+
archive.write(b"not a tar archive")
125+
else:
126+
with tarfile.open(fileobj=archive, mode="w") as tar:
127+
member = tarfile.TarInfo("link")
128+
member.type = tarfile.LNKTYPE if invalid_kind == "hardlink" else tarfile.SYMTYPE
129+
member.linkname = "keep.txt" if invalid_kind == "hardlink" else "../outside"
130+
tar.addfile(member)
131+
archive.seek(0)
132+
await session.state.snapshot.persist(archive)
133+
archive.close()
134+
135+
resumed = await client.resume(session.state)
136+
try:
137+
with pytest.raises(WorkspaceArchiveWriteError):
138+
await resumed.start()
139+
assert (workspace / "keep.txt").read_bytes() == b"live workspace"
140+
assert sorted(path.name for path in workspace.iterdir()) == ["keep.txt"]
141+
assert not await resumed.running()
142+
finally:
143+
await resumed.shutdown()
144+
await session.shutdown()
145+
146+
147+
@pytest.mark.asyncio
148+
async def test_unix_local_resume_cancellation_waits_for_archive_validation(
149+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
150+
) -> None:
151+
workspace = tmp_path / "workspace"
152+
client = UnixLocalSandboxClient(inherit_host_environment=False)
153+
session = await client.create(
154+
manifest=Manifest(root=str(workspace)),
155+
snapshot=LocalSnapshotSpec(base_path=tmp_path / "snapshots"),
156+
)
157+
await session.start()
158+
(workspace / "keep.txt").write_bytes(b"live workspace")
159+
await session.stop()
160+
archive = await session.state.snapshot.restore()
161+
started = threading.Event()
162+
release = threading.Event()
163+
events: list[str] = []
164+
validate = unix_local_module.validate_tarfile
165+
166+
async def restore(self: LocalSnapshot, **kwargs: object) -> io.IOBase:
167+
return archive
168+
169+
def slow_validate(tar: tarfile.TarFile, **kwargs: object) -> None:
170+
started.set()
171+
assert release.wait(timeout=5)
172+
validate(tar, allow_external_symlink_targets=False)
173+
events.append("validated")
174+
175+
monkeypatch.setattr(LocalSnapshot, "restore", restore)
176+
monkeypatch.setattr(unix_local_module, "validate_tarfile", slow_validate)
177+
resumed = await client.resume(session.state)
178+
task = asyncio.create_task(resumed.start())
179+
try:
180+
while not started.is_set():
181+
if task.done():
182+
await task
183+
pytest.fail("resume did not validate the archive")
184+
await asyncio.sleep(0.005)
185+
task.cancel()
186+
await asyncio.sleep(0)
187+
assert not task.done()
188+
assert not archive.closed
189+
release.set()
190+
with pytest.raises(asyncio.CancelledError):
191+
await task
192+
assert events == ["validated"]
193+
assert archive.closed
194+
assert (workspace / "keep.txt").read_bytes() == b"live workspace"
195+
finally:
196+
release.set()
197+
await resumed.shutdown()
198+
await session.shutdown()
199+
200+
51201
@pytest.mark.asyncio
52202
async def test_unix_local_inherits_host_environment_by_default(
53203
tmp_path: Path,

0 commit comments

Comments
 (0)