## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A native Runner agent keeps a warm provider session per task. A
follow-up run on the same task can reuse that session and its managed
instruction directory.
> - When a follow-up run cannot resume the saved session (for example,
the effective run configuration changed), it first reserves the prior
owner's instruction directory. Then it starts a new session identity and
must retire the prior owner.
> - Retirement treated the run's own directory reservation as another
executor's busy turn. The run failed at startup with
`native_session_supervisor_busy`.
> - That failure happened after the remote workspace was prepared, so
failure handling retained the sandbox and blocked the task. A board
follow-up comment left the task `blocked` with no agent progress.
> - This pull request lets a run retire the prior owner that it reserved
itself, and keeps the directory that it adopted. Any other reservation
or turn is still busy.
> - The benefit is that a follow-up on a task with a rotated session
runs once, and the task does not become blocked.
## Linked Issues or Issue Description
**What happened?**
A board follow-up comment with reopen woke an agent on a task that had
just finished a successful run. The new run reused the task's own
sandbox. The saved session could not resume because the effective run
configuration changed, so the run started a new session identity. At
startup (right after the native execution claim) the run failed with
`native_session_supervisor_busy`. The run got the error code
`native_continuation_requires_reconciliation`, the sandbox was retained
for workspace repair, and the task became `blocked`.
The agent had another live run on a different task at the same time.
That run used a different sandbox and a different workspace, so it was
not the cause. The busy owner was the task's own prior warm session. The
new run had reserved that session's instruction directory itself
(`reserveWarmNativeInstructionDirectory` sets `preparingRunId` to the
new run). `retireSupersededWarmNativeSessions` then saw `preparingRunId`
and rejected the run.
**Expected behavior**
The follow-up run retires the prior warm owner of its own task, keeps
the instruction directory it adopted, starts the new session, and runs
once. The task does not become blocked.
**Steps to reproduce**
1. Run a native Runner (Codex app-server) task to completion with a warm
session and a managed instruction directory.
2. Change the agent's effective run configuration, so the saved session
cannot resume.
3. Wake the same task again (for example, a board comment with reopen).
4. Before this change, the run fails at startup with
`native_session_supervisor_busy` and the task becomes blocked.
**Paperclip version or commit**
Observed on staging at `7fd05e13`. The code is unchanged on `master`.
## What Changed
- `retireSupersededWarmNativeSessions` now receives the current run id.
When the prior owner of the same task (same logical owner scope) is
reserved by this run (`preparingRunId === runId`), retirement continues
instead of throwing `native_session_supervisor_busy`.
- That retirement closes the prior owner with
`preserveInstructionsForRunId`, so the directory that this run adopted
is not collected. This matches the existing configuration-change branch
in warm reuse.
- After a successful close, the reservation is cleared. A failed close
keeps the reservation, so its `release()` retries retirement as before.
- A reservation by any other run, a busy owner, and an executing scope
still throw `native_session_supervisor_busy`.
## Verification
- Red before the fix, green after
(`server/src/services/native-runtime/native-session-executor.test.ts`,
"managed directory warm checkpoints"):
- "retires its own reserved directory owner when the session identity
rotates": before, the run rejected with
`native_session_supervisor_busy`. After, the prior owner closes once,
the new session runs once, the adopted directory is not collected during
retirement, and it is collected once when the new owner retires.
- "retires its own reserved directory owner after the Runner claim when
the session identity rotates" (the production `useRunnerd` path, where
retirement happens after the claim): before, admission rejected with
`native_session_supervisor_busy`. After, admission retires the prior
owner and keeps the adopted directory.
- Safety case (green before and after): "still rejects a session
identity rotation over another run's directory reservation". The
provider does not start and the other run's owner is not closed.
- Existing safety case (green): "does not retire an active turn when a
new session identity arrives".
- `npx vitest run
src/services/native-runtime/native-session-executor.test.ts
src/services/heartbeat/instruction-working-copy`: 1163 passed.
- Staging evidence was read only. This change is not deployed.
## Risks
- Low risk. The change applies only when the prior owner has the same
logical owner scope (company, agent, task, workspace, environment) and
its reservation names the current run. That reservation exists only
after this run validated reuse of the prior directory.
- The claim-path instruction copy (`claimWarmNativeInstructionCopy`,
which sets `busy`) is unchanged. That path is not used by Codex
app-server agents.
- Two related points are unchanged and are out of scope here: a startup
failure after the workspace is prepared still retains the sandbox and
blocks the task, and the "Instruction edits could not be recovered"
warning on that failure is advisory only. With this fix, this flow no
longer reaches that failure.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use (shell,
file edits, browser read of staging run records) 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
- [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
Refs #18893 (shared-sandbox ingress retirement). Refs #19143
(workspace-busy wait).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
