Files
PaperClipAI/server
97737c4f7f fix(workspaces): give a failed saved-workspace restore a stable error code (#22419)
## 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 and restore its saved Git commit
> - When the saved restoration record no longer matches its workspace,
or a restore step fails, the code throws `GitCacheRestorationFailure`
> - That error records which step failed and what kind of failure it
was, but it has no `code`
> - Run-failure reporting groups failures by error code, never by
message. A setup failure without a code falls back to its class name,
and this class reports its name as plain `Error`. So these failures
share one Sentry group with every other uncoded setup failure
> - On staging this one failure makes up almost all of that catch-all
group: hundreds of events from automatic restarts of tasks whose saved
workspace record can no longer be restored
> - This pull request gives the error a stable code
> - The benefit is a separate, correctly named Sentry group for restore
failures, and run records whose `failureCause` names the restore failure
instead of `Error`

## Linked Issues or Issue Description

**What happened?**
On staging, runs keep failing during setup with "The saved workspace
commit could not be restored. Check repository access and retry." The
stack is `selectHeartbeatEnvironment` → `readGitCacheExpiration` →
`readGitCacheRestoration`. The stored restoration record of an archived
workspace fails validation, and the run fails as `setup_failed`. The
error has no code, so the Sentry fingerprint uses `exception:Error` and
puts it in the same group as unrelated setup failures.
`resultJson.failureCause` for these runs is the generic `Error`.

**Expected behavior**
A failed saved-workspace restore has a stable error code. Sentry groups
it on its own, and the run's failure cause names it.

**Related**
Refs #19736, which added the safe `step` and `kind` restore diagnostics
this change keeps. #22093 took the same approach for the
execution-target Git context probe. I found no open PR for this error.

**Steps to reproduce**
Construct `new GitCacheRestorationFailure()` (or call
`readGitCacheRestoration` with a record that does not match its
workspace). On current master the error has no `code`,
`failureCauseFromError` returns `Error`, and the run-failure diagnostics
record no root code.

## What Changed

- `server/src/services/git-workspace-restoration.ts`: add
`GIT_CACHE_RESTORATION_FAILED_CODE` (`git_cache_restoration_failed`) and
set it as `code` on every `GitCacheRestorationFailure`.
- The message, `step` and `kind` do not change.
`classifyWorkspaceRestorationError` still checks the class first, so
restore classification does not change.
- `server/src/__tests__/git-workspace-restoration-diagnostic.test.ts`:
add a test that the error carries the code, with and without a step
diagnostic, that `failureCauseFromError` returns it (also when the error
is a `cause`), and that `collectRunFailureDiagnostics` records it as the
root exception code. That root code is what the Sentry fingerprint uses.

## Verification

- Red/green: the new test fails on unmodified master and passes with the
fix.
- `vitest run` on `git-workspace-restoration-diagnostic`,
`git-expiration-auth-fallback` and `run-failure-sentry`: 63 tests pass.
- I also ran the other suites that use this error or its readers locally
(archived nested repository, fetch head, reproducible managed checkouts,
base storage, repository object cache, remote workspace migration, Git
workspace expiration, heartbeat environment selection, closed-workspace
routes). In this sandbox many `remote-workspace-migration` tests stopped
at about 10 seconds each. The migration code doesn't read this error's
`code` (it only compares a database lock code and a fixed supersession
code), so I expect the slow sandbox to be the cause. CI's full run is
the authoritative result.
- I couldn't run the full server typecheck locally because the sandbox
ran out of memory. The change only adds a new `code` field, which
`Error` does not define. CI's Typecheck job covers it.

## Risks

- Low risk. Only an added `code` property on one error class. No control
flow changes.
- `resultJson.failureCause` for these runs becomes
`git_cache_restoration_failed` instead of `Error`. The only code that
compares `failureCause` checks a different prefix
(`remote_workspace_sandbox_disk_full:`).
- Every setup-failure classifier in `run-completion` matches a specific
error class or HTTP error, not any coded error, so the run's `errorCode`
stays `setup_failed` and retry behavior does not change.
- Not in scope: automatic fresh continuations still retry this
deterministic failure. Stopping that needs a recovery-policy change in
`fresh-continuation-fallback`, which decides on `run.errorCode`. That's
a separate change for the recovery owners.

## Model Used

Claude Opus 5.5 (`claude-opus-5-5`) via Claude Code, as the Paperclip
Sentry triage agent.

## 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 (targeted suites; see
Verification for the slow migration suite)
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes (no
documentation describes this error's fields)
- [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 06:13:08 -08:00
..