fix: post_rollout IndexError and missing completion (fixes #726)

[gspeter-max]

Summary

Fixes #726 - post_rollout can crash with IndexError when trajectory is empty and does not have access to completion field.

Root Cause

1. post_rollout runs as a cleanup handler (via @vf.cleanup) BEFORE state["completion"] is set
2. When trajectory is empty (e.g., environment errors before any turns), accessing state["trajectory"][-1] raises IndexError
3. Inconsistent API: rubrics can access completion but cleanup handlers cannot

Changes

1. Code Changes

• verifiers/envs/sandbox_env.py: Added comprehensive docstring + error handling wrapper in destroy_sandbox
• verifiers/envs/experimental/cli_agent_env.py: Added error handling wrapper in destroy_sandbox

2. Tests

• tests/test_post_rollout_safety.py (NEW): 5 comprehensive test cases
  • Empty trajectory handling
  • Missing trajectory key handling
  • Cleanup with empty trajectory
  • Error handling in destroy_sandbox
  • Custom post_rollout with trajectory access
• tests/test_multiturn_env.py: Added test for early error scenarios

3. Documentation

• docs/environments.md: Added "Cleanup Handlers and post_rollout" section with:
  • Execution order explanation
  • Available state data
  • Safe trajectory access patterns
  • Practical examples

Test Results

All 25 tests passed ✅
- test_post_rollout_safety.py: 5/5 passed
- test_multiturn_env.py: 18/18 passed  
- test_sandbox_env.py: 2/2 passed

Impact

• ✅ Rollouts no longer crash when environment errors occur before any trajectory steps
• ✅ Environment designers have clear guidance on safe post_rollout patterns
• ✅ Consistent error handling across all cleanup handlers
• ✅ Comprehensive test coverage prevents regression
• ✅ Backward compatible - no breaking changes

Checklist

• Implementation complete
• Tests added and passing
• Documentation updated
• No over-engineering
• Follows project conventions

Refs: #726

---

Note

Low Risk
Small, backward-compatible robustness change limited to cleanup paths plus tests/docs; main behavior change is swallowing post_rollout exceptions to ensure sandbox deletion continues.

Overview
Prevents rollout teardown from crashing when an environment errors before any turns by wrapping post_rollout execution in destroy_sandbox (both SandboxEnv and CliAgentEnv) and logging failures while still deleting the sandbox.

Adds regression coverage for empty/missing state["trajectory"] and early-setup failures, plus documentation clarifying that @vf.cleanup handlers (including post_rollout) run before state["completion"] is set and showing safe trajectory access patterns for environment authors.

^{Written by Cursor Bugbot for commit 6bb1480. This will update automatically on new commits. Configure here.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[gspeter-max]

Thanks for the feedback @cursor[bot]! I've updated the file to include the new cleanup handler and post_rollout guidance.

The changes include:

• Critical execution order documentation (cleanup runs BEFORE completion)
• Safe post_rollout implementation examples
• Available state data in cleanup handlers
• Safe trajectory access patterns
• Reference to full documentation in docs/environments.md

This ensures users following the skill will get proper cleanup handler patterns.