2 Commits

Include renames

Author	SHA1	Message	Date
3 people	83e13db8fa	fix(inbox): keep automatic recovery cleanup out of personal participation (#16063) ... ## 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 at f5346c05b9. 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 commit 44c3787888. 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>	2026-10-12 19:25:15 -07:00
DottaandPaperclip	7d9b93aee2	docs: establish paired feature and agent access maps (#16025) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Contributors use the feature map to understand and verify product capabilities. > - Agents need APIs and usable entry points within their permission boundaries. > - Product recipes and agent access need separate records with shared capability IDs. > - This pull request establishes that contract and gives maintenance ownership of both maps. > - The benefit is repeatable access review without changing product behavior or permissions. ## Linked Issues or Issue Description Refs: #15983, which added the portable verification skills and updated the feature map. This is its contract-only follow-up. Related: #15288 added the original feature map. **Issue type** Missing documentation and maintenance contract. **Where is the issue?** The product map, its missing agent access companions, and the verification skills. **What's wrong?** There is no shared convention for API presence, agent entry points, permission boundaries, access gaps, or evidence. An API declaration does not prove that a permitted native or remote agent can use it. **Suggested fix** Keep the product and agent access maps as siblings under `maps/`. Reuse capability IDs. Record representative source inventory separately from operation review and live proof. Keep both maps aligned through the maintenance skill. ## What Changed - Move the existing product map to `maps/feature-map/`. Preserve its recipes and Poteto format. Update relative links and add companion links. - Add `maps/agent-access-map/` with 35 area files and 171 matching capability IDs. Seed representative API operations, agent paths, policies and known gaps from the reviewed source inventory. Mark entries as `baseline`, `source-only`, and live verification `not-run`. - Define the shared contract in `maps/README.md`. Track API presence, agent availability, policy, evidence and review depth separately. Require operation enumeration before marking a broad capability operation-reviewed. - Extend `maintain-verification-skill` to reconcile both maps and inspect actual route policy and production tool admission. Update creation, verification, notices and contributor references to use the shared contract. - Add `scripts/check-maps.mjs` and ten regression tests. Check matching areas/IDs, indexes, references, contract fields, API method/path examples, justified exceptions and evidence-state consistency. - Keep the coverage inventory unchanged. Preserve skill invocation policies and both MIT license blocks. No product API, permission, UI, runtime helper, migration, dependency or workflow changes. ## Verification - Passed: `node scripts/check-maps.mjs` reports 35 paired areas and 171 matching capability IDs. All local map references resolve. - Passed: `node --test scripts/check-maps.test.mjs` runs ten tests. Fixtures cover missing companions, renamed/orphan/duplicate IDs, broken references, missing operation fields, empty exceptions, missing API examples, empty policy fields, and verified evidence without passed verification. - Passed: metadata validation for all three verification skills. Skill and contributor links resolve. Invocation policies and both license blocks are unchanged. - Compared relocated recipes with current master. Contents differ only in relative links and companion links. `coverage.json` is byte-for-byte unchanged. Master's updated read-only interaction test reference is retained. - Passed: `git diff --check`. The branch starts from current master and contains only this contract change. - Repository-wide typecheck, tests and build were not run locally for this documentation and Node structural-check scope. Live agent access was not exercised. Those gaps are explicit in the baseline entries; the structural check does not certify behavior. CI and automated review are pending. ## Risks - The companions are representative source baselines. They are not complete operation inventories or passed agent journeys. - The checker cannot establish actual permissions, native tool admission, operation completeness or truthful live evidence. Maintenance must inspect source and verify with the actual permitted agent context. - External links to the old product-map directory may need updates. Repository references have been updated. - Existing access gaps and board/user restrictions remain recorded. This contract does not change authority or implement missing paths. ## Model Used OpenAI GPT-6 through Codex assisted with this change. The session does not expose the exact serving model ID, configured context-window size, or reasoning setting. Capabilities used: source analysis, file edits, shell commands, and structural regression tests. ## 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 Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-12 14:52:28 -05:00