mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
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>
This commit is contained in:
2 files changed
+27
-1
No files matched your search
@@ -1,5 +1,12 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { classifyWorkspaceRestorationError, GitCacheRestorationFailure } from "../services/git-workspace-restoration.js";
|
||||
import type { heartbeatRuns } from "@paperclipai/db";
|
||||
import {
|
||||
classifyWorkspaceRestorationError,
|
||||
GIT_CACHE_RESTORATION_FAILED_CODE,
|
||||
GitCacheRestorationFailure,
|
||||
} from "../services/git-workspace-restoration.js";
|
||||
import { collectRunFailureDiagnostics } from "../services/run-failure-diagnostics.js";
|
||||
import { failureCauseFromError } from "../services/heartbeat/run-failure-cause.js";
|
||||
import { workspaceReopenDiagnostic } from "../services/execution-workspaces.js";
|
||||
import { GitConnectionFailureError } from "../services/git-connection-failure.js";
|
||||
|
||||
@@ -56,4 +63,20 @@ describe("workspace restoration diagnostic", () => {
|
||||
expect(classifyWorkspaceRestorationError(gitError("", { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", killed: true }))).toBe("git_command");
|
||||
expect(classifyWorkspaceRestorationError(Object.assign(new Error("unknown"), { code: "EUNRECOGNIZED" }))).toBe("unknown");
|
||||
});
|
||||
|
||||
it("gives every restoration failure a stable code that run diagnostics and failure causes record", () => {
|
||||
const run = { id: "run-restore", companyId: "company-restore", errorCode: "setup_failed", resultJson: null } as typeof heartbeatRuns.$inferSelect;
|
||||
for (const failure of [
|
||||
new GitCacheRestorationFailure(),
|
||||
new GitCacheRestorationFailure({ step: "saved_commit", kind: "commit_unavailable" }),
|
||||
]) {
|
||||
expect(failure.code).toBe(GIT_CACHE_RESTORATION_FAILED_CODE);
|
||||
expect(failureCauseFromError(failure)).toBe(GIT_CACHE_RESTORATION_FAILED_CODE);
|
||||
expect(failureCauseFromError(new Error("Workspace reopen failed", { cause: failure }))).toBe(GIT_CACHE_RESTORATION_FAILED_CODE);
|
||||
const exceptions = collectRunFailureDiagnostics(run, { error: failure, phase: "setup" }).exceptions;
|
||||
expect(exceptions.at(-1)?.code).toBe(GIT_CACHE_RESTORATION_FAILED_CODE);
|
||||
expect(classifyWorkspaceRestorationError(failure)).toBe(failure.kind ?? "verification");
|
||||
expect(failure.message).toBe("The saved workspace commit could not be restored. Check repository access and retry.");
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -91,7 +91,10 @@ export type GitCacheRestorationStep = "recipe" | "trash_recovery" | "source_chec
|
||||
export type WorkspaceRestorationFailureKind = "remote_unavailable" | "auth_rejected" | "commit_unavailable" | "timeout"
|
||||
| "verification" | "filesystem" | "git_command" | "unknown";
|
||||
|
||||
export const GIT_CACHE_RESTORATION_FAILED_CODE = "git_cache_restoration_failed";
|
||||
|
||||
export class GitCacheRestorationFailure extends Error {
|
||||
readonly code = GIT_CACHE_RESTORATION_FAILED_CODE;
|
||||
readonly step: GitCacheRestorationStep | null;
|
||||
readonly kind: WorkspaceRestorationFailureKind | null;
|
||||
constructor(diagnostic: { step: GitCacheRestorationStep; kind: WorkspaceRestorationFailureKind } | null = null) {
|
||||
|
||||
Reference in new issue
Block a user