mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
fix(ui): keep a Retry for retained-file holds whose source cannot be verified (#19840)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - When a native run finishes but its files cannot be saved, the task stays blocked behind a retained-file recovery hold. > - The server records that hold as blocked and retryable, and the task notice tells the user to "Retry to try again". > - The task page hides its own Retry for these holds and relies on the retained-file recovery panel instead. > - That panel only binds the recovery record when a read-only source inspection returns `verified`. > - Inspection can return `blocked` for normal reasons: a sandbox that predates ownership receipts (state saved by an older release), or a workspace that moved on after its files were recovered. > - Then neither surface offers an action, and "Check file recovery status" always answers "File recovery changed. Refresh the task", also after a reload. > - This pull request binds the record by its own identity, uses inspection only to gate the physical file-recovery request, and keeps the task Retry visible whenever the panel has no control of its own. ## Linked Issues or Issue Description Refs #18848 (the change that added the retained-file recovery panel and hid the generic Retry for these holds). **What happened?** A blocked task with an active `native_workspace_sync_out_retry_exhausted` hold showed "The saved files need recovery before work can continue", "The recorded source is unavailable or has changed", and "Saving the agent's files failed after automatic retries. Retry to try again". It showed no Retry and no recover button. "Check file recovery status" always answered "File recovery changed. Refresh the task to inspect the current recovery", and a reload did not change it. The hold was saved by an earlier release: `systemRecovery` exhausted with `allocation_ownership_ambiguous` / `service_required`, and `workspaceRecovery` blocked with `retryable: true`. The source inspection endpoint returned `status: "blocked"` for it. A second task whose files were already recovered showed the same "need recovery" and "has changed" text, because its inspection reported a reference mismatch after recovery. **Expected behavior** A retryable hold always shows a working Retry or recover control. A notice that says "Retry" has a Retry button. Status checks never loop on "changed, refresh". Recovered files show as recovered. When the source cannot be verified, the page names the reason and who must inspect it. **Steps to reproduce** 1. Use an active retained-export hold whose `workspaceRecovery` is blocked and retryable, and whose `systemRecovery` is exhausted. 2. Make the source inspection (`GET /api/issues/:id/recovery-actions?inspectSourceRunId=…&inspectSourceActionId=…`) return `status: "blocked"`. 3. Open the task as a board operator. 4. Before this change, the page shows no Retry and no recover button. "Check file recovery status" reports "File recovery changed. Refresh the task". **Paperclip version or commit** Observed on build `8812c19`. The regressions fail on master `0f5ce5050e` before the production edits. ## What Changed - `WorkspaceExportRecovery`: bind the recovery record by action, run and schema identity, not by inspection status. Inspection status now gates only the physical "Recover saved files" request (and the request re-checks it before POST). - `WorkspaceExportRecovery`: report through `onRecoveryControlChange` whether the panel offers its own control. It reports `true` only while the source is loading or verified and the files are not yet recovered, or while it shows the previous-server stop confirmation. - `IssueDetail`: hide the task Retry for retained-export holds only while the panel reports that it owns the control. Otherwise the existing task Retry (`POST /issues/:id/retry`) shows. The server renews a bounded recovery generation and re-verifies the source. - Show recovered files as recovered even when inspection no longer matches after recovery. - Name an unverifiable source in plain words (with the code for other reasons). State that Paperclip does not apply files it can't verify. - Recovery text never asks a person to inspect a sandbox or environment, and never names an owner or administrator as the one who must act. This covers the retained-file panel, the run source inspector, the copyback wait, and the native cleanup quarantine message. The execution blocker and the recovery action read model describe a spent recovery budget from its current state, so text saved by older releases ("If Retry keeps failing, inspect the run and its environment") is not shown. - Task Retry uses the existing `createUuid()` helper, so it works on plain-HTTP previews without `crypto.randomUUID`. An accepted Retry also refreshes the inspected file-recovery state. After a failed accepted request, the unverified-source reason stays visible; it hides only while recovery runs. - When the recovery record was replaced, "Check file recovery status" reloads the task detail instead of telling the user to refresh. - Tests: component regressions for an old-release hold, a recovered hold with a mismatched source, verified ownership, and a replaced record. A page regression proves Retry is shown and calls `retryTask` for unverified and stale sources. A server safety test proves that Retry for the old-release hold shape is accepted, opens one new bounded generation, queues file recovery again, keeps the hold active, and is idempotent. ## Verification - RED (master `0f5ce5050e` production files, new tests): 5 component tests fail. The failure output shows the exact staging text: "Check file recovery status", "File recovery changed. Refresh the task to inspect the current recovery.", "The recorded source is unavailable or has changed." 2 page tests (unverified and stale) fail with `expected [ 'Check file recovery status', … ] to include 'Retry'`. - GREEN: `cd ui && npx vitest run src/components/WorkspaceExportRecovery.control.test.tsx src/components/WorkspaceExportRecovery.test.tsx src/components/RunWorkspaceRecoverySurface.test.tsx src/components/ExecutionBlockerNotice.test.tsx src/pages/IssueDetail.test.tsx` passes 320 tests. - Server: `cd server && npx vitest run src/services/task-retry.test.ts` passes 81 tests, including the new old-release safety case. This is safety evidence, not a red: the server path was already correct, and the defect was in the UI. - Full UI suite: 11564 pass. 4 tests in `IssuesList.test.tsx` and `CompanyEnvironments.test.tsx` failed under full-suite load and pass in isolation (106/106). They are unrelated to this change. - `pnpm check:token-gates` is clean. `node scripts/run-tsc.mjs -p ui/tsconfig.json --noEmit` reports no errors in the touched files. The remaining errors are local artifacts that were not built (plugin SDK UI entry, generated Storybook catalog). - Staging was read only (GET requests). The inspect request did not loop in a fresh tab: two calls in 30 seconds. Most of the tab's request volume is periodic company issue-list refetches, which this change does not touch. ## Risks - Low risk. This is a UI-only behavior change. Server authorization, source verification, stop receipts, and the bounded recovery policy are unchanged and remain authoritative. - The task Retry is now visible for retained-export holds whose source does not verify. Retry renews one recovery generation. The worker re-runs the same source-identity checks, so Retry cannot bypass an ownership refusal. If the refusal is permanent (for example an ambiguous sandbox allocation), the hold returns to exhausted and the page names the reason. An automatic fallback for such sources is follow-up work. - Wording: a parametrized UI test renders every recovery state and asserts that no administrator, owner, or "inspect the environment" copy appears. A server test proves that a stored old-release message is replaced by state-derived text. Both failed before the change. - Previous-release story: the old-release hold shape (board-owned, `systemRecovery` revision 5 exhausted with `service_required`, `workspaceRecovery` blocked and retryable) is covered by component, page, and server tests. No persisted state shape changes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, used through Claude Code with tool use (repository search, file edits, shell, test execution, and a read-only browser). ## 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 - [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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
630411af53
commit
824b25654c
18 files changed
+356
-58
No files matched your search
@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import type { IssueRecoveryAction } from "@paperclipai/shared";
|
||||
import { ApiError } from "../api/client";
|
||||
import { queryKeys } from "../lib/queryKeys";
|
||||
import { writePendingSend } from "../lib/pending-send";
|
||||
import { WorkspaceExportRecovery } from "./WorkspaceExportRecovery";
|
||||
|
||||
const api = vi.hoisted(() => ({ inspect: vi.fn(), recover: vi.fn(), resume: vi.fn() }));
|
||||
@@ -153,7 +154,106 @@ describe("governed retained-file recovery", () => {
|
||||
} });
|
||||
await mount();
|
||||
expect(button("Recover saved files")).toBeUndefined();
|
||||
expect(container.textContent).toContain("source is unavailable or has changed");
|
||||
expect(container.textContent).toContain("can’t verify the saved files’ recorded source (source_binding_invalid)");
|
||||
});
|
||||
|
||||
// Recovery saved by an older release: a board-owned hold whose
|
||||
// sandbox predates ownership receipts. The server still records a retryable
|
||||
// blocked recovery, but the read-only source probe cannot verify ownership.
|
||||
const legacyHold = { ...action, id: "legacy-hold", ownerType: "board", evidence: { runId: "run-1",
|
||||
workspaceRecovery: { schema: "paperclip.workspace-recovery.v1", runId: "run-1", stage: "verifying_stop",
|
||||
status: "blocked", attempt: 1, attemptLimit: 6, requestIds: [], retryable: true,
|
||||
message: "Automatic recovery of saved work stopped after 1 attempts (last failure: allocation_ownership_ambiguous)." },
|
||||
systemRecovery: { schema: "paperclip.system-recovery.v1", phase: "verify_execution", state: "exhausted", revision: 5,
|
||||
sourceRunId: "run-1", attempts: 1, retriesUsed: 0, preservationOperationIds: [], freshAttemptRunId: null,
|
||||
failure: { code: "allocation_ownership_ambiguous", retryClass: "service_required" } },
|
||||
originalFailureCode: "native_workspace_sync_out_failed", workspaceFinalizeAttempt: 3, previousWorkspaceRecovery: null },
|
||||
} as unknown as IssueRecoveryAction;
|
||||
const blockedInspection = (value: IssueRecoveryAction, failureCode = "allocation_ownership_ambiguous") => ({
|
||||
active: value, actions: [value], sourceInspection: { schema: "paperclip.workspace-source-inspection.v1",
|
||||
actionId: value.id, runId: "run-1", status: "blocked", failureCode,
|
||||
scope: "recorded_source_identity", observedAt: "2026-11-07T14:44:46Z" } });
|
||||
|
||||
it("hands the next action to the task Retry for an old-release hold whose source cannot be verified", async () => {
|
||||
api.inspect.mockResolvedValue(blockedInspection(legacyHold));
|
||||
const owns = vi.fn();
|
||||
await act(async () => root.render(<QueryClientProvider client={client}>
|
||||
<WorkspaceExportRecovery action={legacyHold} issueId="issue-1" companyId="company-1" onRecoveryControlChange={owns} />
|
||||
</QueryClientProvider>));
|
||||
await settle();
|
||||
expect(owns).toHaveBeenLastCalledWith(false);
|
||||
expect(button("Recover saved files")).toBeUndefined();
|
||||
// No dead-end: no "changed, refresh" alert and no status check that can only repeat it.
|
||||
expect(button("Check file recovery status")).toBeUndefined();
|
||||
expect(container.textContent).not.toContain("has changed");
|
||||
expect(container.textContent).toContain("can’t confirm that this run alone used the sandbox");
|
||||
expect(api.recover).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("does not request recovery when the source stops verifying between render and click", async () => {
|
||||
api.inspect.mockResolvedValueOnce(inspection()).mockResolvedValueOnce({ ...inspection(), sourceInspection: {
|
||||
...inspection().sourceInspection, status: "blocked", failureCode: "allocation_ownership_ambiguous" } });
|
||||
await mount();
|
||||
await click("Recover saved files");
|
||||
expect(api.recover).not.toHaveBeenCalled();
|
||||
expect(container.textContent).toContain("can’t confirm that this run alone used the sandbox");
|
||||
expect(container.textContent).not.toContain("File recovery changed");
|
||||
expect(button("Recover saved files")).toBeUndefined();
|
||||
});
|
||||
|
||||
it("keeps naming the unverified source after an accepted request failed", async () => {
|
||||
const key = "accepted-request";
|
||||
writePendingSend("workspace-file-recovery:company-1:issue-1:legacy-hold:run-1:board-1",
|
||||
{ idempotencyKey: key, payload: { actionId: "legacy-hold", runId: "run-1" }, createdAt: Date.now() });
|
||||
const failed = { ...legacyHold, evidence: { ...legacyHold.evidence, workspaceRecovery: {
|
||||
...(legacyHold.evidence.workspaceRecovery as object), requestIds: [key] } } } as IssueRecoveryAction;
|
||||
api.inspect.mockResolvedValue(blockedInspection(failed));
|
||||
await mount(failed);
|
||||
expect(container.textContent).toContain("File recovery has not finished");
|
||||
expect(container.textContent).toContain("can’t confirm that this run alone used the sandbox");
|
||||
// While recovery is running, the panel shows progress instead of the reason.
|
||||
const running = { ...failed, evidence: { ...failed.evidence, workspaceRecovery: {
|
||||
...(failed.evidence.workspaceRecovery as object), status: "recovering" } } } as IssueRecoveryAction;
|
||||
api.inspect.mockResolvedValue(blockedInspection(running));
|
||||
await act(async () => client.invalidateQueries({ queryKey: queryKeys.issues.recoveryActions("issue-1", "legacy-hold", "run-1") }));
|
||||
await settle();
|
||||
expect(container.textContent).toContain("Recovering saved files");
|
||||
expect(container.textContent).not.toContain("can’t confirm that this run alone used the sandbox");
|
||||
expect(api.recover).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("keeps ownership of the next action while the source is verified", async () => {
|
||||
const owns = vi.fn();
|
||||
await act(async () => root.render(<QueryClientProvider client={client}>
|
||||
<WorkspaceExportRecovery action={action} issueId="issue-1" companyId="company-1" onRecoveryControlChange={owns} />
|
||||
</QueryClientProvider>));
|
||||
await settle();
|
||||
expect(owns).toHaveBeenLastCalledWith(true);
|
||||
expect(button("Recover saved files")).toBeDefined();
|
||||
});
|
||||
|
||||
it("reports recovered files even when the source no longer matches after recovery", async () => {
|
||||
// Preservation completed, so the workspace moved past the
|
||||
// recorded source and inspection reports a reference mismatch.
|
||||
const recovered = { ...legacyHold, ownerType: "system", evidence: { ...legacyHold.evidence,
|
||||
workspaceRecovery: { ...(legacyHold.evidence.workspaceRecovery as object), status: "recovered" },
|
||||
systemRecovery: { ...(legacyHold.evidence.systemRecovery as object), state: "complete",
|
||||
preservationOperationIds: ["preservation-1"] } } } as IssueRecoveryAction;
|
||||
api.inspect.mockResolvedValue(blockedInspection(recovered, "source_binding_invalid"));
|
||||
await mount(recovered);
|
||||
expect(container.textContent).toContain("Saved files recovered");
|
||||
expect(container.textContent).not.toContain("need recovery");
|
||||
expect(container.textContent).not.toContain("has changed");
|
||||
expect(button("Recover saved files")).toBeUndefined();
|
||||
});
|
||||
|
||||
it("reloads the task instead of looping when the recovery record was replaced", async () => {
|
||||
api.inspect.mockResolvedValue({ active: null, actions: [], sourceInspection: undefined });
|
||||
const invalidate = vi.spyOn(client, "invalidateQueries");
|
||||
await mount(legacyHold);
|
||||
await click("Check file recovery status");
|
||||
expect(container.textContent).not.toContain("Refresh the task");
|
||||
expect(invalidate).toHaveBeenCalledWith({ queryKey: queryKeys.issues.detail("issue-1") });
|
||||
});
|
||||
|
||||
it("persists the exact request before POST and prevents a double click", async () => {
|
||||
@@ -288,6 +388,37 @@ describe("governed retained-file recovery", () => {
|
||||
expect(api.recover).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
// Recovery is automatic. No recovery state may tell a person to fix or inspect
|
||||
// a sandbox, or name an owner or administrator as the one who must act.
|
||||
const manualCopy = /administrator|\bowner\b|operator assistance|service assistance|service attention|inspect the (run|failed run)|environment/i;
|
||||
const withRecovery = (value: IssueRecoveryAction, patch: Record<string, unknown>, system?: Record<string, unknown>) => ({
|
||||
...value, evidence: { ...value.evidence, workspaceRecovery: { ...(value.evidence.workspaceRecovery as object), ...patch },
|
||||
...(system ? { systemRecovery: { ...(value.evidence.systemRecovery as object), ...system } } : {}) } }) as IssueRecoveryAction;
|
||||
const operatorAccess = { userId: "board-1", companyIds: ["company-1"], source: "session", isInstanceAdmin: false,
|
||||
memberships: [{ companyId: "company-1", membershipRole: "operator", status: "active" }] };
|
||||
const viewerAccess = { ...operatorAccess, memberships: [{ companyId: "company-1", membershipRole: "viewer", status: "active" }] };
|
||||
it.each([
|
||||
["verified and retryable", action, inspection(action), operatorAccess],
|
||||
["unverified ownership", legacyHold, blockedInspection(legacyHold), operatorAccess],
|
||||
["unverified binding", legacyHold, blockedInspection(legacyHold, "source_binding_invalid"), operatorAccess],
|
||||
["not inspected", legacyHold, { ...blockedInspection(legacyHold), sourceInspection: { ...blockedInspection(legacyHold).sourceInspection,
|
||||
status: "not_inspected", reason: "source_limit" } }, operatorAccess],
|
||||
["queued", withRecovery(legacyHold, { status: "queued" }), blockedInspection(withRecovery(legacyHold, { status: "queued" })), operatorAccess],
|
||||
["not retryable", withRecovery(legacyHold, { retryable: false }), blockedInspection(withRecovery(legacyHold, { retryable: false })), operatorAccess],
|
||||
["recovered", withRecovery(legacyHold, { status: "recovered" }, { state: "complete", preservationOperationIds: ["op-1"] }),
|
||||
blockedInspection(withRecovery(legacyHold, { status: "recovered" }, { state: "complete", preservationOperationIds: ["op-1"] })), operatorAccess],
|
||||
["viewer", legacyHold, blockedInspection(legacyHold), viewerAccess],
|
||||
["copyback owner hold for an operator", { ...action, evidence: { ...action.evidence,
|
||||
workspaceOwnerRecovery: { state: "operator_required", owner: { token: "token" } } } } as IssueRecoveryAction, inspection(action), operatorAccess],
|
||||
["board-owned status", { ...action, cause: "native_workspace_finalization_owner_unverified", ownerType: "board",
|
||||
evidence: { runId: "run-1" } } as unknown as IssueRecoveryAction, inspection(action), operatorAccess],
|
||||
] as const)("renders no manual sandbox or administrator copy: %s", async (_name, value, response, access) => {
|
||||
client.setQueryData(queryKeys.access.currentBoardAccess, access);
|
||||
api.inspect.mockResolvedValue(response);
|
||||
await mount(value);
|
||||
expect(container.textContent).not.toMatch(manualCopy);
|
||||
});
|
||||
|
||||
describe("previous server stop confirmation", () => {
|
||||
const ownerAction = { ...action, cause: "native_workspace_finalization_owner_unverified", ownerType: "board", status: "escalated",
|
||||
evidence: { runId: "run-1", owner: { token: "owner-token", hostname: "secret-host", pid: 2 },
|
||||
@@ -350,7 +481,7 @@ describe("governed retained-file recovery", () => {
|
||||
companyIds: ["company-1"], memberships: [{ companyId: "company-1", membershipRole: "operator", status: "active" }] });
|
||||
await mount(ownerAction);
|
||||
expect(button("Confirm the previous server stopped")).toBeUndefined();
|
||||
expect(container.textContent).toContain("owner or administrator can confirm");
|
||||
expect(container.textContent).toContain("waiting to confirm that the previous server stopped");
|
||||
expect(api.resume).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
Reference in new issue
Block a user