fix(workspaces): restore rebased sandbox history against its starting snapshot (#15268)

## Thinking Path

> - Paperclip manages agents and preserves their work across runs.
> - Sandbox execution restores Git history and files to the host
workspace.
> - An agent can rebase or amend its branch before it finishes.
> - Restore currently treats the original and rewritten tips as
concurrent work.
> - That merge can conflict even when the host has not changed.
> - This change uses the starting Git snapshot to accept rewritten
history safely.

## Linked Issues or Issue Description

**What happened?**

A successful sandbox turn can end with `workspace_restore_failed` after
the agent rebases and pushes its branch. The restore step merges the
original host tip with the rewritten sandbox tip. This can recreate
conflicts that the agent already resolved.

**Expected behavior**

Accept the rewritten history when the host still has the recorded
starting branch and commit. Preserve concurrent host work through the
existing merge and recovery paths.

**Steps to reproduce**

1. Start a sandbox from a feature branch.
2. Rebase that branch onto an upstream commit that changes the same
file. Resolve the conflict in the sandbox.
3. Restore the sandbox while the host remains on the original commit.
4. The old implementation attempts a conflicting Git merge and fails the
run after the agent finishes.

**Paperclip version or commit**

Reproduced on `cab4263dc9` with a real Git rebase fixture.

**Deployment mode**

Self-hosted server with sandbox execution.

Related work: #15005 records restore failure stages. #11638 preserves
unrelated imported history with a graft. #10601 handles bundle
prerequisites. Those changes do not distinguish a rebase from a
concurrent host edit.

## What Changed

- Pass the run's starting Git branch and commit into sandbox history
integration.
- Adopt a related rewritten tip when the host still matches that
snapshot. Keep the expected-old-value ref update and bounded retry.
- Verify the branch attachment inside a prepared Git transaction while
Git holds its ref locks. Abort if a checkout changed the branch.
- Check host and sandbox Git identity before warm reuse, including
nested repositories. Restage when their tips or branches differ.
- Reject host branch changes and unrelated imports after a concurrent
host commit.
- Retain the existing unrelated-history graft for an unchanged host and
the conservative behavior for callers without a snapshot.
- Export a full bundle for an intentional reset to an ancestor so
restore receives the actual sandbox tip.
- Add real Git and sandbox restore regressions. Document the restore
contract.

## Verification

- Eight Git sync, sandbox restore, and native workspace suites pass: 255
tests.
- The new checkout-race and warm-reuse regressions failed before the
fixes. Real Git hooks verify that prepared transactions prevent a
concurrent HEAD change.
- `pnpm -r typecheck` passed after rebasing onto `984f092ddf` and
applying the Apex findings.
- `pnpm build` passed on `f5132603d6`.
- The earlier `pnpm test:run` attempt reported three
`company-skills-service.test.ts` failures on macOS (`EACCES` renaming a
read-only staging directory). The same failures reproduced on unchanged
master. The broader run was stopped after confirming that baseline
failure; it was not a full-suite pass. Those source and test files are
unchanged in the current base.
- [Apex
review](https://github.com/paperclipai/paperclip/pull/15268#issuecomment-6002549219):
5/5 on `f5132603d6`, requested with `@greptileai apex review`. All three
historical findings are addressed and all review threads are resolved.
- All CI gates passed on `f5132603d6` (53 successful checks, two
skipped). The signoff-policy browser fixture initially timed out waiting
for a local process-agent run; its one retry passed without code
changes. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/37387511152)

## Risks

- A recorded starting snapshot now authorizes replacement of related
rewritten history. A stale or changed host tip retains the
concurrent-history path. Ref writes still compare the expected old
commit.
- Branch changes and unrelated rewrites after host advancement require
recovery instead of replacing host work.
- An intentional reset to an ancestor uses a full bundle. Large
histories can increase transfer time in that case.
- The existing directory merge rules remain in force. The fix does not
resolve an earlier failed restore or replay its external actions.

## Model Used

OpenAI GPT-6 via Codex, with reasoning, repository analysis, code
editing, and local test execution. The exact deployment model ID and
context window were 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 — 255 affected tests; the
broader-suite baseline failure is documented above
- [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>

doc/execution-semantics.md

@@ -452,6 +452,23 @@ Workspace incoherence feeds into the same non-terminal liveness and stranded ass
 
 For runtime-created `git_worktree` execution workspaces, branch coherence is part of workspace coherence. The persisted execution workspace branch is the recorded branch for future dispatch. Reusing that workspace must verify that the worktree is still registered and that `HEAD` is on the recorded branch. Successful run finalization must perform the same check before recording `workspace_finalize=succeeded`. If the run switched to a publishing/PR branch without updating the execution workspace record, finalization may auto-restore the recorded branch only when the worktree is clean, still registered, and the recorded branch points at the current `HEAD`; the repair is recorded as a workspace operation before the successful finalize row. If that safe repair cannot be proven, finalization records a failed workspace finalize and the run fails with bounded evidence for the expected and actual branch. A branch change is sanctioned when a control-plane path updates the execution workspace record before finalization, when publishing work happens in a separate worktree and the managed issue worktree remains on its recorded branch, or when the finalizer performs this clean same-commit restoration.
 
+Sandbox Git restore uses the host branch and commit captured before staging.
+If that identity is unchanged, a rebased or amended sandbox history with shared
+ancestry replaces the starting tip instead of being merged with it. The ref
+update checks the expected old commit; a concurrent change retries through the
+normal history integration path. Git holds the HEAD and applicable branch locks
+while restore verifies the attached/detached branch identity and commits the ref
+transaction. A checkout during integration cannot redirect that write.
+The directory merge still preserves host-only
+file changes under its existing rules. A changed host branch requires recovery.
+An intentional reset to an ancestor exports a full Git bundle so restore keeps
+the actual sandbox tip; an empty delta is reserved for an unchanged tip.
+Unrelated sandbox history keeps the existing history-preserving graft only when
+the recorded host has not advanced; it must not replace concurrent host work.
+Warm sandbox reuse must match the current host Git tip and branch as well as the
+file snapshot and saved stamp, including managed nested repositories. A history
+or branch mismatch restages the host before the next run begins.
+
 ### Workspace scan failures before provider startup
 
 Repository discovery distinguishes an ordinary folder from a failed Git read.