SandboxExecutionGuard

Pluggable concurrency guard for sandbox execution slots.

A guard controls how many concurrent executions are allowed for a given SandboxIsolationKey. The default #noop() imposes no restriction, preserving existing behaviour.

This extension point is primarily useful for IsolationScope#USER, IsolationScope#AGENT and IsolationScope#GLOBAL scopes, where multiple concurrent callers could otherwise race on the same persistent state slot (last write wins). Providing a guard serialises such callers without requiring changes to the surrounding infrastructure.

Implementations may use any backend — JVM semaphores, Redis SET NX leases, ZooKeeper, database advisory locks, etc. — and must be thread-safe.

Usage

`SandboxExecutionGuard guard = key -> {
redisClient.set(key.toString(), token, SetArgs.Builder.nx().px(30_000));
return () -> redisClient.eval(LUA_RELEASE_SCRIPT, key.toString(), token);
};

HarnessAgent.builder()
.filesystem(new DockerFilesystemSpec()
.isolationScope(IsolationScope.AGENT)
.executionGuard(guard))
...
.build();
`

Lifecycle

The harness calls #tryEnter before sandbox acquire/resume and closes the returned SandboxLease after SandboxManager#release completes, so the guard covers the full call window: acquire → start → (call) → stop → release → lease.close().