Should promote snapshot the target itself instead of asking the user to pre-fork?

[mahirhir]

I went through the parallel-attempts transcript. The line I keep coming back to is the comment inside the demo itself, that promote wipes main's own checkpoint history, so the pre-migration fork is what actually survives.

So the demo hand-rolls the mitigation: fork the old state first, then promote. In a tool where nearly everything else is reversible, promote is the one verb whose inverse the user has to remember to build.

Is there a reason promote should not snapshot the target's head itself before repointing? Reaping cost, or does an implicit branch fight the single-fenced-writer invariant somewhere I am not seeing?

[sricola]

Sorry for the slow reply, and thank you for this. You read the demo comment exactly right, and the honest answer to "is there a reason promote should not snapshot the target's head itself?" is: no good one. It was a gap, and it's fixed in v0.2.10 (tagged today).

What promote does now. Before the repoint lands, it keeps the target's current head as a shared fork named <target>-pre-promote, so the undo is:

offshoot promote shop@main-pre-promote --onto main --force

The CLI prints that command after every promote. The MCP tool names the fork in its result so an agent has the handle too, and the daemon/SDKs expose it (no_backup/backup_ttl on the wire, backup=/backup_ttl= in Python, noBackup/backupTtl in TypeScript). --no-backup opts out.

On the two costs you guessed at. You had the right one. Promote (and rollback, compact) materializes a full copy rather than base-pointing precisely because a base pointer into a lineage that's meant to die would pin that lineage's storage forever. The safety fork is a base pointer into main's old lineage, so it does pin it, but it's a fork, so it carries a TTL (24h by default, --backup-ttl to change; a safety fork always has one) and there's exactly one per target, replaced by the next promote. So the pinning is bounded: the old lineage's bytes are reclaimed when the fork is reaped or destroyed instead of at promote time. The fork itself costs two small metadata objects, no data copy, same as any shared fork. Reaping cost is the janitor's normal TTL path.

It doesn't touch the single-fenced-writer invariant: the safety fork is an ordinary branch with its own lineage and its own lease, and the target's own repoint is still one CAS write. Two guardrails so it can't surprise anyone: promote only ever replaces a branch at the -pre-promote name if that branch carries the marker metadata promote itself wrote (a branch of yours that merely shares the name makes promote refuse instead of destroying it), and a live lease on the previous safety fork refuses the promote rather than pulling it out from under whoever is in it.

The parallel-attempts demo no longer forks pre-migration by hand; the recorded transcript in the README is from the new run. Details: the promote section of docs/reference.md and the changelog entry for 0.2.10.

If you're using it and the 24h default is wrong for your workload, I'd like to hear why.