feat: add authoritative issue PATCH receipts (#10478)

<!-- Write all pull request text in Simplified Technical English
(ASD-STE100): short sentences, one instruction per sentence, simple
approved vocabulary, and the active voice. -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents update tasks through the issue API.
> - The update response did not state which values changed.
> - Blocker updates also did not echo the scalar blocker IDs.
> - Agents therefore used an extra GET request to confirm a successful
write.
> - This pull request adds an authoritative change receipt and an
optional small response.
> - The benefit is fewer API calls with a clear and compatible write
contract.

## Linked Issues or Issue Description

No public GitHub issue exists for this change.

### Subsystem affected

Cross-cutting: `server/`, `packages/shared`, and the UI issue cache.

### Problem or motivation

A successful issue PATCH returned the updated issue, but it did not
identify the effective changes. Blocker writes returned relation
summaries without the scalar IDs. Agents could not distinguish a
confirmed clear operation from missing data. The response must confirm
committed field and blocker changes while existing UI clients continue
to receive the full issue by default.

### Proposed solution

Add a `changes` receipt. Add a conditional `blockedByIssueIds` echo.
Support `Prefer: return=minimal`. Keep the full response as the default.

### Alternatives considered

Make the small response the default for agent tokens. This would create
different response contracts by actor type, so this pull request does
not use that design.

### Roadmap alignment

This is a focused control-plane reliability improvement. It does not
duplicate an open roadmap milestone.

## What Changed

- Compute committed issue row and relation changes in the issue service.
- Omit no-op fields and truncate changed long text values to 200
characters.
- Echo blocker ID arrays for blocker set and clear requests.
- Add the opt-in `Prefer: return=minimal` response and
`Preference-Applied` header.
- Keep receipt metadata out of React Query issue caches.
- Add route and embedded Postgres tests for the new contract.

## Verification

- `pnpm exec vitest run
server/src/__tests__/issue-activity-events-routes.test.ts`
- `pnpm exec vitest run server/src/__tests__/issues-service.test.ts -t
"returns authoritative update receipts for row fields and blocker
relations"`
- `pnpm --filter @paperclipai/shared typecheck`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm check:token-gates`
- `git diff --check`

## Risks

- Low compatibility risk. The default response only adds receipt fields.
- Minimal mode is opt-in. Existing clients do not receive a smaller
body.
- The receipt excludes `updatedAt` because the response already returns
it as the freshness anchor.
- Prose API and agent workflow guidance will follow after the server
contract is available.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex based on GPT-5. The exact deployment ID, context window
size, and reasoning mode are not exposed to the agent. The agent used
repository tools, code execution, and test 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
- [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>

server/src/__tests__/issue-activity-events-routes.test.ts

@@ -2,6 +2,7 @@ import express from "express";
 import request from "supertest";
 import { getTableName } from "drizzle-orm";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { buildIssueChanges } from "../services/issue-change-receipt.ts";
 import { normalizeIssueExecutionPolicy } from "../services/issue-execution-policy.ts";
 
 const mockIssueService = vi.hoisted(() => ({
@@ -155,8 +156,29 @@ function makeIssue() {
     createdByUserId: "local-board",
     identifier: "PAP-580",
     title: "Activity event issue",
+    description: null,
+    priority: "medium",
     executionPolicy: null,
     executionState: null,
+    updatedAt: new Date("2026-07-30T12:00:00.000Z"),
+  };
+}
+
+function issueUpdateWithReceipt(issue: ReturnType<typeof makeIssue>, patch: Record<string, unknown>) {
+  const {
+    actorAgentId: _actorAgentId,
+    actorUserId: _actorUserId,
+    blockedByIssueIds: _blockedByIssueIds,
+    ...issuePatch
+  } = patch;
+  const updated = {
+    ...issue,
+    ...issuePatch,
+    updatedAt: new Date("2026-07-30T12:01:00.000Z"),
+  };
+  return {
+    ...updated,
+    changes: buildIssueChanges(issue, updated),
   };
 }
 
@@ -205,6 +227,161 @@ describe("issue activity event routes", () => {
     mockRoutineService.syncRunStatusForIssue.mockResolvedValue(undefined);
   });
 
+  it("returns a field-change receipt and omits a requested no-op field", async () => {
+    const issue = makeIssue();
+    mockIssueService.getById.mockResolvedValue(issue);
+    mockIssueService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) =>
+      issueUpdateWithReceipt(issue, patch));
+
+    const changed = await request(await createApp())
+      .patch(`/api/issues/${issue.id}`)
+      .send({ priority: "high" });
+    expect(changed.status).toBe(200);
+    expect(changed.body.changes).toEqual({
+      priority: { from: "medium", to: "high" },
+    });
+
+    const noOp = await request(await createApp())
+      .patch(`/api/issues/${issue.id}`)
+      .send({ title: issue.title });
+    expect(noOp.status).toBe(200);
+    expect(noOp.body.changes).not.toHaveProperty("title");
+  });
+
+  it("echoes scalar blocker state and summaries when setting and clearing blockers", async () => {
+    const issue = makeIssue();
+    const blockerId = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+    let blockedByIssueIds: string[] = [];
+    const relationSummaries = () => ({
+      blockedBy: blockedByIssueIds.map((id) => ({
+        id,
+        identifier: "PAP-10",
+        title: "Blocker",
+        status: "todo",
+        priority: "medium",
+        assigneeAgentId: null,
+        assigneeUserId: null,
+      })),
+      blocks: [],
+    });
+    mockIssueService.getById.mockResolvedValue(issue);
+    mockIssueService.getRelationSummaries.mockImplementation(async () => relationSummaries());
+    mockIssueService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) => {
+      const from = blockedByIssueIds;
+      blockedByIssueIds = [...new Set(patch.blockedByIssueIds as string[])].sort();
+      return {
+        ...issueUpdateWithReceipt(issue, patch),
+        blockedByIssueIds,
+        changes: buildIssueChanges(issue, issue, {
+          blockedByIssueIds: { from, to: blockedByIssueIds },
+        }),
+      };
+    });
+
+    const setResponse = await request(await createApp())
+      .patch(`/api/issues/${issue.id}`)
+      .send({ blockedByIssueIds: [blockerId] });
+    expect(setResponse.status).toBe(200);
+    expect(setResponse.body).toMatchObject({
+      blockedByIssueIds: [blockerId],
+      blockedBy: [{ id: blockerId }],
+      blocks: [],
+      changes: { blockedByIssueIds: { from: [], to: [blockerId] } },
+    });
+
+    const clearResponse = await request(await createApp())
+      .patch(`/api/issues/${issue.id}`)
+      .send({ blockedByIssueIds: [] });
+    expect(clearResponse.status).toBe(200);
+    expect(clearResponse.body).toMatchObject({
+      blockedByIssueIds: [],
+      blockedBy: [],
+      blocks: [],
+      changes: { blockedByIssueIds: { from: [blockerId], to: [] } },
+    });
+  });
+
+  it("truncates long text receipt values to 200 characters and marks them updated", async () => {
+    const issue = {
+      ...makeIssue(),
+      title: "a".repeat(240),
+      description: "b".repeat(240),
+    };
+    mockIssueService.getById.mockResolvedValue(issue);
+    mockIssueService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) =>
+      issueUpdateWithReceipt(issue, patch));
+
+    const response = await request(await createApp())
+      .patch(`/api/issues/${issue.id}`)
+      .send({ title: "c".repeat(240), description: "d".repeat(240) });
+
+    expect(response.status).toBe(200);
+    expect(response.body.changes).toEqual({
+      title: { from: "a".repeat(200), to: "c".repeat(200), updated: true },
+      description: { from: "b".repeat(200), to: "d".repeat(200), updated: true },
+    });
+  });
+
+  it("returns only the minimal receipt fields when requested", async () => {
+    const issue = makeIssue();
+    mockIssueService.getById.mockResolvedValue(issue);
+    mockIssueService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) =>
+      issueUpdateWithReceipt(issue, patch));
+
+    const response = await request(await createApp())
+      .patch(`/api/issues/${issue.id}`)
+      .set("Prefer", "respond-async, return=minimal")
+      .send({ priority: "high" });
+
+    expect(response.status).toBe(200);
+    expect(response.headers["preference-applied"]).toBe("return=minimal");
+    expect(response.body).toEqual({
+      id: issue.id,
+      identifier: issue.identifier,
+      updatedAt: "2026-07-30T12:01:00.000Z",
+      changes: { priority: { from: "medium", to: "high" } },
+      comment: null,
+    });
+  });
+
+  it("preserves the default full response body with additive receipt fields", async () => {
+    const issue = makeIssue();
+    mockIssueService.getById.mockResolvedValue(issue);
+    mockIssueService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) =>
+      issueUpdateWithReceipt(issue, patch));
+
+    const response = await request(await createApp())
+      .patch(`/api/issues/${issue.id}`)
+      .send({ priority: "high" });
+
+    expect(response.status).toBe(200);
+    expect(response.headers["preference-applied"]).toBeUndefined();
+    expect(response.body).toMatchInlineSnapshot(`
+      {
+        "assigneeAgentId": "22222222-2222-4222-8222-222222222222",
+        "assigneeUserId": null,
+        "changes": {
+          "priority": {
+            "from": "medium",
+            "to": "high",
+          },
+        },
+        "comment": null,
+        "companyId": "company-1",
+        "createdByUserId": "local-board",
+        "description": null,
+        "executionPolicy": null,
+        "executionState": null,
+        "id": "11111111-1111-4111-8111-111111111111",
+        "identifier": "PAP-580",
+        "priority": "high",
+        "status": "todo",
+        "title": "Activity event issue",
+        "updatedAt": "2026-07-30T12:01:00.000Z",
+      }
+    `);
+  });
+
   it("logs blocker activity with added and removed issue summaries", async () => {
     const issue = makeIssue();
     mockIssueService.getById.mockResolvedValue(issue);

server/src/__tests__/issues-service.test.ts

@@ -3516,6 +3516,68 @@ describeEmbeddedPostgres("issueService blockers and dependency wake readiness",
     };
   }
 
+  it("returns authoritative update receipts for row fields and blocker relations", async () => {
+    const companyId = randomUUID();
+    const issueId = randomUUID();
+    const blockerId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(issues).values([
+      {
+        id: issueId,
+        companyId,
+        title: "Receipt issue",
+        description: "old description",
+        status: "todo",
+        priority: "medium",
+      },
+      {
+        id: blockerId,
+        companyId,
+        title: "Blocker",
+        status: "todo",
+        priority: "high",
+      },
+    ]);
+
+    const fieldUpdate = await svc.update(issueId, {
+      title: "Receipt issue",
+      priority: "high",
+      description: "new description",
+    });
+    expect(fieldUpdate?.changes).toEqual({
+      priority: { from: "medium", to: "high" },
+      description: { from: "old description", to: "new description", updated: true },
+    });
+
+    const blockersSet = await svc.update(issueId, { blockedByIssueIds: [blockerId, blockerId] });
+    expect(blockersSet?.blockedByIssueIds).toEqual([blockerId]);
+    expect(blockersSet?.changes.blockedByIssueIds).toEqual({ from: [], to: [blockerId] });
+
+    const blockersCleared = await svc.update(issueId, { blockedByIssueIds: [] });
+    expect(blockersCleared?.blockedByIssueIds).toEqual([]);
+    expect(blockersCleared?.changes.blockedByIssueIds).toEqual({ from: [blockerId], to: [] });
+
+    await db.update(issues).set({
+      title: "Concurrent receipt issue",
+      priority: "medium",
+    }).where(eq(issues.id, issueId));
+    const [titleUpdate, priorityUpdate] = await Promise.all([
+      svc.update(issueId, { title: "Concurrent title" }),
+      svc.update(issueId, { priority: "high" }),
+    ]);
+    expect(titleUpdate?.changes).toEqual({
+      title: { from: "Concurrent receipt issue", to: "Concurrent title" },
+    });
+    expect(priorityUpdate?.changes).toEqual({
+      priority: { from: "medium", to: "high" },
+    });
+  });
+
   it("persists blocked-by relations and exposes both blockedBy and blocks summaries", async () => {
     const companyId = randomUUID();
     await db.insert(companies).values({

server/src/__tests__/paperclip-skill-utils.test.ts

@@ -64,6 +64,16 @@ describe("paperclip skill utils", () => {
     await expect(fs.access(path.resolve("scripts/paperclip-upload-artifact.sh"))).rejects.toThrow();
   });
 
+  it("uses the authoritative PATCH response to confirm monitor scheduling", async () => {
+    const skillBody = await fs.readFile(path.resolve("skills/paperclip/SKILL.md"), "utf8");
+
+    expect(skillBody).toContain("Use that request's default full response");
+    expect(skillBody).toContain("do not issue a confirming GET");
+    expect(skillBody).toContain("`monitorNextCheckAt` is non-null");
+    expect(skillBody).toContain("`assigneeAgentId` is set");
+    expect(skillBody).toContain("`assigneeUserId` is null");
+  });
+
   it("keeps the create-issue-interaction-ui guide as a maintainer-only skill", async () => {
     const skillPath = path.resolve(".agents/skills/create-issue-interaction-ui/SKILL.md");
     const skillBody = await fs.readFile(skillPath, "utf8");

server/src/routes/issues.ts

@@ -204,6 +204,13 @@ const MAX_ISSUE_COMMENT_LIMIT = 500;
 const updateIssueRouteSchema = updateIssueSchema.extend({
   interrupt: z.boolean().optional(),
 });
+
+function prefersMinimalIssueUpdateResponse(req: Request) {
+  return (req.get("Prefer") ?? "")
+    .split(",")
+    .some((preference) => preference.trim().toLowerCase() === "return=minimal");
+}
+
 const refreshExternalObjectsSchema = z.object({
   objectIds: z.array(z.string().uuid()).max(50).optional(),
 }).strict();
@@ -8296,6 +8303,8 @@ export function issueRoutes(
       updatedRelations = await svc.getRelationSummaries(issue.id);
       issueResponse = {
         ...issue,
+        blockedByIssueIds:
+          issue.blockedByIssueIds ?? [...new Set(req.body.blockedByIssueIds as string[])].sort(),
         blockedBy: updatedRelations.blockedBy,
         blocks: updatedRelations.blocks,
       };
@@ -9055,7 +9064,19 @@ export function issueRoutes(
     })();
 
     await queueTaskWatchdogEvaluation(issue, actor.runId);
-    res.json({ ...issueResponse, comment });
+    const changes = issueResponse.changes ?? {};
+    if (prefersMinimalIssueUpdateResponse(req)) {
+      res.setHeader("Preference-Applied", "return=minimal");
+      res.json({
+        id: issueResponse.id,
+        identifier: issueResponse.identifier,
+        updatedAt: issueResponse.updatedAt,
+        changes,
+        comment,
+      });
+      return;
+    }
+    res.json({ ...issueResponse, changes, comment });
   });
 
   router.delete("/issues/:id", async (req, res) => {

server/src/services/issue-change-receipt.ts

@@ -0,0 +1,50 @@
+import { isDeepStrictEqual } from "node:util";
+import type { IssueChanges } from "@paperclipai/shared";
+
+const ISSUE_CHANGE_TEXT_BUDGET = 200;
+
+function truncateIssueChangeText(value: unknown) {
+  if (typeof value !== "string") return value;
+  return Array.from(value).slice(0, ISSUE_CHANGE_TEXT_BUDGET).join("");
+}
+
+function canonicalIdArray(value: unknown): unknown {
+  if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) return value;
+  return [...new Set(value)].sort();
+}
+
+export function buildIssueChanges(
+  existing: Record<string, unknown>,
+  updated: Record<string, unknown>,
+  relationChanges: {
+    blockedByIssueIds?: { from: string[]; to: string[] };
+    labelIds?: { from: string[]; to: string[] };
+  } = {},
+): IssueChanges {
+  const changes: IssueChanges = {};
+  const keys = new Set([...Object.keys(existing), ...Object.keys(updated)]);
+  keys.delete("updatedAt");
+
+  for (const key of keys) {
+    const from = existing[key];
+    const to = updated[key];
+    if (isDeepStrictEqual(from, to)) continue;
+
+    const longText =
+      key === "description" ||
+      (key === "title" &&
+        ((typeof from === "string" && Array.from(from).length > ISSUE_CHANGE_TEXT_BUDGET) ||
+          (typeof to === "string" && Array.from(to).length > ISSUE_CHANGE_TEXT_BUDGET)));
+    changes[key] = longText
+      ? { from: truncateIssueChangeText(from), to: truncateIssueChangeText(to), updated: true }
+      : { from, to };
+  }
+
+  for (const [key, change] of Object.entries(relationChanges)) {
+    const from = canonicalIdArray(change.from);
+    const to = canonicalIdArray(change.to);
+    if (!isDeepStrictEqual(from, to)) changes[key] = { from, to };
+  }
+
+  return changes;
+}

server/src/services/issues.ts

@@ -116,6 +116,7 @@ import { visibleIssueCondition } from "./issue-visibility.js";
 import { finalizeStatusCardsForStalledGeneration } from "./status-card-finalization.js";
 import { finalizeSummarySlotsForTerminalIssue } from "./summary-slot-finalization.js";
 import { logActivity } from "./activity-log.js";
+import { buildIssueChanges } from "./issue-change-receipt.js";
 
 const ALL_ISSUE_STATUSES = ["backlog", "todo", "in_progress", "in_review", "blocked", "done", "cancelled"];
 const MAX_ISSUE_COMMENT_PAGE_LIMIT = 500;
@@ -7063,6 +7064,24 @@ export function issueService(db: Db) {
       }
 
       const runUpdate = async (tx: any) => {
+        // The receipt baseline must be read under the same row lock as the
+        // write. Otherwise a concurrent update can be mistaken for a change
+        // made by this request.
+        const receiptExisting = await tx
+          .select()
+          .from(issues)
+          .where(eq(issues.id, id))
+          .for("update")
+          .then((rows: Array<typeof issues.$inferSelect>) => rows[0] ?? null);
+        if (!receiptExisting) return null;
+        const [previousLabelsByIssueId, previousRelationSummaries] = await Promise.all([
+          nextLabelIds !== undefined
+            ? labelMapForIssues(tx, [id])
+            : Promise.resolve(new Map<string, IssueLabelRow[]>()),
+          blockedByIssueIds !== undefined
+            ? getIssueRelationSummaryMap(existing.companyId, [id], tx)
+            : Promise.resolve(new Map<string, IssueRelationSummaryMap>()),
+        ]);
         const defaultCompanyGoal = await getDefaultCompanyGoal(tx, existing.companyId);
         const [currentProjectGoalId, nextProjectGoalId] = await Promise.all([
           getProjectDefaultGoalId(tx, existing.companyId, existing.projectId),
@@ -7180,6 +7199,31 @@ export function issueService(db: Db) {
           }
         }
         const [enriched] = await withIssueLabels(tx, [updated]);
+        const nextBlockedByIssueIds = blockedByIssueIds === undefined
+          ? undefined
+          : [...new Set(blockedByIssueIds)].sort();
+        const changes = buildIssueChanges(
+          receiptExisting as unknown as Record<string, unknown>,
+          updated as unknown as Record<string, unknown>,
+          {
+            ...(nextLabelIds !== undefined
+              ? {
+                  labelIds: {
+                    from: (previousLabelsByIssueId.get(id) ?? []).map((label) => label.id),
+                    to: enriched.labelIds,
+                  },
+                }
+              : {}),
+            ...(nextBlockedByIssueIds !== undefined
+              ? {
+                  blockedByIssueIds: {
+                    from: (previousRelationSummaries.get(id)?.blockedBy ?? []).map((relation) => relation.id),
+                    to: nextBlockedByIssueIds,
+                  },
+                }
+              : {}),
+          },
+        );
         if (
           (issueData.status === "done" || issueData.status === "cancelled") &&
           existing.status !== issueData.status &&
@@ -7199,7 +7243,11 @@ export function issueService(db: Db) {
               );
           }
         }
-        return enriched;
+        return {
+          ...enriched,
+          ...(nextBlockedByIssueIds !== undefined ? { blockedByIssueIds: nextBlockedByIssueIds } : {}),
+          changes,
+        };
       };
 
       return dbOrTx === db ? db.transaction(runUpdate) : runUpdate(dbOrTx);