[ranst91]

Motivation & Context

A native approval could replay from a durable AG-UI thread snapshot after backend restart but fail to resume with APPROVAL_RESUME_NOT_FOUND: the visible interrupt was persisted while server-owned approval authority was process-local.

This PR stacks on PNI-711 / #1 at bf82841e737aa617eb05414de4a4a68217fa5e05, using fix/ag-ui-snapshot-reconciliation as the review base. It is a local PNI-715 candidate, not an upstream merge or release request.

Description & Review Guide

• What are the major changes? Add explicit AgentFrameworkAgent(..., durable_approvals=True) recovery through private snapshot continuation state. Persist server-issued lifecycle records and middleware state; restore original occurrence/provider call identities, arguments, decisions, results, and retention ages. Commit a claim before a side effect; propagate claim-write failure. Cold unfinished claims become indeterminate instead of executable again.
• What is the impact of these changes? Default behavior stays process-local. Opt-in requires trusted scoped storage that atomically and durably commits the complete snapshot, plus application-owned single-writer serialization per thread. No cross-replica coordination or exactly-once completion across arbitrary crashes is claimed. Legacy replay-only snapshots remain non-resumable. SDK-only session serialization is separate; visible imported controls cannot establish adapter authority.
• What do you want reviewers to focus on? Authority isolation, scope/capacity checks, write-before-execute ordering, canonical results, and conservative crash recovery. Nine subprocess regressions cover real Agent/function-loop approve/decline, original identity/result replay, retries, failed claim/result writes, abrupt process exit inside the tool, replay/scope rejection, and separate SDK session restore. The focused endpoint/lifecycle/result suite totals 525 passing tests with existing deprecation warnings; Ruff, diff checks, and source/new-test Pyright pass. Parent validation now confirms original-call approval and denial after real backend restarts, imported pending approval after another restart and browser reload, exact canonical results once in native storage and Intelligence, cleared pending controls, and same-thread ordinary follow-up retaining historical context.

Readiness is scoped to this cold-approval fix and its PNI-711 prerequisite. Broader parity findings retain their separate owners. GitHub CI is not green: fork review/team/label automation lacks required GitHub tokens, and no Python build/test check appears in the rollup. Passing local tests and parent acceptance are separate evidence; this is not merge or release approval.

Related Issue

PNI-715, under PNI-706. This fork draft is explicitly authorized for the campaign; upstream maintainer agreement and submission are separate. PNI-711 is the prerequisite, not competing cold-resume work.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: implementation, regressions, source review, setup documentation, and PR description. Human campaign acceptance remains pending.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change.