[pengmoubuaixuexi]

AgentScope-Java Version

2.1.0-SNAPSHOT, based on main c416c378e0b4c1f4849bf75d66084c00bff62cef.

Description

Fixes #3595.

When snapshot restoration opens an archive and doSetupWorkspace() subsequently throws, AbstractBaseSandbox.start() currently never closes that stream: setup runs before the try-with-resources block. This affects both lost-workspace recovery and initial snapshot restoration.

Move setup inside the existing resource scope in both branches, retaining setup-before-hydration ordering. Add parameterized regressions through the public start() method for both branches, verifying stream closure, unchanged failure state, no hydration after failed setup, and preservation of the setup exception when closing also throws. Update the matching English and Chinese sandbox docs.

Validation

Latest test-only update: 31 focused tests pass (6 snapshot cleanup + 23 pending-tool recovery + 2 run-id chain). Local JaCoCo 0.8.14 records both changed production lines 90 and 108 as covered (mi=0, ci=2 each). The original exception-only cases reached setup but left these invocation lines unmarked; the successful restoration cases close that coverage gap.

Initial CI: Ubuntu, license, docs and module sync passed. Windows failed on three 10-second blocking timeouts in SubagentPendingToolRecoveryTest and SubagentRunIdChainTest; the four cleanup regressions passed there. The affected 25 subagent tests passed in both local follow-up runs. The remote timeout root cause is not established; the new commit starts fresh CI.

• Regression on original production code: 4 tests, 4 failures (archive close() never called), 0 errors.
• With the fix: all 4 regression cases pass. The follow-up adds 2 successful-restore cases to assert setup -> hydration -> close ordering and ready/running state; all 6 now pass.
• On the initial patch (48410b7), all 161 Harness *Test.java classes selected explicitly: 1,249 tests, 0 failures/errors, 18 skipped (1,231 passed). The skips remain reported; this is not a full-repository test run.
• Existing E2bSandboxRecoveryTest: 8 passed.
• Spotless and git diff --check: pass.
• Documentation link check reports 2,208 broken links in 326 files on both original main docs and the patch; the reported entries match. No links are added by this change.
• Documentation: 13 tests pass; npm run validate passes, including 430 pages / 584 redirects and Mint build validation.

Commands (PowerShell; Java 17, Maven 3.9.12):

mvn -B -T1 -pl agentscope-harness -am '-Dtest=AbstractBaseSandboxSnapshotCleanupTest' '-Dsurefire.failIfNoSpecifiedTests=false' spotless:apply test
$classes = (Get-ChildItem agentscope-harness/src/test -Recurse -Filter '*Test.java' | ForEach-Object BaseName) -join ','
mvn -B -T1 -pl agentscope-harness -am "-Dtest=$classes" '-Dsurefire.failIfNoSpecifiedTests=false' test
mvn -B -T1 -pl agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b -am '-Dtest=E2bSandboxRecoveryTest' '-Dsurefire.failIfNoSpecifiedTests=false' test

AI assistance (Codex) was used for source review, implementation, and tests. Reproductions were executed locally and the final diff was checked against the surrounding code and stream-ownership contract.

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test) — relevant module checks are above; full repository and live-provider tests were not run
• Javadoc comments are complete and follow project conventions (no API changes)
• Related documentation has been updated
• Code is ready for review

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pengmoubuaixuexi]

Pushed 6255e7c to add successful restoration coverage for both snapshot branches, asserting setup -> hydrate -> close ordering and ready/running state. Production code is unchanged.

The four failure-path regressions passed on both CI platforms. Locally, I reproduced the coverage gap: JaCoCo marked the two setup invocation lines as mi=2, ci=0 when setup only threw. With the two successful-path cases, both lines are mi=0, ci=2. This is consistent with JaCoCo's documented handling of exceptions between probes: https://www.jacoco.org/jacoco/trunk/doc/flow.html (see Additional Probes Between Lines).

The Windows job failed on three 10-second blocking timeouts in SubagentPendingToolRecoveryTest and SubagentRunIdChainTest, not on the cleanup regressions. Both affected classes passed locally twice; the latest focused run totals 31 passed, 0 failures/errors/skips. This does not establish the remote timeout's root cause. The new push triggers fresh CI; I have not changed those tests or increased timeouts.