mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 16:29:42 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Before a remote native run starts its provider, the controller selects a provider pack and verifies it in the sandbox > - The verification command retries once. If both reads fail without a result (a timeout, a signal, or a transport error such as HTTP 502), the run fails with `runner_remote_provider_verification_unavailable` > - That code holds the run for a person in every case. The hold exists for reattachment, which does not spend a new provider attempt and could loop > - On a fresh launch the code is also not on the list of failures that prove no provider session started. So the run is classified as "ambiguous state", and the task waits behind a Board-owned Retry > - This pull request retries a fresh launch's unverified pack on the same run, within the provider attempt budget, and keeps the hold for every other attempt > - The benefit is that a short sandbox outage during startup no longer stops a chat or task until a person clicks Retry ## Linked Issues or Issue Description **What happened?** A chat message started a fresh native run on a new sandbox. The preinstalled provider pack did not match, so the controller uploaded the pack. Both reads that verified the uploaded pack failed with "Request failed with status code 502". No provider process started. The run failed with `runner_remote_provider_verification_unavailable`, the recovery mode was `ambiguous_state`, and the chat showed a Retry button. A manual Retry then succeeded. **Steps to reproduce** 1. Start a fresh remote native run. 2. Make both provider-pack verification reads fail without a result, for example with a 502 from the sandbox command API. **Expected behavior** The run retries its startup on the same run, with backoff, because no provider session started. **Actual behavior** The run is held for a person with "Inspect the original provider failure and explicitly resolve the ambiguous session state". ## What Changed - `native-session-executor.ts`: - `nativeProviderRecoveryEvidence` treats `runner_remote_provider_verification_unavailable` as definitely pre-session when the attempt is a fresh bootstrap (the caller passes `bootstrap`). As for every pre-session code, this applies only when the run has no checkpoint and no provider event. - `nativeSessionFailureDisposition` takes an optional `freshBootstrap` flag. With it, `runner_remote_provider_verification_unavailable` is retryable instead of permanent, so the existing same-run startup retry and its three-attempt budget apply. The executor passes the same fresh-bootstrap condition it already uses for `bootstrap`. - Reattachment, warm session recovery and retained transitions do not pass `bootstrap`, so they keep the hold. - `doc/native-workspace-finalization-recovery.md`: describe the fresh-launch retry. - Tests: the disposition retries attempts 1 and 2 of a fresh launch and stops at attempt 3, and the existing reattachment hold test is unchanged. An integration test shows `bootstrap_retry` for a fresh launch with no checkpoint, and `ambiguous_state` without `bootstrap`. ## Verification - `npx vitest run` on the new cases: pass. Both fail without the source change. - `npx vitest run` on the native session executor, controller recovery, remote provider pack, online source, status arbiter corpus, continuation and startup/retry suites: 2203 pass, 8 skipped. - `npx tsc --noEmit` passes for the server. ## Risks - Low. Only a fresh launch with no checkpoint and no provider event changes. A deterministic verification outage now costs up to two more startup attempts, with backoff, before the run is held. - A completed verification that fails (`runner_remote_provider_artifact_incompatible`) is unchanged. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution 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 Co-authored-by: Paperclip <noreply@paperclip.ing>