Devin FoleyandPaperclip
6c198d616e
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Tasks have one owner, and the server records assignment changes. > - An agent can finish its work by handing the task to a human for review. > - The assignment route stops the active run before it saves that handoff. > - When the caller is that run, a slow workspace restore can exceed the stop timeout and prevent the assignment from saving. > - Recovery can then mark the task Blocked while its comment says the handoff succeeded. > - This pull request lets the authenticated legacy run save a human handoff and finish its turn normally. > - Other actors and transfers to executable agents keep the verified stop requirement. ## Linked Issues or Issue Description Refs #13730. Related: #13782, #14700, and #15094. **What happened?** An agent posted its review handoff, then sent `PATCH /api/issues/{id}` to assign the task to its human creator with status `in_review`. The route cancelled that same run before saving the assignment. Workspace restore took 66 seconds. The stop limit is 60 seconds. The assignment never committed. Recovery marked the task Blocked, and it stayed assigned to the agent. **Expected behavior** The authenticated active legacy run can hand its own task to a human and finish normally. The human assignment and requested review status must save without waiting for workspace restore. Native runs, board reassignment, agent API keys, and transfers to another agent still require a verified stop. **Steps to reproduce** 1. Run a legacy agent on its assigned task with a signed run token. 2. Send a task PATCH from that run with a human `assigneeUserId`, a null `assigneeAgentId`, and status `in_review`. 3. Make stopping the sandbox take more than 60 seconds. Before this fix, the handoff fails before the task update. With this fix, the update saves and the run finishes normally. **Paperclip version or commit** Reproduced in hosted execution. The patch is based on master at `56a0bf0d492`. **Deployment mode** Hosted authenticated server with a legacy agent in a remote sandbox. The same route serves local deployments. PR #13782 proposes a broader exemption for all self-handoffs. This focused change limits the exemption to human recipients and legacy runs. It checks the exact active run, agent, company, and task, and it retains the stop requirement before an executable successor can take ownership. PRs #14700 and #15094 address later wake and recovery behavior after a reassignment stop. ## What Changed - Skip the reassignment cancellation only for an authenticated legacy run handing its own task to a human. - Reject later mutations from the outgoing run against its human-owned task, both in route authorization and under the update transaction locks. - Keep assignment permission checks, goal control, and queued human response protection. - Add route regressions for slow stops, active-run lookup, actor and runtime boundaries, recipient types, permission denials, and follow-up edits, completion, and reassignment. - Update the real HTTP low-trust handoff test to prove the run stays alive, its late edit fails, and the human wake receipt remains invalidated. - Add Postgres tests for saved assignment, former-owner rejection, and review state after the outgoing run succeeds or fails. - Document the handoff rule and update the task feature and agent access maps. ## Verification - 328 relevant tests passed across the route, issue service, low-trust HTTP, and legacy recovery suites. The route suite passed all 160 tests, and all 13 low-trust HTTP tests passed after updating the obsolete cancellation expectation. - Removing the production guard makes both slow-shutdown handoff regressions fail with HTTP 500. - `pnpm -r typecheck` passed. - `pnpm build` passed. - `node scripts/check-maps.mjs` passed. - `git diff --check` passed. - All 54 current-head checks passed; 2 optional Storybook checks were skipped. The CI lanes cover the full Vitest suite, typecheck/build, Runner checks, and product E2E checks. - Apex reviewed `c68fbfb356c3d80eb7136babb49940709a3c3459` at 5/5 with no findings; both earlier review threads are resolved. - The complete test lanes passed in CI. The duplicate local full `pnpm test:run` was stopped after CI completed; it did not finish locally. All 328 focused local tests and full local typecheck/build passed. ## Risks - The outgoing legacy turn stays alive after the human takes ownership. Route and transactional ownership checks reject its later mutations of the human-owned task. Read and comment access follows normal policy. Goal control still runs before the handoff. - This exemption does not apply to native runs or another agent as recipient. Those paths still stop the old execution before assignment. - This fix prevents future failed handoffs. It does not infer or replay old assignment requests. - There is no schema change or API shape change. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository tools, and code execution. The session does not expose a more specific runtime model ID or context window size. ## 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>
5.6 KiB
Task creation and lifecycle — agent access
Product map: Task creation and lifecycle.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
create
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/issues.
Agent access: available — Native create_task; REST / CLI / MCP.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Creation is implemented; agent/user assignment and attachments may need narrower/different APIs.
organize
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/issues.
Agent access: available — Native search_tasks; REST / CLI; UI grouping/navigation
state separately.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Search/filter API exists; sorting/grouping/presentation defaults are not necessarily shared server preferences.
properties
Review: baseline.
API: present — representative operation IDs:
PATCH /api/issues/{id}.PUT /api/issues/{id}/title.
Agent access: partial — Native set_task_title/reassign_task/set_dependencies; fallback
for permitted non-lifecycle fields; REST.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules. A legacy run can assign its own task to a human without cancelling itself only with its signed run token and matching active run, agent, company and task. The outgoing run cannot mutate its human-owned task afterward, including through a late update already admitted before the handoff. Agent keys, native runs, board reassignment and transfers to another agent retain verified-stop requirements.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability. Focused route
regressions in ownership tests
cover a human handoff and stop enforcement for other actors, runtimes and targets;
they use mocked services and do not claim live execution proof.
Gaps: Native fallback blocks status/assignment/dependency policy fields. Dedicated tools differ in scope and supported fields.
discussion
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/comments.POST /api/companies/{companyId}/issues/{issueId}/attachments.
Agent access: available — Native report_progress/comment_on_task/register_deliverable;
REST / CLI / MCP.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Other-task comments and active-task progress have separate scopes; explicit reopen/interrupt is not a generic comment capability.
completion
Review: baseline.
API: present — representative operation IDs:
PATCH /api/issues/{id}.
Agent access: available — Native paperclip_finish/paperclip_block through runner
protocol; legacy agent REST disposition.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Server governs whether a reported result becomes done/review/blocked. A generic lifecycle PATCH is intentionally rejected for native runs.