Files
PaperClipAI/server
ef18d71672 fix(workspaces): reopen an expired workspace after its move to remote storage (#22429)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Before a run starts, Paperclip can reopen a task's archived
execution workspace
> - Git cache expiration removes the local files of an idle workspace
and saves a local restore recipe
> - Remote workspace storage migration can later move that expired
workspace into a saved snapshot. The migration changes the workspace
`cwd` to `/workspaces/<id>`, but it keeps the local restore recipe. That
recipe still names the removed worktree path
> - Run setup reads the recipe through `readGitCacheExpiration` before
it reopens the workspace. The recipe no longer matches the workspace
`cwd`, so validation fails and every run on that task fails in setup
> - This pull request makes run setup read only the current lifecycle's
expiration marker for a workspace in remote storage
> - The benefit is that the task reopens from its saved snapshot. The
reopen path already does this for remote-storage workspaces

## Linked Issues or Issue Description

Refs #22419 (gave this failure its own error code,
`git_cache_restoration_failed`). Refs #19736 (restore diagnostics). I
found no open PR for this cause.

**What happened?**
On staging, runs on some tasks fail during setup with "The saved
workspace commit could not be restored. Check repository access and
retry." The stack is `selectHeartbeatEnvironment` →
`readGitCacheExpiration` → `readGitCacheRestoration`. The task's
workspace is archived with `cleanupReason:
reproducible_git_cache_expired`. It also has a `remoteWorkspace`
authority from the storage migration, and `cwd` is `/workspaces/<id>`.
Its `gitCacheRestoration.worktreePath` is still the old local worktree
path. `readGitCacheRestoration` requires `recipe.worktreePath ===
workspace.cwd`, so it throws. Automatic recovery repeats the run and the
run fails again.

**Expected behavior**
Run setup sees that git cache expiration removed the workspace, and it
reopens the workspace. `reopenClosedIsolatedExecutionWorkspaceForIssue`
restores a workspace with a remote authority from its snapshot and does
not read the local recipe.

**Steps to reproduce**
1. Archive an isolated workspace with a completed `gitCacheExpiration`
marker and a `gitCacheRestoration` recipe.
2. Apply what the remote storage migration does: set `remoteWorkspace`
authority and set `cwd` to `/workspaces/<id>`.
3. Start a run on the bound task. On current master,
`selectHeartbeatEnvironment` throws `GitCacheRestorationFailure`.

## What Changed

- `server/src/services/heartbeat/environment-selection.ts`: add
`gitCacheExpirationRemovedWorkspace`. For a workspace without a remote
authority, it uses `readGitCacheExpiration` as before, with the full
recipe check. For a workspace with a remote authority, it reads only the
`gitCacheExpiration` marker. The marker must have the expected schema,
`workspaceRemoved: true`, and a `generation` that equals the current
`lifecycleGeneration`. A marker from an earlier lifecycle does not start
a reopen.
- `server/src/services/heartbeat/environment-selection.test.ts`: add two
tests that use the real `readGitCacheExpiration`, a migrated workspace
row and a committed snapshot. One test runs the real reopen operation
through `selectHeartbeatEnvironment`. It checks that the same workspace
becomes active, keeps its `/workspaces/<id>` cwd, stays bound to the
issue, and that `lifecycleGeneration` advances from 3 to 4. One test
checks that a marker from an earlier lifecycle does not start a reopen.

## Verification

- Red/green: on unmodified master, both new tests fail (rechecked after
the review change) with "The saved workspace commit could not be
restored" and the same stack as the staging events. With the fix, they
pass.
- `pnpm exec vitest run
src/services/heartbeat/environment-selection.test.ts`: 27 passed.
- `pnpm exec vitest run src/__tests__/execution-workspace-reopen.test.ts
src/__tests__/git-workspace-restoration-diagnostic.test.ts`: all pass.
(When I ran the two files together, one reopen test hit its 25 s
timeout. It passes alone, and that file does not import the changed
module.)
- `pnpm --filter @paperclipai/server typecheck` (all layers): passes.

## Risks

- Low risk. The change only affects archived workspaces that have a
remote authority. Local workspaces keep the full recipe check.
- A remote-storage workspace now reopens through the existing remote
path. That path checks the saved snapshot first
(`inspectRemoteWorkspacePersistence`) and returns `rebuild_failed` if
the snapshot is not ready. So a missing snapshot still fails the run
with a clear reason.
- Not in scope: the migration keeps the stale local recipe in metadata.
Other readers of that recipe do not run for remote-storage workspaces in
this path.

## Model Used

Claude Opus 5.5 (`claude-opus-5-5`) via Claude Code, as the Paperclip
Sentry triage agent, with tool use and code execution.

## 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
- [ ] I have updated relevant documentation to reflect my changes (no
documentation describes this check)
- [x] 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 10:47:43 -08:00
..