Files
PaperClipAI/server/src
DottaandClaude Opus 5.5 ca23330c69 fix(recovery): continue a task on its own when its saved files are permanently lost (#21541)
## 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>
2026-11-15 05:22:00 -06:00
..
…
…
…
…
…
…