## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - When a run stops before it finishes, the recovery system saves its
files and then continues the task in a fresh run from that save
> - A native run that already did work can still fail during setup, for
example while the incoming server reattaches it after a graceful release
swap
> - That failure (`setup_failed`) is not a restart-class code, so the
backlog pass did not continue it. The task waited about 10 minutes and
showed Retry, although the system owned the next step
> - Recovery must be automatic and fast: a needed-Retry rate of 0%, and
recovery latency in seconds
> - This pull request continues such a task as soon as its saved work is
recovered, and shows it as "continuing" with no Retry while it waits
> - The benefit is that a setup failure after work is invisible to the
user: the task continues in seconds, not 10 minutes
## Linked Issues or Issue Description
Refs #22118 (that PR prevents the gateway refusal that caused this
instance; this PR fixes the class).
**What happened?**
In a release-swap test wave, a native run had done about 13 minutes of
agent work. It was handed to the incoming server at a graceful swap.
Reattachment failed and the run ended with `setup_failed` at 23:13:38Z.
Saved-work recovery saved the run's files 7 seconds later. The next run
started at 23:23:40Z, 10 minutes and 2 seconds after the failure. For
that whole time the task view showed `failed` with `canRetry: true`.
**Expected behavior**
A failure during setup or reattachment of a run that already did work
continues the task automatically within seconds. While the system owns
the next step, the task shows a system-owned "continuing" state and no
Retry. Retry shows only when nothing automatic is pending, and then it
works.
**Steps to reproduce**
1. Start a native run and let it do provider work.
2. Make the run fail during setup (for example a definite refusal of the
reattach resume), so it ends `setup_failed` with a restore hold on its
files.
3. Let saved-work recovery save the files.
4. See that no continuation starts until an unrelated system wake
reaches the 10-minute fresh-continuation bound, and that the task shows
Retry in the meantime.
**Paperclip version or commit**
`master` at 4afcbfc0c7.
Root causes:
- Latency: the backlog pass (`continueHeldExecutions`) selects held
records only for "recent interruptions" (`recentInterruptionSourceSql`):
restart-class codes, recovery runs, or setup failures before provider
work. A first run that failed setup after provider work matched none of
them. So nothing called the fallback after the restore hold settled. The
task continued only when a later system wake reached the fallback after
`FRESH_CONTINUATION_PENDING_BOUND_MS` (10 minutes).
- Latency: even for an eligible record, a check made while saved-work
recovery was running was deferred to its backed-off `nextCheckAt` (1 to
4 minutes). Recovery completion did not wake the disposition worker.
- Presentation: no fresh-continuation check was recorded and no
saved-work recovery was active, so the projection fell through to
`failed` with `canRetry: true`.
## What Changed
- `continuation-cause.ts`: export `SETUP_FAILURE_CODES` (`setup_failed`
and the transient setup codes).
- New `fresh-continuation-eligibility.ts`: the held-record and
eligibility predicates move here from `fresh-continuation-fallback.ts`
with no behavior change (`heldExecutionWhere`,
`interruptionEligibility`, `recentInterruptionSourceSql`, the backlog
age constants, and the Blocked-ownership check the fallback uses). The
fallback re-exports the public names. The fallback file goes from 992 to
about 900 lines.
- Eligibility: the backlog pass now continues a system-owned setup
failure of a run that did provider work
(`executionRecovery.providerWorkStarted` is not `false`) whose files are
held for saved-work recovery or were recovered by it. A failure before
provider work, a person-owned code, and an exhausted saved-work recovery
keep their Retry.
- `expediteFreshContinuationChecks` (fallback module): makes the run's
pending `exact_recovery_pending` checks due now and wakes the
execution-disposition worker. `firstPendingAt` is kept, so the wait
bounds do not reset. `workspace-recovery.ts` calls it in the transaction
that completes saved-work recovery.
- `continueHeldExecutions` records its check in the same transaction as
the decision. A saved-work completion on the same hold then waits for
that commit, so its expedite cannot be overwritten by a stale future
check.
- `runsAwaitingSystemContinuation` (eligibility module): the held
records the backlog pass will continue by itself: same predicates,
system eligibility only, no person's wait recorded, no pending question
or approval, and a Blocked status that the failure owns (the same check
the fallback makes).
- `task-interruption-presentation.ts`: such a run shows
`freshContinuation: continuing` (system-owned, `working`, no Retry). A
pending Retry of that run keeps its own wait message. A task at the
hourly cap keeps `retry_scheduled`.
- Tests:
- New `setup-failure-after-work-continuation.test.ts` (embedded
Postgres, real saved-work recovery): the full sequence, plus no-work and
person-owned cases.
- `fresh-continuation-fallback.test.ts`: eligibility, expedite, the
completion-during-decision ordering, the cap presentation, and the
exhausted case.
- `fresh-continuation-schedule-queries.test.ts`: the oracle predicate
gets the same clause, and the fixture includes `setup_failed`.
## Verification
- Red/green:
`server/src/services/setup-failure-after-work-continuation.test.ts`,
"continues in a fresh run as soon as its saved work is recovered, and
never offers Retry". The sequence: a run with work fails setup, a
restore hold is recorded, the disposition pass runs, real saved-work
recovery completes, the disposition pass runs again, continuations are
delivered. The task view is checked at each step. On master the first
check fails (`state: "failed"`). With the fix every step shows
`responsibility: system, state: working, canRetry: false`. The successor
is created less than 5 s after the decision, with `previousRunId` and
`forceFreshSession`.
- `setup-failure-after-work-continuation.test.ts` "leaves a setup
failure before any provider work on its Retry path" guards the
provider-work gate.
- Red/green: `fresh-continuation-fallback.test.ts` "continues a setup
failure of a run that already did work once its saved work is recovered"
(master: not selected, 0 continued).
- `fresh-continuation-fallback.test.ts` "keeps a setup failure whose
saved-work recovery is still under way ...": the check waits, then the
expedite makes it due at once and the next pass continues.
- `pnpm verify` (selected files) and focused runs:
`fresh-continuation-*`, `task-interruption-*`, `workspace-recovery-*`,
`runner-lost-mid-turn-continuation`,
`heartbeat-native-remote-failure-retention`, `assigned-work-invariant`.
Recovery latency for this class, from saved-work completion to the new
run:
- Before: 10 min 2 s (the 10-minute pending bound).
- After: the next disposition pass, which the completion wakes. The
worker is throttled to one pass per 15 s, so the bound is 15 s. The test
asserts under 5 s. End to end from the failure, add the saved-work
recovery time (7 s in the observed case).
## Risks
- More tasks continue automatically: every system-owned setup failure of
a run that did provider work and whose files were saved, also when the
provider turn was in flight. The fresh run never replays the old turn.
Its opening context names the cut-off run and asks the agent to check
unverified actions before it repeats them. This is the same contract as
restart-class interruptions.
- The per-task cap (6 continuations per rolling hour), the per-server
backlog pacing (10 per minute) and the aggregate automatic-run brake are
unchanged and apply to these continuations. Judge the change by
company-wide automatic run starts per hour and their success rate.
- The task view predicts the fallback's decision from the same
predicates and Blocked-ownership check. A rarer refusal (for example a
dependency wait) can show "continuing" until the next disposition pass
records it, then Retry shows.
- The task view runs one more bounded query when listed tasks have an
unfinished latest run.
- No schema change. Records saved by the previous release are read the
same way. No work is added before `turn.start`.
> 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 (`claude-opus-5-5`), Anthropic. Agentic coding with
tool use (shell, file edits, test runs) in Claude Code.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Automatic task recovery continues a task when its run ends for a
reason that is not a person's to fix
> - A continuation or recovery run can itself fail before it does any
work: a sandbox create timeout, a full sandbox disk, a lease mismatch, a
provider pack check, or a database deadlock
> - Today the stranded reconciler treats such a failure as non-retryable
and blocks the task for the board. The assigned-work sweep then leaves
the board hold alone, because its list of temporary causes is a short
allow-list. The held backlog pass uses a similar allow-list. Nothing
continues the task, and it shows "failed, Retry"
> - This pull request makes the cause test "not owned by a person" on
these paths, and routes a failed continuation run back through the
fresh-continuation fallback
> - The benefit is that such a task continues from its saved work, under
the existing hourly cap, and nobody needs to press Retry
## Linked Issues or Issue Description
**What happened?**
A task was continued automatically after an interruption. The
continuation run failed during setup, before any provider turn (for
example `setup_failed` with a sandbox HTTP timeout). The stranded
reconciler then set the task to `blocked` with a board-owned recovery
hold. The assigned-work sweep left the task to that hold, and the
fresh-continuation fallback never owns that hold kind. The task stayed
blocked and showed a Retry button. Settled holds whose run was a
recovery run that failed with `adapter_failed`, `setup_failed` or a
provider pack error stayed in the same state, because the held backlog
pass accepted only restart-class codes.
**Expected behavior**
A run that ends for a reason a person does not own is continued again
from saved work. The continuation goes through the fresh-continuation
fallback, so the old workspace epoch is fenced or a new isolated
workspace is used. The per-task limit of 6 automatic continuations per
hour still applies. At the limit the task waits for the next window and
is not blocked.
**Steps to reproduce**
1. Record a fresh continuation for an interrupted run of an
agent-assigned task.
2. Let the continuation run fail with `setup_failed` before provider
work.
3. Run the stranded reconciler. The task becomes `blocked` with a board
hold.
4. Run the assigned-work sweep. It returns `left_to_hold_owner`. No
continuation follows.
**Paperclip version or commit**
master at 6917d0568d
**Deployment mode**
Hosted (two servers can run at once during a deploy)
## What Changed
- New `continuation-cause.ts` holds the cause classification:
`PERSON_OWNED_FAILURE_CODES` (moved, unchanged), a new short list
`PERMANENT_FAILURE_CODES` (low-trust boundary codes,
`adapter_engine_unavailable`, `agent_not_invokable`, `agent_not_found`,
`agent_interaction_delivery_denied`), `isSystemOwnedFailureCode`, and
`isAutomaticContinuationRun` (a retry, scheduled retry, fresh
continuation, sweep or recovery run; never a person's Retry).
`fresh-continuation-fallback.ts` re-exports what callers use.
- `stranded-hold-continuation.ts`: the sweep continues a recent (24
hours) board hold when the failure cause is system-owned, not only for a
short allow-list. A reusable sandbox resume failure still needs a
transient cause.
- `recovery/service.ts`: the stranded reconciler does not escalate an
agent-assigned `todo` or `in_progress` task to the board when its latest
run was an automatic continuation or recovery run that ended within 24
hours with a system-owned cause. The assigned-work sweep owns that task.
A person's Retry, a person-owned cause, a permanent cause, or an older
failure escalates as before.
- `assigned-work-sweep.ts`: for a failed automatic continuation run, the
sweep asks the fresh-continuation fallback first. A recorded
continuation is the repair (fenced epoch or new isolated workspace). On
the fallback's hourly backoff the sweep records "not started" with the
retry time and keeps the task unblocked. While exact recovery still
waits, it records the retry time. A person-owned reason from the
fallback is written on a refused attempt.
- `task-automatic-attempts.ts`: the shared 6-per-hour ledger also counts
`server_restart` and `interrupted_preparation` scheduled retries, so the
sweep cannot add attempts on top of those lanes in the same hour.
- `fresh-continuation-fallback.ts`: the held backlog pass also accepts a
source run that was an automatic continuation or recovery run with a
system-owned code (24 hours, 5 per pass, 10 per minute unchanged). With
no hold to carry a pending check, a wait is measured from the source
run's end, so it is bounded.
- `fresh-continuation-fallback.ts`: rechecks the cause with the shared
classifier and applies the shared hourly cap inside the task lock. A
continuation keeps the old writer's workspace unless a wait was actually
cut short (bound measured from a recorded check, or a wait skipped).
- New test file `failed-continuation-continues-again.test.ts` (15
tests).
### Changed test expectations
- `interrupted-preparation-hold-settle.test.ts`, "bounds repeated lost
leases before provider work" (both cases): the lane cap still holds (2
and 12 successors). The end state is no longer `blocked`: the task keeps
its status, no further run exists, and the sweep returns a deferral with
a future retry time (`deferred_cap` at 12 ledger attempts,
`deferred_rate_limit` spacing at 2). The fixture now settles the
scheduled wakes and retry times the loop leaves behind, so the sweep
reads the real state. A person's Retry is still accepted.
- Same file, "blocks the task when a replaced preparation's lane is
spent" is renamed "leaves the task to the assigned-work sweep, not
blocked, when a replaced preparation's lane is spent". It still expects
no successor run, and now expects `todo` with no active hold.
- `heartbeat-process-recovery.test.ts` and `task-retry.test.ts`: no
change. Their runs either ended months before (outside the 24-hour
window) or were a person's Retry, so they escalate as before. The bound,
no-duplicate, and redaction tests keep their assertions.
## The one classifier
`continuation-cause.ts` `continuesAutomatically(run)` (and its SQL twin
`continuesAutomaticallySql`) decides whether a failed run continues on
its own:
- the cause is system-owned: not in `PERSON_OWNED_FAILURE_CODES`
(unchanged), not in the new `PERMANENT_FAILURE_CODES`, not an external
execution whose stop cannot be confirmed (Dot and Muse, the same rule
the retry scheduler uses to decline them permanently), and a reusable
sandbox resume failure only with a transient cause; and
- the run was an automatic continuation or recovery run (a scheduled
retry, a recovery wake, a fresh continuation; never a person's Retry),
or a first run that ended with a restart-class code or a transient setup
failure before provider work (the pre-existing allow-list for the
backlog and the board-hold takeover).
A person's failed Retry keeps master's outcome at every entry point: the
classifier never treats it as an automatic run. Whether it should
continue on its own is a separate product decision.
## Every entry point and the cap it uses
Shared cap = `sharedContinuationAttempts` in
`recovery/continuation-ledger.ts`: 6 per task per rolling hour, counting
fresh continuation records, settled sweep wakes, and transient, restart
and preparation retries. Only attempts that started or created a run
count.
- Disposition pass (`settleUnrecoverableExecutions` to
`continueFreshInTransaction`): cause test of the classifier and the
shared cap, inside the fallback under the task lock. Run kind is not
required on this path: it handles fresh failures of any run.
- Held backlog (`continueHeldExecutions`): `continuesAutomaticallySql`
in the listing; then the fallback's cause test and shared cap. Pacing 5
per pass, 10 per minute, 24 hours.
- System continuation wake in the queue (`heartbeat/queue.ts`,
unchanged) to the fallback: cause test and shared cap.
- Dispatch refusal (`run-dispatch` Postgres adapter, unchanged) to the
fallback: cause test and shared cap.
- Sweep board-hold takeover (`strandedHoldContinuesAutomatically`):
`continuesAutomatically`, 24 hours.
- Sweep route to the fallback (trigger `assigned_work`): recovery run
with a system-owned cause, then the fallback's cause test and shared
cap; the sweep claim also applies its ledger.
- Old reconciler deferral (`assignedWorkSweepOwnsFailedRun`): automatic
run with a system-owned cause (`canContinueRecoveryRunAutomatically`),
24 hours. First runs keep their existing escalation and budgets.
- Sweep plain wake (unchanged path, for first runs): the sweep claim
ledger (`taskAutomaticAttempts`: started sweep attempts, scheduler
retries, and fresh records from other paths), spacing from every
attempt.
## Self-review: places where the rule still differs, on purpose
- The fallback's fresh path continues a first run with any system-owned
cause, while the backlog limits first runs to restart-class and
transient setup codes. The backlog limit is the existing herd rule for
records older releases left behind.
- The fallback treats a pending question as a person's wait; the sweep
treats a question asked before a person's Retry as superseded. In that
one shape the sweep sends its ordinary wake, as before.
- The scheduler lanes (transient, restart, preparation) keep their own
bounds and do not read the shared cap before scheduling; their runs
count in it, so every other path stops once they fill the hour. Changing
the scheduler is outside these files.
- The sweep's plain wake path does not test the cause; it relies on the
invariant's waiting reasons, as before.
## Waits and their bounds
- Every exact-recovery wait in the fallback (settling execution, native
finalizer, live controller lease, preparation lane, saved-work recovery,
workspace restore owner, retained-source check, previous local process):
it starts at the first recorded pending check on the run's hold. When no
check is recorded (no hold, a hold nobody checks, or a replaced record),
it starts at the source run's end (`finished_at`, a database row that
every server reads the same). Bound: 10 minutes idle, 15 minutes while
the owner shows progress, 30 minutes while saved-work recovery advances.
Then the fallback continues from saved work.
- A source run that ended more than 24 hours ago with no recorded check
does not wait: the fallback answers `retry_needed` (the existing named
state that leaves an old hold for a person's Retry), so nothing waits
silently and the 24-hour rule holds.
- The sweep on a fallback backoff: waits until the oldest continuation
leaves the hour (6 per task per hour), task stays unblocked.
- The sweep while exact recovery waits: rechecks at the fallback's retry
time (at most 4 minutes), until the bound above.
## Decisions on permanent causes
- `PERSON_OWNED_FAILURE_CODES` is not changed. A separate
`PERMANENT_FAILURE_CODES` list keeps causes that cannot heal by
themselves out of the new automatic paths, so they still block and tell
a person. `repository_catalog_unavailable` was transient in the old
allow-list too; in the failing Retry test it was a person's Retry, which
the reconciler still escalates.
## Verification
- `failed-continuation-continues-again.test.ts`: 28 tests, including a
12-case table (person's Retry, automatic continuation, first assignment;
a person's Retry gets master's outcome everywhere) x (setup failure,
restart code, permanent code, person-owned code) through the backlog,
the sweep takeover and route, and the reconciler, and a test that
waiting checks spend no attempt (red before the fix for the first-run
case and for the cap); earlier: 15 tests (the latest three added
red-first: permanent codes and a person's Retry stay blocked on the
backlog; no entry point continues a person-owned or permanent code; six
mixed attempts stop the backlog until the next window; plus a pin that
the ledger uses the restart lane's window, cap and reason). Earlier:
Before the fix, the 10 behavior tests failed for the expected reasons
(board escalation, `left_to_hold_owner`, no backlog continuation,
endless wait with no hold, endless wait on an unchecked hold at 20
minutes and 30 hours, checked alternately by two sweep instances). The
person-owned guard passed before and after. After: 11 of 11 pass. After
the last change, alone: `fresh-continuation-fallback.test.ts` 72/72,
`fresh-continuation-move-forward-offer.test.ts` 14/14,
`assigned-work-invariant.test.ts` 31/31,
`interrupted-preparation-hold-settle.test.ts` 29/29.
- Locally after the change, one file at a time:
`assigned-work-invariant.test.ts` 31/31,
`recovery/assigned-work-invariant.test.ts` 50/50,
`interrupted-preparation-hold-settle.test.ts` 29/29,
`task-retry.test.ts` 117/117, the 10 previously failing
`heartbeat-process-recovery.test.ts` tests 12/12 (filtered run),
`fresh-continuation-fallback.test.ts` 66/72 in a loaded run with 6
timeouts at 30 to 90 s that pass alone (8/8 filtered).
- `tsc --noEmit` for `server`: clean.
- CI supplies the full suite.
## Risks
- Behavior change: a recent failure with a cause outside the
person-owned list is no longer escalated to the board by the stranded
reconciler. The sweep continues it instead, at most 6 times per hour per
task, then once per window. Some codes outside that list may be
configuration a person must change (for example `low_trust_*`,
`adapter_engine_unavailable`, `agent_not_found`). Such tasks now retry
at the capped pace instead of blocking. The person-owned list is not
changed in this pull request.
- Upgrade: tasks blocked by an older release with a board hold for such
a cause, within 24 hours, are continued by the sweep on its first
passes. The sweep's 10 repairs per minute per process, the delivery
pacing, and the hourly cap bound the burst.
- Two servers: the sweep's claim and the fallback each run under the
task row lock, and the fallback is idempotent per source run.
## Model Used
- Claude Fable 5.2 (Anthropic), via Claude Code with tool use and code
execution.
## 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 Fable 5.2 <noreply@anthropic.com>