## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Ephemeral web servers must preserve native Runner sessions before
removing local storage.
> - Legacy session imports validate the workspace and saved provider
authority.
> - A protocol lease can retain a logical workspace ID while copy-back
uses a separate physical sandbox lease ID.
> - Comparing these different IDs blocks valid legacy sessions during
enrollment.
> - This pull request checks the workspace binding, retains the full
saved protocol identity check, and bounds checkpoint inserts inside the
owner transaction.
> - Existing sessions can migrate without changing their identity or
discarding files.
## Linked Issues or Issue Description
Refs #18943 and #18841.
**What happened?**
The first full staging enrollment stopped with
`native_controller_migration_artifact_binding`. A successful native
session had valid controller and provider-pack identities, but its
physical sandbox lease had a different ID.
**Expected behavior**
Import the original session when its workspace and saved provider
authority match. Reject foreign workspaces and protocol identities.
**Steps to reproduce**
Create a retained session whose sync record points to the execution
workspace and a separate physical lease. Run the offline controller
migration. The prior comparison rejects this valid record.
**Paperclip version or commit**
Reproduced on `84aa989bf9d08fc005ac273c37f9e1d860a4db25`.
**Deployment mode**
Docker with external PostgreSQL and shared object storage.
## What Changed
- Compare the sync record's workspace ID with the frozen execution
workspace.
- Keep the full saved provider-pack check for company, agent, workspace,
session, Runner, protocol lease, remote path, and provider digest.
- Use distinct physical and protocol IDs in the database-backed
migration fixture. Reject a foreign workspace and a changed protocol
lease before any checkpoint import.
- Limit migration inserts to 64 records and about 512 KiB of serialized
rows per statement. Send a larger individual record alone. Keep all
statements in the same transaction.
- Verify that a conflict in a later batch rolls back earlier batches,
then import and decrypt the complete checkpoint.
- Record both live failures and the comparison evidence in the
preservation plan.
## Verification
- The updated fixture failed on the original comparison and passes with
this fix.
- Targeted migration, controller recovery, and provider authority tests:
39 passed.
- Full repository typecheck and the latest server typecheck passed
locally. The complete PR workflow passed on `a1f3637c96` (run
41827558125), including build and test gates. The Docker Compose setup
download failed once before the test step; its infrastructure retry
passed. A separate full local test/build run is still in progress.
- A read-only staging preflight inspected 807 selected legacy sessions.
It found zero mismatches under the corrected workspace and full
saved-provider checks.
- A single 538-record, 2.2 MB checkpoint insert repeatedly closed the
live database connection on pooled and direct endpoints. A
forced-rollback comparison imported the identical checkpoint with
batches of 64. An unbatched control failed again after cache warm-up.
The exact server-side disconnect cause remains unknown; all failed
receipts are retained.
- The original failed enrollment and volume are retained. The corrected
importer committed 32 additional sessions and 2,982 checkpoint records.
Full import and deploy handoff remain pending while memory use is
investigated.
## Risks
The import checks durable session authority. A weaker identity check
could import the wrong session. This change retains the saved provider
authority validation and adds an explicit foreign-protocol rejection
test. Batching adds statements for large imports, but a late failure
still rolls back the complete owner transaction. It does not rewrite
session identity, change provider lifecycle, or detach any volume.
## Model Used
OpenAI Codex, GPT-6 family, with reasoning, tool use, and code
execution. The exact deployment model ID and context window are not
exposed in this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
