Files
PaperClipAI/doc
Devin FoleyandPaperclip 1b1861c29d Fix skill upload conflicts blocking first-agent onboarding (#22477)
## Thinking Path

> - Paperclip manages agents and the skills they need to work.
> - First-agent setup resolves the bundled skills before onboarding can
finish.
> - Skill packages use durable upload claims to protect their
object-storage receipts.
> - A failed attempt kept its claim active for ten minutes. A concurrent
caller received an immediate conflict.
> - This pull request expires a failed owner's unpublished claim and
waits for an active upload to settle.
> - Onboarding can retry skill setup without a false upload-in-progress
error.

## Linked Issues or Issue Description

**What happened?**

First-agent onboarding could show "This skill package is being saved.
Retry after its upload settles." during the subscription connection
step. The agent's bundled skill setup called the package store. A failed
upload retained its active claim, and calls from another database client
also returned a conflict while an upload was in progress.

**Expected behavior**

A failed attempt permits an immediate retry with new object keys.
Concurrent callers reuse the completed receipt or claim the failed
attempt. They preserve another owner's active lease and every published
receipt.

**Steps to reproduce**

1. Fail the first object upload while resolving the first agent's
bundled skills.
2. Retry the same skill selection before the ten-minute lease expires.
3. Observe the upload-in-progress conflict. The new regression
reproduces this through
`companySkillService.resolveRequestedSkillEntries`.

**Paperclip version or commit**

Reproduced on `6bf312270c3e`.

**Deployment mode**

Hosted onboarding; the package-store fix also applies to self-hosted
instances.

Related implementation: #18082. Searched open and closed pull requests
and open issues for related skill-upload and lease failures. No
duplicate fix was found.

## What Changed

- Expire only the failed attempt's token-matched, unpublished upload
claim. Keep its exact keys for the existing deletion outbox. Cleanup has
a one-second client deadline and a transaction-local statement timeout.
Queued cleanup skips its write after that deadline; failed cleanup
retains the original crash lease.
- Wait for a competing package preparation within the existing
three-minute deadline. Re-read the receipt every 250 ms while this
concrete request remains active. Release the database connection between
reads and stop on cancellation. This adds no idle worker or permanent
polling.
- Preserve cancellation reasons, published receipts after lost commit
replies, and claims acquired by a newer owner.
- Add real PostgreSQL regression coverage for first-agent bundled skill
setup, cross-client contention, failed-owner takeover, crash expiry,
cancellation, ambiguous publication, and ownership changes.
- Document upload recovery behavior. No schema or public API change is
required.

## Verification

- Red: four new or updated checks failed against the original
implementation. They reproduced the exact conflict and the retained
ten-minute lease.
- Green: 189 targeted tests passed across
`skill-package-upload.test.ts`, `skill-package-store.test.ts`,
`skill-package-work.test.ts`, both package-storage migration suites, and
`agent-skills-routes.test.ts`. The combined run passed 188 tests. The
final SQL-lock regression passed separately.
- Command: `pnpm exec vitest run
server/src/__tests__/skill-package-upload.test.ts
server/src/__tests__/skill-package-store.test.ts
server/src/services/skill-package-work.test.ts
server/src/services/skill-package-storage-migration.test.ts
server/src/services/skill-package-storage-migration-postgres.test.ts
server/src/__tests__/agent-skills-routes.test.ts`.
- `pnpm --filter @paperclipai/server typecheck` passed, including source
and test layers.
- The cancellation test first exposed Node's timer wrapping the caller's
abort reason. The final implementation preserves that reason, and the
full targeted run passed.
- Greptile identified an unbounded cleanup write. Two new
real-PostgreSQL tests reproduced delayed errors and cancellations behind
an occupied one-connection pool. They now pass and prove that late
cleanup skips its write. A further row-lock test proves that the
PostgreSQL statement timeout frees the pool while another transaction
still holds the package row.
- Local setup initially lacked macOS embedded-Postgres library links.
Repaired ignored dependency links before the red and green database
tests. The initial server typecheck also lacked SDK links for excluded
plugin packages; ran the maintained `node
scripts/link-plugin-dev-sdk.mjs` helper before repeating it.
- `pnpm verify --explain` returned exit 2 and requested broader CI
coverage. No full local suite was substituted for that CI requirement.
- `git diff --check` passed. Reviewed the full diff for secrets, private
URLs, personal data, generated files, and run artifacts.
- Final revision: `4b4814ac01522599901a3dc29f650a1b33c0b4e2`. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/44880245673)
passed all applicable checks, including typecheck, build, all general
and serialized server test shards, all e2e shards, Runner verification,
and the final verify gate. [Greptile
review](https://github.com/paperclipai/paperclip/pull/22477#issuecomment-7059199437)
scored this revision 5/5 with no unresolved threads. GitHub reports the
branch as mergeable and clean.

## Risks

Contended preparations now wait within their existing request deadline.
A crashed process or an unavailable cleanup database still uses the
ten-minute lease expiry. Genuine storage failures remain errors; this
change does not hide an unavailable backend. The existing object
deletion grace remains intact.

Live provider authorization and a deployed Cloud onboarding journey were
not run. Tenant release and deployment are separate from this source
fix. No production migration is needed.

## Model Used

OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through the Codex harness, with xhigh
reasoning effort and tool use.

## 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

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-21 00:25:10 -08:00
..
…
…
…
…