[tonicmuroq]

Part of simular-ai/box#60 (item 6).

• Refs written in the user's repo: refs/box/offload/<id>, refs/box/index/<id>, refs/box/pre-back/<id>, refs/box/box/*, fetched refs/box/back/<id>.
• A back that can't land cleanly goes to box/back-<time> instead of cocoonbox/back-<time>.
• Old refs/cocoonbox/* already in users' repos are left alone; nothing reads them.

Needs simular-ai/box#78 on the box image first: an older agent only knows refs/cocoonbox/offload/<id> and fails the snapshot check.

[chenchenSimular]

One blocking issue: a new client against a box on an older image fails with an unclear error.

Boxes don't upgrade their image on their own (upgrade is a rebase the user confirms), while the skill runs npx -y @simular-ai/box@^0.2.0, so every plugin user picks up a 0.2.x release right away. "Image first, then client" therefore doesn't prevent the mismatch; it will exist for weeks. Today offload sends only refs/box/offload/<id> (cli/src/offload/offloader.js:93) and the old agent fails with "refs/cocoonbox/offload/ is missing from the copy", which tells the user nothing.

Please either block it in the preflight with a clear "upgrade your box first" message, the way imageFinding (cli/src/offload/preflight.js:22-26) already gates older images (needs the first sbxdesk:vN that includes #78), or also write the legacy snapshot ref for older images.

[chenchenSimular]

Pushed 4e6c9ea to fix the old-image case from the review: a new client against a box still on an image from before simular-ai/box#78.

What changed

• Offload now also writes the snapshot under the old name, refs/cocoonbox/offload/<id>, so the old agent's check passes. The ref is deleted from the user's repo once the send finishes or fails, so only the box copy keeps it.
• Back fetches refs/box/back/<id> first. If that fails, it fetches the old refs/cocoonbox/back/<id> into the same local ref. If both fail, the error shows both reasons.
• Test: the fake agent has a FAKE_BOX_LEGACY mode that rejects a send with no refs/cocoonbox/offload/<id>, like the real old agent. A new e2e test runs offload and back against it and checks that no refs/cocoonbox/ ref is left in the user's repo. The test fails without the fix. npm test (66/66) and npm run lint pass.

Why this instead of a preflight gate on the image version
No image contains #78 yet (it is still open; prod default is sbxdesk:v11), so there is no version number to gate on yet. Sending the old name as well works on every image and needs no version check. Images with #78 read refs/box/ first and ignore the extra ref. Both the extra ref and the fallback can go once old images are retired.

[chenchenSimular]

Approving with 4e6c9ea: the client also sends the legacy snapshot ref and falls back to the legacy back ref, so a new client works against boxes on images from before simular-ai/box#78. Both can go once old images are retired.