fix(sandbox): serialize same-key concurrent calls to prevent persisted state races

[larry-zy]

Closes #2845

Background

On a single HarnessAgent, two concurrent calls that resolve to the same SandboxIsolationKey read and write the same persisted sandbox state record.

The sandbox acquire → resume → persist → release window runs outside the delegate's serializeOnKey gate, and the sandbox-layer guard defaulted to noop() — so there was no serialisation. Both calls started independent containers from the same state, mutated them in parallel, and overwrote each other on completion: workspace changes are silently lost (last write wins), with a transient double-container in between.

This is not covered by #2490. That fix isolates the in-memory live binding for different-key concurrent calls; it does not stop same-key calls from racing on the persisted state.

Changes

• Add InProcessSandboxExecutionGuard (JVM-local default guard): serialises per SandboxIsolationKey, one fair Semaphore(1) per key. Semaphore rather than ReentrantLock because acquire happens in the reactive resource supplier and release in the corresponding cleanup, which may run on different threads — Semaphore is not thread-ownership bound.
• Flip the default guard from noop() to inProcess() (HarnessAgent): single-instance deployments serialise out of the box; multi-instance deployments can still supply a distributed guard via SandboxFilesystemSpec#executionGuard or a DistributedStore.
• Move sandbox acquire/release onto a boundedElastic thread: the guard now genuinely blocks (potentially for the full duration of a same-slot peer call), so it must never tie up a WebFlux event-loop thread and starve unrelated sessions.
• Release the lease in a finally (SandboxLifecycleMiddleware): lease.close() is guaranteed regardless of what persist/release throw, preventing a permit leak that would block every future same-slot call forever; also restores the interrupt flag cleared by InterruptedException.
• Add inProcess(Duration) as a backstop against a wedged holder, throwing SandboxExecutionTimeoutException on expiry. This is a wedged-holder backstop, not a contention timeout — set it well above the maximum realistic call duration.

Tests

• InProcessSandboxExecutionGuardTest — queued serialisation, timeout, no slot leak, cross-thread release.
• SandboxSameSessionSerializationTest — same-key concurrent calls no longer overwrite each other end-to-end.
• HarnessAgentSandboxOffThreadTest — acquire/release never run on the subscriber thread.

Deployment note

This guard coordinates within a single JVM only. When the same slot can be contended across multiple instances, supply a distributed implementation (e.g. Redis SET NX).

[codecov]

Codecov Report

❌ Patch coverage is 73.23944% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...s/agent/middleware/SandboxLifecycleMiddleware.java	40.00%	11 Missing and 1 partial ⚠️
.../agent/sandbox/InProcessSandboxExecutionGuard.java	88.09%	4 Missing and 1 partial ⚠️
.../io/agentscope/harness/agent/DistributedStore.java	0.00%	1 Missing ⚠️
...e/harness/agent/sandbox/SandboxExecutionGuard.java	50.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[muranchenhui]

LGTM

[muranchenhui]

LGTM

[guslegend0510]

LGTM