The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat: add authoritative issue PATCH receipts (#10478)
Dotta627728bddeee
diff --git a/docs/api/issues.md b/docs/api/issues.mdindex 617b17f557..e63e70c172 100644--- a/docs/api/issues.md+++ b/docs/api/issues.md@@ -68,6 +68,62 @@ Updatable fields: `title`, `description`, `status`, `priority`, `assigneeAgentIdFor `PATCH /api/issues/{issueId}`, `assigneeAgentId` may be either the agent UUID or the agent shortname/urlKey within the same company.+### Update Response++Without a `Prefer` header, a successful update returns the full, updated issue row with two additive fields:++- `changes`: a receipt containing only values that actually changed in the committed write+- `comment`: the comment created by the optional `comment` input, or `null`++Each `changes` entry has `from` and `to` values. Requested no-ops are omitted, so `changes` is `{}` when the write made no receipt-visible changes. Server-applied side effects may appear when they are part of the same committed update; `updatedAt` is not included as a change.++```json+{+ "id": "issue-99",+ "identifier": "PAP-99",+ "title": "Implement caching layer",+ "priority": "high",+ "updatedAt": "2026-07-30T12:01:00.000Z",+ "changes": {+ "priority": { "from": "medium", "to": "high" }+ },+ "comment": null+}+```++Receipt values for `description` are limited to the first 200 characters and include `updated: true`. A `title` receipt uses the same truncation and marker when either its `from` or `to` value exceeds 200 characters. The full default response still contains the authoritative, untruncated current row values.++When the request includes `blockedByIssueIds`, the response also includes:++- top-level `blockedByIssueIds`, echoing the normalized committed ID array+- `blockedBy`, with summaries of issues that block this issue+- `blocks`, with summaries of issues this issue blocks++Empty arrays are confirmed-empty state, not missing data. For example, clearing all blockers returns `blockedByIssueIds: []` and `blockedBy: []`; `blocks: []` likewise confirms that the issue blocks nothing.++For a compact write receipt, request the minimal representation:++```http+PATCH /api/issues/{issueId}+Prefer: return=minimal+```++The server sets `Preference-Applied: return=minimal` and returns exactly:++```json+{+ "id": "issue-99",+ "identifier": "PAP-99",+ "updatedAt": "2026-07-30T12:01:00.000Z",+ "changes": {+ "priority": { "from": "medium", "to": "high" }+ },+ "comment": null+}+```++**The PATCH response is the authoritative post-write state. A confirming GET after a 2xx PATCH is unnecessary.**+## Checkout (Claim Task)```diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex 521616c7bd..8b59a27db6 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -818,6 +818,8 @@ export type {ExternalObjectSummaryItem,CompactIssue,Issue,+ IssueChangeReceiptEntry,+ IssueChanges,IssueAssigneeAdapterOverrides,IssueBlockerDiagnosticFlag,IssueBlockerDiagnosticIssueSummary,diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex 34a8bdf50e..5602149739 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -542,6 +542,8 @@ export type {export type {CompactIssue,Issue,+ IssueChangeReceiptEntry,+ IssueChanges,IssueWorkMode,IssueAssigneeAdapterOverrides,IssueBlockerDiagnosticFlag,diff --git a/packages/shared/src/types/issue.ts b/packages/shared/src/types/issue.tsindex 44867a219f..343d93f577 100644--- a/packages/shared/src/types/issue.ts+++ b/packages/shared/src/types/issue.ts@@ -711,6 +711,14 @@ export interface IssueWatchdog extends IssueWatchdogSummary {updatedByRunId: string | null;}+export interface IssueChangeReceiptEntry {+ from: unknown;+ to: unknown;+ updated?: true;+}++export type IssueChanges = Record<string, IssueChangeReceiptEntry>;+export interface Issue {id: string;companyId: string;diff --git a/server/src/__tests__/issue-activity-events-routes.test.ts b/server/src/__tests__/issue-activity-events-routes.test.tsindex 550acc57c4..4560fb43e0 100644--- a/server/src/__tests__/issue-activity-events-routes.test.ts+++ b/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);diff --git a/server/src/__tests__/issues-service.test.ts b/server/src/__tests__/issues-service.test.tsindex ffa2879e34..e3069cdb6a 100644--- a/server/src/__tests__/issues-service.test.ts+++ b/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({diff --git a/server/src/__tests__/paperclip-skill-utils.test.ts b/server/src/__tests__/paperclip-skill-utils.test.tsindex 420d8fddc6..898866dd38 100644--- a/server/src/__tests__/paperclip-skill-utils.test.ts+++ b/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");diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex f414934ec7..1bb7c5379a 100644--- a/server/src/routes/issues.ts+++ b/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) => {diff --git a/server/src/services/issue-change-receipt.ts b/server/src/services/issue-change-receipt.tsnew file mode 100644index 0000000000..a69a6165e7--- /dev/null+++ b/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;+}diff --git a/server/src/services/issues.ts b/server/src/services/issues.tsindex 760dda43ff..4acf9bec04 100644--- a/server/src/services/issues.ts+++ b/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);diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.mdindex 50aedf42ce..bab984ae8a 100644--- a/skills/paperclip/SKILL.md+++ b/skills/paperclip/SKILL.md@@ -157,7 +157,7 @@ A "watcher" or "monitor" is not something that lives inside a run. A run/heartbeBecause of that, follow these rules:-- **Only claim a watcher/monitor exists after you have actually scheduled one.** Describing a watcher in a comment does not create it. Schedule it by setting `executionPolicy.monitor.nextCheckAt` (with `kind`/`serviceName`/`externalRef`/`timeoutAt`/`maxAttempts`) via `PATCH /api/issues/{id}`, then confirm the issue now reports a non-null `monitorNextCheckAt` **and** that it is agent-assigned (no `assigneeUserId`) and sitting in `in_progress`/`in_review` — the stored timestamp only fires under those conditions. Run a check on demand with `POST /api/issues/{id}/monitor/check-now`.+- **Only claim a watcher/monitor exists after you have actually scheduled one.** Describing a watcher in a comment does not create it. Schedule it by setting `executionPolicy.monitor.nextCheckAt` (with `kind`/`serviceName`/`externalRef`/`timeoutAt`/`maxAttempts`) via `PATCH /api/issues/{id}`. Use that request's default full response (not `Prefer: return=minimal`) to confirm `monitorNextCheckAt` is non-null, `assigneeAgentId` is set, `assigneeUserId` is null, and `status` is `in_progress` or `in_review` — do not issue a confirming GET. The stored timestamp only fires under those conditions. Run a check on demand with `POST /api/issues/{id}/monitor/check-now`.- **Describe it in checkable terms.** State the monitor's kind, next check time, and attempt/timeout bounds — not vague "a watcher will wake me" background magic. If you cannot name those, you have not scheduled one and must not imply that you have.- **Never imply a live watcher on a task you are marking `done`.** `done` means no follow-up on this issue, which contradicts an ongoing watcher. If real re-checking is still needed, keep the issue `in_progress`/`in_review` with a scheduled monitor instead of closing it.- This is enforced by state, not by narration: the disposition guard rejects an agent move to `in_review` (`invalid_issue_disposition`) unless a real review path exists — interaction, approval, human reviewer, typed participant, or an actually-scheduled monitor with a real `monitorNextCheckAt` — and the recovery classifier flags `in_review_without_action_path` for anything parked with no live wake path. Keep your comments consistent with that real state.diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.mdindex a21a3eae6a..6582aa6cea 100644--- a/skills/paperclip/references/api-reference.md+++ b/skills/paperclip/references/api-reference.md@@ -191,6 +191,48 @@ The response also includes `blockedBy` and `blocks` arrays showing first-class dBlocker wake semantics are strict: `issue_blockers_resolved` only fires when every blocker reaches `done`. A blocker moved to `cancelled` still requires manual re-triage or relation cleanup.+### Issue Update Response (`PATCH /api/issues/:issueId`)++The default successful response is the full, authoritative updated issue row plus:++- `changes`: only values that actually changed in the committed write, keyed by field+- `comment`: the comment created by the optional `comment` input, or `null`++Each `changes` entry contains `from` and `to`. Requested no-ops are omitted, so an update with no receipt-visible changes returns `changes: {}`. Server-applied side effects can appear when they are part of the same committed update; `updatedAt` is not emitted as a change.++```json+{+ "id": "issue-99",+ "identifier": "PAP-99",+ "priority": "high",+ "updatedAt": "2026-07-30T12:01:00.000Z",+ "changes": {+ "priority": { "from": "medium", "to": "high" }+ },+ "comment": null+}+```++Receipt values for `description` are limited to the first 200 characters and include `updated: true`. A `title` receipt uses the same truncation and marker when either its `from` or `to` value exceeds 200 characters. The default full response still contains the authoritative, untruncated current row values.++If the request includes `blockedByIssueIds`, the response also echoes the normalized committed ID array as top-level `blockedByIssueIds` and returns the current `blockedBy` and `blocks` summary arrays. Empty arrays are confirmed-empty state, not missing data: `blockedByIssueIds: []`, `blockedBy: []`, or `blocks: []` may be used directly without a follow-up read.++Clients that need only a compact receipt can send `Prefer: return=minimal`. The response includes `Preference-Applied: return=minimal` and exactly this shape:++```json+{+ "id": "issue-99",+ "identifier": "PAP-99",+ "updatedAt": "2026-07-30T12:01:00.000Z",+ "changes": {+ "priority": { "from": "medium", "to": "high" }+ },+ "comment": null+}+```++**The PATCH response is the authoritative post-write state. A confirming GET after a 2xx PATCH is unnecessary.**+### Blocker Diagnostics (`GET /api/issues/:issueId/diagnostics/blockers`)Use this read-only diagnostic when an issue appears stuck on dependencies, especially after an `issue_blockers_resolved` wake or when an issue looks blocked against a blocker that is already `done`.@@ -1199,7 +1241,7 @@ Terminal states: `done`, `cancelled`| GET | `/api/issues/:issueId/diagnostics/wakes` | Read-only wake-history diagnostic with `diagnosis`, bounded events, and Case-B inference || GET | `/api/issues/:issueId/diagnostics/subtree` | Read-only subtree diagnostic combining visible child, blocker, and wake edges with `diagnosis` || POST | `/api/companies/:companyId/issues` | Create issue (supports `blockedByIssueIds: string[]` for dependencies) |-| PATCH | `/api/issues/:issueId` | Update issue (optional `comment` field; `blockedByIssueIds` replaces blocker set) |+| PATCH | `/api/issues/:issueId` | Update issue; response is authoritative and includes `changes` + `comment` (`Prefer: return=minimal` supported); `blockedByIssueIds` replaces blocker set || POST | `/api/issues/:issueId/checkout` | Atomic checkout (claim + start). Idempotent if you already own it. || POST | `/api/issues/:issueId/release` | Release task ownership || GET | `/api/issues/:issueId/comments` | List comments |diff --git a/ui/src/api/issues.ts b/ui/src/api/issues.tsindex 73e6798b89..8ac720470d 100644--- a/ui/src/api/issues.ts+++ b/ui/src/api/issues.ts@@ -9,6 +9,7 @@ import type {FeedbackTrace,FeedbackVote,Issue,+ IssueChanges,IssueAttachment,IssueCostSummary,IssueComment,@@ -30,6 +31,8 @@ import { api, type RequestOptions } from "./client";export type IssueUpdateResponse = Issue & {comment?: IssueComment | null;+ changes: IssueChanges;+ blockedByIssueIds?: string[];};export type ResolveRecoveryActionResponse = {diff --git a/ui/src/pages/IssueDetail.tsx b/ui/src/pages/IssueDetail.tsxindex 1e7c0507a8..fdea401769 100644--- a/ui/src/pages/IssueDetail.tsx+++ b/ui/src/pages/IssueDetail.tsx@@ -2134,7 +2134,7 @@ export function IssueDetail() {return { previousDetailQueries, previousList, selectedCompanyId };},- onSuccess: ({ comment: _comment, ...nextIssue }) => {+ onSuccess: ({ comment: _comment, changes: _changes, blockedByIssueIds: _blockedByIssueIds, ...nextIssue }) => {const issueRefs = new Set<string>([issueId!, nextIssue.id]);if (nextIssue.identifier) issueRefs.add(nextIssue.identifier);mergeIssueResponseIntoCaches(issueRefs, nextIssue);