Python: Preserve checkpoint ancestry when workflows resume from storage

[davidahmann]

Resumed workflows can lose deterministic checkpoint ancestry after a process restart, which makes replay artifacts harder to audit and compare.

Current behavior is insufficient because the runner restores _iteration from the checkpoint, but resumed runs restart checkpoint creation with previous_checkpoint_id = None, so newly created checkpoints can break the saved chain even when execution resumes correctly.

Why now: Agent Framework explicitly markets durable, checkpointed workflows across restarts, so checkpoint lineage needs to stay intact when a run resumes.

Claim-to-codepath map:

• Resume and checkpoint sequencing in python/packages/core/agent_framework/_workflows/_runner.py
• Workflow run entrypoints in python/packages/core/agent_framework/_workflows/_workflow.py
• Checkpoint model/serialization in python/packages/core/agent_framework/_workflows/_checkpoint.py
• Durable workflow docs in docs/features/durable-agents/README.md

Requested behavior:

• After restoring from checkpoint N, the first new checkpoint created by the resumed run should point back to N through previous_checkpoint_id.
• Repeated resume-from-same-checkpoint runs should preserve the same ancestry contract.

Evidence Packet

• Commit under test: 1b7668119d47
• Runtime environment:
  • OS: Darwin 25.3.0 arm64
  • Python: 3.14.0
  • uv: 0.8.19
• Minimal repro:
  1. Build a checkpointed workflow with at least two supersteps.
  2. Run it once and capture an intermediate checkpoint ID.
  3. Start a fresh workflow instance, resume from that checkpoint, and inspect newly created checkpoints.
• Expected behavior: resumed checkpoints continue the existing previous_checkpoint_id chain.
• Actual behavior: the restored checkpoint lineage can be broken on the first resumed checkpoint.

Acceptance Criteria

• Preserve previous_checkpoint_id continuity after resume.
• Add focused regression coverage that resumes from stored checkpoints and verifies ancestry on newly created checkpoints.
• Keep the fix scoped to the checkpoint sequencing contract.

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

Repro: Runner.run_until_convergence() in python/packages/core/agent_framework/_workflows/_runner.py always sets local previous_checkpoint_id = None (line ~72), ignoring the checkpoint restored via restore_from_checkpoint(). The _mark_resumed() helper (line ~227) stores only iteration count. Minimal repro: call runner.restore_from_checkpoint(some_id, checkpoint_storage=storage), inject a message, call run_until_convergence(), and observe the first new checkpoint has previous_checkpoint_id=None instead of some_id.

• Failing test: python/packages/core/tests/workflow/test_checkpoint_ancestry_bug.py
• Files examined: python/packages/core/agent_framework/_workflows/_runner.py, python/packages/core/agent_framework/_workflows/_checkpoint.py, python/packages/core/tests/workflow/test_runner.py
• Tests run: python/packages/core/tests/workflow/test_checkpoint_ancestry_bug.py::test_checkpoint_ancestry_preserved_after_resume
• Current version: 1.9.0