fix: enforce a ruleset's paths, unify stop, serve workspace bytes, and let an operator change the ceilings

[DEENUU1]

Closes #95, #96, #97, #98 — the four open issues, one commit each.

#97 — a ruleset's per-path rules reached nothing

A PermissionRuleset handed to ConsoleCapability reached requires_approval (the approval flags) and _denied_tools (drop a tool whose operation defaults to deny). Nothing read OperationPermissions.rules. So the shape a caller writes when they want "allow the workspace, deny credentials and the system tree" was no enforcement at all:

read_file  /.env            -> 'OPENAI_API_KEY=sk-live-secret'
read_file  /etc/passwd      -> 'root:x:0:0'
write_file /sub/.env        -> 'Wrote 1 lines to /sub/.env'
grep       PASSWORD         -> matched /credentials.txt, with the line

Which is worse than rejecting the ruleset, because it looks like a working boundary. PermissionChecker answered correctly the whole time; it was never asked.

PermissionGuard has been here since LocalBackend needed it and only LocalBackend ever used it. GuardedBackend puts it on any backend, applied in backend_for — the one place every tool resolves its backend, which is what makes the cover total rather than a list somebody has to remember to extend. guarding returns the backend untouched when there is no ruleset or when it enforces one of its own, so every existing caller behaves exactly as before.

grep_raw is filtered rather than refused: GrepMatch carries the matching line, so an unfiltered grep hands over the contents of the very files the rules protect. ls/glob filter on their own rules and deliberately not on read, matching LocalBackend — documented, with a test pinning it.

Two things found writing it:

• command_path_targets resolved a path before matching, and resolve() follows symlinks — so on macOS /etc/passwd became /private/etc/passwd and a rule reading /etc/** matched nothing. Any symlinked directory does the same anywhere. Both forms are matched now, which can only deny more.
• execute is reached through __getattr__ rather than declared. The toolset asks hasattr(backend, "execute") to decide whether to answer "Backend does not support command execution"; a declared method would make that true for a StateBackend, turning a friendly answer into a raise.

#98 — stop had three signatures

RemoteSandbox.stop(purge=False), DockerSandbox.stop(remove=False), and DaytonaSandbox.stop() / KubernetesPodSandbox.stop() / BaseSandbox.stop() taking nothing. A caller holding "a sandbox" could not call it:

TypeError: DaytonaSandbox.stop() got an unexpected keyword argument 'purge'

Quiet in the worst place — teardown sits in a broad except, so the call that should have released the resource was the one that raised. In AgenticOS that meant a Daytona sandbox was never deleted on any path, once per run, on the customer's own cloud account.

purge everywhere, defaulting to False everywhere — the default matters as much as the name, since stop() is what a turn ending calls and must not discard files the next turn expects. Daytona and Kubernetes accept it and document that it makes no difference to them.

Not breaking: stop() works everywhere it did, and DockerSandbox.stop(remove=...) still works and warns. test_sandbox_stop_contract.py asserts the shape, so a backend added later fails the moment it invents a fourth spelling.

#96 — the archive could only read text

WorkspaceArchive.read returns str, so a chart, a rendered PDF or an image came back decoded and re-encoded: a corrupt file that downloads successfully, which is worse than an error. Consumers had to allowlist text suffixes and refuse everything an agent is most likely to have produced — so the container backend, the one you would use for real work, was the one whose outputs could not be fetched.

read_bytes on the client, POST /workspaces/{id}/read_bytes on the service, reusing the ReadBytesRequest/ReadBytesResponse pair the live-session route already had. The service's max_read_bytes still applies, and that is the ceiling that matters: it returns a whole file. Tests cover the issue's own criterion (first four bytes \x89PNG) plus the two refusals worth having on a route that reads the host volume — a path escaping the workspace, and a file over the ceiling.

#95 — no way to change the ceilings without a restart

Both shapes the issue offered, because they answer different questions. PUT /policy is what an operator screen sits on; SANDBOXD_POLICY_OVERRIDES is the same thing for a deployment that would rather not expose a write endpoint.

One source of truth with two entrances, not two paths. Both call apply_policy_update — the only place that validates, the only place that writes. Two implementations of "what may change" would drift, and the one that drifted wider would be the security hole.

Ceilings and lifetimes are writable. The refusals are the point:

Refused	Because
runtimes membership	Adding an alias means naming an image
network_mode	host is not a ceiling, it is an escape
oci_runtime	The same, one level lower
sandbox_uid	0 is root
work_dir	Where the workspace volume mounts and the archive reads
persist_containers, prewarm	Startup shape, not ceilings

CreateSessionRequest carries no container settings because a process holding the Docker socket can start a privileged container that mounts the host, and that reasoning does not stop applying because the caller holds the service token: the token is held per tenant by an application, and an organization's administrator is not the person who runs the host.

extra="forbid", so one of those is a 422 naming the field rather than a key quietly dropped. An unknown alias is a 400 — refused, never created. Absent means "leave it alone", because None is meaningful for most of these and a model that could not tell absent from null would wipe a ceiling every time somebody changed a different one.

A change applies to the next sandbox; Docker sets the ceiling on the container, so one already resident keeps what it was created with. Documented rather than worked around.

A malformed overrides file is logged and ignored — an operator who mistypes a ceiling should get a log line, not a daemon that will not boot and takes every resident sandbox with it. A deleted one is left alone rather than reverted, since reverting means keeping a second copy of the environment's values.

Verified

1664 tests pass, 100% coverage, ruff, pyright and mypy all clean.

Worth saying where the verification reaches and where it does not: the remote tests drive the real ASGI app through TestClient, so the routes, the wire models and the archive are exercised for real. The Docker and Daytona paths are fakes, as they were before — test_sandbox_stop_contract.py is written against the real classes' signatures precisely because a fake cannot catch a signature drift.

Three things deliberately not done:

• runtimes membership stays read-only. The issue asked for "the runtime allowlist and per-alias ceilings", and the allowlist cannot be writable without letting a caller name an image — which the same issue asks to reject. Ceilings per alias are writable; the aliases are not.
• ls/glob still show the name of a file whose contents are denied. Changing that is a behaviour change for LocalBackend too, and a listing that hid a file exists reports would send an agent rewriting one it cannot read.
• Commands are not filtered by pattern. execute_denial_reason catches path arguments, and that is defence in depth — real isolation is the container's.