83e13db8fa
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The personal inbox uses issue activity to identify a person's participation. > - Issue reads can cancel stale recovery actions and record that cleanup as the reader's action. > - This adds unrelated tasks to the inbox and refreshes their activity timestamps. > - A workspace owner hold can also alternate between creation and cancellation after a task finishes. > - This pull request corrects cleanup attribution, excludes historical read cleanup, and retains one exact owner hold. > - Agents can read authorized issue activity to diagnose the same problem themselves. ## Linked Issues or Issue Description Refs #15742 excludes logs by the execution-recovery actor from activity timestamps. This PR covers reader-attributed stale recovery cleanup, personal inbox participation, exact workspace owner holds, and sandbox issue activity access. I searched open issues and PRs for recovery inbox and activity bridge fixes. I found no duplicate for this defect. **What happened?** Loading issue lists cancels stale recovery actions under the reader's identity. The personal inbox treats those rows as user participation. One completed issue had hundreds of such rows and no edits or comments by the affected reader. A retained native workspace owner repeatedly creates a verification action that read projections then cancel. Sandbox agents cannot inspect the issue activity because the reverse bridge rejects the route. **Expected behavior** Automatic cleanup belongs to the system and does not add an issue to a reader's inbox. Historical cleanup rows remain auditable but do not count as participation or recent activity. An unresolved physical workspace owner keeps one stable verification action. Agents can inspect activity only for issues their identity may read. **Steps to reproduce** 1. Finish a task whose native run retains an unverifiable workspace owner receipt. 2. Repeat workspace recovery checks and GET requests for issue detail, compact lists, and recovery actions. 3. Observe new recovery action IDs and reader-attributed cancellations in the activity history. 4. Query the personal inbox for that reader and observe the unrelated task. 5. From a sandbox agent, request GET /api/issues/:id/activity and observe Route not allowed. **Paperclip version or commit** Observed atf5346c05b9. Regression tests use current master behavior. **Deployment mode** Authenticated hosted instance with native and legacy sandbox agents. The inbox defect is independent of the adapter. ## What Changed - Attribute automatic stale recovery cleanup to the recovery system actor. - Exclude exact historical read cleanup rows from personal inbox membership, unread counts, and both activity timestamp queries. Keep all audit rows and explicit user recovery decisions. - Retain owner verification holds only while the exact company, run, issue, and owner fingerprint still match. Apply the same rule to reads and background recovery. - Make repeated checks for the same owner hold leave its identity, attempts, and timestamps unchanged. Keep physical takeover blocked. - Allow GET issue activity through the sandbox bridge. Keep the existing company and issue-read authorization and reject broader audit routes. - Add regressions and update the runtime API and recovery documentation. Refresh generated source references for the documentation edits. Update the paired activity, inbox, and recovery maps. ## Verification - Focused Vitest verification: 315 tests pass across five files. The updated terminal owner hold regression also passes. The files cover issue service, recovery routes, activity authorization, sandbox callback bridge, and native workspace finalization. - `pnpm -r typecheck` and `pnpm build` pass locally. The full general and serialized unit test matrix passes in CI on the latest commit. The duplicate local `pnpm test:run` was stopped after about 30 minutes once that full CI coverage passed; it did not report a local full-suite pass. - `node scripts/check-maps.mjs` passes for all paired areas and capability IDs. - Apex is 5/5 on commit44c3787888. Its access map finding is fixed and resolved. All CI checks are green on this commit. - The new regression repeats reads and background sweeps for done and cancelled tasks. It checks one unchanged hold, zero physical copyback, zero personal inbox participation, and system cleanup after the exact receipt is cleared. - Historical cleanup tests preserve explicit recovery decisions, nullable metadata, unread counts, and the original audit rows. - Authorization tests permit an authorized agent and reject cross-company or issue-boundary reads. Bridge tests reject write methods, extra path segments, and company-wide audit routes. ## Risks Existing inbox items can disappear if their only participation evidence was automatic read cleanup. No data migration or audit deletion is needed. An unresolved workspace owner remains visible after task completion; this preserves the physical writer fence. A stale or cleared owner does not retain the hold. Issue activity access expands only the sandbox transport allowlist and still uses existing controller authorization. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository inspection, code editing, shell execution, and test tools. The session identifies the model family as GPT-6. A more specific runtime model ID and context window size are not exposed. ## 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> Co-authored-by: Amy (Opus) <noreply@anthropic.com>
8.5 KiB
Recovery — agent access
Product map: Recovery.
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.
diagnosis
Review: baseline.
API: present — representative operation IDs:
GET /api/issues/{id}/diagnostics/blockers.GET /api/issues/{id}/recovery-actions.
Agent access: available — REST / native call_api; CLI issue diagnostics.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board.
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: Diagnostics expose recorded cause and boundaries; source-backed reading does not prove successful recovery.
bounded-continuation
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/recovery-actions/resolve.
Agent access: partial — Eligible agent REST / CLI; native generic mutation restricted.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board.
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: Underlying route has agent checks; no corresponding default native recovery mutation tool is advertised.
source-action
Review: baseline.
API: present — representative operation IDs:
GET /api/issues/{id}/recovery-actions.POST /api/issues/{id}/recovery-actions/resolve.
Agent access: partial — Eligible agent REST / CLI; source-bound recovery state.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board. Completion or cancellation of a task does not clear its exact unresolved native workspace owner hold. Physical owner release still requires the operator stop-verification procedure.
Evidence: source-only — implementation at
the reviewed commit above. Exact owner hold retention in the
recovery state helper
was reviewed at 89770ba707fb1ebd4cabd184eec2e7fee226e0c3.
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. Local
recovery route regressions
verify one unchanged hold across reads and sweeps on done/cancelled tasks, no
physical copyback, and cleanup after the receipt is cleared. Exercise this
sequence in a disposable instance; automatic cleanup must use the system actor
and must not create reader participation. No live recovery proof is claimed.
Gaps: Need operation-level eligibility and a real native binding for permitted recovery actions; do not route around lifecycle authority.
exhaustion
Review: baseline.
API: present — representative operation IDs:
GET /api/issues/{id}/recovery-actions.GET /api/heartbeat-runs/{runId}.
Agent access: partial — REST / native call_api reads; operator escalation flow.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board.
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: Reading exhaustion is supported. Continuing past the recorded gate requires the specified owner/action.
workspace
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/recovery-actions/retry-workspace-export.POST /api/execution-workspaces/{id}/reconcile-branch.
Agent access: restricted — Board/runtime management APIs; agent reads diagnosis and
performs permitted workspace work.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Export retry/reconciliation APIs exist but require board. Native generic execution-control mutations are also blocked.
unknown-outcome
Review: baseline.
API: present — representative operation IDs:
POST /api/chat-endpoints/{endpointId}/publications/{publicationId}/resolve.
Agent access: restricted — Board provider-outcome resolution; agent may inspect
assigned provider tools.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Uncertain-side-effect resolution is operator/source-specific; do not replay to obtain apparent parity.
user-continuation
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/comments.
Agent access: partial — User comment API and server-owned wake reconsideration; native
agent consumes bound wake.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board.
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: Receiving the continuation is supported; impersonating a saved user message or retry control is not.
reconnect
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/events/ws.GET /api/issues/{id}.
Agent access: partial — Existing event protocol; REST refresh of persisted task state.
Policy: Task/run visibility, run ownership and source/action policy; workspace export retry and some operator controls require board.
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: Streaming reconnect needs its protocol client. Polling/read APIs remain available; replay is not proof of a fresh successful action.