mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - When a run stops early, Paperclip recovers its saved files and then continues the task automatically > - Sometimes the sandbox is gone. Then saved-work recovery ends with `source_unavailable` (use another strategy) > - In that state the task showed Retry. Retry worked, because it continues in a fresh workspace. But nothing continued the task automatically > - A task must never need a person's Retry for a system failure. The target is 0% > - This pull request lets the system take the same fresh-workspace step that Retry takes, when the saved files are permanently lost > - The benefit is that these tasks continue on their own, and the sweep reports them correctly ## Linked Issues or Issue Description Refs #21478 **What happened?** A legacy run on a remote sandbox failed in setup. Its unsaved files were held for saved-work recovery. The sandbox was gone, so the recovery ended `source_unavailable` / `use_alternative_strategy`. The task then showed Retry. For about 2 hours, the assigned-work sweep logged `retry_offered` with outcome `not_started` every 15 minutes. A person had to press Retry. **Root cause** The fresh-continuation fallback returned `person_owned` / `retry_needed`. It does this when a later run of the task was withheld at dispatch (here, a scheduled retry that the hold blocked) and the source run does not continue automatically. The source was a person's earlier Retry that failed with `setup_failed`, so it was not an automatic recovery run and not a restart-class failure. Without the withheld run, the same task already continued automatically. Restore-hold ownership (`isOwnedReconciliationHold`) and the legacy refusal in `inspectFallback` were not the blocker. **Expected behavior** When saved-work recovery proves that the files are permanently gone, the system continues the task in a fresh workspace on its own. This is the same path that Retry takes. ## What Changed - `fresh-continuation-fallback.ts`: the eligibility rule (`interruptionEligibility`, which the fallback and the backlog pass share) also accepts a system-owned source run when a hold of that run has saved-work recovery `exhausted` with a permanent unverifiable-source failure (`UNVERIFIABLE_SOURCE_CODES` × `PERMANENT_SOURCE_RETRY_CLASSES`). - `recovery/assigned-work-sweep.ts`: admission can settle the hold and coalesce the sweep's wake into a pending fresh continuation. The sweep now reports this as `repaired` / `queued` (`continuedFromSavedWork`). Before, it reported `enqueue_refused` / `not_started`. - `legacy-execution-recovery.ts`: the stranded sweep calls `terminalizeLegacyExecution` for the same failed run on every pass. Its restore-hold branch rewrote the hold every time, with a new `automaticRecovery.recordedAt`, a new `updatedAt`, and `continuationDelivery: "invalidated"`. The branch now returns early when the hold already records the same no-replay decision for this run, or when a fresh continuation took the hold over. Finding: a continuation that was already recorded was not clobbered, because the existing `executionReconciliation.runId` guard returned early. But a hold with a `coalesced` delivery state would have been reset, and the churn kept bumping `updatedAt`. - New regression test `legacy-source-unavailable-continuation.test.ts`. The existing `assigned-work-invariant` test now expects the corrected sweep outcome. ## Verification - Red/green: `legacy-source-unavailable-continuation.test.ts` uses `failedRemotePreparation()` with a `destroyed` termination receipt, `recoverRetainedWorkspace`, a withheld scheduled retry, and a source that was a person's Retry. Then it runs `assignedWorkSweep(...).checkIssue` with the real `heartbeatService(db).wakeup`. - Without the fix: outcome `enqueue_refused`, and the fallback returns `person_owned` / `retry_needed`. - With the fix: outcome `repaired`. A stranded pass keeps `continuationDelivery: "pending"`. `deliverReconciledExecutions` starts the successor run. The task no longer shows Retry. There is no `not_started` entry. - Red/green: the "revisits" test fails without the `terminalizeLegacyExecution` guard, because the hold evidence changes. It passes with the guard. - Locally passing: `fresh-continuation-fallback`, `fresh-continuation-move-forward-offer`, `fresh-continuation-retry-delivery`, `legacy-execution-recovery`, both `assigned-work-invariant` suites, `assigned-work-stalled-queued-run`, `assigned-work-sweep-round-trips`, `saved-work-recovery-overdue`, and the new test file (10 files, 225 tests). `tsc --noEmit` passes for `server`. - Not run locally: the full suite. CI covers it. ## Risks - Behavior shift: a task whose source failure is system-owned now continues automatically after its saved files are proven permanently gone, even when an earlier wake was withheld. The new run does not replay the old run. It starts in a fresh workspace, with the same notes and quarantine that Retry uses. Person-owned failure codes still wait for a person. - The new hold guard can skip a rewrite. It skips only when the hold is already resolved with the same no-replay decision and the same restore-recovery data. A changed decision is still written; the test covers this. - No schema changes. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, local Vitest against embedded Postgres). ## 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 - [ ] 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: Claude Opus 5.5 <noreply@anthropic.com>