Files
PaperClipAI/server
DottaandClaude Fable 5.2 3f030971dc fix(recovery): deliver a recorded continuation as the person's Retry run, keeping its isolation (#21378)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When Paperclip cannot resume a cut-off run exactly, the
fresh-continuation fallback records a continuation for the task. A
delivery pass later starts it as a run. Staging shows this pending state
can last 30 to 110 minutes for backlog items.
> - The fallback also decides how the next run is isolated from the old
writer. For `fresh_isolated_workspace`, the next run must prepare a new
workspace.
> - A person's Retry pressed while the continuation was recorded but not
yet delivered started its own run at once. That run did not carry the
recorded isolation, so it could use the shared directory next to a
writer that is not proven stopped. It also did not carry the
continuation's recovery context.
> - This pull request makes wake admission deliver the recorded
continuation as the person's run, under the task lock. It also folds a
saved Retry into a delivered continuation for every record kind.
> - The benefit is one run per interruption, whatever arrives first, and
the recorded isolation decision is never lost.

## Linked Issues or Issue Description

Refs #21348

**What happened?**
A person's Retry (`requestTaskRetry` + `resumeTaskRetry`), pressed while
a fresh continuation was recorded but not delivered, was admitted at
once as an ordinary `task_retry` run. That run had no
`freshContinuationIsolation` and no `recoveryActionId`. On a projectless
task the run used the shared directory that the fallback had decided to
isolate from. The later delivery pass marked the continuation as
superseded by that run. The reproduction showed exactly one run, so the
reported "two runs" did not happen in that order. The isolation was lost
for all three record kinds tested. For `writer_ended` and native
records, a Retry saved before delivery was not folded into the delivered
continuation, because the fold only covered `fresh_isolated_workspace`.

**Expected behavior**
With a recorded, undelivered continuation, the next run admitted for the
task is that continuation. It has the recorded isolation and the
person's Retry is recorded as answered by it.

**Steps to reproduce**
1. Record a fresh continuation (`ensureFreshContinuation`, delivery
`recorded`) for a projectless task whose legacy writer is on another
host.
2. Call `requestTaskRetry` and then `resumeTaskRetry`.
3. Before this change: one `task_retry` run without
`freshContinuationIsolation` or `recoveryActionId`, while the record is
still `pending`.

## What Changed

- `fresh-continuation-retry-fold.ts`:
- `undeliveredContinuation` reads the task's pending fresh-continuation
record under the task lock (`for update`). It returns nothing when a run
of the task was created after the record.
- `undeliveredContinuationContext` gives the run the continuation's
`recoveryActionId`, `retryOfRunId`, `forceFreshSession` and, for
`fresh_isolated_workspace`, `freshContinuationIsolation`.
- `deliverContinuationAsRun` marks the record `delivered` to the new run
in the same transaction, settles its coalesced holds, and folds other
waiting Retries.
- `foldWaitingRetriesIntoRecordedContinuation` folds a waiting Retry
into any delivered fresh continuation, not only an isolated one.
- `heartbeat/queue.ts` (wake admission, issue transaction): a
non-system, non-delivery wake with no execution blocker takes the
pending continuation. The run is inserted as before, then delivered as
the continuation. The fold after a delivery wake now applies to every
fresh-continuation kind. No change to ranking or to the claim loop.
- `execution-recovery-resolution.ts`: the delivery pass folds a saved
Retry for every fresh-continuation kind. The superseded-run fold keys on
`recoveryActionId`.
- The person's run keeps its `task_retry` wake reason and the user's
wake receipt, so the existing #21349 rules rank it as person work.
- Limits: the person-triggered delivery does not spend an automatic
attempt. It adds no `issue.continued_automatically` entry and no
scheduled transient retry, and it is not gated by the hourly cap or by
delivery-pass pacing. The record itself was already counted when it was
recorded. The agent's concurrency limit still applies at claim time.

## Verification

New file
`server/src/services/fresh-continuation-retry-delivery.test.ts`, with 12
tests. All cases cover `fresh_isolated_workspace`, `writer_ended` and
native (`remote_epoch`) records, through the real `requestTaskRetry` +
`resumeTaskRetry` path:
- A Retry during pending delivery gives exactly one run. That run is the
continuation, carries the recorded isolation (the workspace readiness
reads `fresh_isolated_workspace`), coalesces the Retry, and ranks as
person work. Later delivery passes add nothing.
- Delivery first, then a saved Retry: one run, and the Retry is
coalesced. A Retry on the delivered run joins it through the busy path.
- A Retry and two delivery passes race (concurrent transactions): one
run.
- After the continuation's own failure, a Retry gets its own run.
- The delivery pass is held by pacing (backlog source, agent queue
full), and the hourly cap and the shared attempt ledger are exhausted.
The person's Retry still starts the run.

Red before the fix: 8 of 12 failed. Green after: 12 of 12.

Local runs, one file at a time:
- `fresh-continuation-fallback.test.ts`: 71 of 72. The failure is "runs
a person's Retry pressed before delivery…", a deadlock in `afterEach`
truncate. It passes alone, and it fails the same way on unmodified
master under this machine's load.
- `__tests__/recovery-wake-herd.test.ts`: 29 passed
- `__tests__/execution-control-work.test.ts`: 27 passed
- `__tests__/issue-recovery-actions.test.ts`: 112 passed
- `workspace-recovery-fallback.test.ts`: 19 passed
- `heartbeat/queue.test.ts`: 101 passed
- `task-retry.test.ts`: 117 passed;
`legacy-preparation-retry-hold.test.ts`: 5 passed
- `server` `tsc --noEmit`: clean

## Risks

- A person's message, chat input or manual wake that arrives while a
continuation is pending also becomes that continuation, with a fresh
session and the recorded isolation. Before, such a wake ran without
isolation and superseded the record. This is the same rule for every
admission path, and it closes the shared-directory gap there too.
- A wake that takes the context and is then deferred by a later gate can
keep the isolation marker in its saved context. If the record is
delivered meanwhile, that later run prepares a new isolated workspace.
That is the safe direction.
- No schema change and no migration. Nothing is added before turn start
for healthy runs: the new read runs only at wake admission.

> 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 (Anthropic), Claude Code agent with tool use (shell, file edit,
test runs). Model ID `claude-opus-5-5`.

## 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
- [ ] I have updated relevant documentation to reflect my changes (no
documented behavior or command 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>
2026-11-13 07:13:49 -06:00
..