Files
806440d12c feat(runner): relaunch a released task as the next run after a restart (#22343)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - An environment plugin can keep a warm task for an agent session.
After each turn, Core releases the task's Runner, and the next run of
the session resumes it
> - #22288 added `resumeIdentityVersion: 1`: for a provider that stops a
released Runner, Core rotates the session to the next run and the
provider starts the Runner again directly as that run
> - Core takes that path only while it still holds the released session
in memory. After a Core restart, it recovers the released task through
the older hand-off: it resumes the task as the previous run, then
switches the Runner's authority to the new run
> - So a provider that advertises the capability still has to keep the
hand-off for every follow-up after a Core restart, and cannot drop it
> - This pull request makes restart recovery take the same path when the
provider advertises the capability
> - The benefit is that a provider with the capability gets one start
shape for a released task, before and after a Core restart, and can
retire the hand-off

## Linked Issues or Issue Description

Follows #22288.

**What existing behavior does this improve?**

The first run of a warm plugin session after a Core restart, when its
task was released and its provider advertises `resumeIdentityVersion:
1`.

**Subsystem affected**

The native session executor and the plugin Runner task owner.

**Current behavior**

After a restart, Core finds the released source on disk
(`inspectRemoteWarmSessionRecovery`), creates a backend that adopts the
task, and calls `recoverSession`. The task owner calls `resume` without
`runner`, the provider starts the Runner as the previous run, and Core
hands it to the new run.

**Proposed behavior**

When the provider advertises the capability, Core recorded the build the
task was released on, the process configuration is unchanged, and the
session is not moving to another task, Core treats the recovery like a
cached released session. It revalidates the recovery, loads the warm
checkpoint, and opens a new backend on the same task with
`relaunchReleased`. A new task owner takes over the submitted task
without adopting a Runner process, prepares the claimant run with the
released source as `priorIdentity`, and calls `resume` with `runner`.
Every other recovery keeps the hand-off.

**Reason and benefit**

A provider that advertises the capability no longer needs the hand-off
for its own tasks, after a restart or not.

## What Changed

- Executor: a remote warm recovery with a released source, a recorded
build, a reusable process configuration and no session move, on a
provider that advertises the capability, revalidates the recovery and
becomes a relaunch: `relaunchReleased` with the released source and
build, the warm checkpoint, and no `remoteWarmRecovery` for the backend.
The startup context ends as for a cached relaunch.
- Executor: the relaunch's task owner can now come from the new backend
(`onPluginTaskOwner`), so the unavailable-reuse fallback and the
rotation revert work without a retained owner. Without an owner, no
relaunch can have started, so the revert applies.
- Backend: a relaunch neither stops a resumed task that has no durable
binding nor resolves a `resumeFrom` task.
- Task owner: an owner created with `relaunch` and the capability takes
over an already submitted task, as an adopting owner does, but adopts no
process: its prepare sends the released source as `priorIdentity`, and
its launcher calls `resume` with `runner`.
- `doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md`: Core prepares the claimant
run before the resume, also after a restart, and a provider must accept
that prepare without state kept in memory.

## Verification

- `server`: `npx vitest run
src/services/native-runtime/plugin-runner-release-resume.integration.test.ts`:
new `adopted restart relaunch` cases for Codex and Claude, with real
runnerd processes. Core restarts while the task is released; the next
run relaunches the task as itself, with no claim, one inspection and no
second submit. The existing `adopted relaunch` case now relaunches both
follow-ups, since the idle close also recovers through this path.
- `server`: `plugin-runner-task.test.ts`: a new owner relaunches without
submitting or adopting, and prepares with the released source; without
the capability it prepares a new task.
- `server`: `plugin-runner-release-resume.integration.test.ts` and
`plugin-runner-eviction.integration.test.ts`: 61 passed.
`native-session-executor.test.ts`: 1535 passed, 7 skipped.
`plugin-runner-task.test.ts`: 118 passed.
- Typecheck: `server` passes.
- Red-green: with the executor lane turned off, both `adopted restart
relaunch` cases fail. Without the task owner change, the new-owner
relaunch test fails.

## Risks

- Only providers that advertise `resumeIdentityVersion: 1` see a change.
Recovery without a recorded build, with a changed process configuration,
or for a session moving to another task keeps the hand-off.
- The provider sees a `prepare` for the claimant run on a released task
right after a Core restart. A provider that tracked unclaimed released
tasks only in memory must handle that prepare (the doc now says so).
- A Core restart in the middle of this path is still not qualified, as
for the cached relaunch.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use
(code search, editing, local test runs).

## 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: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 11:20:48 -08:00
..