fix(recovery): persist interrupted-run handoffs

[cryppadotta]

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work.
• The heartbeat service starts and tracks agent work.
• A server shutdown can interrupt a run after the task enters progress.
• The old recovery path did not persist the handoff decision or its outcome.
• This pull request records each interrupted-run handoff and reconciles it through one durable state machine.
• The user can now see queued, recovered, withheld, and exhausted recovery states with run and receipt evidence.

Linked Issues or Issue Description

Refs #9874

Refs #9552

Refs #7218

Related review: #10495

What Changed

• Add a company-scoped interrupted_run_handoffs table with durable status, owner, successor, action, and receipt data.
• Reconcile interrupted runs atomically during startup and shutdown recovery.
• Preserve wakeup receipt data when a wakeup response is incomplete.
• Add shared recovery contracts and issue read-model fields.
• Show recovery state, ownership, run links, and receipt evidence in the task UI and run ledger.
• Add recovery UX lab examples for desktop and mobile review.
• Document the interrupted-run handoff and reconciliation rules.
• Use database unique constraints for composite foreign keys so backup restore keeps dependency order.

Verification

• Run pnpm -r typecheck.
• Run pnpm build.
• Run pnpm check:token-gates.
• Run the changed server recovery tests. All 141 tests pass.
• Run the full UI project. All 3,752 tests pass.
• Run the server test project. All 3,786 tests pass and 4 tests skip.
• Run the embedded PostgreSQL worktree backup and restore regression test.

Risks

• This change adds one database table and two composite unique constraints.
• Migration generation and migration safety checks pass.
• The embedded PostgreSQL backup and restore test covers the new constraint dependency order.
• Recovery now creates durable records. The service uses a unique fingerprint and atomic updates to prevent duplicate handoffs.

For core feature work, check ROADMAP.md first and discuss it in #dev before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See CONTRIBUTING.md.

Model Used

• OpenAI Codex with gpt-5.6-sol. The agent used high-reasoning mode, tool use, code execution, and repository tests. The runtime did not expose the context window size.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have not referenced internal/instance-local Paperclip issues or links (only public GitHub #NNN / github.com/paperclipai/paperclip URLs)
• My branch name describes the change (e.g. docs/..., fix/...) and contains no internal Paperclip ticket id or instance-derived details
• I have run tests locally and they pass
• I have added or updated tests where applicable
• I have updated relevant documentation to reflect my changes
• I have considered and documented any risks above
• All Paperclip CI gates are green
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge

[cryppadotta]

@greptile review

[cryppadotta]

@greptile review

[cryppadotta]

@greptile review

[cryppadotta]

@greptile review

[cryppadotta]

@greptile review