## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A person presses Retry on a stopped task, and the Retry API answers before dispatch runs > - The route answered 202 "accepted" when it saved the request. Admission ran afterwards > - When admission refused the request for a reason another click cannot change, the person saw "accepted", no run started, and the task showed no Retry > - A Retry that is shown must work, or the answer must say clearly why it did not start > - This pull request admits a plain Retry before the route answers (bounded wait) and answers a refusal as a refusal > - The benefit is that the API never reports "accepted" for a Retry that admission refused, and the UI shows the reason ## Linked Issues or Issue Description Refs #21481 (a fix for one cause of the refusal). **What happened?** On a hosted staging instance, two tasks got HTTP 202 `accepted: true` from `POST /api/issues/:id/retry`. No run was created. The tasks then showed a failed state with no Retry button and the wait reason `previous_execution_unverified`. **Expected behavior** The Retry answer either reports a Retry that admission took, or it names the refusal so that the UI can show it. It never reports "accepted" for a request that admission refused. **Steps to reproduce** 1. Stop a task's run so that its outcome is unknown (for example, a recorded provider event in a stopped preparation). 2. Press Retry. 3. See HTTP 202 `accepted: true`, then see that the saved request waits on `previous_execution_unverified` and no run starts. **Paperclip version or commit** `master` at `a48eaaef57`. ## What Changed - `POST /api/issues/:id/retry` runs admission of a plain Retry (not a saved-result finalization, not a connected chat retry) before it answers. It waits at most 5 seconds. If admission takes longer, admission continues after the answer, and the answer stays "accepted" as before. - When admission refused the request for a reason another click cannot change (`heldRetryOffersRetry` is false), the answer is HTTP 200 with `accepted: false` and `refused: { reason, message }`. The message is the same stable text that the task view shows. - The saved request is kept. If its gate clears later (for example, saved-work recovery verifies the files), it still starts by itself. - New `taskRetryRefusal` and `taskRetryWaitMessage` in `server/src/services/task-interruption-presentation.ts`. - UI: `taskRetryNotStartedReason` shows `refused.message`; the API type includes `refused`. - Tests that asserted 202 for a held Retry now assert the refusal answer. ## Verification - Red without the route change, green with it: `cd server && npx vitest run src/services/legacy-preparation-retry-hold.test.ts` (new test: a stopped preparation with a recorded provider event; the route answers 200 with `refused.reason: previous_execution_unverified`, and the saved request stays deferred). - Red without the hook change, green with it: `cd ui && npx vitest run src/hooks/useTaskRetry.test.tsx`. - Updated and passing: `src/services/workspace-recovery-preparation-gates.test.ts` (48), `src/services/workspace-recovery-preparation-proof.test.ts` (53), `src/services/workspace-recovery-preparation-dispatch.test.ts` (25). - Passing unchanged: `src/__tests__/issue-scheduled-retry-routes.test.ts` (34), `src/services/unrecoverable-saved-work-retry.test.ts` (5), `src/services/workspace-recovery-warm-handoff.test.ts` (44), `src/__tests__/heartbeat-native-restart-suspension.test.ts` (115), `src/__tests__/issue-agent-mutation-ownership-routes.test.ts` (229), `src/__tests__/agent-cross-tenant-authz-routes.test.ts` (18). - Not run locally: `src/__tests__/chat-channels.integration.test.ts` (did not finish on the loaded machine). CI covers it. ## Risks - The Retry answer can take up to 5 seconds longer when admission is slow (for example, when the agent's start lock is held). Before, the route answered at once and admitted in the background. - A refused request can still start later by itself when its gate clears. The answer then said "not started", but the task view updates when the run starts. - API change: a refused Retry is now HTTP 200 with `accepted: false` and `refused`. The board UI handles it. Other clients that only check `accepted` see a refusal, which is correct. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code with tool use (shell, file edits, 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 - [ ] 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
title, summary
| title | summary |
|---|---|
| Issues | Issue CRUD, checkout/release, comments, documents, interactions, and attachments |
Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, issue-thread interactions, keyed text documents, and file attachments.
List Issues
GET /api/companies/{companyId}/issues
Query parameters:
| Param | Description |
|---|---|
status |
Filter by status (comma-separated: todo,in_progress) |
assigneeAgentId |
Filter by assigned agent |
projectId |
Filter by project |
view |
index: collection rows without bodies or diagnostics; rows: rows with diagnostic summaries but no bodies; compact: existing board row contract |
ids |
One to 100 comma-separated task UUIDs; requires view=index or view=rows without attention |
parentIds |
One to 100 comma-separated parent UUIDs for batched child context; same projection restriction as ids |
oneChildPerParent |
With view=index and parentIds, return at most one readable child per parent for collapsed-tree affordances |
Results sorted by priority.
The index and rows projections include listProjection and return a null
description. They are partial collection snapshots: fetch the issue detail
endpoint for its instruction and related content. Company and private-task access
checks apply before results are returned. The UI uses a lightweight index to
establish list order, then enriches only visible rows in batches of at most 50.
Get Issue
GET /api/issues/{issueId}
Returns the issue with project, goal, and ancestors (parent chain with their projects and goals).
The response also includes:
planDocument: the full text of the issue document with keyplan, when presentdocumentSummaries: metadata for all linked issue documentslegacyPlanDocument: a read-only fallback when the description still contains an old<plan>block
Create Issue
POST /api/companies/{companyId}/issues
{
"title": "Implement caching layer",
"description": "Add Redis caching for hot queries",
"status": "todo",
"priority": "high",
"assigneeAgentId": "{agentId}",
"parentId": "{parentIssueId}",
"projectId": "{projectId}",
"goalId": "{goalId}"
}
Update Issue
PATCH /api/issues/{issueId}
Headers: X-Paperclip-Run-Id: {runId}
{
"status": "done",
"comment": "Implemented caching with 90% hit rate."
}
The optional comment field adds a comment in the same call. For execution-policy review or approval decisions, the decision comment must be included in this same PATCH; a prior POST /api/issues/{issueId}/comments does not satisfy the stage decision guard.
Updatable fields: title, description, status, priority, assigneeAgentId, projectId, goalId, parentId, billingCode.
For PATCH /api/issues/{issueId}, assigneeAgentId may be either the agent UUID or the agent shortname/urlKey within the same company.
When updating executionPolicy, you can also send expectedExecutionPolicy with the complete policy object from your last task read (or null if no policy exists). The server compares this snapshot under the task row lock. If the policy has changed, the update returns 409 with code execution_policy_changed. Read the task again before retrying. Snapshot-guarded requests must contain only executionPolicy and expectedExecutionPolicy. They cannot change task status or ownership, including through a policy transition. Mixed requests return 422 before execution-control side effects. Omit this field to retain the existing update behavior.
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 writecomment: the comment created by the optionalcommentinput, ornull
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.
{
"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 issueblocks, 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:
PATCH /api/issues/{issueId}
Prefer: return=minimal
The server sets Preference-Applied: return=minimal and returns exactly:
{
"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)
POST /api/issues/{issueId}/checkout
Headers: X-Paperclip-Run-Id: {runId}
{
"agentId": "{yourAgentId}",
"expectedStatuses": ["todo", "backlog", "blocked", "in_review"]
}
Atomically claims the task and transitions to in_progress. Returns 409 Conflict if another agent owns it. Never retry a 409.
Idempotent if you already own the task.
Re-claiming after a crashed run: If your previous run crashed while holding a task in in_progress, the new run must include "in_progress" in expectedStatuses to re-claim it:
POST /api/issues/{issueId}/checkout
Headers: X-Paperclip-Run-Id: {runId}
{
"agentId": "{yourAgentId}",
"expectedStatuses": ["in_progress"]
}
The server will adopt the stale lock if the previous run is no longer active. The runId field is not accepted in the request body — it comes exclusively from the X-Paperclip-Run-Id header (via the agent's JWT).
Release Task
POST /api/issues/{issueId}/release
Releases your ownership of the task.
Retry a Stopped Task (Board)
POST /api/issues/{issueId}/retry
{
"idempotencyKey": "{uuid}",
"observedRunId": "{runIdTheBoardSaw}"
}
Saves a Retry request for the task's latest stopped run. The same idempotencyKey returns the same request. The server tries to admit the request before it answers, for at most five seconds.
202withaccepted: true: admission took the request, or admission is still running after five seconds and continues after the answer.200withaccepted: falseandrefused: { reason, message }: admission refused the request for a reason that another click cannot change.messageis the text that the task view shows. The request stays saved. If its reason clears later, it starts by itself.200withaccepted: falseandstale: true:observedRunIdis no longer the task's latest run. Read the task again.
Every answer includes presentation, the task's current interruption state.
Comments
List Comments
GET /api/issues/{issueId}/comments
Add Comment
POST /api/issues/{issueId}/comments
{ "body": "Progress update in markdown..." }
Agent @-mentions are context only and do not trigger heartbeats. Normal comment feedback can still wake the current assignee. Use explicit assignment or a review request to ask another agent to act.
Discard a Queued Comment
GET /api/issues/{issueId}/queued-comments
DELETE /api/issues/{issueId}/queued-comments/{commentId}
{ "queueId": "{queueId}", "revision": "{revision}" }
Use the queue ID and revision from the queue response. Board users with access to
the task can discard their own queued comments and comments authored by agents.
Other people's queued comments remain author-only. Editing remains author-only.
Agents cancel their own queued comments through
DELETE /api/issues/{issueId}/comments/{commentId}?mode=cancel.
The discard removes the pending comment and its queue linkage. Removing the last
entry also cancels its queued continuation. A changed queue or a message that is
already being sent returns 409; read the queue again before retrying.
Issue-Thread Interactions
Interactions are structured cards in the issue thread. Agents create them when a teammate needs to choose tasks, answer questions, or confirm a proposal through the UI instead of hidden markdown conventions.
List Interactions
GET /api/issues/{issueId}/interactions
Create Interaction
POST /api/issues/{issueId}/interactions
{
"kind": "request_confirmation",
"resolverPolicy": "human_only",
"idempotencyKey": "confirmation:{issueId}:plan:{revisionId}",
"title": "Plan approval",
"summary": "Waiting for the board/user to accept or request changes.",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"prompt": "Accept this plan?",
"acceptLabel": "Accept plan",
"rejectLabel": "Request changes",
"rejectRequiresReason": true,
"rejectReasonLabel": "What needs to change?",
"detailsMarkdown": "Review the latest plan document before accepting.",
"supersedeOnUserComment": true,
"target": {
"type": "issue_document",
"issueId": "{issueId}",
"documentId": "{documentId}",
"key": "plan",
"revisionId": "{latestRevisionId}",
"revisionNumber": 3
}
}
}
Supported kind values:
suggest_tasks: propose child issues for the board/user to accept or rejectask_user_questions: ask structured questions and store selected answersrequest_confirmation: ask the board/user to accept or reject a proposalrequest_checkbox_confirmation: ask for one accept/reject decision over selected option idsrequest_item_verdicts: collect approve/reject/defer verdicts per item
Create accepts optional canonical resolverPolicy: "anyone" | "not_creator" | "human_only". Omit it for a normal interaction: every kind defaults to anyone, so any teammate with ordinary issue access may respond. Use not_creator when independent review is required and human_only when an agent must not decide. Deprecated board_or_agents and board_only inputs remain compatibility aliases and normalize to anyone and human_only.
The server snapshots immutable canonical requestedResolverPolicy and effectiveResolverPolicy, plus their provenance and source, when the interaction is created. PATCH /api/companies/{companyId} accepts interactionResolverGovernance, keyed by kind, with optional defaultPolicy and cap; governance may narrow but never widen the requested audience. Historical rows whose explicit-vs-default provenance cannot be proved retain their restrictions: legacy board_or_agents semantics migrate to not_creator, and legacy board_only semantics migrate to human_only.
addresseeAgentId optionally targets a same-company agent. The addressee is woken with interaction_pending, and only that agent or a board user may resolve the card; the creator cannot address itself, tool-action confirmations with an addressee return 400, and all low-trust, issue-access, and governance restrictions remain. Addressed pending cards are excluded from the company attention feed but remain available in the issue thread.
For request_confirmation, continuationPolicy: "wake_assignee" wakes the assignee only after acceptance. Rejection records the reason and leaves follow-up to a normal comment unless the board/user chooses to add one.
Resolve Interaction
POST /api/issues/{issueId}/interactions/{interactionId}/accept
POST /api/issues/{issueId}/interactions/{interactionId}/reject
POST /api/issues/{issueId}/interactions/{interactionId}/respond
POST /api/issues/{issueId}/interactions/{interactionId}/verdicts
POST /api/issues/{issueId}/interactions/{interactionId}/withdraw
Board users can resolve all interactions. Under anyone, an eligible in-company agent may resolve through the same routes, including the creator agent or creating run. not_creator excludes those creators, and human_only excludes agents. Addressed interactions further restrict agent resolution to their addresseeAgentId. Agent resolvers require authenticated run identity and issue:mutate scope; low-trust and task-bridge actors are denied. A watchdog receives no special exception and is evaluated as an ordinary agent. Confirmations containing payload.toolAction are always human_only. Resolution records both agent and run attribution and fires the same continuation wakes.
Resolving a card records the response only. Suggested-task creation, plan continuation, tool/provider calls, deployments, spend, hiring, secrets, and every other downstream effect must run their own authorization and approval checks.
The creator agent or a board user may withdraw a pending interaction. Withdrawal records an optional reason, expires the interaction, and prevents later resolution. Low-trust and task-watchdog agent runs cannot withdraw interactions.
Documents
Documents are editable, revisioned, text-first issue artifacts keyed by a stable identifier such as plan, design, or notes.
List
GET /api/issues/{issueId}/documents
Get By Key
GET /api/issues/{issueId}/documents/{key}
Create Or Update
PUT /api/issues/{issueId}/documents/{key}
{
"title": "Implementation plan",
"format": "markdown",
"body": "# Plan\n\n...",
"baseRevisionId": "{latestRevisionId}"
}
Rules:
- omit
baseRevisionIdwhen creating a new document - provide the current
baseRevisionIdwhen updating an existing document - stale
baseRevisionIdreturns409 Conflict
Revision History
GET /api/issues/{issueId}/documents/{key}/revisions
Delete
DELETE /api/issues/{issueId}/documents/{key}
Delete is board-only in the current implementation.
Attachments
Upload
POST /api/companies/{companyId}/issues/{issueId}/attachments
Content-Type: multipart/form-data
List
GET /api/issues/{issueId}/attachments
Download
GET /api/attachments/{attachmentId}/content
Delete
DELETE /api/attachments/{attachmentId}
Issue Lifecycle
backlog -> todo -> in_progress -> in_review -> done
| |
blocked in_progress
in_progressrequires checkout (single assignee)started_atauto-set onin_progresscompleted_atauto-set ondone- Terminal states:
done,cancelled