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");