[bugfix]: add presuspend sanity check and fix a bug in retry

[zhongkechen]

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Issue Link, if available

Fixes #291

Description

Just before go suspend, we do sanity check to make sure:

• it's not suspended more than once
• there is at least one operation pending completion, otherwise, the backend will throw an exception

This change is to help us detect possible issues with suspend in our test cases, not to prevent them.

bug fix in runUserHandler

Found a bug in runUserHandler with the additional check.

The future was completed but the step was not retried because the following check in runUserHandler failed.

        if (runningUserHandler.get() != null) {
            throw new IllegalStateException("User handler already running");
        }

For a failed operation that is polling in the background, the runningUserHandler is already set. The exception thrown from here was swallowed because it's chained to a future.

The fix is not only checking if it's null, but also check if it's done and the execution will be terminated if it's not null and not done, meaning a user function is still running.

Demo/Screenshots

Checklist

• I have filled out every section of the PR template
• I have thoroughly tested this change

Testing

Unit Tests

Have unit tests been written for these changes?

Integration Tests

Have integration tests been written for these changes?

Examples

Has a new example been added for the change? (if applicable)

[zhongkechen]

With this change we found a bug in Step operation: #295

[zhongkechen]

The retry example still failing: https://github.com/aws/aws-durable-execution-sdk-java/actions/runs/23824927742/job/69445906795

The step operation failed at 45.429 second

{
    "@timestamp": "2026-04-02T16:40:45.429Z",
    "ecs.version": "1.2.0",
    "log.level": "WARN",
    "message": "Async operation failing on attempt 1",
    "process.thread.name": "durable-exec-16",
    "log.logger": "software.amazon.lambda.durable.examples.step.RetryInProcessExample"
}

the polling request properly made afte ~1 second

{
    "@timestamp": "2026-04-02T16:40:46.848Z",
    "ecs.version": "1.2.0",
    "log.level": "DEBUG",
    "message": "Calling durable checkpoint API with 0 updates: []",
    "process.thread.name": "durable-sdk-internal-1",
    "log.logger": "software.amazon.lambda.durable.execution.CheckpointManager"
}

And the response contains the READY operation

NewExecutionState=CheckpointUpdatedExecutionState(Operations=[Operation(Id=6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b, Name=flaky-async-operation, Type=STEP, StartTimestamp=2026-04-02T16:40:45.700Z, Status=READY, StepDetails=StepDetails(Attempt=1, Error=ErrorObject(ErrorMessage=*** Sensitive Data Redacted ***, ErrorType=*** Sensitive Data Redacted ***, ErrorData=*** Sensitive Data Redacted ***, StackTrace=*** Sensitive Data Redacted ***)))])).

The poller future was completed

{
    "@timestamp": "2026-04-02T16:40:46.904Z",
    "ecs.version": "1.2.0",
    "log.level": "DEBUG",
    "message": "1 operations processed and 1 pollers completed (latency=625002ns). ",
    "process.thread.name": "durable-sdk-internal-1",
    "log.logger": "software.amazon.lambda.durable.execution.CheckpointManager"
}

The future was completed but the step was not retried because the following check in runUserHandler failed.

        if (runningUserHandler.get() != null) {
            throw new IllegalStateException("User handler already running");
        }

For a failed operation that is polling in the background, the runningUserHandler is already set. The exception thrown from here was swallowed because it's chained to a future.

[wangyb-A]

Can we have a test case for this bug fix?

[zhongkechen]

Can we have a test case for this bug fix?

The new validation logic added in this PR caused existing cases to fail. No extra test case required.