mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Native runs execute a provider turn, then close the provider session
and prove it stopped
> - When close cannot prove that the old runner, provider and tools
stopped, the runner holds a cleanup gate
(`native_session_cleanup_quarantined`) that refuses the next session on
that task
> - A run finished its provider turn and saved its work. A server
restart had left one tool callback without a saved result, so close
could not prove the drain, and the gate refused the run's own same-run
recovery 30 seconds later
> - The task then showed "Couldn't finish this attempt" with a Retry
button, but the retry route refuses this error code with 409. The saved
error text told an operator to act
> - This pull request makes the task projection, the execution blocker,
the executor and the retry route agree, and replaces the operator text
with plain wording
> - The benefit is that finished work no longer looks like a failed
attempt, and the UI never offers a Retry that the server refuses
## Linked Issues or Issue Description
**What happened?**
A remote native run completed its provider turn and saved its comments
and documents. A server restart during the turn left one semantic tool
callback without a saved result. Session close then reported
`native_session_settlement_incomplete` (runner suspended, provider drain
unproven), and the runner kept an operator-required cleanup gate. The
same-run disposition recovery was refused at admission, and the run
ended `failed` with `native_session_cleanup_quarantined`.
**Expected behavior**
The task should show its real state (here, waiting on a child task). It
should not show a failure banner or a Retry that the server refuses. No
text should ask an administrator to act.
**Steps to reproduce**
1. Start a remote native run and restart the server while a tool
callback runs.
2. Let the resumed turn complete without a semantic result, so a
same-run recovery is scheduled.
3. Observe the refusal at admission, the "Couldn't finish this attempt"
banner, and a Retry that returns 409.
**Paperclip version or commit**
master at d0057ee384 (remote native runner, Daytona sandbox).
## What Changed
- Add `server/src/services/native-runtime/completed-turn-cleanup.ts`. It
holds one predicate for "a cleanup-gate refusal after this run's own
provider turn completed" and the plain user wording. It reads only the
saved `errorCode` and `runnerProfileJson.sessionCheckpoint`.
- `task-interruption-presentation.ts`: the projection never sets
`canRetry: true` for a cleanup-quarantined run, which matches
`routes/agents.ts` and `canRetryStoppedRun`. A quarantine after a
completed turn projects as `resolved` only while the task waits on
unresolved blocker tasks, so the task shows that wait. Without such a
wait, the missing task disposition stays visible. Other quarantined runs
show a plain settling message without Retry. The list query computes the
completed-turn fact in SQL.
- `native-session-executor.ts`: the refusal keeps its permanent, named
code, its hold and its ownership, and does not replay provider work. The
next action uses plain wording, and names the saved work after a
completed turn.
- `execution-blocker.ts`: show plain wording for this code instead of
the stored error text, also for rows that earlier releases saved.
- Runner error message and retry-route conflict message use plain
wording.
- `doc/execution-semantics.md`: document how the cleanup gate settles
and how the task shows it.
## Verification
- Red before the fix, green after:
- `server/src/services/task-interruption-presentation.test.ts` "native
cleanup quarantine presentation" (2 failed before: `canRetry: true`,
`state: failed`).
- `server/src/__tests__/task-interruption-query.test.ts` "reads a
quarantine saved after a completed turn as settled work" (real Postgres,
row in the previous release's saved shape; before: `state: failed,
canRetry: true`).
- `server/src/services/native-runtime/native-session-executor.test.ts`
"settles a cleanup refusal after a completed turn" (before: operator
next action and board ownership).
- `server/src/services/explicit-native-continuation.test.ts` "shows
plain wording for a cleanup refusal saved with the earlier operator
text" (before: stored operator text).
- The four files pass in full: 1851 tests.
- `tsc --noEmit` passes for `server` and `packages/paperclip-runner`.
- `pnpm verify` returns exit 2 (a global doc input changed), so required
CI supplies the broad coverage.
- No UI files changed, so token gates and UI tests do not apply.
## Risks
- Previous-release story: no persisted shape changes. Runs that earlier
releases quarantined carry forward. The new rules read existing fields,
so these runs show the new projection without a migration.
- The code stays permanent and named. No automatic provider replay is
added.
- A quarantine whose turn did not complete keeps its board-owned
recovery. Only its text and its Retry visibility change.
- The runner still keeps the in-process cleanup gate until environment
release proves the stop. Existing lease termination receipts
(`acknowledgeRemoteStop`) clear it. This PR does not change the runner
drain rule for a callback that a restart orphaned. That is a separate
follow-up.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through 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 Opus 5.5 <noreply@anthropic.com>
51 lines
2.6 KiB
TypeScript
51 lines
2.6 KiB
TypeScript
/**
|
|
* A native run can finish its provider turn and then be refused by the
|
|
* runner's cleanup gate: the previous session's shutdown is still unproven
|
|
* (`native_session_cleanup_quarantined`). The work of that turn is already
|
|
* saved. Cleanup settles on its own once the environment proves the old
|
|
* runner, provider and tools stopped (lease release and termination receipts,
|
|
* see `acknowledgeRemoteStop` in heartbeat/run-control.ts). It is not a failed
|
|
* attempt and it never needs an administrator.
|
|
*
|
|
* Every rule here reads only fields earlier releases already persisted
|
|
* (`errorCode` and `runnerProfileJson.sessionCheckpoint`), so runs quarantined
|
|
* before this change are classified the same way without a migration.
|
|
*/
|
|
|
|
export const NATIVE_SESSION_CLEANUP_QUARANTINED = "native_session_cleanup_quarantined";
|
|
|
|
/** Plain wording for the cleanup gate. It names no person who must act. */
|
|
export const NATIVE_CLEANUP_SETTLING_MESSAGE =
|
|
"The previous session is still shutting down. Your work is saved, and Paperclip finishes the cleanup automatically.";
|
|
|
|
/** Shown for a quarantined run whose provider turn had already completed. */
|
|
export const NATIVE_COMPLETED_TURN_CLEANUP_MESSAGE =
|
|
"This run finished its work and saved it. Paperclip finishes the session cleanup automatically. Send a message to continue; it starts once the previous session has stopped.";
|
|
|
|
const record = (value: unknown): Record<string, unknown> =>
|
|
value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
|
|
|
|
/** The run's own saved checkpoint records a completed provider turn and no
|
|
* turn still active. Only the checkpoint saved for this exact run counts. */
|
|
export function nativeCheckpointRecordsCompletedTurn(runnerProfileJson: unknown, runId: string): boolean {
|
|
const checkpoint = record(record(runnerProfileJson).sessionCheckpoint);
|
|
const terminal = record(checkpoint.terminal);
|
|
return record(checkpoint.identity).runId === runId
|
|
&& (checkpoint.activeTurnId === null || checkpoint.activeTurnId === undefined)
|
|
&& terminal.turnTerminalState === "completed";
|
|
}
|
|
|
|
/** A failed native run whose only failure is unproven cleanup after its
|
|
* provider turn completed. Its work is done; it is not an attempt to retry. */
|
|
export function isCompletedTurnCleanupQuarantine(run: {
|
|
id: string;
|
|
runtimeMode?: string | null;
|
|
status?: string | null;
|
|
errorCode?: string | null;
|
|
runnerProfileJson?: unknown;
|
|
}): boolean {
|
|
return run.runtimeMode === "native" && run.status === "failed"
|
|
&& run.errorCode === NATIVE_SESSION_CLEANUP_QUARANTINED
|
|
&& nativeCheckpointRecordsCompletedTurn(run.runnerProfileJson, run.id);
|
|
}
|