fix: serialize concurrent issue reference syncs (#13898)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The server keeps issue references synchronized with issue title and
description changes.
> - Concurrent updates can rebuild the same source issue's reference
mentions at the same time.
> - The replacement writes can then collide on the unique mention key
and return a 500 error.
> - This pull request serializes each source issue's reference rebuild
and adds concurrent regression coverage.
> - The benefit is that repeated unchanged descriptions complete without
duplicate-key failures.

## Linked Issues or Issue Description

Fixes #13731

## What Changed

- Lock the source issue row before replacing title and description
reference mentions.
- Add a 20-way concurrent regression test with repeated `COM-2`
references.

## Verification

- `pnpm exec vitest run
server/src/__tests__/issue-references-service.test.ts
packages/shared/src/issue-references.test.ts` passed with 10 tests.
- `pnpm --filter @paperclipai/server typecheck` passed under Node
22.22.1; the repository declares Node >=24.11 and emitted engine
warnings.
- `git diff --check` passed.

## Risks

- The row lock serializes rebuilds for one source issue and may reduce
concurrency for simultaneous updates to that issue.
- A theoretical lock-order risk remains for concurrent syncs of
different mutually referencing source issues. That path is outside this
fix and is not covered by the focused regression.
- Remote CI and Greptile review have not run yet.

## Model Used

OpenCode runtime, model `supercodes5/gpt-5.6-luna`; context window size
is not exposed. Repository tool use and reasoning were enabled.

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

server/src/__tests__/issue-references-service.test.ts

@@ -175,6 +175,49 @@ describeEmbeddedPostgres("issueReferenceService", () => {
     expect(pap3?.sources.map((source) => source.label)).toEqual(["description"]);
   });
 
+  it("serializes concurrent syncs for a description with repeated references", async () => {
+    const companyId = randomUUID();
+    const sourceIssueId = randomUUID();
+    const targetIssueId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip Concurrent References",
+      issuePrefix: `C${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(issues).values([
+      {
+        id: sourceIssueId,
+        companyId,
+        title: "Source issue",
+        description: "Coordinate COM-2 and confirm COM-2 again.",
+        status: "todo",
+        priority: "medium",
+        identifier: "COM-1",
+      },
+      {
+        id: targetIssueId,
+        companyId,
+        title: "Target issue",
+        status: "todo",
+        priority: "medium",
+        identifier: "COM-2",
+      },
+    ]);
+
+    await expect(Promise.all(
+      Array.from({ length: 20 }, () => refs.syncIssue(sourceIssueId)),
+    )).resolves.toHaveLength(20);
+
+    const mentions = await db
+      .select()
+      .from(issueReferenceMentions);
+    expect(mentions).toHaveLength(1);
+    expect(mentions[0]?.targetIssueId).toBe(targetIssueId);
+  });
+
   it("backfills existing references for a company without requiring write-time sync", async () => {
     const companyId = randomUUID();
     const sourceIssueId = randomUUID();

server/src/services/issue-references.ts

@@ -174,8 +174,8 @@ export function issueReferenceService(db: Db) {
     }
   }
 
-  async function issueById(issueId: string, dbOrTx: any = db) {
-    return dbOrTx
+  async function issueById(issueId: string, dbOrTx: any = db, lock = false) {
+    const query = dbOrTx
       .select({
         id: issues.id,
         companyId: issues.companyId,
@@ -183,13 +183,14 @@ export function issueReferenceService(db: Db) {
         description: issues.description,
       })
       .from(issues)
-      .where(eq(issues.id, issueId))
+      .where(eq(issues.id, issueId));
+    return (lock ? query.for("update") : query)
       .then((rows: Array<{ id: string; companyId: string; title: string; description: string | null }>) => rows[0] ?? null);
   }
 
   async function syncIssue(issueId: string, dbOrTx: any = db) {
     const runSync = async (tx: any) => {
-      const issue = await issueById(issueId, tx);
+      const issue = await issueById(issueId, tx, true);
       if (!issue) throw notFound("Issue not found");
 
       await replaceSourceMentions({