61 Commits

Include renames

Author	SHA1	Message	Date
Devin FoleyandPaperclip	fe85fd7ac4	Expire closed workspaces that open descendants do not use (#17464) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Git cache expiration removes closed issues' worktrees and saves restore points for unsaved work > - It treated a workspace as closed only when the source issue and every descendant were done or cancelled > - A routine that closes a parent and leaves children open for days therefore kept every parent worktree, although the children work in their own workspaces > - The idle path did not help, because the children are updated every day > - This pull request counts only the issues that use the workspace when it decides that a closed workspace can expire > - The benefit is that closed parent worktrees are removed while their children work elsewhere, and a child that later binds to the workspace gets it back from the restore point ## Linked Issues or Issue Description Refs #17271. Bug report described in-PR (bug report template). **What happened?** On one instance, an hourly routine creates a parent issue, works it in its own worktree, marks the parent done, and leaves child issues open (`blocked`, `in_review` or `in_progress`) for days. The children work in their own workspaces. They are not bound to the parent's workspace. Git cache expiration kept every parent worktree (about 300 MB each), because the closed-tree check and the workspace reaper required all descendants to be closed. In one project, 18 of 19 long-closed parent worktrees were kept only by open children that did not use them. The idle path never ran, because the children were updated daily. **Expected behavior** A closed issue's worktree expires while descendants are open, as long as no open descendant uses that workspace. **Steps to reproduce** 1. Enable git cache expiration and restore points. 2. Close an issue that has an isolated git worktree, and leave a child issue open that works in its own workspace (or has no workspace binding). 3. Wait past the terminal delay and run the workspace reaper: the parent worktree stays, and the reaper counts it as `skippedNonTerminalTree`. **Paperclip version or commit:** `master` at 410e5c6eed. **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). ## What Changed - `isGitWorkspaceExpirationEligible` (closed path, not the idle path): the "tree closed for one day" check now covers only the issues in the tree that use the workspace. An issue uses the workspace when it is the source issue, when its `execution_workspace_id` is the workspace, or when its current `workspace_selection` or its `workspace_pending_selection` selects it as the `existing` workspace. Inheritance from a parent (`reuse_existing`) and `existing` selections are both stored as `execution_workspace_id`, and heartbeat workspace resolution reuses an existing workspace only through that binding or a run's persisted native binding. An open descendant without one of these references gets a new workspace on its next run, so it no longer keeps the parent's worktree. - All other checks stay the same: any open issue bound to the workspace, live or unsettled runs of any issue in the tree or of the workspace (including a run whose context names the workspace), finalizations, leases, recovery actions, runtime services, shared cwd and the reopen fence. - Workspace reaper: when the source issue is closed, git cache expiration applies, and no reopen is pending, the reaper routes the workspace by the same rule. It takes the restore point due time from the source issue and the descendants that use the workspace, also after every descendant is closed. A recently closed child that used the workspace still holds it for the terminal delay. The compaction delay and the archive cooldown still use the whole tree when it is closed. - Workspace reaper: compaction and the normal archive path keep their behavior. While any descendant is open, the reaper does not compact the worktree, and the expiration branch handles the workspace and continues. The archive path still requires a closed subtree. With expiration off, or a pending reopen, routing is unchanged. - New exported helper `listIssuesUsingGitWorkspace` shares the SQL "uses the workspace" predicate between eligibility and the reaper. - Docs: `doc/recoverable-disk-cleanup.md` and the `PAPERCLIP_GIT_RESTORE_POINT_TERMINAL_DELAY_DAYS` entry in `doc/DEVELOPING.md`. - The existing `preserves live descendants and pending reopening` case now binds its open child to the workspace. An unbound open child no longer keeps the worktree by design. ## Verification - `pnpm exec vitest run src/__tests__/git-restore-point-expiration.test.ts src/__tests__/git-workspace-expiration.test.ts src/__tests__/heartbeat-git-restore-point-resume.test.ts` in `server/`: all pass. - `pnpm exec vitest run src/__tests__/git-workspace-expiration src/__tests__/git-restore-point src/__tests__/execution-workspace src/__tests__/heartbeat-git-restore-point-resume src/services/heartbeat/environment-selection src/__tests__/isolated-repository` in `server/`: 15 of 17 files passed in one parallel run. The other failures were the updated descendant case (now fixed) and 45-second timeouts in restore point tests while 17 embedded Postgres files ran at the same time. Both files pass when run on their own. - `pnpm run typecheck` in `server/`: passes. - New embedded Postgres cases with real git repositories: - A closed parent with open `blocked`, `in_review`, `in_progress` and `todo` children and a grandchild in their own workspaces (or with none): the worktree expires with a restore point and the reopen restores it exactly. - The reaper archives it, timed from the issues that use the workspace. A child closed one minute ago with its own workspace does not delay it. - A recently closed child bound to the workspace holds it until its terminal delay passes. - When every child is closed and the most recent one used its own workspace, the reaper does not restart the restore point delay. - The worktree is kept when an open child is bound to it, when an open grandchild under a child with its own workspace is bound to it, when a child created later with `issueService.create` inherits it with `reuse_existing`, when an open child selects it through `workspace_selection` or `workspace_pending_selection`, when a child run that references it is live, and when the parent was closed inside the delay. - The reaper never compacts the worktree while children are open, with expiration on or off. A pending reopen keeps its current fence handling. - After expiry, an open child that binds to the workspace reopens it with the saved commits, index, working tree and untracked files. - Heartbeat: a queued run for an open child that binds to the expired workspace of a closed parent restores the workspace and runs the agent in it with the saved state. - Mutation checks (each run against the two restore point test files): - Closed-tree check restored to the whole tree: 7 tests fail. - `execution_workspace_id` removed from the rule: 3 fail. - `workspace_selection` removed from the rule: 1 fails. - `workspace_pending_selection` removed from the rule: 1 fails. - Reaper `latestTerminalAt` from the whole tree: 3 fail. - Reaper routing by the whole tree: 2 fail. - Reaper restore point due time from the whole tree once it is closed: 1 fails. - Pending-reopen gate removed: 1 fails. - Compaction gate (`!treeOpen`) removed: no test fails. Compaction's own guard under the lifecycle lock still rejects open trees, so the gate only skips work that cannot succeed. - Not run: the full server suite and the UI suites. CI covers them. ## Risks - Closed parent worktrees now expire while their children are open. A child that later binds to the workspace depends on the restore point and on the run-side reopen from #17271. The new tests cover this path. When restore points are off, only exactly reproducible worktrees expire. - An open child with no workspace binding no longer keeps the parent's worktree. Heartbeat resolution never reuses a workspace without a binding, so this does not change where the child runs. - The rule is conservative. A workspace selected only by an issue's current or pending selection is kept, and live runs of any issue in the tree still block. - The reaper runs one extra indexed query for each closed workspace when git cache expiration applies. No migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use. ## 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-24 12:43:57 -07:00
Devin FoleyandPaperclip	785d54636e	Delete re-homed isolated clones when their contents are reproducible (#17410) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Isolated task workspaces are Git worktrees on the server disk, and the terminal workspace reaper keeps that disk usage bounded > - #17369 moves old workspaces off their private per-issue clones onto the project's shared clone and then deletes the private clone > - On one instance, the first live sweep moved 12 workspaces but deleted none of their clones (about 600 MB each), and 3 workspaces could not move because their restore point was "too large" > - The kept clones are not referenced by any workspace, so no other cleanup removes them > - This pull request replaces the clone check with a real reproducibility check, sweeps the orphaned clones, lifts the restore point limits for local transfers, and fixes a false `source_identity_changed` > - The benefit is that the disk space #17369 was meant to reclaim is reclaimed, without deleting unique work ## Linked Issues or Issue Description Refs #17369. Bug report described in-PR (bug report template). **What happened?** On one instance, with `PAPERCLIP_ISOLATED_SOURCE_REHOME_ENABLED=true` and dry run off, the first sweep re-homed 12 workspaces, skipped 5 with `live_or_unresolved_consumer` and 3 with `restore_point_too_large`. No clone was removed: 11 logged `cloneKeptReason: "clone_checkout_has_files"` and 1 logged `"source_identity_changed"`. Each clone's own checkout was clean (`git status --porcelain --untracked-files=all` empty). Its only history that the shared clone lacked was remote branches and release tags that the shared clone never fetched, which exist on the remote. An operator removed 11 clones by hand after verifying them. **Expected behavior** A re-homed clone whose checkout is clean and whose local history is in the shared clone or on the remote is deleted. A clone with real unique work is kept. Workspaces whose changes exceed the upload limits still move, because the transfer is local. **Steps to reproduce** 1. Use a project repository whose `.gitignore` (or the clone's `info/exclude`) contains `.paperclip/`, with a release tag on a commit that is not on any branch. 2. Re-home an isolated workspace of that repository with #17369. 3. The old worktree is removed, the empty `.paperclip/worktrees` directory stays, and `git ls-files --others --ignored --directory` lists `.paperclip/`. The clone is kept with `clone_checkout_has_files`. Without the ignore line, the local release tag keeps it with `unique_clone_history`. 4. Add a file larger than 64 MiB to a workspace. The move skips with `restore_point_too_large`. **Paperclip version or commit:** `master` at aa0037a137 (rebased on ee29e2850d, after #17407). **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). ## What Changed - New clone reproducibility check (`cloneDisposable` in `server/src/services/isolated-repository-rehome.ts`), used before deleting a re-homed clone: - `git worktree prune`, then only the clone's own worktree may remain (`base_has_worktrees`); - no tracked changes and no untracked files (`clone_checkout_has_files`); the only untracked exception is Paperclip's compaction trash; - ignored files only inside regenerable directories (`node_modules`, `dist`, ...) or Paperclip's compaction trash. Ignored entries are listed with `--no-empty-directory`, and a non-regenerable ignored directory is expanded file by file, so empty directories such as the old worktree's `.paperclip/worktrees` parent no longer count; - only `refs/heads`, `refs/tags` and `refs/remotes` (no stash, notes or replacement refs: `unsupported_clone_refs`); - every commit reachable from local branches, local tags, non-remote reflogs, `ORIG_HEAD` and `HEAD` (so a detached checkout counts) must be on a remote-tracking ref, present in the shared clone, or on the remote. The remote check reuses `hasCommitsMissingUpstream` (now exported), which fetches the remote's branches and tags into a temporary store, and it runs only when some commit is in neither place. A local tag is accepted when its commit is on the remote. Otherwise the clone is kept (`unique_clone_history`), or kept with `managed_checkout_upstream_unavailable` when the remote cannot be read; - existing 5,000 budgets for refs, reflog entries and unique commits (`clone_history_budget`), plus at most 1,000 ignored directories outside regenerable ones, read in one Git call (`clone_file_budget`); - the log entry now includes `cloneKeptPaths`: up to five paths, worktrees, refs or commits that kept the clone. - Cleanup also checks that the clone's `origin` still matches the workspace `repoUrl` before deleting it. - Old worktree ownership (#4): it is proven by `git rev-parse --git-common-dir`, or, when that fails, by the worktree's `.git` pointer into `<clone>/.git/worktrees/`. - Orphan sweep (`sweepOrphanedIsolatedRepositorySources`): at the first reaper rotation after server start (feature on), it walks `isolated-repository-sources/<company>/<issue>/checkout`. It holds the isolated source lock and skips clones that a workspace still needs (an open workspace with matching `isolatedRemoteSource`, a closed one that is not expired with its worktree removed, a project workspace or a running service), clones with a pending move, and clones whose re-homed workspace still has its own cleanup pending. The repository URL comes only from the database: the issue's workspaces must record exactly one URL and the clone's `origin` must equal it (`unproven_repository` or `source_identity_changed` otherwise), so a rewritten `origin` is never fetched. It then applies the same check (using the shared clone of a workspace of the same issue and repository when one exists), renames to trash and deletes. It logs `event: "execution_workspace.isolated_source_orphan_cleanup"` and removes leftover trash directories from interrupted removals. It inspects at most eight issue directories per reaper sweep and resumes from the saved position in the next sweep, so slow remotes cannot hold up other cleanup. When a full walk kept any orphan, it registers a deadline one day later in the reaper's existing deadline set. Otherwise it registers nothing until the next server start. No new timer. - Restore point limits for re-home (#3): `ISOLATED_REHOME_RESTORE_POINT_LIMITS` (500,000 files, 1 GiB per file and in total, 1.5 GiB bundle, 1,000,000 commits) replaces the upload defaults for this local transfer. Verification is unchanged (exact snapshot equality). In `git-restore-point.ts`, `applyRestorePoint` now streams `git diff --binary` into `git apply` instead of buffering it (and skips the pipe when there is no diff, so no new Git version is needed). On a failure it kills both processes and waits for both. The ignored-file read sizes its buffer from the tree instead of the default limit. - Docs: `doc/recoverable-disk-cleanup.md`. ### What I found for `source_identity_changed` (#4) In #17369, cleanup ran `git rev-parse --git-common-dir` in the old worktree and used `""` when the command failed. Then it compared that to the clone's `.git` path, so any Git failure in the old worktree was reported as `source_identity_changed`. Git fails there when the old worktree's registration in the clone (`<clone>/.git/worktrees/<name>`) is gone while the directory still exists. Its `.git` file then points to a missing directory. I reproduced this by deleting the registration after a re-home: the old code keeps the clone with `source_identity_changed`, the new code removes the old worktree and the clone. I could not inspect the instance, so the exact event that removed that one registration is not confirmed. The check was a false positive in that case, and the fix proves ownership from the `.git` pointer instead. A worktree whose pointer leads outside the clone is still kept. ## Verification - `pnpm exec vitest run src/__tests__/isolated-repository-rehome.test.ts` in `server/`: 28 passed (real Git repositories, embedded Postgres). New cases: - a clean clone whose only extra history is a remote branch and a release tag on a commit outside any branch, both absent from the shared clone, with `.paperclip/` ignored in the clone: deleted; - a clone with a local branch commit that is neither upstream nor in the shared clone: kept (`unique_clone_history`, the commit is in `cloneKeptPaths`); - a clone with a tracked change, then an ignored non-regenerable file next to an ignored `node_modules`, then an untracked `build/notes.txt`: each kept (`clone_checkout_has_files` with the path), then deleted after cleanup; - a clone with a second registered worktree: kept (`base_has_worktrees`); - a clone whose detached `HEAD` holds the only copy of a commit (reflogs expired): kept (`unique_clone_history`); - an old worktree whose registration was pruned: old worktree and clone removed; - an orphan whose `origin` was rewritten is kept with `source_identity_changed`, and with `unproven_repository` once no workspace records its repository; - 1,001 ignored directories keep a clone (`clone_file_budget`); - orphan sweep: a batch of one returns a resume position and the next batch finishes the walk; a dry run changes nothing. Then an orphan whose history is in the shared clone or on the remote is deleted, and an orphan with no workspace rows and an unpushed commit is kept, with the next deadline one day later; - a workspace with 65 MiB untracked and ignored files (default capture refuses them with `restore_point_too_large`) moves with an exact snapshot match. - After rebasing on #17407 (nested clone migration, which reuses helpers from the re-home module): `isolated-repository-rehome`, `nested-clone-migration`, `execution-workspaces-service`, `execution-workspaces-routes`, `execution-workspace-reopen`, `execution-workspace-compaction`, `execution-workspace-policy`, `execution-workspace-runtime-control-conflict`, `execution-workspace-runtime-lease-route`, `git-workspace-expiration`, `git-restore-point`, `git-restore-point-expiration`: 405 passed; typecheck passes. - Related suites in `server/` (before the rebase): `git-workspace-expiration`, `git-restore-point`, `git-restore-point-expiration`, `execution-workspace-reopen`, `execution-workspaces-service`, `execution-workspace-compaction`, `heartbeat-git-restore-point-resume`, `heartbeat-project-repositories`, `git-reproducible-managed-checkouts`, `isolated-remote-workspace-source`, with the new suite: 398 passed. - `pnpm run typecheck` in `server/` passes. - Mutation checks, each failing a test: - remote proof replaced by "always unique": the unfetched-history and orphan tests fail; - remote proof replaced by "never unique": the local-commit and orphan tests fail; - `.git` pointer fallback removed: the pruned-registration test fails; - re-home limits removed: the large-file test fails; - orphan sweep removed from the reaper: the orphan test fails; - worktree count check removed: the second-worktree test fails; - regenerable-directory exception applied to untracked files: the dirty-checkout test fails; - orphan batch limit removed: the orphan test fails; - orphan URL taken from the clone again: the rewritten-origin test fails; - ignored directory budget removed: the many-directory test fails; - `HEAD` left out of the checked commits: the detached-HEAD test fails. - Dropping only `--no-empty-directory` does not fail a test, because the per-directory expansion also accepts an empty ignored directory. The two mechanisms are redundant on purpose. - Not run: the full server suite, or the change on a live instance. ## Risks - Deleting a clone now depends on reading the remote when some local commit is neither on a remote-tracking ref nor in the shared clone. If the remote cannot be read, the clone is kept. - Commits that only remote-tracking refs hold (for example a remote branch deleted upstream after the clone fetched it) are treated as not unique, as before. They were pushed once. - The orphan sweep deletes clones that no workspace refers to. A closed workspace that is expired with its worktree removed does not count as a user, because reopening it rebuilds from the shared clone or clones again. - Re-home transfers can now use up to about 1.5 GiB of memory for a single restore point payload, so a very large workspace uses more memory during its move than before. - The orphan sweep runs once per server start and then only while it keeps an orphan, so a clone that becomes orphaned later waits for the next restart. - No migration. No schema change. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file editing, Git, test runs). ## 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-24 09:17:28 -07:00
Devin FoleyandPaperclip	70de7d49e9	Migrate standalone nested clones onto the shared project clone (#17407) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Each task runs in a git worktree. Extra project repositories sit in the task under `.paperclip-repositories/`. > - #17382 made new nested checkouts git worktrees of one shared clone per project repository. Existing standalone nested clones stayed as full clones. > - Long-lived tasks keep those clones for a long time. Many tasks hold the same large repository, so most of the disk is duplicate `.git` data. > - #17369 added a locked and verified move of isolated workspaces onto the shared clone, with a reaper sweep behind a setting. > - This pull request adds the same kind of locked and verified conversion for standalone nested clones in open tasks, and runs it from the same reaper path behind a new setting. > - The benefit is that the duplicate clones go away without losing any state or local history, and the disk stops filling. ## Linked Issues or Issue Description Refs #17382 #17369. Bug report described in-PR (bug report template). **What happened?** On one instance, 44 open task worktrees in one project each hold a standalone nested clone of the same large repository. Together they use about 25 GB. About 16 GB of that is duplicate `.git` data. Another project has 33 smaller clones. The clones are removed only when their tasks expire, and many tasks stay open for a long time. The disk keeps filling. **Expected behavior** Existing standalone nested clones in open tasks become worktrees of the project's shared clone, with the same state and local history, and the standalone clones are deleted. **Steps to reproduce** 1. Prepare a task with a nested project repository before #17382, or without a shared clone, so that `.paperclip-repositories/<name>` is a standalone clone. 2. Create the project's shared clone, as #17382 does for new tasks. 3. Observe that the old checkout stays a full clone until the task expires. **Paperclip version or commit:** `master` at 8549ecaf9a. **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). ## What Changed - New `server/src/services/nested-clone-migration.ts`. It converts one standalone nested clone in an open execution workspace into a worktree of the shared clone: - It holds the source lock and workspace lifecycle lock (as git cache expiration does), the per-shared-clone lock from #17382, and the expiration lock files (`index.lock`, `HEAD.lock`, current branch ref lock) in the clone. - It requires the #17369 no-live-consumer eligibility (no live runs, leased finalizations, unreleased leases, running services, or reopen flag). It checks again before the swap. - It identifies the repository by managed checkout name, project workspace rows and the origin URL, and it requires a verified shared clone. - It brings local history into the shared clone under the checkout's own `paperclip/<id>/` prefix. The current branch becomes `paperclip/<id>/<branch>`, tracking `origin/<branch>`. Unpushed local branches become `paperclip/<id>/<branch>`. Unpushed tags become `paperclip/<id>/tags/<tag>`. A restore point carries the commits, the `HEAD` reflog and `ORIG_HEAD`. - It stages the worktree at `<name>.clone-migrating`, applies the restore point, copies the `HEAD` reflog and `ORIG_HEAD`, and moves regenerable dirs, untracked `.env` files and `.claude/settings.local.json` by rename. Old and new must then match exactly (snapshot, history, branch, created refs, moved items). - Swap: it renames the clone to `<name>.clone-standalone`, runs `git worktree move` and `git worktree repair`, updates a saved restoration recipe that lists the checkout, and then renames the old clone to trash and deletes it. - A `nestedCloneMigrationPending.<name>` metadata record makes recovery possible. A crash before the swap rolls back (moves items back, removes the staged worktree and the created branches). A crash after the swap rolls forward. - Skip reasons (nothing changes): `live_or_unresolved_consumer`, `unknown_managed_checkout`, `local_source_checkout`, `foreign_origin`, `no_shared_base`, `shared_base_repo_mismatch`, `unsupported_base_git_config`, `nested_clone_has_stash` (stashes are skipped, because `refs/stash` would be shared by every worktree), `nested_clone_has_worktrees`, `nested_clone_has_hooks`, `unsupported_local_git_config`, `unsupported_local_git_state`, `unsupported_info_exclude`, `unsupported_nested_clone_refs`, `unsupported_index_flags`, `unique_branch_reflog_commits`, `nested_clone_ref_conflict`, `snapshot_mismatch`, `history_mismatch`, restore point limits, and `nested_migration_recovery_conflict`. - Reaper: `sweepTerminalWorkspaces` runs the conversion for open workspaces when `PAPERCLIP_NESTED_CLONE_MIGRATION_ENABLED=true` (default off). `PAPERCLIP_NESTED_CLONE_MIGRATION_DRY_RUN=true` only reports. Each attempt logs `event: "execution_workspace.nested_clone_migration"` with outcome, reason, branch, candidate bytes and reclaimed bytes. There is no new timer. A retry deadline is registered on the existing reaper deadlines only for a pending record or a transient skip (live consumer, busy lock, changed row). A workspace is attempted again at most hourly. A workspace without standalone clones costs one directory listing. - `isolated-repository-rehome.ts`: I exported the shared pieces (eligibility, locks, safe base config check, transfer plan, history boundary, snapshot and history keys, item moves, rollback and verification) instead of copying them. Re-home behavior does not change. - `nested-repository-worktrees.ts`: I exported the stale registration cleanup and added the `moveNestedRepositoryWorktree` (move and repair) and `trackNestedWorktreeUpstream` helpers. - Docs: `doc/recoverable-disk-cleanup.md` (new section about the conversion) and `doc/DEVELOPING.md` (settings). ## Verification - `cd server && pnpm exec vitest run src/__tests__/nested-clone-migration.test.ts`: 19 passed. It uses embedded Postgres and real git repositories, and covers: - Conversion with an unpushed commit, a second branch with unpushed commits, a lightweight tag and an annotated tag, staged and unstaged edits, a deleted file, an untracked file with mode 0600, an ignored file, `node_modules`, `.env` and the settings file. The result is a worktree of the shared clone (`--git-common-dir`), with the same HEAD, status, staged content and reflog, the owned branch tracking `origin/main`, and the history under the task's prefix. No other branch in the shared clone changes. The old clone is gone and reclaimed bytes are reported. - Skips with nothing changed: stash, live run, foreign origin, unknown checkout, no shared clone, local excludes, and a change between capture and verification (hook). - Two tasks convert concurrently against one shared clone. The test holds the shared-clone lock and shows that neither conversion advances. Then they run one at a time (peak 1), and each keeps its own branches. - Crash recovery at `afterAside`, `afterMove` and `afterFinalize` (roll forward), and before the swap (roll back, then convert). A dry run reports the pending record and changes nothing. - Expiration and restore of a converted checkout work afterwards. Unpushed branches in a converted checkout block expiration (`unpushed_managed_checkout_branches`). - Reaper: disabled by default; dry run changes nothing and registers no deadline; a live run registers a retry deadline that survives a second sweep; enabled conversion leaves no deadline. - Commits that only the clone's `origin` remote-tracking refs hold are kept as `paperclip/<id>/remotes/origin/<branch>`. - A pending conversion is finished after the workspace is archived, and forgotten (keeping unpushed branches) when the worktree is gone. - A filter planted in the shared clone right before the worktree add is refused (`unsupported_base_git_config`) and never runs. - Only checkouts named after configured project repositories are considered; at most 8 per sweep, pending first, rotating (unit test). - Related suites (run before review fixes; the nested, re-home and execution workspace service suites were rerun after them): `pnpm exec vitest run` on execution-workspaces-routes, execution-workspaces-service, git-reproducible-managed-checkouts, git-restore-point (all 5 files), git-workspace-contents, git-workspace-expiration, git-workspace-expiration-eligibility, heartbeat-git-restore-point-resume, heartbeat-project-repositories, isolated-repository-rehome, nested-clone-migration: 15 files, 393 tests passed. - `cd server && pnpm run typecheck` (`tsc --noEmit`): passes. - Mutation checks. Each mutation makes the targeted test fail, and I reverted each one: - Remove both eligibility checks: the live run test fails. - Remove the snapshot comparison: the capture/verify change test fails. - Disable roll forward after the swap: the recovery tests fail. - Drop the `paperclip/<id>/` prefix from transferred branches: the conversion and concurrency tests fail. - Remove the shared-clone lock: the concurrency test fails. - Drop remote-tracking refs from the plan, the deadline restore during backoff, archived recovery, or the config check before the worktree add: each targeted test fails. - Not run: the full server suite and a run on a live instance. ## Risks - The setting is off by default. Enable a dry run first and read the `execution_workspace.nested_clone_migration` logs. - A clone that a run writes to between verification and the swap rename can lose those writes. This window is the same as in #17369. Locks, the eligibility check and the git lock files make it small. - A crash in the short time between the rename aside and `git worktree move` can collide with a run that recreates `<name>`. In that case the conversion stops with `nested_migration_recovery_conflict` and keeps both copies. Expiration keeps such a workspace because of the `.clone-` names. - Stashes, annotated tag messages (the tagged commit is kept as a branch), custom hooks, custom local config and per-branch reflog-only history are not converted. Clones with them are skipped with a named reason. Only unpushed branches and tags get a name in the shared clone. A pushed local branch name is not kept, but its commits stay on the remote. - The conversion fetches the shared clone first. A failed fetch is ignored, and then the restore point can be larger. - Pushing from a converted checkout needs an explicit destination, as for all #17382 nested worktrees. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file editing, 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-23 19:52:07 -07:00
Devin FoleyandPaperclip	8549ecaf9a	Re-home isolated repository workspaces onto the shared project clone (#17369) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Each isolated task workspace is a Git worktree on the server disk, and the terminal workspace reaper and git cache expiration keep that disk usage bounded > - For some days, workspace preparation gave each isolated `git_worktree` workspace its own full clone under `isolated-repository-sources/`, with the worktree inside it. #16963 removed that creation path, but the existing clones stay, and restoring an expired workspace still recreates its private clone > - On one instance, 30 such clones use about 23 GB: 12.1 GB of `.git` data, 5.2 GB of unused default-branch checkouts and 5.75 GB of real worktrees. 28 of them back open workspaces, and the disk is nearly full > - This pull request moves each such open workspace onto the project's shared managed clone with its exact state, deletes the private clone, and makes restore use the shared clone > - The benefit is that disk use drops to one shared clone per project repository, with no lost work and no change for workspaces that cannot move safely ## Linked Issues or Issue Description Refs #16963. Bug report described in-PR (bug report template). **What happened?** On one instance, 30 per-issue clones under `isolated-repository-sources/<companyId>/<issueId>/checkout` use about 23 GB. 28 of them back open workspaces. No process moves these workspaces to the shared project clone that new workspaces use, and git cache expiration does not remove a clone while its workspace is open. Reopening an expired workspace whose recipe has `sourceKind: "isolated_remote"` clones the full repository again. Separately, a restore point with a non-default file mode cannot be restored: the reference read back from jsonb has reordered `modes` keys, so `loadGitRestorePoint` fails with `restore_point_manifest_mismatch`. **Expected behavior** An open workspace with a private clone moves to the shared project clone with the same branch, HEAD, index, worktree, untracked and ignored files, and file modes. The private clone is then deleted. Reopening an expired workspace uses the shared clone when one exists. A restore point with non-default file modes restores. **Steps to reproduce** 1. Create an isolated `git_worktree` workspace with `materializeIsolatedRemoteWorkspaceSource` and record `isolatedRemoteSource` metadata, as preparation did before #16963. 2. Keep its issue open. The clone stays, because no sweep moves or removes it. 3. Expire the workspace with a restore point that has a file with mode `0600`, then reopen it. The private clone is created again, and the restore fails with `restore_point_manifest_mismatch`. **Paperclip version or commit:** `master` at ec2e0d6407. **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). ## What Changed - New `server/src/services/isolated-repository-rehome.ts` with `rehomeIsolatedRepositoryWorkspace`. It holds the isolated source lock, the `execution_workspace_lifecycle:<id>` advisory lock and expiration-style Git lock files (`index.lock`, `HEAD.lock` and the branch ref lock in the clone). - Eligibility uses the safety checks of git cache expiration that matter while a workspace stays open: no live or unfinished relevant runs, no unsettled native finalizations, no unreleased environment leases, no running runtime services, no pending reopen, and no other workspace on the same path. It does not require a closed or idle issue tree. The check runs again inside the update transaction. - The target base is the project's existing shared managed clone for the same `repoUrl` (the paths `ensureManagedProjectWorkspace` uses, verified with the same origin and storage checks as restoration). - The move captures a restore point of the old worktree. The upstream boundary is commits that both repositories have, so the bundle is small. It imports the bundle into the shared clone, creates `refs/heads/<branch>` or fast-forwards it from an ancestor, and adds the worktree at `<base>/.paperclip/worktrees/<branch>`. Then it applies the restore point. It copies the `HEAD` reflog and `ORIG_HEAD`, copies the branch's upstream config when it creates the branch, and moves regenerable directories, untracked `.env`/`.env.*` files, `.claude/settings.local.json` and nested `.paperclip-repositories/*` checkouts by rename. Standalone nested clones move as is. Nested checkouts that are worktrees of their own shared clone (#17382) move too, followed by `git worktree repair` in that clone so the registration follows the new path, and their `paperclip/<hash>/` branch is renamed to the new path's prefix so ownership checks still pass. Entries inside a moved nested checkout (for example its `node_modules`) move with it. Rollback and interrupted-move recovery repair them again after moving them back, and verification checks that each one still resolves to the same shared clone. - Verification: the restore point snapshot (HEAD, index, worktree, ignored files, modes) of the new worktree must equal the old one before and after the move. The reflog and `ORIG_HEAD` must match, and every moved item must exist. Only then does one transaction set `cwd`/`providerRef`, drop `isolatedRemoteSource` and `gitCacheExpiration`, rewrite a saved active restoration recipe to `managed_project`, and record `isolatedRepositoryRehome: { at, from, to, cleanedAt }`. A failure before that removes the new worktree, moves items back, restores the branch, and leaves the old worktree untouched. - Safety of the checkout in the shared clone: the move skips with `unsupported_base_git_config` when the shared clone's local config sets filter drivers, includes, attribute files, worktree config or command settings, or when it has `info/attributes`. It checks before planning and again right before `git worktree add`. - Crash safety before the update: the move records `isolatedRepositoryRehomePending` (base, target, branch, head, previous branch tip, planned moves) before the first change to the shared clone. The next attempt undoes an interrupted move under the same locks: it moves items back, removes the new worktree only when it is proven to be this move's (a linked worktree of the shared clone on the issue branch that no workspace row references), and restores the branch. A live failure removes the target only after this attempt created it. When an item exists in both places, rollback stops with `rehome_rollback_conflict` and keeps the target and the record, so no copy is lost. - Cleanup after the update: remove the old worktree (rename to trash, then delete, then `worktree prune`). Delete the clone (rename to trash, then delete) only when no other workspace, project workspace or running service uses it, it has no other worktree, its checkout has no changes or non-regenerable files, its refs are only branches, tags and remote-tracking refs, and every local commit is on a remote-tracking ref or present in the shared clone. Cleanup reads at most 5,000 refs, reflog entries and unique commits (`clone_history_budget`). `cleanedAt` records completion. A crash after the update leaves a pending record that the next pass finishes, also after the workspace is archived: the reaper scan includes archived rows with unfinished re-home cleanup when the feature is on. - Reaper integration in `sweepTerminalWorkspaces`: behind `PAPERCLIP_ISOLATED_SOURCE_REHOME_ENABLED` (default `false`) and `PAPERCLIP_ISOLATED_SOURCE_REHOME_DRY_RUN`, only when git cache expiration is enabled. It logs `event: "execution_workspace.isolated_source_rehome"` with outcome, reason, candidate bytes and reclaimed bytes. A skipped workspace gets a retry deadline one hour later in the reaper's existing deadline set. No new timer. - Restore: `reopenClosedIsolatedExecutionWorkspaceForIssue` calls `rehomeExpiredIsolatedRestoration` first. For an expired workspace with an `isolated_remote` recipe, it uses the shared clone when one exists and the branch there is absent or at the saved commit. It keeps the old behavior for recipes with worktree-backed nested checkouts on branches, because those branch names are bound to the old path. It also requires that the shared clone has every base commit (prerequisite) of the saved restore point bundle. It rewrites the row and recipe to the shared clone and the standard worktree path, then the existing restore runs (`ensureGitRestorePointCommit`, `ensureSavedGitCommit`, apply). Without a shared clone, the old behavior stays. - Fix: restore point `modes` comparison in `git-restore-point-storage.ts` compares by path and mode, so jsonb key order does not matter. - Small exports: `allocatedBytes`, `expirationScope`, `managedSourcePaths`, `verifiedGitCacheSource`. - Docs: new "Isolated repository sources" section in `doc/recoverable-disk-cleanup.md`, new settings in `doc/DEVELOPING.md`. Deviations from the requested design: - The sweep does not create a missing shared clone. When none exists, it skips with `no_shared_base`, because a new network clone in a cleanup path can use more disk. Restore follows the same rule and keeps the old behavior. - History moves through the restore point bundle, not a separate fetch from the clone. The bundle contains HEAD and every reflog/`ORIG_HEAD` commit that the shared clone does not have. The move then checks that all of them are present. - The standard location is `<base>/.paperclip/worktrees/<branch>`. A worktree outside the clone's standard location is skipped (`nonstandard_worktree_location`). - Lock files use a token derived from the workspace id, so a crashed attempt's locks are recovered without a database marker. - A clone that another open workspace still uses is kept and marked `cloneRetained: "base_has_consumers"`. That workspace's own move removes it later. Skip reasons: `live_or_unresolved_consumer`, `unsupported_base_git_config`, `rehome_rollback_conflict`, `nested_branch_conflict`, `invalid_rehome_record`, `interrupted_rehome_pending` (dry run only), `lifecycle_busy`, `source_busy`, `workspace_changed`, `no_shared_base`, `shared_base_repo_mismatch`, `missing_worktree`, `nonstandard_worktree_location`, `source_identity_changed`, `branch_identity_changed`, `unproven_worktree_admin`, `unsupported_worktree_git_state`, `unique_worktree_refs`, `unknown_worktree_git_logs`, `unsupported_local_git_state`, `unique_git_refs`, `unsupported_index_flags`, `unsupported_branch_name`, `invalid_restoration_recipe`, `unsupported_restoration_recipe`, `target_worktree_exists`, `base_branch_checked_out`, `base_branch_diverged`, `untransferable_ignored_files`, `untransferable_managed_checkouts`, `worktree_git_busy`, `head_changed`, `history_not_transferred`, `transfer_conflict`, `snapshot_mismatch`, `history_mismatch`, `transfer_incomplete`, and restore point reasons such as `untracked_nested_repository`, `submodules_unsupported`, `filtered_paths`, `restore_point_too_large`. Clone kept reasons: `base_has_consumers`, `base_has_live_services`, `base_has_worktrees`, `clone_checkout_has_files`, `unsupported_clone_refs`, `unique_clone_history`, `clone_history_budget`. ## Verification - `pnpm exec vitest run src/__tests__/isolated-repository-rehome.test.ts` in `server/`: 18 passed. It uses real Git repositories and embedded Postgres. It covers: - a move with an unpushed commit, staged and unstaged edits, a deletion, an untracked file with mode `0600`, an ignored file, `node_modules`, `.env`, `.claude/settings.local.json` and a nested `.paperclip-repositories` checkout. Snapshots, branch, HEAD, `git status` and reflog match, the row points to the new path without `isolatedRemoteSource`, and the old worktree and clone are gone; - skips with nothing changed on disk or in the database: live run, branch in the shared clone at an unrelated commit, no shared clone, an untracked nested repository, and a concurrent change between capture and verify (hook). The new worktree is removed and the old one keeps its moved items; - the clone is kept while another workspace references it; - a worktree-backed nested checkout moves with the task worktree, stays registered in its shared clone at the new path (not prunable), and keeps its changes, with its branch renamed to the new path's prefix. On rollback it returns to the old path with its registration repaired and its branch name restored. A standalone nested checkout moves together with its own ignored `node_modules`; - a file recreated in the old worktree before verification stops the rollback and keeps both copies, then the move completes once the conflict is gone; - a hostile `filter.*.smudge` in the shared clone's config makes the move skip without running it; - a clone with more than 5,000 refs is kept, and is deleted once the refs are gone; - a move interrupted before the database update is reported (not undone) by a dry run, then undone and completed on the next attempt; - a target that another party creates right before `git worktree add` is never deleted; - a crash after the database update; after the row is archived, a later reaper sweep removes the old worktree and clone; - restore keeps the private-clone fallback when the shared clone lacks the restore point's base commits; - disabled by default (both flags needed), dry run changes nothing, and the retry deadline is registered; - reopening an expired `isolated_remote` workspace rebuilds it in the shared clone with the restore point applied and no clone created. - After the round 4 fixes, the related suites (`git-workspace-expiration`, `git-restore-point-expiration`, `execution-workspace-reopen`, `execution-workspaces-service`, `heartbeat-git-restore-point-resume`, `heartbeat-project-repositories`, `isolated-remote-workspace-source`) with the new suite: 326 passed. - After rebasing on #17382, the related suites (adding `heartbeat-project-repositories`) with the new suite: 374 passed. - After the first review fixes, the related suites (`git-workspace-expiration`, `git-restore-point`, `git-restore-point-expiration`, `execution-workspace-reopen`, `execution-workspaces-service`, `execution-workspace-compaction`, `heartbeat-git-restore-point-resume`, `isolated-remote-workspace-source`) with the new suite: 301 passed. - Related suites in `server/` (first commit): `pnpm exec vitest run` on `git-workspace-expiration`, `git-workspace-expiration-eligibility`, `git-restore-point`, `git-restore-point-expiration`, `git-restore-point-expiration-config`, `git-restore-point-ledger`, `git-restore-point-ledger-config`, `execution-workspace-reopen`, `execution-workspaces-service`, `execution-workspace-compaction`, `heartbeat-git-restore-point-resume`, `isolated-remote-workspace-source`, `isolated-remote-workspace-source-lock`, `git-workspace-base-storage`, `git-reproducible-managed-checkouts`, `git-expiration-auth-fallback` and `workspace-runtime`: 550 passed, 2 failed. The 2 failures are in `workspace-runtime.test.ts` (base ref resolution) and also fail on unmodified `master` on the same machine. - `pnpm run typecheck` in `server/` passes (after `pnpm -r --filter "./packages/**" build`). - Mutation checks. Each reverted guard fails one test in the new suite: - eligibility always true: "keeps a workspace with a live run" fails; - snapshot verification removed: "removes the new worktree and keeps the old one when the workspace changes during the move" fails; - clone reference check removed: "keeps the clone while another workspace still references it" fails; - restore re-home removed from reopen: "restores an expired isolated workspace into the shared project clone" fails; - old `JSON.stringify` modes comparison: the same restore test fails; - interrupted-move recovery removed: the interrupted-move test fails; - target existence check before `git worktree add` replaced by assumed ownership: the foreign-target test fails; - bundle prerequisite check removed: the stale shared clone restore test fails; - archived-row cleanup scan removed: the crash test fails; - dry run check before interrupted-move recovery removed: the interrupted-move test fails; - `git worktree repair` after the forward move removed: both nested worktree tests fail. The repair after moving back removed: the rollback test fails; - nested branch rename forward or back removed: the matching nested test fails; - rollback conflict check removed: the reappearing-file test fails; - covered-entry filter removed: the full re-home test fails; - shared clone config check removed: the hostile filter test fails; - ref budget removed: the many-ref test fails. - Not run: the full server suite, and the move on a live instance. ## Risks - Workspace paths change for re-homed workspaces. Agents that resume an old session can remember the old path. The run's working directory comes from the updated row, but text in a resumed conversation can still name the old path. - The feature is off by default. It runs only with `PAPERCLIP_ISOLATED_SOURCE_REHOME_ENABLED=true` and git cache expiration enabled. Dry run is available. The restore change is not behind the flag: reopening an expired private-clone workspace now uses the shared clone when one exists. - A run can start between the last eligibility check and the database update. The update transaction checks eligibility again, and the old worktree is deleted only after another check. This is the same window that git cache expiration accepts. - Imported restore point objects stay in the shared clone as unreachable objects after a failed attempt until Git garbage collection removes them. Base expiration keeps a base with unreachable objects, so this only delays base expiration. - A workspace that cannot move (for example `no_shared_base`) is retried each hour while the feature is on. Each retry runs a few Git commands for that workspace. - No migration. No schema change. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file editing, Git, test runs). ## 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-23 18:25:26 -07:00
Nicky Leach	100477e887	Avoid live workspace inspection in task context reads (#17396)	2026-10-23 17:05:06 -07:00
Devin FoleyandPaperclip	ec2e0d6407	Share one clone across nested project repository checkouts (#17382) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A project can attach extra repositories, and every task worktree gets a managed checkout of each one under `.paperclip-repositories/<name>` > - Each of these nested checkouts is a full clone. The clone uses `--dissociate`, so no objects are shared between tasks > - On one instance, 44 task worktrees held nested checkouts of the same repository: 24 GB of 27 GB of worktrees. Each new task added about 0.5 GB, and the disk filled twice in one day > - Main task worktrees already avoid this, because they are git worktrees of one managed project clone > - This pull request makes nested checkouts git worktrees of one shared clone per project and repository, and adapts expiration, restore points, restore and cleanup to them without weaker safety checks > - The benefit is that repository objects are stored once, and a new task adds only its working files ## Linked Issues or Issue Description No public issue exists. This is the in-PR bug report. **What happened?** Every task in a project with extra repositories got a full, independent clone of each extra repository under `.paperclip-repositories/`. On one instance this used 24 GB of 27 GB of task worktrees (16 GB of it `.git` data) and filled the disk twice in one day. **Expected behavior** Nested checkouts of the same repository share one object store, like main task worktrees share the managed project clone. Disk use per new task is only its working files. **Steps to reproduce** 1. Create a project with a primary repository and a second repository that has a repository URL and no local folder. 2. Run several tasks in isolated git worktrees in that project. 3. Look at `<task worktree>/.paperclip-repositories/<name>/.git`: each one is a full directory with its own copy of every object. **Paperclip version or commit:** `master` at ff835a3fc6. **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). Related: #15662 (SSH restores skip nested worktrees) touches a different path; this PR does not change adapter sync. ## What Changed - New `server/src/services/nested-repository-worktrees.ts`. It finds the shared clone (the managed project checkout for the repository URL, from `ensureManagedProjectWorkspace`), adds nested worktrees, restores them, removes their registrations, and serializes all of these operations and fetches per shared clone with an in-process lock. - `prepareProjectRepositoryWorkspaces` takes a `sharedBase` (company and project). For a repository without a configured local folder, it fetches the shared clone and adds a worktree at the same `.paperclip-repositories/<name>-<key>` path. Each worktree gets its own branch `paperclip/<id>/<branch>` that tracks `origin/<branch>` (`<id>` derives from the worktree path), or a detached HEAD for a tag or commit ref. An existing worktree must belong to the project's shared clone. Configured local-folder copies and existing standalone clones are unchanged. Moving a worktree to `detached-repositories` repairs its registration. Heartbeat preparation and fresh-start reopening pass `sharedBase`. - `assertReproducibleManagedCheckout` and `provenManagedCheckoutHistory` accept worktree-backed checkouts. They verify the worktree link, its admin directory, the shared clone identity and origin, and that HEAD is detached or on a branch under the worktree's own prefix. History checks scope to HEAD, the per-worktree HEAD reflog, ORIG_HEAD and the owned branches with their reflogs. Other tasks' branches are not inspected. Stashes, unsupported refs and custom config in the shared clone still block. The upstream proof reads objects from the common git directory. - Restoration contents record `worktree: { base, admin }` for a worktree-backed checkout. Validation checks its shape and the owned branch name, and every use checks the base against the project's expected clone paths. - Expiration locks for a worktree-backed checkout sit in the shared clone (`.git/worktrees/<admin>/index.lock`, `HEAD.lock`, and the owned branch ref lock). `gitCacheExpirationLockLocations` is now async. - `finishGitCacheTrash` removes the expired worktree's registration and deletes its owned branch only at the recorded commit. - `restoreGitWorkspaceContents` recreates a worktree-backed checkout from the shared clone, and clones the shared clone again if it is gone. It imports the restore point into the shared clone, adds the worktree on the saved branch and commit, writes reflog-only commits back into the new HEAD reflog, and applies the restore point. - `cleanupExecutionWorkspaceArtifacts` (terminal reaper archival, close and delete) collects the task's nested worktrees first. After the task directory is gone, it removes their registrations and deletes owned branches only when every commit is on a remote-tracking ref. An unpushed branch stays in the shared clone. - Review follow-ups. Owned branches always track origin, including names with dots, and the config check accepts their tracking keys. A ref held by a retained detached checkout gets `paperclip/<id>/r<n>/<branch>`. Restore derives the upstream from the saved source ref. Each new worktree fetches with `--prune`, refreshes `origin/HEAD` when no ref is configured, and strips `refs/heads/` from branch refs. Git commands on the shared clone run with hooks disabled. The worktree `gitdir` pointer is read through a bounded, non-following, non-blocking handle, and more than 64 owned branches stop the proof before reflog reads. - Docs: new "Nested project repository worktrees" section in `doc/recoverable-disk-cleanup.md`, and updates in `doc/DEVELOPING.md`. ## Verification - `pnpm -r --filter "./packages/**" build`, then `pnpm run typecheck` in `server/`: passes. - `pnpm exec vitest run` in `server/` for `git-workspace-expiration`, `git-reproducible-managed-checkouts`, `git-workspace-contents`, `git-restore-point*`, `heartbeat-project-repositories`, `execution-workspaces-service`, `execution-workspaces-routes`, `execution-workspace-compaction`, `workspace-compaction`, `heartbeat-git-restore-point-resume`, `managed-repository-checkout`, `task-workspace-repositories*`, `native-workspace-sync*`, `heartbeat-managed-clone-credentials`, `services/heartbeat/workspace-preparation`, `project-repositories-persistence`, `git-workspace-base-storage`, `agent-directory-probe`, `workspace-runtime`, `workspace-preparation-history` and `native-completion-feedback`: 866 passed, 2 failed. The 2 failures are in `workspace-runtime.test.ts` (`rejects explicit main on a master-only remote...` and `does not diagnose a missing remote branch...`). They fail the same way on unmodified `master` on this machine. - New tests (embedded Postgres, real git repositories) in `git-workspace-expiration.test.ts`, section "nested checkouts as worktrees of a shared base": - Two tasks get worktrees of one shared clone. `--git-common-dir` points to it, each task has a distinct `paperclip/<id>/main` branch, upstream is `origin/main` and the remote is the repository URL. - Concurrent preparation of three tasks succeeds, and preparation waits while the shared clone lock is held. - A legacy standalone clone is still adopted, and no shared clone is created for it. - Expiring a clean nested worktree removes only its registration and branch. The sibling worktree and branch stay. Reopening recreates the worktree from the shared clone on the same branch and commit, with its local settings. - Reopening clones a deleted shared clone again. - Unpushed commits and uncommitted files block plain expiration, are saved in a restore point and are restored exactly. - Reflog-only history is saved and written back into the restored HEAD reflog, and it survives `gc --prune=now` of the shared clone. - Stashes, a checked-out branch outside the worktree's prefix, and unpushed owned branches or owned reflog entries outside HEAD history block expiration. - Another task's unpushed branch does not block, and it stays after expiration. - A worktree of a foreign clone at the nested path is rejected by preparation and by the prover. - Expiration locks in the shared clone are recovered after a process exit. - Deleting a task removes only its nested registrations, keeps its unpushed branch and deletes the sibling's pushed branch when the sibling is deleted. - Follow-up tests: dotted branch tracking, a ref switched away and back with a retained checkout, a changed remote default branch, a renumbered branch restored next to a same-named remote branch, a fully qualified branch ref after the remote advances, a branch deleted upstream, planted `post-checkout` and `reference-transaction` hooks, more than 64 owned branches, and a FIFO, oversized or symlinked `gitdir` pointer. Each fix was mutation-checked. - `heartbeat-project-repositories.test.ts`: a repository-URL-only sibling is now a worktree of the shared clone on an owned branch, and its detached copy is still a valid checkout after its repository leaves the project. In `workspace-preparation.test.ts`, the publication guard now runs before any worktree exists. - Mutation checks. I reverted one guard at a time and confirmed that a test fails: the owned-HEAD check, the owned-branch check in restore point mode, the owned-reflog check, the shared-clone identity check, the pushed-only branch deletion on cleanup, the cleanup release hook, the registration removal on expiration, the reflog-only history write-back on restore, and the shared clone lock. The owned-branch-tip check alone is also covered by the owned-reflog check, so removing only one of the two keeps the tests green. - Not run: the full server test suite, the UI and e2e suites, and a live instance migration. ## Risks - Behavior change for agents: a nested checkout of a URL-only repository is now on `paperclip/<id>/<branch>`, not `<branch>`. `git pull` and `git status` work as before. A plain `git push` now fails because the branch names differ. Agents must push with an explicit destination, for example `git push origin HEAD:<branch>`. Branches in the shared clone are visible to all tasks of the project, like main task worktree branches. - Agent-created branches outside the worktree's prefix, stashes, and local config live in the shared clone. Stashes and custom config block expiration of every worktree of that clone (fail-closed). Other branches stay in the shared clone after a task is deleted. - The shared clone is the managed project checkout for that repository URL. Fetches into it update its remote-tracking refs. A concurrent restore point capture of a sibling can then roll back and retry on the next sweep. - The base lock is per process. Across processes, git's own ref and index locks apply. - No migration in this PR. Existing standalone nested clones keep their disk use until their tasks are removed or expired. A safe migration helper is a follow-up. Task repositories (`task-repo-*`) and configured local-folder copies stay standalone clones. - Restoration recipes now can carry `contents.checkouts[].worktree`. An older server rejects such a recipe as invalid (fail-closed) and does not restore without it. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file editing, 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-23 16:05:13 -07:00
Devin FoleyandPaperclip	d69631b01b	feat: reopen a fresh workspace with a warning when its restore point expired (#17269) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - #17248 and #17257 let git cache expiration remove closed issues' worktrees after saving encrypted restore points > - Restore points are kept for 90 days after an issue tree closes, then deleted > - Reopening a workspace whose restore point had expired failed, so the issue could not get a workspace back > - This pull request starts a fresh workspace on the same branch instead, and warns that the saved work is gone > - The benefit is that old issues can always be resumed, with a clear record of what was lost ## Linked Issues or Issue Description Refs #17248, #17257. Bug report described in-PR (bug report template). **What happened?** After `PAPERCLIP_GIT_RESTORE_POINT_RETENTION_DAYS` passes, the retention worker marks the restore point expired and deletes it. Reopening that workspace then fails with the git cache restoration error, every time. **Expected behavior** Reopening succeeds with a fresh workspace on the issue's branch, and the issue says that unsaved work from before the cleanup is no longer available. **Steps to reproduce** 1. Enable restore points and let a closed issue's worktree expire with unsaved work. 2. Let its restore point expire. 3. Reopen the issue: the workspace rebuild fails. **Paperclip version or commit:** `master` at 650581b2f0. **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). ## What Changed - **Detection:** `gitRestorePointExpired(recipe)` is true when the main restore point or any nested checkout's restore point has `expiredAt`. - **Reopen** (`execution-workspaces.ts`): - `restoreGitCacheBase(..., { freshStart: true })` prepares the base without the saved commit or the bundle. - The saved recipe is left out of the metadata handed to the runtime, and dropped from the stored metadata only when the reopen succeeds, so a failed attempt can be retried and still warns. The runtime recreates the worktree on its branch: the branch tip if the repository still has it, otherwise a new branch from the base ref. When the expired recipe had nested checkouts, the project's repositories are prepared with `prepareProjectRepositoryWorkspaces` (without the expired saved state) right after the worktree is recreated and before the provision command runs, with the same copy identity and access rechecks as other reopen copies. - The result carries `warning`, the `execution_workspace.reopened` activity records `restorePointExpired` and the warning, and a system comment on the issue posts the warning in the same transaction. - **Retention:** `markGitRestorePointExpired` now also marks nested checkouts' restore points, matched by object key. - **Docs:** `doc/recoverable-disk-cleanup.md` describes the fresh start. No code comments were added. ## Verification - `pnpm exec vitest run src/__tests__/git-restore-point-expiration.test.ts` (in `server/`): 13 passed. New case: an expired restore point reopens fresh with the warning and the system comment, on the original branch, even after the base lost the branch and its unpushed commit; the recipe is gone. A first attempt that fails keeps the expired recipe, and the retry still warns and comments exactly once. - New nested case in `git-workspace-expiration.test.ts`: an expired nested checkout restore point is marked on the checkout entry and reopens fresh with the warning, with the nested repository cloned again at its pushed commit and without its expired uncommitted files. - **Mutation checks:** each of these fails a case: - removing the fresh base path (reopen fails); - removing the system comment; - handing the runtime the old recipe; - dropping the stored recipe before the rebuild succeeds; - marking only the main restore point expired; - skipping nested repository preparation on a fresh start. - `pnpm exec vitest run git-workspace-expiration git-workspace-contents git-restore-point execution-workspaces` plus the environment selection and heartbeat resume suites (in `server/`): 257 passed. - `pnpm run typecheck` (in `server/`): pass. - Not run: server build and boot smoke. ## Risks - **Only with restore points enabled:** recipes get `expiredAt` only from the restore point retention worker, so nothing changes otherwise. - **Lost work is intended:** the fresh workspace has no uncommitted files and, when the repository no longer has the branch, no unpushed commits. The warning says so. - **Recipe dropped:** after a fresh start the workspace no longer carries the expired recipe, so later expirations start from a clean slate. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file edits, 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-22 22:20:52 -07:00
Devin FoleyandPaperclip	5ef783d971	feat: expire idle open issues' worktrees with restore points (#17271) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - #17248 and #17257 let git cache expiration remove a closed issue tree's worktree after saving an encrypted restore point > - Issues that stay open but go untouched for weeks still keep their worktrees forever, so disks keep filling > - This pull request expires those idle worktrees the same way, and has the next run restore its workspace automatically > - The benefit is bounded disk use for stalled open work, with nothing lost when work resumes ## Linked Issues or Issue Description Refs #17248, #17257. Bug report described in-PR (bug report template). **What happened?** With restore points enabled, expiration only considers worktrees whose whole issue tree has been `done` or `cancelled` for a while. A worktree whose issue stays `todo`, `in_progress`, `blocked` or `in_review` with no activity for weeks is never removed. **Expected behavior** An open issue's worktree that has been idle long enough is saved to a restore point and removed, and the next run on that issue gets it back exactly. **Steps to reproduce** 1. Enable git cache expiration and restore points. 2. Leave an issue open with an isolated worktree and no activity for weeks. 3. The worktree is never removed. **Paperclip version or commit:** `master` at 650581b2f0. **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). ## What Changed **Expiration** (`git-workspace-expiration.ts`): - `isGitWorkspaceExpirationEligible(..., idleCutoff)`: in idle mode the closed-tree conditions are replaced by idle ones. No issue in the tree, and no other issue bound to the workspace, was updated after the cutoff, and no relevant run was created, started or finished after it. Runs of bound issues now count as relevant runs in both modes. Every other check stays, including no live run, recovery action, unsettled finalization, environment lease or running service. - `gitWorkspaceLastActivityAt` returns the latest of those timestamps, sharing the same tree and run scope. - `expireReconstructableGitWorkspace` takes `idleCutoff` and passes it to all three eligibility checks. **Reaper** (`execution-workspaces.ts`): - For an open tree's isolated git worktree, when restore points and git cache expiration are on and `idleMs` is set, the reaper computes the idle deadline (last activity + `PAPERCLIP_GIT_RESTORE_POINT_IDLE_DAYS`). - Before the deadline, it records the deadline, so the next sweep wakes then. Open trees cause no recurring checks before that. - At the deadline, it runs expiration with a restore point. A kept workspace is retried after an hour, like terminal ones. - An expiration interrupted after archiving (`completed: false`) is resumed by later sweeps even while the tree is open, with a retry scheduled until cleanup finishes. **Runs** (`heartbeat/environment-selection.ts`): - When a run's issue is bound to a workspace that git cache expiration removed (archived, `workspaceRemoved`), the run reopens it as the agent through `reopenClosedIsolatedExecutionWorkspaceForIssue`, with the restore point applied. - It then clears the reopen fence, since the live run now holds the workspace, and continues with the reopened row. - A failed restore fails the run instead of silently starting a new workspace. - Comments and agent updates on the issue already reopened closed workspaces through the issue routes. **Config:** `PAPERCLIP_GIT_RESTORE_POINT_IDLE_DAYS` (default `7`, `0` turns idle expiry off). Docs in `doc/recoverable-disk-cleanup.md` and `doc/DEVELOPING.md`. No code comments were added. ## Verification - `pnpm exec vitest run src/__tests__/git-restore-point-expiration.test.ts -t "idle open issues"` (in `server/`): 7 passed, with real repositories and embedded Postgres. - **Round trip:** an open issue's worktree, idle for 8 days with unsaved work, is skipped without idle mode, expires with a restore point in idle mode, and reopens exactly. - **Kept:** issue activity 3 days ago, or a run finished 2 days ago, keeps the worktree. - **Interrupted:** an idle expiration interrupted after archiving is finished by the reaper while the issue stays open, and reopens exactly. - **Shared workspace:** a recent update on another issue bound to the workspace keeps it, and moves the last activity time. - **Reaper:** before the deadline the sweep skips the worktree and schedules exactly that deadline; at the deadline it expires it with an active restore point. With idle expiry off, nothing is scheduled or expired. - `pnpm exec vitest run src/services/heartbeat/environment-selection.test.ts` (in `server/`): 14 passed. New cases: a run reopens its expired workspace as the agent, clears the fence with the reopen's generation and binds the reopened row; a failed restore fails the run; a workspace archived for other reasons is left alone. - `pnpm exec vitest run src/__tests__/heartbeat-git-restore-point-resume.test.ts` (in `server/`): 1 passed. Assembled heartbeat journey with no mocked restore: a real worktree with an unpushed commit and uncommitted notes is idle-expired, a queued run executes, the agent runs in the original worktree path with the original workspace id, the commit and notes are back, the workspace is no longer archived with no reopen fence left, and the issue stays bound. Disabling the run-side reopen fails it. - `git-restore-point-expiration-config.test.ts`: the default is 7 and `0` turns it off. - **Mutation checks:** each of these fails a case: - dropping the idle deadline; - dropping the idle cutoff; - dropping the run activity condition; - not failing the run on a failed restore; - not re-reading the reopened workspace; - not resuming a pending expiration on an open tree; - ignoring bound issues' activity. - `pnpm exec vitest run git-restore-point git-workspace-expiration git-workspace-contents execution-workspaces src/services/heartbeat/environment-selection src/services/heartbeat/workspace-preparation` plus `heartbeat-git-restore-point-resume` (in `server/`): 312 passed. - `pnpm run typecheck` (in `server/`): pass. - Not run: server build and boot smoke. ## Risks - **Off unless enabled:** requires `PAPERCLIP_GIT_CACHE_EXPIRATION_ENABLED=true` and `PAPERCLIP_GIT_RESTORE_POINTS_ENABLED=true`. `PAPERCLIP_GIT_RESTORE_POINT_IDLE_DAYS=0` keeps restore points for closed trees only. - **First run after idle expiry is slower:** it waits for the restore, about as long as a reopen. - **Failed restore blocks runs:** a restore that fails closed (for example a missing restore point) fails each run on that issue until an operator fixes or rebinds the workspace. This is deliberate, so work is never silently continued in an empty workspace. - **Kept idle workspaces are rechecked hourly**, matching the existing behavior for closed trees that cannot be expired. - **Retention:** restore points of open trees are not deleted while the tree stays open, as before. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file edits, 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-22 20:02:21 -07:00
Nicky LeachandPaperclip	989ee668e0	Support provider-owned fresh retry workspaces (#17252) ... ## Thinking Path > - Paperclip coordinates AI agents and retains their work across failures. > - A retry can require a new workspace while preserving the failed attempt. > - Core rejects this recovery strategy for provider-owned storage. > - Providers should implement the required outcome using their own storage design. > - This pull request adds a semantic fresh-preparation contract and delegates recovery preparation. > - The benefit is that a supported provider can run a fresh retry without losing prior work. ## Linked Issues or Issue Description **What happened?** A retry that selects `fresh_isolated_workspace` fails with `fresh_workspace_storage_unsupported` for provider-owned storage. **Expected behavior** Core asks a capable provider to prepare new storage and attach verified recovery files. The failed workspace remains intact. **Steps to reproduce** Run a task in a task-capable plugin environment. Let the task fail without a verified workspace preservation receipt. Retry the task so Core selects a fresh attempt. **Paperclip version or commit** 6204239cf (rebased on current master). **Deployment mode** Self-hosted server with a plugin task environment and managed workspace provider. Search found no duplicate implementation. This branch includes the default-provider changes from #17247 and preserves their source selection behavior. ## What Changed - Define an opt-in fresh-preparation contract with a stable attempt identity and verified recovery file descriptors. - Describe retained-storage and recovery-attachment guarantees without requiring a Git storage layout. - Reserve replacement task bindings with revision checks and keep the failed workspace intact. Projectless and project-backed task environments both replay their stable attempt reservation. - Reconcile an interrupted preparation against its reserved workspace and stable operation identity. - Stage verified recovery archives at stable transfer paths. Delegate attachment materialization to the provider. - Preserve projectless attempt directory identities through later turns and pin the intent into each execution lease. - Protect fresh intent and projectless ownership from caller metadata replacement or injection. ## Verification - SDK workspace-provider tests: 4 passed. - Targeted reservation and task-dispatch tests: 31 passed. - Recovery transfer staging and lifecycle focus: 7 passed. The separate cache-cleanup failure reconciliation case also passed. - After rebasing on current master, 7 focused preparation and ownership cases passed. These cover inherited provider defaults, fresh preparation, stable projectless identity, and authorization denial. - The focused metadata authority regression passed, including forged intent, replacement, and null metadata patches. - Three assembled interrupted task-reservation cases passed: projectless, project with a saved source, and project with a newly selected default source. - Targeted tests use worktree SDK sources. No full local build or typecheck ran. - Local checks remain targeted as requested. Latest-head GitHub CI passed: 54 successful checks, including typecheck, build, server suites, Runner validation, and E2E shards; 2 unrelated Storybook checks were skipped. - Greptile reviewed commit 73595b0c61 at 5/5 with zero unresolved threads. - Live VM E2E has not run. ## Risks - Existing providers retain their existing behavior. Fresh attempts require explicit version support. - The companion provider implementation must materialize recovery snapshots safely and preserve the old workspace. - Fresh retries require the companion provider implementation. Providers without the version marker fail closed. ## Model Used - OpenAI GPT-6.1 (`gpt-6.1-sol`), reasoning and coding tools. The runtime does not expose the context-window limit. ## 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>	2026-10-22 17:46:27 -07:00
Nicky LeachandPaperclip	6204239cfc	Support installed default project workspace providers (#17247) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Storage plugins already own project storage and task checkout preparation. > - Core only selected these plugins through an explicit project policy. > - Installation could therefore leave new and existing projects on incompatible Core preparation. > - This pull request adds one generic manifest declaration and one shared effective-policy resolver. > - Project configuration shows inheritance while durable workspace bindings retain their owners. ## Linked Issues or Issue Description **Subsystem affected** Plugin contracts, project configuration, and execution workspace preparation. **Problem or motivation** An installed storage provider cannot become the company default. Projects without an explicit provider keep Core preparation, even when their execution environment cannot use a Core Git checkout. **Proposed solution** A provider declares supported `workspaceProvider.defaultForProjects` mode and strategy. Company-enabled installations supply inherited defaults. Explicit plugin selections and explicit Core/local (`storageProviderPluginId: null`) win. Conflicting defaults require an operator choice. The declaration and implementation contain no provider-specific identifiers. **Alternatives considered** Rewriting every project would lose the distinction between inheritance and overrides. Selecting by worker health would silently change storage on an outage. **Roadmap alignment** Extends the existing workspace and sandbox provider contracts. The roadmap has no duplicate default-provider implementation. Related public work includes #17243, which covers prepared execution directories rather than provider selection. ## What Changed - Add a validated generic default-provider declaration and document it in the SDK. - Resolve provider selection and Git defaults consistently in project responses, source selection, heartbeat source resolution, reservation, and preparation. - Keep stored policy separate from effective configuration. Add the normal project configuration selector for inheritance, explicit plugins, and Core/local. - Preserve existing local and plugin workspace ownership. Pin selection through preparation and keep provider failures visible. - Add database, API, manifest, heartbeat, and UI regressions. Update the verification maps. ## Verification - Targeted Vitest runs cover manifest validation, project defaults and API access, explicit overrides, existing ownership, new/imported task inheritance, heartbeat routing, source-free tasks, selection pinning during setup, and UI configuration. - Combined policy, provider integration, and heartbeat run: 58 tests pass; 60 unrelated cases excluded. After the final shared-provider fallback fix, all 47 policy tests pass, including shared and operator-mode regressions. - Server and UI TypeScript checks, SDK build, verification-map validation, credential-pattern scan, added-comment scan, and `git diff --check` pass. - A downstream integration uses this Core resolver and preparation service with a real storage hook and mocked remote infrastructure. A new Git project reaches the hook without a stored provider ID. - Standard Greptile and Apex both scored 5/5 on 5d42998466. All review threads are resolved. - Final GitHub CI is fully green on 5d42998466. Browser shard 3 initially hit a PostgreSQL deadlock during cleanup cancellation, which left an experiment flag enabled for a later test. A failed-job retry passed all 26 browser tests. The workflow completed successfully on attempt 2. Full final verification was delegated to CI at the user's request. - No live provider or hosted tenant run was performed. ## Risks - Installing one default-claiming provider changes effective selection for unconfigured projects. Existing explicit settings and workspace ownership remain intact; incompatible explicit settings fail clearly. - Each configuration/admission resolution reads installed plugin metadata and the selected company's enablement. Project list reads share one catalog query. Selection does not call workers or external providers. - Deploy the Core contract before any downstream manifest uses the declaration. No migration or backfill is required. A downstream immutable image pin must include this change before packaging its declaration. - No merge or deployment is authorized by this PR. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository tools, and code execution. The exact served model ID and context-window size are not exposed in this session. ## 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 described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket id - [x] I have run targeted tests locally and they pass; full gates are delegated to CI at the user's request - [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 on 5d42998466ad42400564ba34f48124f40c53fbc5; the branch has no merge conflicts - [x] Standard Greptile is 5/5 on 5d4299846 after all fixes, with no unresolved threads - [x] Apex is 5/5 on 5d42998466, after standard Greptile 5/5 on that same head - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-22 17:12:29 -07:00
Devin FoleyandPaperclip	6d44b80a5e	feat: expire closed git worktrees with unsaved work behind restore points (#17248) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Git cache expiration removes a closed issue's worktree only when the remote can reproduce it exactly > - Most closed worktrees hold unpushed commits or uncommitted files, so they are kept forever and disks fill up > - #17238 added restore points (an encrypted save of exactly what the remote cannot reproduce) and #17241 added their lifecycle > - This pull request lets expiration remove those worktrees after saving a restore point, and restores them exactly when the work resumes > - The benefit is bounded disk use for closed work without losing anything a user could need, behind a setting that is off by default ## Linked Issues or Issue Description Refs #17238, #17241. Bug report described in-PR (bug report template). **What happened?** With `PAPERCLIP_GIT_CACHE_EXPIRATION_ENABLED=true` and dry run off, one instance's last 111 expiration checks removed nothing: | Skip reason | Checks | |---|---| | `dirty_or_untracked_files` | 39 | | `unpushed_managed_checkout` | 32 | | `live_or_unresolved_consumer` | 21 | | `unique_ignored_files` | 9 | | commit not on the remote | 10 | Without expiration, the terminal workspace reaper archives only merged, clean worktrees. Closed issues' worktrees therefore accumulate without bound. **Expected behavior** A closed worktree whose only obstacle is unsaved work can be removed after that work is saved, and restored exactly if the issue is reopened or work resumes. **Steps to reproduce** 1. Close an issue whose worktree has an unpushed commit or an uncommitted file. 2. Enable git cache expiration with dry run off. 3. The worktree is never removed. **Paperclip version or commit:** `master` at 12bb7e1976. **Deployment mode:** any. **Agent adapter(s) involved:** not adapter-specific (core). ## What Changed **Expiration** (`server/src/services/git-workspace-expiration.ts`): - **When it applies:** with `PAPERCLIP_GIT_RESTORE_POINTS_ENABLED=true` (default `false`), a worktree that fails the reproducibility check for a relaxable reason is reconsidered once its issue tree has been closed for `PAPERCLIP_GIT_RESTORE_POINT_TERMINAL_DELAY_DAYS` (default `3`). The relaxable reasons are uncommitted or untracked files, a commit not on the remote, reflog or `ORIG_HEAD` history, and ignored `.env` files. A leftover `COMMIT_EDITMSG` still blocks expiration unless it matches a commit in the worktree's reflog, because restore points do not save draft messages. - **What still blocks:** a relaxed inspection (`inspectGitCacheRecipeForRestorePoint`) keeps every other check. Nested managed checkouts, submodules, special git state, local config and other unique ignored files still prevent expiration. - **Capture:** inside the existing source and lifecycle locks, a restore point is captured with the #17238 library against a remote-verified boundary (the `HEAD` itself, or its merge base with `origin/HEAD`), then encrypted, uploaded, read back and hash-checked (`git-restore-point-storage.ts`). - **Commit before touching disk:** it is activated in the #17241 table in the same transaction that archives the workspace with a `paperclip.git-cache-restoration.v2` recipe referencing it, still before anything on disk is touched. - **Final check:** under the file locks, the worktree must still match the captured snapshot (`HEAD`, index, working tree, modes). Otherwise the existing rollback runs. The rollback now also drops the restore point reference and returns the recipe to v1, so a later restore can never apply a stale restore point over the live worktree; the stored restore point is marked superseded. - **Failure paths:** the `pending` row is inserted in a transaction that first registers a `git-restore-points` notification. If the upload or read-back fails, the row is marked `superseded` so retention deletes any uploaded object. Nothing is deleted from disk. - **Encryption key:** restore points are refused (`restore_point_key_not_durable`) on `s3` storage unless the secrets master key comes from `PAPERCLIP_SECRETS_MASTER_KEY`. - **Dry run** reports `restorePoint: true` candidates without storing anything. **Restore** (`git-workspace-restoration.ts`, `workspace-runtime.ts`, `execution-workspaces.ts`): - **Recipe versions:** `readGitCacheRestoration` and `savedGitWorkspaceRestoration` accept v1 without a restore point, or v2 with a valid one. Older servers reject v2 instead of restoring the commit without the saved work. - **Before the saved commit is needed:** reopening (`restoreGitCacheBase`) and the runtime path import the bundle when the saved commit is missing locally. - **After the worktree is re-added:** the runtime always imports the bundle, so history-only commits are present again as objects even when the base was rebuilt (they are not recreated as branches), then applies the restore point, verifies the result, and records `appliedAt`. Reopen persists that through a callback, as it already does for saved contents. - **Never overwriting:** a worktree that already matches is only marked applied. A worktree that diverged from the saved commit's clean state is never overwritten; the restore fails closed and can be retried. Missing, corrupt or expired restore points also fail closed. **Retention:** the #17241 worker's expiry hook now marks the recipe's restore point expired before its object is deleted. **Config and docs:** - `server/src/config.ts` adds the two settings; `doc/recoverable-disk-cleanup.md` and `doc/DEVELOPING.md` describe them. - No code comments were added. **Not in this PR (follow-ups):** - workspaces with nested `.paperclip-repositories` checkouts; - removing idle worktrees of issues that are still open; - starting a fresh workspace with a warning when a restore point has expired. ## Verification - `pnpm exec vitest run src/__tests__/git-restore-point-expiration.test.ts` (in `server/`): 12 passed, with real repositories and embedded Postgres. The cases: - **Round trip:** an unpushed commit, staged and unstaged edits of one file, a deletion, and an untracked file are restored exactly on reopen, `.env` is dropped, and the restore point is active. Restoring through the runtime path works the same way, and a later run never re-applies over newer work. - **Kept:** a worktree that is not yet due, one with the feature disabled (today's skip reason), and one whose encryption key is not durable. - **Change after capture:** rolls back, keeps the worktree, returns the recipe to v1 and supersedes the restore point. - **Missing restore point:** fails closed, keeps the row archived and unapplied, and fails closed again on retry. - **Dry run:** stores nothing. - **Reproducible worktrees:** expire as before, with a v1 recipe. - **History-only commits:** reopen imports them even after they are pruned from the base. - **Draft messages:** a draft commit message keeps the worktree. - **Upload failure:** a failed upload marks the pending restore point for cleanup and keeps the worktree. - **Mutation checks:** each of these fails at least one case: - removing the pre-deletion snapshot check; - keeping the restore point reference on rollback; - removing the runtime apply; - removing the re-apply guard (the divergence check then fails closed instead of overwriting); - skipping the import for a matching worktree, relaxing the draft message guard, or not marking a failed upload's row. - `pnpm exec vitest run src/__tests__/git-restore-point-expiration-config.test.ts`: 5 passed. - `pnpm exec vitest run git-workspace-expiration git-workspace-contents git-restore-point workspace-runtime execution-workspaces` (in `server/`): 529 passed on the first revision. Two `workspace-runtime.test.ts` cases about remote base refs fail, and they also fail on unmodified `master` on this machine. After the review fixes, the expiration, contents, restore point and execution workspace suites passed again: 222 tests. - `pnpm run typecheck` (in `server/`): pass. - The server builds, the runtime bundle builds, and `scripts/server-boot-smoke.sh node server/dist-runtime/index.mjs` reaches healthy. ## Risks - **Off by default:** nothing changes unless both `PAPERCLIP_GIT_CACHE_EXPIRATION_ENABLED=true` and `PAPERCLIP_GIT_RESTORE_POINTS_ENABLED=true` are set. Roll out with `PAPERCLIP_GIT_CACHE_EXPIRATION_DRY_RUN=true` first to see which worktrees would receive restore points. - **Data at rest:** restore points contain source and uncommitted files, encrypted with keys wrapped by the instance secrets key. Losing that key makes them unrecoverable, which is why `s3` storage requires an environment-provided key. Untracked `.env` files are not stored. - **Interrupted apply:** a crash in the middle of applying a restore point leaves a worktree that neither matches the restore point nor is clean. The restore then fails closed rather than overwriting it, and an operator must reset that worktree to retry. - **Rollback:** disable the setting. Already-expired worktrees keep their v2 recipes and restore points, so reverting the code would leave those recipes unreadable until restored by a server with this change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file edits, tests, local server builds and boots, read-only measurements on live instances). ## 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-22 16:50:15 -07:00
Nicky LeachandPaperclip	8b4ab65b1c	Add plugin-owned project storage and task workspaces (#17001) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Tasks can use isolated repository workspaces. > - Core currently prepares those repositories on its own filesystem. > - A storage provider may only expose repositories inside remote agent computers. > - Project storage and task workspace preparation must have one provider owner. > - This pull request adds that contract and keeps execution as a separate plugin interface. > - Core keeps authorization, durable task bindings, and lifecycle fences. ## Linked Issues or Issue Description **Subsystem affected** Plugin SDK, project workspace policy, heartbeat preparation, execution leases, and workspace lifecycle. **Problem or motivation** Core cannot prepare a task workspace when its repository storage is unavailable on the Core host. An execution lease must not be required just to prepare persistent storage. **Proposed solution** Let one plugin provide project resource lifecycle and workspace prepare, inspect, restore, and remove behavior. Core reserves a task workspace before it calls the plugin. The plugin returns an opaque durable reference. The matching execution plugin receives that reference on its task RPC. **Alternatives considered** Preparing repositories on Core would require a provider mount on Core. Preparing them only during task launch would tie persistent workspace lifecycle to execution leases and agent availability. **Roadmap alignment** This extends the remote provider model in ROADMAP.md. Related execution work is in #16978. This PR does not replace that task bridge. Native execution of managed storage requires the bridge; this change fails closed when it is absent. ## What Changed - Add one storage provider declaration with supported modes/strategies, a capability, a validated RPC contract, and a test harness. - Persist provider ownership, repository revision, and execution-workspace identity before external effects. Reconcile retries with a stable operation ID. - Prepare provider storage before environment acquisition. Keep Core filesystem preparation out of this path. - Pin the durable reference to the matching execution plugin and validate the lease binding before task dispatch. - Route inspection, reopen, and removal through the existing lifecycle process. Keep local data when remote recovery is uncertain. - Keep the application database pool free during lifecycle locks. Preserve pending workspace selections, validate source edits before retirement, and retry unfinished closed storage cleanup. - Protect provider metadata and live repository sources from caller edits. Storage edits retire only closed records with confirmed removal; retired records cannot reopen. ## Verification - Current head `8214b3ca5`: all 25 provider lifecycle tests pass with `maxConnections=1`. They cover preparation, inspection, reopening, removal, a paused provider with responsive ordinary SQL and a competing source edit, pending selection preservation, rejected source edits, cleanup retry scheduling, and providers that cache operation results, and committed cleanup notifications for storage intent and recovered state. - Final frozen-tree lifecycle run on `8214b3ca5`: all 318 tests passed in 10 files, covering workspace services, reopen, compaction, task binding, project sources, heartbeat preparation, display caching, and source locks. - Direct server `tsc --noEmit` passes. The SDK build and all 128 SDK tests passed during initial verification; later SDK changes are documentation only. - Full CI on the previous head `ec5c7209a` passed all 55 applicable checks; 2 conditional checks skipped. Standard Greptile reviewed current head `342e6d9c3` at 5/5 with no unresolved threads. All 55 applicable CI checks passed on `342e6d9c3`; 2 conditional checks skipped. The Slack browser and CLI startup jobs passed on their single unchanged-head rerun. Its Apex review returned 4/5 with one pending-restoration issue. Commit `1b58943b1` reconciles that durable intent before cleanup, advances the generation without reopening the Core row, and blocks direct removal or retirement while intent remains unresolved. Standard Greptile reviewed `1b58943b1` at 5/5 with no new findings. All 54 applicable CI checks passed on `1b58943b1`; 3 conditional checks skipped. The chat job passed on its single unchanged-head rerun. Apex then returned 4/5 for a missing cleanup wake after recovery. Commit `8214b3ca5` atomically registers cleanup intent before storage intent and recovery-result writes. Its provider test observes real committed notification hints and the visible advanced generation. Standard Greptile reviewed `8214b3ca5` at 5/5 with no new findings. All 55 applicable current-head CI checks passed on the first run; 2 conditional checks skipped. Final Apex verification completed at 5/5 on this exact head: 38 files reviewed, no new comments, and no unresolved threads. The PR is ready for review and mergeable. - The first Apex review found five issues after a standard 5/5: application-pool starvation, stale pending selections, retirement during rejected source edits, lost cleanup retries, and reused inspection identities. Commits `6d72e7fd4` and `342e6d9c3` fix each with regression coverage. Archive lock waits use dedicated connections, and source edits fail promptly if the lifecycle is busy. Retirement compares normalized values. The normalized-source regression initially failed with the raw-value comparison; after moving the check after normalization, a clean provider-suite rerun passed all 24 tests at that stage. Those threads are resolved; the earlier Apex 0/5 is not a passing acceptance result. - Earlier local integration attempts could not bind localhost inside the sandbox. The same suites passed with permission to start local PostgreSQL. - The earlier broad local `pnpm test:run` overlapped edits and reported stale-revision and checkout-path/Git-fixture failures. It was not a final-tree result. Full CI subsequently passed; the original local failure remains part of verification history. - Local repository-wide typecheck/build cannot complete because `cargo` is unavailable. Direct server TypeScript checks and affected tests pass; full Rust and build validation comes from CI. - An earlier browser run on `ff918c5a8` failed in the unchanged case-filter journey: expected “Done,” received “All statuses,” with an announcement handler recorded during the assertion. The cause is not confirmed. [The failed job](https://github.com/paperclipai/paperclip/actions/runs/39500611857/job/118896954508) remains verification history. The unchanged shard passed in the next full CI run on `ec5c7209a`; no UI or fixture change was made. - Current-head browser shard 2 failed waiting five seconds for the mocked Slack setup Success heading. This PR changes neither that UI nor its fixture. [The failed job](https://github.com/paperclipai/paperclip/actions/runs/39506070513/job/118916021232) remains verification evidence. The cause is not confirmed; the single unchanged-shard rerun passed; no UI or fixture change was made, and the original cause remains unconfirmed. - The workspace test shard passed its 3,978 general tests, then its CLI company-import/export fixture timed out after 30 seconds waiting for startup health before creating any company or workspace. [The failed job](https://github.com/paperclipai/paperclip/actions/runs/39506070513/job/118916021855) remains verification history. The child reached external-PostgreSQL startup without exiting or reporting an exception. Its cause is not confirmed; the single unchanged-job rerun passed, including the CLI fixture. No startup or fixture change was made, and the original cause remains unconfirmed. - The new cached-removal regression initially failed because its fake worker advertised availability for unrelated fixture plugins, so another workspace changed its fake checkout state. Worker availability now matches the fixture plugin; the complete 25-test provider suite passes. - On `1b58943b1`, the chat shard timed out polling for one conversation after an authorized GitHub description edit. [The failed job](https://github.com/paperclipai/paperclip/actions/runs/39510521657/job/118930193418) remains evidence. The exact case passes locally against PostgreSQL (1 passed, 1,380 unrelated cases skipped), and this PR changes neither that test nor its handler. The original cause is unconfirmed; the single unchanged-job CI rerun passed without a code or fixture change. The original cause remains unconfirmed. - The diff was checked for credentials, private references, and generated artifacts. ## Risks This is an additive provider contract with no database migration. Existing projects keep their local behavior unless their policy selects a storage plugin. A selected provider must be ready and enabled. Unknown or unsafe cleanup fails closed. Managed native execution depends on #16978. Core refuses a host Runner fallback. Providers must fence lifecycle generations, preserve ambiguous retries, and report remote recovery honestly. Provider-specific live storage and guest mount qualification remain separate from these Core contract tests. ## Model Used OpenAI Codex (GPT-6), with repository inspection, code execution, and tests. The exact model variant was 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 linked existing issues or described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket id - [x] I have run tests locally and they pass (affected suites; broad-run limits are documented above) - [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>	2026-10-20 16:35:33 -07:00
DottaandPaperclip	813e808af4	Remove filesystem history authorization from workspace preparation (#16963) ... Remove physical-root source/reader authorization and sticky directory classifications from workspace preparation. Preserve current task/run authority, app-record privacy, credential authorization, containment, and lifecycle/publication integrity. Validate replacement selections against persisted new inputs and refresh verified checkout ownership so bounded reuse survives earlier workspace relocation. Add real PostgreSQL/Git regressions, a reproducible history-scaling benchmark, and documentation. Full CI passed all 48 jobs and Greptile scored 5/5 at 3d5da6c259. Five preparation-guard medians improved from 20,512.99 ms to 52.22 ms on the 8,500-workspace fixture; these are not end-to-end startup timings. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-10-20 09:19:59 -05:00
DottaandPaperclip	16689de291	fix: add one-click retry for restricted workspace setup (#16909) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Tasks need a clear way to resume after a setup failure. > - A shared repository can contain another task that the assigned agent cannot read. > - Paperclip correctly stops before the agent starts, but the user must then understand workspace settings to recover. > - This pull request gives that failure a single Retry button and selects a clean copy of the configured repository through normal admission. > - The task keeps its assigned agent and execution settings, while access checks and existing work remain protected. ## Linked Issues or Issue Description Related: #16895 classifies the restricted source failure. This change adds the user recovery action. #16906 handles retained files after execution; this change handles a setup failure before execution starts. **What existing behavior does this improve?** Recovery of a task whose shared repository includes a task workspace the assigned agent cannot read. **Current behavior** The task stops before provider work and asks the user to understand workspace choices or access grants. **Proposed behavior** Show Retry above the task message box, independent of loaded conversation history. One click requests one attempt using a clean checkout of the configured remote. Show Retrying while the request is pending. Show an error only if the request fails. **Reason and benefit** The user can resume work without understanding repository isolation or changing access to another task. **Breaking changes** None. The recovery source value is server-owned. The public workspace selection request does not accept it. No migration is required. ## What Changed - Add one Retry control above the composer in both task conversation views. It stays available when an older notice is outside the loaded comment pages. - Bind recovery to the latest failed run, current assignee, and recorded proof that provider work did not start. - Use the existing atomic recovery route and pending workspace selection. Normal admission clears the old session and creates the isolated checkout. - Choose a fresh task-owned branch for recovery, including fixed project branches, existing task branches, and adapter branch overrides. Preserve the model, environment, setup commands, pending user workspace choices, previous files, and all execution gates. - Update execution documentation and both workspace maps. ## Verification - Passed all 461 tests in the eight affected database, Git, HTTP, workspace binding, and conversation suites after the review fixes. An additional 292 tests passed after the final compatibility fixes, including IssueDetail and recovery action routing. - Concurrent HTTP retries produce one wakeup. Paused projects and runs that started provider work reject recovery without changing the workspace. - Real Git tests exclude private files, private commits, and unpublished original files from the clean checkout, preserve the original, and exercise reuse, cleanup, and reopen. - Verified in a running local app: a task failed twice, displayed only Retry, and reached Done after one click. A second browser test put the failure notice behind 501 newer comments and used a fixed project branch. Retry stayed visible and the task reached Done. The credential-free process worker used the selected checkout and wrote its result there. This does not claim a live model-provider run. - The first manual fixture lacked a responsible-user membership and failed after successful workspace recovery. Corrected the fixture, retained that failure evidence, and verified the full flow with ordinary authorization. - Full typecheck, build, token gates, and map checks passed. The full local suite was stopped after review changed its source during execution; current-head CI provides the complete suite result. - An earlier unrelated peer-comment read test hit a socket hangup. The next complete affected-suite run passed; the first failure is retained in local evidence. - Current-head CI hit an unchanged runner credential-concurrency test failure. That lane passed on the preceding commit, and all 42 credential tests passed locally. The original failed job is retained; the one-time rerun passed. All latest-head CI checks are green (55 success, 2 skipped, 1 neutral), and Greptile is 5/5 with both review threads resolved. ## Risks - A remote repository outage can still prevent the next attempt. Retry does not grant access or copy unpublished files from the old checkout. - Recovery accepts only the latest recorded pre-provider failure and preserves normal execution gates. This limits duplicate work and stale recovery requests. - No database migration, dependency, or lockfile change. - The first review found fixed-branch retry loops and dependence on paginated notice history. Both had failing regressions before the fixes and now pass targeted tests and the combined browser journey. - Full CI then caught assumptions about missing run evidence and unrelated recovery actions. The final changes tolerate absent evidence and scope the new lookup to board-owned actions with valid run IDs. The previously failing suites now pass locally. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, repository tools, code execution, and browser verification. The exact serving model ID and context window are not exposed in this session. ## 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>	2026-10-19 21:49:44 -05:00
3 people	18e9ca7277	fix(server): retry read-only delivery lookups after a pooled disconnect (#16859) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Execution workspaces have a close-readiness check. The board uses it before it archives or cleans up a workspace. The terminal-workspace reaper and workspace hydration use the same delivery assessment. > - The delivery assessment reads the source issue tree and the pull request work products of the source issue. > - A pooled database connection can become stale. Then postgres.js rejects the query with `write CONNECTION_CLOSED`. > - The issue-tree read had no retry. One stale socket failed the full close-readiness request with a 500. > - The database client does not replay disconnects globally, because a write can commit before the disconnect (#14773). Callers that know a lookup is read-only opt in with `retryIdempotentDatabaseOperation` (#14873, #15248, #15300). > - This pull request wraps the two read-only delivery lookups in that helper. > - The benefit is that close readiness, hydration and the reaper recover from one stale pooled socket. ## Linked Issues or Issue Description Refs #14773, #14873, #15248, #15300 (same retry pattern for other read-only lookups). **What happened?** A hosted staging server returned an error for an execution workspace close-readiness request. The issue-tree query in the delivery assessment failed with `write CONNECTION_CLOSED` through a transaction-mode database pooler. **Expected behavior** A read-only lookup recovers after one transient pooled disconnect. Persistent failures still propagate. **Steps to reproduce** 1. Use a pooled PostgreSQL endpoint that closes idle client sockets. 2. Let a pooled connection go stale. 3. Request close readiness for an execution workspace that has a source issue. 4. The first query on the stale socket fails and the request fails. **Paperclip version or commit** `master` at 9966f31. **Relevant logs or output** `Error: Failed query: select "id", "status", "completed_at", "cancelled_at", "updated_at" from "issues" where ... WITH RECURSIVE issue_tree ...` caused by `write CONNECTION_CLOSED`. ## What Changed - `listWorkspaceIssueTree` now runs inside `retryIdempotentDatabaseOperation`. It is a plain recursive SELECT. - `listDeliveryPullRequestProducts` now runs inside `retryIdempotentDatabaseOperation`. It is a plain SELECT. - Both functions capture `sourceIssueId` before the retry callback. Each attempt builds a new query. - Two regression tests in the embedded PostgreSQL `getCloseReadiness` suite: - One transient disconnect on each delivery read gives the same readiness result as a healthy database. - Three disconnects on the issue-tree read propagate the last error. The pull request read does not run. ## Verification - `pnpm exec vitest run src/__tests__/execution-workspaces-service.test.ts` (in `server/`): 80/80 tests pass. - The two new tests fail without the service change. The first fails with `write CONNECTION_CLOSED`. The second records one attempt, not three. - I did not run the full server typecheck or the full suite locally. The sandbox has a 4 GB memory limit and the native `tsc` process was killed. CI runs both. ## Risks - Low risk. The change wraps two read-only SELECTs. It does not wrap writes or transactions. - A persistent outage adds up to about 150 ms of retry pauses before the error propagates. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, used as an agent with tool use (shell, code editing, test execution) and extended reasoning. ## 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: devinfoley <139239+devinfoley@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-19 09:51:45 -07:00
DottaandPaperclip	790b729086	fix: restore nested project repositories and settings after expiration (#16691) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents use isolated Git workspaces with managed project repository copies. > - Finished workspaces can expire when Git can reproduce their contents. > - The saved recipe records the main commit but omits nested commits and local settings. > - Reopening can therefore use newer nested code and lose merged user settings. > - This pull request saves and restores those contents before workspace provisioning. > - It also permits verified FETCH_HEAD metadata so ordinary fetches do not block safe expiration. ## Linked Issues or Issue Description Refs #16457, #16586, #16621. Related performance work: #16579. **What happened?** After a finished workspace expires, its nested project checkout can reopen at the current upstream commit instead of its previous commit. Cleanup also treats local Claude settings as disposable, although that file can contain user settings. Ordinary linked-worktree FETCH_HEAD metadata prevents otherwise safe cleanup. **Expected behavior** Restore the main and nested repositories at their saved commits. Preserve local settings bytes and permissions. Skip files and Git state that cannot be reproduced. Permit standard fetched metadata only when its commits remain recoverable. **Steps to reproduce** 1. Prepare a managed nested project repository at commit A and add ignored local settings. 2. Advance upstream to B, finish the task tree, and expire its workspace and base. 3. Reopen the workspace through the normal service path. Before this fix, nested preparation selects B. ## What Changed - Extend the existing restoration recipe with exact nested commits, branches, source identity, and encrypted local settings. Keep the schema compatible with older recipes. - Restore nested repositories and settings before provisioning. Recheck company/project source access and preserve conflicting files on retry. - Recheck recorded contents under cleanup locks before deletion. Persist lock ownership before atomic publication so process exits recover safely and foreign locks stay intact. Preserve changed or unsupported contents, including tracked settings. - Keep saved project repository selections through normal preparation. Checkpoint restored contents before provisioning so failed setup can retry without overwriting later edits. - Accept bounded linked-worktree FETCH_HEAD records only after local ancestry or fresh upstream proof. Preserve local-only fetched commits. - Add real Git/Postgres lifecycle cases and focused content, access, publication-retry, and fetched-state controls. Document the behavior. ## Verification - `pnpm -r typecheck` passed. - `pnpm build` passed. - The original real Git/Postgres experiment failed with nested B instead of A. The same path passes with this change. - The integrated lifecycle suite passed 42 cases in 91.66s. Related preparation, credential, content, and Git metadata controls passed 46 cases in 24.41s. The final heartbeat checkpoint persistence case passed separately in 8.17s. - Coverage includes exact main/nested commits, encrypted settings and modes, upstream failure and retry, provisioning order, concurrent reopening, changed unique files, tracked settings, malformed metadata, and company boundaries. - Exact-head CI passed the implementation, typecheck, build, security, and test matrices. One browser shard passed on a single rerun after an unrelated fixture teardown raced an activity-log write; its feature assertions passed in the initial attempt. - The broad local test run was stopped after about 12 minutes of unrelated serial tests. Full parallel CI is required before merge; no local full-suite pass is claimed. - Single-workspace deployment, real-backlog reclamation, and ordinary product reopening remain required acceptance work after merge. ## Risks - Expired Git repositories still depend on upstream access. A failed restoration returns the existing retryable error and never substitutes the default branch. - Saved settings use the existing local encryption provider. Recovery requires that encryption key to remain available. - Unsupported files, tracked settings, unknown sources, and unverified Git state remain on disk. This can reduce reclaimed space. - No database migration, recovery-retention change, public API, or fleet-default change is included. ## Model Used OpenAI Codex, GPT-6 family, with tool use, code execution, and an independent agent review. The runtime does not expose a more specific model identifier. ## 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>	2026-10-17 22:54:28 -05:00
DottaandPaperclip	2aca41464b	fix(workspaces): preserve compaction and expire standard Git bases (#16476) ... ## Thinking Path > - Paperclip manages AI agents and their task workspaces. > - Finished tasks can release reproducible Git files and restore them later. > - Unique work must stay on disk, while regenerable dependencies can be removed. > - Linux Git templates include an empty legacy directory that blocked base cleanup. > - The new expiration branch also skipped the existing guarded dependency cleanup. > - This change accepts the standard empty directory and retains that cleanup order. > - Private bases can expire, and protected workspaces still shed regenerable files. ## Linked Issues or Issue Description Refs: #16457 Live acceptance of #16457 removed a worktree but retained its private base because Linux Git created an empty `.git/branches` directory. A pending-base dry run then tried to resolve the already removed worktree and hid the preservation reason. A local integration comparison also showed that enabling Git expiration skipped existing dependency compaction. It deferred pending startup compaction by an hour. Both failures were reproduced before the fix. ## What Changed - Accept `.git/branches` only when it is an empty real directory. Preserve populated entries, files, and symlinks. - Inspect pending base cleanup without resolving an absent worktree. - Run existing guarded compaction before Git expiration. Exclude already closed rows from compaction and retain its pending deadline. - Keep failed expiration checks from reaching legacy whole-workspace deletion. Existing compaction remains independent of Git expiration dry-run mode. - Extend real Git/PostgreSQL tests and retain the acceptance failures in the delivery state note. ## Verification - Linux-template baseline: private-base expiration failed before the fix. The first sandboxed attempt could not bind PostgreSQL; the authorized retry reproduced the behavior. - Compaction baseline: two regression cases failed in 7.67 seconds. They reproduced skipped dependency cleanup and the lost startup deadline. - After the fixes, `pnpm exec vitest run server/src/__tests__/execution-workspace-compaction.test.ts server/src/__tests__/git-workspace-expiration.test.ts server/src/__tests__/terminal-workspace-work.test.ts` passed all 49 cases in 43.79 seconds. - Controls cover unique work, active runs, unfinished descendants, previews, concurrent reopening, interrupted removal, exact-commit restoration, and retryable upstream failures. - Full `pnpm -r typecheck` and `pnpm build` passed for the final commit. All exact-head CI and security checks passed. Greptile is 5/5 with all findings resolved. - Final staging acceptance will let the restarted worker resume the retained base cleanup, then reopen normally at the recorded commit and persist subsequent work. The base has not been manually removed. The superseded preview build was cancelled before dispatching a replacement. ## Risks - Legacy branch definitions can hold unique data. Only an empty real directory qualifies for deletion. - Compaction preserves its existing lifecycle guard and regenerable-directory allowlist. It cannot fall through to legacy deletion after an expiration failure. - Already closed workspaces must only resume their recorded expiration; they do not enter compaction. ## Model Used OpenAI Codex, GPT-6.1-sol, with reasoning, code execution, Git, database, and browser tools. The exact context-window size is not exposed by this session. ## 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>	2026-10-15 14:36:00 -05:00
DottaandPaperclip	59a70dc9e2	fix(workspaces): expire reproducible Git files and restore exact commits (#16457) ... ## Thinking Path > - Paperclip manages AI agents and their task workspaces. > - Isolated Git worktrees and private repository copies remain on the host after tasks finish. > - These files can fill the disk even when every commit is available upstream. > - Cleanup must retain unique files, local Git state, live work, and recovery data. > - This pull request records and verifies an exact-commit restoration recipe before expiration. > - Normal reopening restores that commit even after upstream advances. > - The benefit is lower host disk use while finished tasks remain available for later work. ## Linked Issues or Issue Description Refs #10285 and #2022. Follows #16433 for skill-cache expiration. Related #11936 provides separate host-local cleanup tooling; this change extends the existing company-scoped lifecycle worker and normal workspace reopening. ROADMAP.md does not specify a competing implementation. ## What Changed - Add opt-in expiration for verified Paperclip-owned Git worktrees after their whole task tree has been done or cancelled for 24 hours. - Preserve active and scheduled runs, previews, pending reopening, unresolved recovery, dirty files, unknown ignored files, and unsupported or unique Git state. - Verify an authenticated fetch in a fresh object store. Save repository identity, exact commit, branch, and ownership before any deletion. - Rename eligible files into recorded managed trash. Resume interrupted cleanup under source and lifecycle locks. - Expire private base clones only after consumer, file, reference, reflog, and object checks pass. Preserve shared project base clones. - Rebuild missing bases and worktrees through normal reopening at the recorded commit. Return an explicit retryable error when repository access fails. - Add independent workspace/base switches, dry-run reports, reclaimed-byte counts, and operational documentation. No table, public API, UI, or recovery-retention change. ## Verification - Real local bare remote plus Postgres: create at A, advance upstream to B, expire the worktree and private base, reopen at A, then make and retain a subsequent commit. - Final lifecycle suite: all 20 tests passed in 46.41 seconds at `d72947a2e45be5d0c912debb03c46b15863b4798`. Review fixes cover second-cycle expiration, newer-branch recovery, normal preparation after restoration, branch adoption, and Git administration path controls. Eleven existing branch reconciliation controls also passed. Covers unique files and Git state, live descendants, scheduled runs, recovery, previews, unauthorized access, upstream failure, concurrent reopening, interrupted deletion, shared bases, and nested private worktrees. - Final guard regressions: 3 affected tests passed. Existing workspace/runtime/preparation/source controls: 328 tests passed in 238.69 seconds. - Full repository typecheck and build passed locally. The full local test attempt did not pass: initial native-session cases hit macOS Postgres shared-memory exhaustion, source changes invalidated two discovery cases, and the checkout disappeared near the end. The final-code retry of the remaining skill and unrelated controls passed all 103 tests. All checks passed on this exact head, including typecheck, general and serialized tests, Runner checks, build, canary dry-run, browser E2E, and security scans. Greptile reviewed the head at 5/5 with all findings resolved. - Fixed a blocking CI policy false positive for `docker-compose-secrets.test.mjs`. The test still rejects GitHub secret expressions, including dot, bracket, and multiline forms. Its full 15-test suite passes. - Map validation and `git diff --check` passed. - Staging dry-run inspection, measured reclamation, and ordinary product acceptance remain pending. No live acceptance is claimed. ## Risks - Git restoration depends on continued upstream availability and credentials. Cleanup skips unverified commits; restoration never substitutes the default branch. - File deletion requires multiple conservative proofs. Unknown or unsupported state is retained and can limit reclamation. - Source and lifecycle locks serialize preparation, reopening, and expiration. Remote verification has a deadline but can delay work on the same source. - Start with both expiration switches disabled. When enabled, dry-run remains the default. Rollback disables further deletion while retaining restoration support. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository inspection, tool use, and code execution. The exact backend model ID and context-window size are not exposed in this session. ## 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 (focused tests; full local limitation documented above) - [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>	2026-10-15 13:09:59 -05:00
DottaandPaperclip	cccde7122b	Trace execution preparation and durable response persistence (#16419) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The server prepares an execution environment before it starts an agent. > - Operators need to distinguish preparation, provider wait, and response persistence. > - Existing preparation phases start separate traces, and the native session trace ends before the final response is saved. > - This pull request adds an execution-attempt trace and detailed spans at the existing work boundaries. > - The benefit is a measurable startup and settlement path without changing execution policy. ## Linked Issues or Issue Description **What existing behavior does this improve?** Operator-configured OpenTelemetry tracing for agent preparation, startup, and durable response storage. **Subsystem affected** Server orchestration, native Runner startup, and the Honeycomb run link. **Current behavior** Preparation phases start independent roots. Workspace lock waits, authorization groups, runtime asset work, provider-pack fallback, and the gap after provider completion are hard to attribute. **Proposed behavior** Use a server-owned async context for each execution attempt. Parent nested work to that attempt. Link the separately sampled native session because its ingress and queue history can begin earlier. Record transaction entry, lock waits, grouped authorization, asset preparation, artifact fallback, copyback, and response commit. **Reason and benefit** Operators can identify expensive work from recorded boundaries instead of inferring the cause from elapsed time. Nested and concurrent durations remain visible and must not be added together. **Breaking changes** No API or execution-policy change. New Observability span names and closed count attributes are documented. The existing local run-performance schema also records the additional provider-pack and harness measurements. Refs: #16178, #16205, #16330. ## What Changed - Add `task.execution_attempt` with same-run async ownership, independent root sampling, and native-session links. - Measure workspace transaction entry and settlement, advisory and row waits, source scans, reader groups, notifications, and writes. - Measure runtime selection and each concurrent instructions, skills, and MCP branch. Separate manifest, cache, materialization, and verification work. - Measure provider-pack discovery, verified reuse or upload, final verification, and remote harness state checks. - Measure workspace settlement, accounting, liveness, response authorization, comment commit, and publication enqueue. - Preserve the silent endpoint-off path, including when another library has registered a tracer. Bound repeated detail spans to 16 per name per attempt. - Extend the Honeycomb run link and document the actual coverage and remaining gaps. ## Verification - After resolving the conflict with retained-reader batching on `b98cdaea531c8447637cd4dcc19c61b3f5f41844`, all 61 targeted query, authorization, workspace-preparation and trace-boundary tests passed. The server typecheck passed. Reader tests still bound query count, avoid loading retained run payloads and enforce fresh project grants on every publication attempt. - Before that base integration, the tracing/exporter group passed 855 tests with 2 optional-SDK skips across 10 files and no inherited OTLP endpoint. It covers real PostgreSQL waits/rollback, durable response commit, assembled heartbeat preparation, concurrent parentage, sampling and tracer failure isolation. Native workspace/history tests passed 23 cases. These results remain supporting evidence for the unchanged tracing paths. - Full workspace typecheck and build passed during implementation. Full sharded CI, release validation, E2E and Apex 5/5 passed on prior head `8cebad80f3856dbcff6f3a6d5d34880ff77a20f2`. Fresh CI, security and Apex review are required on the current head before merge. - `pnpm check:token-gates` passed. No styles changed. - Earlier CI runs exposed exact-source-expression assertions changed by wrappers, missing run hashes on transaction-boundary spans, and sampling fixtures without an enabled endpoint. The fixes preserve the calls, add the declared hash and span cap, and enable tracing explicitly in the sampling fixtures. Focused repairs passed; the full prior-head CI passed after those repairs. Earlier failed run: https://github.com/paperclipai/paperclip/actions/runs/38729131366. - The full local `pnpm test:run` was stopped after the base advanced during that process. Its mixed-version results are not final-head evidence. A full local-suite pass is not claimed. - The old-head Superagent scan stalled at 35%. The current head has a fresh scan; no security pass is inferred from the old pending result. - No deployed Honeycomb acceptance is claimed by this code change. ## Risks - Enabled tracing creates more spans. Repeated detail spans are bounded, and inventories use group spans. - The attempt and native session remain linked traces. Historical queue time can precede the attempt, and nested intervals overlap. - A committed comment proves durable server storage. Publication enqueue and realtime dispatch do not prove external delivery or browser paint. - New custom attributes use only the existing run hash and validated file/byte counts. No SQL, paths, permissions, content, or exception text is added. ## Model Used OpenAI GPT-6 through Codex. The serving model ID and context window size are not exposed in this session. The agent used reasoning, tools, code editing, and code 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-15 08:13:53 -05:00
Devin FoleyandPaperclip	aec80cbc8c	fix(server): keep workspace compaction out of the startup sweep (#16328) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - When the server starts, `/api/health` answers "starting" until startup recovery finishes, and deploy tooling waits for "ok" > - Startup recovery waits for the first sweep of the terminal-workspace worker > - #16304 added workspace compaction to that sweep. Compaction walks worktrees, runs Git, and deletes dependency trees, and it re-checks every eligible workspace after a restart > - Compaction is never needed to serve requests, so it should not delay readiness > - This pull request skips compaction in the startup sweep only; later sweeps compact as before > - The benefit is that a compaction backlog cannot make a restart slower ## Linked Issues or Issue Description Follow-up to #16304. **What existing behavior does this improve?** Server startup time after #16304. **Current behavior** `await terminalWorkspaceWorker.ready` blocks the readiness flip until the first terminal-workspace sweep ends. That sweep compacts every eligible workspace in its page. The per-cycle compaction memo is in memory, so after each restart every eligible workspace is walked and checked with Git again, and any directories found are deleted before the sweep ends. **Proposed behavior** The first sweep skips compaction. Pending compactions keep their deadlines, so the worker wakes and a later sweep compacts them. **Reason and benefit** Readiness depends only on work that is needed to serve requests. On one measured instance the first sweep took 5–8 s with compaction; with a larger backlog, compaction could add seconds per workspace. **Breaking changes** None. Compaction happens one sweep later after a restart. ## What Changed - `sweepTerminalWorkspaces(limit, signal, { compact })`: `compact: false` skips compaction for that sweep and keeps each pending compaction deadline. - `registerTerminalWorkspaceWork` passes `compact: false` to its first sweep (the one readiness waits for) and `compact: true` after that. - `server/src/index.ts` forwards the option through the logging wrapper. - `doc/DEVELOPING.md`: the compaction section says the startup sweep never compacts. ## Verification - `pnpm exec vitest run src/__tests__/terminal-workspace-work.test.ts src/__tests__/execution-workspace-compaction.test.ts src/__tests__/workspace-compaction.test.ts` (in `server/`): 35 passed. - New: the worker passes `compact: false` only to the startup sweep and `compact: true` to the next one. - New: a sweep with `compact: false` leaves the files in place, the compaction deadline stays due, and the next sweep compacts. - `pnpm typecheck` in `server/`: passed. ## Risks - Low risk. After a restart, compaction runs a few seconds later than before. Archive behavior does not change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file edits, test runs). ## 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-14 15:27:28 -07:00
DottaandPaperclip	ad0bd26bb7	perf(heartbeat): avoid Git inspection for stored workspace reads (#16306) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Heartbeat selects and restores a saved execution workspace before dispatch. > - These reads used the workspace detail reader, which also scans Git and resolves delivery state. > - Configuration reads do not use those live display fields. Each extra process can delay other controller work. > - This pull request adds a stored-record reader and uses it in configuration, environment selection, and finalization. > - It also derives ancestry from the existing ahead/behind result and skips delivery HEAD reads for unfinished tasks. > - The benefit is fewer Git processes while live execution and cleanup guards remain in place. ## Linked Issues or Issue Description Related: #16282, #16302, #13619. Those changes reduce background or display scan demand. This change removes live display inspection from execution configuration reads. **What existing behavior does this improve?** Heartbeat workspace configuration reads and workspace close-readiness checks. **Current behavior** Reading saved workspace configuration also loads runtime health, Git status, ancestry, and delivery state. Close readiness walks history twice to determine ancestry. **Proposed behavior** Execution reads stored configuration through a company-checked method. Live branch validation and destructive cleanup still inspect current Git state. Close readiness uses its ahead/behind result to determine ancestry. **Reason and benefit** A synthetic benchmark of the actual service returned identical stored fields for 20 workspaces. Detail reads launched 60 Git commands and took 689 ms. Stored reads launched zero Git commands and took 8 ms. This was a local macOS measurement, not an end-to-end cloud latency claim. **Breaking changes** None to public APIs or saved data. Workspace detail responses keep their live fields. ## What Changed - Add `getStoredById(companyId, id)` and use it in three heartbeat reads. - Preserve the access-denied error for a foreign-company workspace. - Remove the extra `merge-base` process and the unused HEAD read for unfinished tasks. - Add recovery, company-boundary, ancestry, and cleanup regressions. - Add a repeatable database/Git benchmark and document the read boundary. ## Verification - The new environment-selection regression failed before the fix with `Live Git inspection is unavailable` and passes after it. All eight environment-selection tests pass. - On the final rebased commit, workspace service, environment selection, and branch finalization: 89 tests passed. Branch-containment, runtime-execution, and display-cache suites also passed during development. - `pnpm -r typecheck`: passed. - `pnpm build`: passed. - `pnpm test:run`: started locally, then stopped after all full-suite CI test shards passed on the final commit. The complete local run was not finished; CI provides the full-suite result. - Final commit `9a13ef0481b7bf6a60b2b7ac13f35f78a14e232c`: 55 successful checks and 2 expected skips. Greptile: 5/5, no actionable findings. - `pnpm --filter @paperclipai/server exec tsx ../scripts/benchmark-workspace-record-reads.ts`: identical stored fields, 60 to zero Git commands, 689 ms to 8 ms for 20 reads. ## Risks - Execution callers must use saved fields only. Detail readers and live branch and cleanup guards remain separate. - A failed ancestry comparison stays unknown. Automatic cleanup still rejects unknown delivery state and rechecks Git before deletion. - This patch has not been deployed. It does not prove the full slow-run latency is resolved. ## Model Used OpenAI Codex, GPT-6. The exact model identifier and context window are not exposed in this session. Used reasoning, repository inspection, code editing, and local command 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 - [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>	2026-10-14 12:53:41 -05:00
Devin FoleyandPaperclip	5b29b9062e	fix(server): compact finished task worktrees and shorten the reaper cooldown (#16304) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Each task can run in its own isolated Git worktree, and each worktree installs its own dependencies > - The terminal-workspace reaper removes a worktree only when the task tree is finished, the delivery is merged, the files are clean, and a 7-day cooldown has passed > - A recurring task that runs every hour keeps a week of worktrees, and each worktree holds gigabytes of `node_modules`. A finished task with no merged pull request, or with leftover agent files, keeps its worktree forever > - On a busy instance this fills the disk in days, and a larger volume only delays the next failure > - This pull request adds compaction: one hour after a task tree finishes, the reaper removes regenerable directories from the worktree and keeps the workspace, the branch, and all source changes > - The benefit is that finished tasks stop holding gigabytes of disk, and no work is lost because a resumed task regenerates the files when its workspace is provisioned again ## Linked Issues or Issue Description Refs #2022 (retention for workspace cleanup). Related: #11936 and #14608 add external reclaim scripts (a scheduled tool and a disk-guard step). This pull request does the reclaim inside the server's terminal-workspace reaper instead. That way it uses the reaper's lifecycle lock, issue-tree checks, and live-run checks, and needs no extra scheduler. **What existing behavior does this improve?** Disk retention of execution workspaces after their tasks finish. **Current behavior** A finished task keeps its full worktree, including installed dependencies and build output, for at least 7 days. If the delivery is not merged, or the worktree has uncommitted or untracked files, the reaper never removes it. On one instance, an hourly recurring task created about 22 worktrees per day at about 3 GB each (about 2.8 GB of that was `node_modules`). Together with finished tasks that had no merged pull request, they filled a 100 GB volume in about two days. **Proposed behavior** One hour after a task tree becomes terminal, the reaper removes regenerable directories (installed dependencies, build output, tool caches) from the worktree. It keeps the worktree, the branch, the commits, and every tracked, untracked, or other ignored file. When the task resumes, the existing reuse path runs the provision step, which reinstalls the dependencies. Clean, merged worktrees are archived after 1 day instead of 7. **Reason and benefit** Most of a finished worktree's size is regenerable. Compaction removes that part without the risk of deleting work, so it can apply to workspaces that the reaper must keep (no merged pull request, leftover files). The shorter cooldown limits the cost of the source checkouts that stay. **Breaking changes** None. The default archive cooldown changes from 7 days to 1 day. `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS` still overrides it. `PAPERCLIP_WORKSPACE_COMPACTION_ENABLED=false` turns compaction off. ## What Changed - New `server/src/services/workspace-compaction.ts`: - Finds directories with a regenerable name (`node_modules`, `dist`, `build`, `coverage`, `storybook-static`, `target`, `.cache`, `.next`, `.nuxt`, `.parcel-cache`, `.svelte-kit`, `.turbo`, `.vite`). - Keeps only the directories that the repository's own `.gitignore` files ignore and that hold no tracked file. A negated pattern (`!build/`), a global excludes file, and `.git/info/exclude` do not count. Each candidate is checked per path, so dependencies below an ignored parent (`vendor/tool/node_modules`) are found. - Searches inside a regenerable-named directory that does not qualify (for example a tracked `build/`), so its ignored dependencies still go. - Never enters `.git` or `.paperclip` (the worktree instance data), and never follows a symlink. - Each Git read has a 60-second deadline and stops when the sweep is aborted. - Moves the directories into `.paperclip-compaction-trash` beside the worktree with a same-filesystem rename, and can restore them. - `sweepTerminalWorkspaces` compacts each terminal workspace once per terminal cycle, after the compaction delay and before the archive cooldown check: - Only isolated linked Git worktrees qualify. A shared workspace, a project's main checkout, or a row whose `.git` is a directory is never compacted. - The move runs inside a transaction that holds the workspace lifecycle lock. The guard checks a fresh row and the same lifecycle generation. It also checks that the issue tree is terminal, that no queued or running run works on the tree or the workspace (by checkout or execution run, or by run context), and that no runtime service runs from the workspace. - The guard runs before the move and again after it. If the second check fails (for example, the task reopened or a run started), the directories move back. Otherwise the trash is deleted. - The worker wakes at the compaction deadline, not only at the archive deadline. - Stale trash from an interrupted compaction or a failed delete is purged by later sweeps. The sweep checks each worktree parent at most every 30 minutes, whether or not anything is left to compact. - New counters `compacted` and `compactionFailed` in the sweep result. The activity log gets an `execution_workspace.regenerable_files_removed` entry with the removed paths. - Config: new `PAPERCLIP_WORKSPACE_COMPACTION_DELAY_HOURS` (default `1`) and `PAPERCLIP_WORKSPACE_COMPACTION_ENABLED`. The default for `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS` changes from `7` to `1`. Both new keys are added to the run-failure diagnostics allowlists. - Docs: `doc/DEVELOPING.md` documents the new variables and has a new "Terminal workspace compaction" section. `doc/SPEC-implementation.md` describes compaction. - `execution-workspaces.ts` was already above 1,000 lines. The file-system logic is in the new module. Only the guarded orchestration, which uses the existing lifecycle lock and run predicates, is in the service. ## Verification - `pnpm exec vitest run src/__tests__/workspace-compaction.test.ts src/__tests__/execution-workspace-compaction.test.ts` (in `server/`): 27 passed. `workspace-reaper-cooldown-config.test.ts`: passed. - Unit tests: directory selection (ignored, untracked, regenerable name only, `.env` and local data kept, tracked `coverage` kept, `.paperclip` skipped, symlinks not followed), nested candidates under a source `build/` and under an ignored `vendor/`, a negated `!build/` kept, global and `info/exclude` rules ignored, glob characters in names, abort, main checkout vs linked worktree, move and restore, restore that keeps a recreated directory, and stale-trash purge. - Embedded Postgres tests: - A no-PR, unmerged, dirty workspace is compacted. HEAD, the branch ref, `git status --porcelain --untracked-files=all`, untracked notes, `.env`, local data, and `.paperclip` data stay the same, and the row stays active. - A delivered workspace inside the cooldown is compacted. - The delay is respected, and the worker wakes at the delay. - An active checkout run, a queued run found through its context, an unfinished child issue, and a running runtime service all block compaction. - The task reopens during the move: the files are restored and unchanged. - A run starts during the move: the files are restored. - A shared workspace and a main checkout are never compacted. - Compaction runs once per terminal cycle and again after a later cycle. - Disabled compaction does nothing. - End to end: `realizeExecutionWorkspace` creates a worktree, the sweep compacts it, and a second `realizeExecutionWorkspace` reuses the same worktree. The provision command regenerates `node_modules`, and the untracked notes and the unmerged commit are still present. - Leftover trash is purged when the workspace has nothing left to compact. - Mutation checks: when the post-move guard is disabled, both race tests fail. Without the negation fix or the repository-only source fix, their tests fail. - `pnpm exec vitest run` for `execution-workspaces-service.test.ts`, `terminal-workspace-work.test.ts`, `execution-workspace-reopen.test.ts`, `server-startup-feedback-export.test.ts`, and `workspace-runtime.test.ts`: 335 passed. Two `workspace-runtime.test.ts` cases fail locally with and without this change (`does not diagnose a missing remote branch as a rejected credential`, `rejects explicit main on a master-only remote ...`). They also fail on unmodified `master` on the same machine, so the cause is the local Git environment. - `pnpm typecheck` in `server/`: passed. `pnpm check:module-boundaries`: passed. ## Risks - A repository can keep something that is not regenerable in an ignored `dist`, `build`, `target`, or `.cache` directory. Compaction removes it. The fixed name list, the ignore check, and the tracked-file check limit this. `PAPERCLIP_WORKSPACE_COMPACTION_ENABLED=false` turns compaction off. - A repository without a provision command does not get dependencies back automatically. This is the same state as a new worktree for that repository, where the agent already installs them. - A resumed task pays for a dependency install again. This happens only for tasks that finished more than an hour earlier. - The shorter default cooldown removes clean, merged worktrees after 1 day instead of 7. An operator who wants the old hold can set `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS=7`. - Self-hosted instances get the same behavior. There is no schema change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), 1M context, through Claude Code with tool use (shell, file edits, test runs). A separate Claude agent read the reaper code during the diagnosis. ## 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 - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-10-14 09:49:04 -07:00
DottaandPaperclip	74ba530b9e	fix(workspaces): keep cleanup Git scans fresh and dedupe page reads (#16302) ... ## Thinking Path > - Paperclip manages execution workspaces for agent tasks. > - It must preserve work when it closes a workspace. > - The terminal-workspace worker checks Git before it decides whether a workspace can close. > - A request for fresh Git status could join a scan that started before a file changed. > - Several records for one directory can also repeat the same Git work in a bounded page. > - The worker already reads the task tree before Git, then reads it again for delivery assessment. > - This pull request fixes the fresh-read boundary and removes those repeated reads. ## Linked Issues or Issue Description - Refs #14759 and #14423 for the background Git scan load. - Refs #16282 for the merged event-driven terminal-workspace worker. - Refs #13619 for the original community investigation and tests. Thanks to @fayonation for identifying the shared-directory and in-flight scan cases. This implementation starts from current master and adapts those ideas to the new worker. ## What Changed - Give correctness-sensitive Git status requests their own scheduler scan. They skip completed cache entries and older scans in progress. - Share compatible Git readiness results across workspace records in one bounded worker page. The key includes company, path, branch, base ref, and runtime ownership. Each record keeps its own task and delivery assessment. - Reuse the task tree already read by the worker during delivery assessment. - Add regression tests for a file created during an older scan, compatible scan sharing, and company and branch separation. Update developer and workspace map documentation. ## Verification - `pnpm exec vitest run server/src/services/workspace-git-operation-scheduler.test.ts server/src/__tests__/execution-workspaces-service.test.ts` — 92 tests passed. - `pnpm -r typecheck` — passed with the repository's pnpm 9.15.4. - `node scripts/check-maps.mjs` — passed. - `pnpm build` — passed. - The full local `pnpm test:run` was interrupted when its original worktree disappeared. All PR test shards passed in GitHub CI. - Latest commit `e7622127c7d978a9a90857112675834725965d72`: 53 successful PR checks, 2 expected skips, and no failures. Greptile reviewed this commit at 5/5 with no open findings. ## Risks - A shared page inspection can become stale if the directory changes before the next record is assessed. The final cleanup still starts a separate Git scan and checks current task, ownership, and lifecycle state under the existing guards. - The new scan key changes request coalescing for correctness-sensitive callers. They still use the scheduler's concurrency and queue limits. There is no database migration or API change. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI GPT-6 through Codex, with reasoning, code editing, and shell tools. The exact serving model ID and context window are not exposed in this session. ## 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>	2026-10-14 10:36:41 -05:00
DottaandPaperclip	7c016c049b	perf(workspaces): wake terminal cleanup from committed changes (#16282) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents use execution workspaces to retain their files and Git branches. > - A reaper closes eligible workspaces after their task tree is terminal. > - The reaper scanned every heartbeat tick and read Git before cheap eligibility checks. > - Permanent scans also query idle databases when no cleanup work exists. > - This pull request wakes cleanup after transaction settlement and restores bounded work at startup. > - The benefit is fewer scans while fresh cleanup guards continue to protect retained work. ## Linked Issues or Issue Description Related work: Refs #13619, Refs #11753. Those PRs bound scans or back off unchanged candidates. This PR uses the transaction work coordinator to remove the permanent reaper tick. It overlaps their early terminal-state filtering but does not change their runtime restart behavior or introduce a second Git scheduler cache. **What existing behavior does this improve?** Terminal workspace cleanup and Git inspection for workspace detail reads. **Subsystem affected** Server orchestration, execution workspaces, and idle sleep admission. **Current behavior** The heartbeat tick scans workspace candidates every thirty seconds. It runs Git before rejecting nonterminal trees, cooldowns, and active runs. Display inspections expire after five seconds. **Proposed behavior** Recover workspace rows in bounded startup pages. Wake after relevant issue, workspace, and pull-request work-product transactions settle. Schedule the terminal tree cooldown or a five-minute eligibility retry. Back off unchanged candidates across unrelated wakes, and invalidate their backoff after relevant committed changes. Park empty and nonterminal-only lanes. Reuse display inspections for thirty seconds. Read fresh Git before destructive cleanup. **Reason and benefit** Avoid recurring database and Git work when no cleanup is possible. Retain transaction admission holds, restart recovery, and fresh deletion checks. Retention eligibility can wait for the next host wake; active and failed recovery work still blocks sleep. **Breaking changes** No schema or API shape changes. Display Git state can lag by thirty seconds. Cleanup eligibility retries can take five minutes. ## What Changed - Add a terminal-workspace worker to the existing transaction work coordinator and scheduler. - Signal relevant writes before mutation on the owning transaction. Outer transaction settlement wakes cleanup. - Derive cooldown deadlines from the full company-scoped terminal task tree. Continue bounded recovery pages without a permanent sweep. - Bound unchanged candidate inspections to five minutes, retain at most 256 entries, and invalidate affected entries with scoped transaction hints. Repeated wakes preserve the earliest inspection deadline. - Collect deadlines from task trees already read by bounded pages. Restore the cursor after a failed page and rescan commits received during a rotation. - Check terminal state, cooldown, and active runs before Git. Preserve lifecycle locks, generation fences, and fresh final checks. - Keep failed or incomplete recovery visible to idle admission. Preserve the passive retention exception. - Extend the bounded display cache to thirty seconds and document the scheduling and wake limits. ## Verification - Focused workspace, coordinator, cache, and local sleep suites: 111 tests passed with real local PostgreSQL and Git worktrees where applicable. - Final worker, display cache, and local sleep suites: 28 tests passed. - The regressions prove three ineligible workspaces invoke zero Git scans, cached clean display state cannot remove new untracked files, and real producer notifications wait for outer transaction settlement. - `pnpm -r typecheck` and `pnpm build` passed locally. Map and module-boundary checks passed. - Work-product and sleep-safety suites: 221 tests passed. Reopen and issue-tree control suites: 46 tests passed. Final backoff, workspace, worker, and work-product suites: 87 tests passed. - Final workspace and worker suites: 81 tests passed. Deadline selection performs zero database reads. A failed full page retries its unread terminal workspace before recovery can park. - Full CI coverage passed on head `2c397970f7`: general tests, serialized server suites, runner verification, E2E shards, typecheck, build, and the final verification gate. The duplicate serial local `pnpm test:run` was stopped after full CI coverage passed; it is not reported as a completed local pass. - Greptile: 5/5 with both findings resolved. The security scan also passed. No failing or pending PR checks remain. ## Risks - Display state can be stale for thirty seconds. Destructive guards bypass the display cache. - Undelivered or otherwise ineligible terminal work retries after five minutes instead of each heartbeat tick. - Transaction signals cover the owning `createDb` scope. Direct SQL and independent server processes require startup recovery. - Local cooldown timers are maintenance hints. They do not establish an external wake alarm or whole-instance sleep safety. Existing blockers remain in force; failed bounded recovery keeps the host awake. ## Model Used OpenAI GPT-6, model ID `gpt-6`, through Codex. Reasoning, repository inspection, shell execution, and browser tools assisted the change. The runtime does not expose the 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>	2026-10-14 08:28:45 -05:00
Devin FoleyandPaperclip	c7f4b74111	fix: isolate fresh task sources from restricted project workspaces (#16095) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Each task must have an isolated workspace that its agent can read. > - Older project checkouts can contain worktrees for restricted tasks. > - The source access check correctly rejects these shared checkouts. > - A fresh task then fails even when its agent can clone the project remote. > - This pull request gives fresh default tasks a separate clone of the same remote. > - The task can start while the restricted task files remain protected. ## Linked Issues or Issue Description **What happened?** Fresh tasks fail with `Task workspace access is no longer available` when their default project checkout contains a restricted task worktree. The caller has access to the new task and its remote repository. The shared local Git source is unsafe to copy. **Expected behavior** Use a separate clone of the same authorized remote for a fresh default task. Keep source access checks and responsible-user Git credentials in force. **Steps to reproduce** 1. Put a restricted task worktree inside a project checkout. 2. Assign a new default task to an agent that cannot read the restricted task. 3. Start the new task. The current source check fails before workspace creation. 4. With this fix, the task uses a separate remote source. The restricted files are absent. Later runs reuse the same owned source. Related work: Refs #15749, Refs #15528. This change keeps their source retention and workspace ownership checks. ## What Changed - Add a remote source path scoped to the company and task. - Clone through the run’s Git connection after the shared source fails its access check. - Reject reused workspaces, explicit selections, pinned branches, local sources, credential-bearing URLs, and symlink paths. - Check source access again before publishing the workspace. - Resolve later runs from the verified recorded source. Ignore leftover clones that the saved workspace does not own. - Record provenance for new implicit Git defaults. Read the current task binding before fallback. Preserve explicit, inherited and ambiguous legacy checkout choices. - Keep the effective task strategy during startup validation of matching implicit defaults. Preserve the existing explicit-selection write check. - Add regression coverage and document the fallback. ## Verification - Merged master `c8efdbfba43` and resolved both rounds of catalog/index conflicts. All upstream suites, classifications, source references and story IDs are preserved. Both fix branches combine cleanly in either merge order, with no catalog fingerprint drift. - Passed locally: 313 focused source-isolation, preparation, task-creation, binding and trust tests before the final startup fix. The final fix passes all 100 source-trust, task-binding and environment-selection tests. Earlier workspace-resolution and persisted-source suites also passed. - Real-Git regressions cover all three review findings. Reconstruction ignores an unrecorded clone and preserves unpublished commits/files. Explicit and parent-inherited checkout IDs without typed selections retain their denial and branch tips without cloning or acquiring an environment. A protected-project heartbeat completes and resumes using the task’s Git strategy with read access. Explicit selection still requires writes, and a mismatched default is rejected. - Passed: the complete Storybook catalog check with no drift errors, feature and agent map structure checks, and all 17 catalog/index script tests. The generated index counts match the merged catalog. The current upstream verification-route inventory remains unchanged. The catalog contains all 262 authored suites and 2,481 story IDs. - Passed: full workspace typecheck and build after the final guard changes, on latest head `79d2adadcb6d3d7a04b9943a91bdb8b0b6abea6d`. - Latest head `79d2adadcb6d3d7a04b9943a91bdb8b0b6abea6d`: complete CI passed (54 successful checks, two intentional skips), including the full general/serialized suites and all eight browser shards. Fresh Greptile Apex review is 5/5 on this same commit, with no unresolved findings or recommendations. The full local test command was attempted earlier without a complete aggregate result; the complete suite result is from CI. - Manual check: configure a shared project checkout with a restricted task worktree. Admit a fresh default task using the authorized remote. Confirm separate Git storage and no restricted local branch or file. Reuse, close and reopen the task workspace. Confirm that explicit, literal branch and low-trust selections retain the denied source. ## Risks - A clean remote clone excludes unpublished local work. The fallback applies only to fresh default tasks and rejects existing workspace or branch selections. - A private remote can fail to clone when the responsible user lacks Git credentials. The run then reports the failure; access checks are not bypassed. - Older untyped checkout bindings cannot prove default provenance. They keep the source denial instead of silently dropping unpublished work. - New implicit Git defaults use the existing workspace-intent contract. The source directory uses existing instance storage. No schema migration is required. ## Model Used OpenAI GPT-6, model ID `gpt-6`, through Codex. Used reasoning, repository inspection, code editing, terminal tools, and test execution. The API session does not expose an exact 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>	2026-10-13 12:31:40 -07:00
DottaandPaperclip	f329b24ee1	feat: give tasks durable project-optional workspaces (#15749) ... Give tasks durable company-scoped workspace bindings independent of project assignment, channel defaults and authorized repository preparation. Reuse verified input seeds and sparse output recovery while preserving trust, privacy and controller provisioning boundaries. Full CI and E2E, Superagent, legacy checks and Greptile Apex 5/5 passed on reviewed head 753680b61c. All review findings are resolved; the PR records focused verification and historical acceptance limits. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-10-12 20:45:18 -05:00
DottaandPaperclip	3a726e676f	feat: enforce private task permissions across execution and data (#10633) ... Enforce private task and project access across direct reads, search, execution, files, plugins, live delivery, and sharing mutations. Preserve downward-only sharing, current responsible-user authorization, and audited emergency access. Bind historical draft assets with migration 0314. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-10-07 07:06:40 -05:00
Devin FoleyandPaperclip	e9debd3eac	fix(workspaces): allow larger status output for readiness checks (#14414) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The server checks workspace contents before it allows cleanup or branch reconciliation. > - These checks need the full Git status output to count untracked files. > - Nested task worktrees can make this output exceed the scheduler's default 1 MiB limit. > - A scan failure then blocks an otherwise inspectable workspace. > - This pull request raises the limit for these status checks to 32 MiB. > - The checks retain exact counts and still protect uncommitted work from cleanup. ## Linked Issues or Issue Description Refs #14194 and #14253. Those changes address snapshot enumeration. This PR addresses buffered execution-workspace status checks. Refs #13619 for separate work on caching these checks. The related journal identity failure is covered by #14312. **What happened?** Close-readiness checks failed when Git status output exceeded 1 MiB. A workspace with thousands of long untracked paths could not report its file count or complete readiness inspection. **Expected behavior** Allow up to 32 MiB of status output for execution-workspace readiness and branch reconciliation. Preserve exact counts. Continue to block cleanup when the workspace has uncommitted data or the scan exceeds its bound. **Steps to reproduce** 1. Create an execution workspace with a merged delivery. 2. Add 5,000 long untracked filenames under a nested task directory. The status output exceeds 1 MiB. 3. Request close readiness. Before this fix the status scan fails. After this fix it reports all 5,000 files. 4. Run the terminal-workspace sweep. Confirm that it preserves the workspace and files. **Paperclip version or commit** Reproduced on master at `14795136f5` before this fix. **Deployment mode** Server with managed Git workspaces. ## What Changed - Set a 32 MiB stdout bound for execution-workspace status scans. - Add a real Git regression with 5,000 long untracked paths and a cleanup-preservation assertion. Assert that the measured status output exceeds 1 MiB. - Document the bound and failure behavior. ## Verification - The new regression failed on master before the service change: the status result had no untracked files or count after the scan exceeded its bound. - `pnpm exec vitest run server/src/__tests__/execution-workspaces-service.test.ts server/src/services/workspace-git-operation-scheduler.test.ts` passed: 82 tests, including the new regression. The regression and server typecheck also passed after the explicit byte-count assertion. - `pnpm build` and `pnpm -r typecheck` passed. The full local `pnpm test:run` was attempted and stopped after the failures listed below. Greptile is 5/5 with zero unresolved review threads on the latest head. All checks for head `45f93ad5ad` passed (53 successful, two intentional skips). - Full local validation did not pass. The attempt reproduced 13 company/runtime skill-cache permission failures, the terminal-workspace cleanup assertion, and a heartbeat feedback timeout. It was stopped during the general-server stage after these failures. Remaining general-server tests, other workspace groups, and serialized-server stages did not complete locally. Earlier clean-master checks reproduced the cache failures and isolated cleanup retries passed. The latest-head GitHub suite passed all of these groups. - One GitHub browser shard initially failed because its GitHub-connection test checked the resume-action array before the mocked request completed. The single failed-job retry passed without a source change. All latest-head checks are green. - No browser suites ran locally. This change does not affect browser behavior. ## Risks - Each active status scan can buffer up to 32 MiB before parsing. The existing scheduler bounds scan concurrency and queue size. - Output above the bound still fails the scan and blocks destructive cleanup. The change does not truncate output or change cleanup rules. - There are no API, database, or snapshot-streaming changes. ## Model Used OpenAI Codex, GPT-6, with repository inspection, code editing, and test execution. The exact deployment model ID and context window are not exposed in this session. ## 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 (focused suites; full local-run failures and incomplete stages are documented above) - [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>	2026-09-28 09:59:56 -07:00
DottaandPaperclip	a05b828bcd	Reduce run polling and workspace inspection amplification (#13174) ... ## Thinking Path > - Paperclip manages agent work and shows run progress to operators. > - Run lists, live events, transcripts, and workspace details must remain responsive as usage grows. > - Run-list redaction rereads the full context for every run. Hidden tabs can still trigger requests through live events and manual timers. > - Workspace detail reads repeat Git inspection even when concurrent callers request the same state. > - This pull request batches registry reads, pauses hidden-tab refreshes, and caches Git inspection for display. > - Cleanup keeps fresh Git checks, and redaction keeps company and run boundaries. ## Linked Issues **What happened?** Run-list responses perform one extra database read per run and parse full context JSON to obtain small secret registries. Hidden tabs continue transcript reads and event-triggered refetches. Workspace detail requests repeat Git scans. **Expected behavior** A run list reads registries once. Hidden tabs stop recurring run reads and reconcile when visible. Concurrent workspace detail reads share a short-lived Git result. **Steps to reproduce** 1. Open run lists and task transcripts in several tabs while agents run. 2. Hide some tabs and observe transcript and event-triggered requests. 3. Request a 200-run list and count redaction database queries. 4. Request the same workspace detail concurrently and count Git inspections. Related: #5255 adjusts polling cadence. This change addresses hidden-tab lifecycle, batched registry reads, and workspace inspection reuse. No duplicate with this scope was found. ## What Changed - Batch heartbeat and live-run redaction into one company-scoped registry query. Select only registry JSON for run and issue redaction. - Resolve duplicate secret values once per request. Preserve each run's registry and remove registry material from responses. - Suspend company event sockets and transcript reads while hidden. Refresh active queries and resume transcript offsets on return. - Prevent queued event invalidations and developer health polling from fetching in hidden tabs. Gate legacy run-log readers in both UI variants. - Exclude legacy plugin placeholder connections from remote health probes. Select only due connection IDs in SQL before the sweep limit. Preserve existing plugin records. - Cache concurrent Git display inspections for five seconds, with at most 256 entries. Leave close-readiness and cleanup checks uncached. - Add regression coverage and document the performance behavior. - Stabilize the existing Rust descendant-lineage fixture: allow a bounded 30 seconds for 300 durable notifications under concurrent test load, retaining every correctness assertion and adding timeout diagnostics. ## Verification - Regression coverage verifies one registry query for 200 runs, per-run isolation, request-local secret resolution, decryption failures, Git cache expiry/bounds, hidden-tab pause, and visibility recovery. - Real PostgreSQL redaction/run-route suites passed all 57 tests; workspace-service coverage passed. The health-sweep regression verifies plugin placeholders and chat connections remain untouched and do not consume the sweep limit. - Both legacy transcript viewers retain history and resume their byte offset after visibility changes. The related visibility/progress/chunk suites passed all 29 tests. Other focused UI suites and token gates passed. - Full `pnpm -r typecheck` and `pnpm build` passed. Affected-package typechecks/builds passed after review fixes. The concurrent Rust provider suite passed 84 tests (two ignored), and Rust formatting passed. - Full local `pnpm test:run` stopped after the general-server group: 10,538 passed, 65 skipped, four failed. Fresh chat-delivery and health-sweep reruns passed; building the debug runner fixture cleared the native-event test. One unchanged native-session recovery assertion still fails locally with a semantic-digest error instead of the expected settled-session message. The full local command is therefore not green. CI runs the later groups separately and skips the two native-session tests requiring a prebuilt runner binary (confirmed in its 37-test native-session suite). - All CI gates pass on final head `ee610e737`: typechecking, general and serialized tests, browser tests, runner verification, build, and canary dry run. One server shard passed on its single retry after exposure fixtures encountered port 42001 where they assumed 42000; that suite also passed locally (25 passed, three platform-specific skips). - Greptile reviewed the final head at 5/5 with no actionable findings. ## Risks - Workspace delivery display can lag local Git changes by five seconds. Destructive operations still inspect current state. - Hidden tabs do not receive company live-event notifications until visible. Active queries refresh on return. - This change preserves legacy plugin records and does not repair instance-specific workspace rows. There is no database migration. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, repository tools, code execution, and browser inspection. The exact model identifier and context-window size are not exposed in this session. ## 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 (targeted regressions; full-suite limitation documented above) - [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>	2026-09-11 08:34:24 -05:00
DottaandPaperclip	b51112798f	feat(apps): improve gateway and workspace connection UX (#12340) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - App connections must work in both the operator UI and agent tool gateway. > - The first stack layer adds secure remote connections. > - Operators still need clear setup, test, and recovery states. > - This pull request adds the gateway behavior and the workspace connection experience. > - The benefit is a connection flow that is easier to understand and recover. ## Linked Issues or Issue Description Refs #11965 This is stack 2 of 11. It depends on stack 1 and replaces another reviewable part of #11965. ## What Changed - Improve remote tool gateway connection behavior. - Add clearer app setup, test, and recovery states. - Add focused server and UI tests for the new paths. - Keep the diff isolated from later identity and catalog work. - Stabilize DNS-pinned remote HTTP protocol fixtures and the managed-runtime public-origin fixture for this independently tested layer. ## Verification - `pnpm -r typecheck` - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/tool-access-service.test.ts` (150 passed) - `pnpm test:run` - `pnpm check:token-gates` - `pnpm build` ## Risks - Gateway errors now surface through new user-facing states. - A stale connection can require a new setup attempt. - The change does not add a database migration. - The injected HTTP transport and public URL are test-only fixtures; production DNS pinning and runtime behavior are unchanged. > I checked `ROADMAP.md`. This stack continues the existing app connection work from #11965 and does not duplicate another planned item. ## Model Used OpenAI Codex, GPT-5. The runtime model ID and context window were not exposed. The model used reasoning, tool use, and code 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 - [x] My branch name describes the change 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>	2026-08-29 12:08:32 -05:00
3 people	417336f8be	fix(workspaces): attach PR preparation to existing branches (#11703) ... <!-- Write all pull request text in Simplified Technical English (ASD-STE100): short sentences, one instruction per sentence, simple approved vocabulary, and the active voice. --> ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Execution workspaces isolate an agent task from the primary checkout. > - Pull request preparation can need a branch that already contains completed work. > - The workspace policy could not require an exact existing branch. > - Workspace cleanup also treated worktree creation as branch ownership. > - This pull request adds an exact existing-branch policy and separate branch ownership metadata. > - The benefit is safe pull request preparation that preserves every existing commit and operator-owned branch. ## Linked Issues or Issue Description **What happened?** A pull request preparation run could not pin its execution workspace to an exact existing branch. Workspace reuse and cleanup could also confuse worktree creation with branch ownership. **Expected behavior** The run must attach only to the requested branch in an isolated Git worktree. It must fail if the branch is missing, busy, or inconsistent. Cleanup must not delete a branch that Paperclip does not own. **Steps to reproduce** 1. Create a branch that contains completed work. 2. Configure a pull request preparation task to use that branch. 3. Start the task and observe that the prior policy cannot require the exact branch. **Paperclip version or commit** This behavior reproduces on the base revision before this pull request. **Deployment mode** Local development with isolated Git worktrees. ## What Changed - Add `existingBranch` to the execution workspace policy and shared validation contracts. - Require `existingBranch` to use an isolated Git worktree and reject conflicting branch templates. - Attach to the exact branch without creating, renaming, resetting, or deleting it. - Track branch ownership separately from worktree creation and use that ownership during cleanup. - Return HTTP 422 for invalid existing-branch settings on every issue-producing route. - Add a bounded repair script for existing pull request preparation tasks. - Add focused policy, route, heartbeat, runtime, and ready-comment tests. - Document the exact-branch behavior and safety rules. ## Verification - `pnpm exec vitest run server/src/__tests__/execution-workspace-policy.test.ts server/src/__tests__/heartbeat-workspace-session.test.ts server/src/__tests__/issue-existing-branch-validation-status.test.ts server/src/__tests__/workspace-runtime.test.ts server/src/services/workspace-runtime-exposure.test.ts server/src/services/workspace-runtime-ready-comment.test.ts` passed 335 tests. - `pnpm -r typecheck` passed for all workspace projects. - `pnpm test:run` passed 4,431 tests. Two unrelated embedded-Postgres setup hooks timed out under aggregate load. Their isolated rerun passed 74 tests. - `pnpm build` passed for all workspace projects. - The two review regressions passed with 139 unrelated tests skipped. - All latest-head CI gates passed after one unrelated timing-sensitive test passed on rerun. - Greptile scored the latest head 5/5 with no unresolved review threads. ## Risks - Invalid workspace settings now return HTTP 422 instead of a generic validation response. - The exact branch must already exist and must not be checked out by another worktree. - The new policy fails closed when it cannot prove branch identity or ownership. - This change has no database migration. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex from the GPT-5 family assisted with this change. The runtime did not expose its exact deployment ID or context window. The agent used high-reasoning mode, repository tools, shell execution, and code 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 - [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: Claude Fable 5 <noreply@anthropic.com>	2026-08-21 17:23:18 -05:00
DottaandPaperclip	1b4de0b65c	fix(workspaces): recover degraded runtime databases (#11651) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Managed workspaces run local web services and embedded PostgreSQL databases > - A listening process could return an unhealthy response and still be reused > - Embedded PostgreSQL failures had no bounded restart owner > - Cleanup inferred ownership from a branch slug instead of exact persisted instance data > - This pull request validates runtime health, supervises database recovery, and uses exact cleanup ownership > - The benefit is reliable replacement of degraded services without deleting active instances ## Linked Issues or Issue Description **What happened?** Workspace reconciliation could reuse a degraded Paperclip process after any successful HTTP response. Embedded PostgreSQL could stop without bounded recovery. Cleanup could infer database ownership from a branch slug and select the wrong instance. **Expected behavior** Paperclip must require a semantic healthy response from the assigned loopback listener. It must replace degraded processes. It must supervise embedded PostgreSQL with bounded restarts. Cleanup must use exact persisted worktree and instance-root ownership. **Steps to reproduce** 1. Start a managed workspace runtime. 2. Make its health endpoint return HTTP 200 with an unhealthy status, or stop its embedded PostgreSQL process. 3. Reconcile the workspace or run instance cleanup. 4. Observe that the old implementation can reuse the degraded runtime or infer ownership from its branch slug. **Paperclip version or commit** Current `master` before this pull request. **Deployment mode** Local dev with managed workspace services. ## What Changed - Require `{ "status": "ok" }` from the assigned loopback health endpoint before runtime reuse or adoption. - Refresh persisted runtime health and replace degraded managed processes. - Add bounded embedded PostgreSQL restart supervision with coordinated shutdown and hot-restart support. - Stop the unhealthy web process when PostgreSQL recovery is exhausted so reconciliation can replace it. - Require exact persisted instance-root ownership before cleanup can reclaim an embedded database. - Add focused regression tests for degraded HTTP responses, ownership mismatches, bounded recovery, active instance preservation, and confirmed orphan reclamation. ## Verification - `pnpm --filter @paperclipai/server typecheck` - `pnpm --filter @paperclipai/server test -- src/embedded-postgres-supervisor.test.ts src/services/workspace-instance-cleanup.test.ts src/services/workspace-runtime.test.ts src/services/execution-workspaces-service.test.ts` - `pnpm -r typecheck` - `pnpm build` - `git diff --check` - The full local stable test runner also found host-owned listeners on ports 42000 and 52000. Those listeners conflict with the exposure test fixture. The focused changed suites pass, and CI runs on a clean host. ## Risks - A custom process that returns HTTP 2xx without the Paperclip health contract is now degraded by design. - Restart exhaustion terminates the managed web process. The runtime reconciler then starts a clean process. - Cleanup now fails closed when persisted ownership is missing. This can retain an ambiguous orphan for manual review. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI GPT-5 Codex. The exact serving revision and context-window size are not exposed. The model used agentic reasoning, repository tools, code execution, and 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) - [ ] 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-08-18 17:40:54 -05:00
3 people	fe803bedf1	feat(server): add a configurable cooldown to the terminal workspace reaper (#11642) ... ## Thinking Path > - Paperclip is an open source app that manages AI agents for work. > - The server manages execution workspaces and their worktrees. > - The terminal workspace reaper removes a workspace when its issue tree reaches a terminal state. > - Immediate removal prevents a person from reopening recently completed work. > - This pull request adds a configurable cooldown before the reaper archives the workspace. > - The cooldown keeps recent work available and keeps immediate cleanup available with value `0`. ## Linked Issues or Issue Description Refs: #7790 **Problem** The reaper archives an execution workspace and deletes its worktree as soon as the issue tree becomes terminal. A person cannot reopen recent work without extra effort. **Expected behavior** The reaper should keep a recently completed workspace during a configurable cooldown window. It should archive older work and support immediate cleanup when the value is `0`. **Proposed solution** Read the cooldown from `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS`. Use a seven-day default. Use the latest terminal timestamp in the source issue tree as the cooldown anchor. ## What Changed - Add `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS` with a seven-day default. - Treat `0` as no cooldown and use the default for negative or non-numeric values. - Use the latest `completedAt` or `cancelledAt` value in the source issue tree. - Use `updatedAt` when a terminal timestamp is null. - Skip candidates inside the cooldown and report them in `skippedCooldown`. - Recheck the cutoff during the guarded archive operation. - Document the environment variable and add focused tests. ## Verification - Run `npx vitest run server/src/__tests__/execution-workspaces-service.test.ts`. - Confirm that the test run passes 66 tests. - Confirm that the tests cover a recent tree, an old tree, value `0`, and a null terminal timestamp. - Confirm that the changed files pass `tsc --noEmit`. ## Risks The default changes terminal workspace cleanup from immediate removal to a seven-day delay. A value of `0` preserves immediate cleanup. The guarded archive check limits race risk during concurrent lifecycle changes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap. ## Model Used OpenAI Codex, GPT-5, tool use and code execution. This model assisted with the implementation review and PR preparation. ## 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: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>	2026-08-18 11:23:27 -07:00
DottaandPaperclip	8087661bb8	fix: bound workspace Git scans (#11572) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Workspaces let users and agents inspect files that belong to an issue > - Changed-file views use full-tree Git status scans > - Many issue views could start those scans at the same time and make the server unresponsive > - Route-level limits did not protect the process or coalesce work for one repository > - This pull request adds one bounded scheduler for every expensive workspace Git scan > - It also starts browser scans only when the file panel is open and visible > - The benefit is bounded child-process use and responsive health checks during request storms ## Linked Issues or Issue Description **What happened?** Many changed-file requests could start full `git status --porcelain=v1 -z --untracked-files=all` scans at the same time. One production incident produced about 270 direct Git child processes. The Node process stayed alive but stopped answering health requests in time. **Expected behavior** Paperclip must bound expensive Git work across all companies, actors, issues, repositories, and browser tabs. Duplicate requests for one worktree must share work. Excess requests must fail fast with a retryable response. Hidden or closed file panels must not start scans. **Steps to reproduce** 1. Open changed-file views for many issue and actor keys. 2. Send requests for two large workspace roots at the same time. 3. Observe that route-level limiter keys allow many full Git scans to run together. 4. Observe delayed health responses and accumulated Git children. **Paperclip version or commit** Reproduced on master before commit `43ab441f0f`. **Deployment mode** Self-hosted server with local workspace repositories. ## What Changed - Add a process-wide scheduler with configurable concurrency, queue capacity, timeout, and cache TTL. - Add fair admission, a bounded queue, canonical worktree keys, single-flight joins, and bounded result caching. - Add subprocess timeouts, TERM-to-KILL escalation, bounded output, waiter cancellation, and slot cleanup. - Route full-tree status work from file resources, workspace runtime, execution workspaces, and adapter overlay sync through the scheduler. - Return stable retryable `503` and `504` error codes for saturation and timeout. - Add structured logs with safe workspace hashes, durations, queue state, cache use, joins, and terminal outcomes. - Gate UI queries on panel and document visibility. Cancel queries on close, hide, unmount, and workspace change. - Disable focus and reconnect bursts. Keep one explicit refresh action and a retryable unavailable state. - Document the 10-second default freshness tradeoff and all configuration variables. - Add unit, route, UI, adapter, and deterministic 500-request load coverage. ## Verification - `pnpm -r typecheck` - `pnpm build` - `pnpm check:token-gates` - `pnpm --filter @paperclipai/server exec vitest run src/services/workspace-git-operation-scheduler.test.ts src/__tests__/file-resources-git-scan-load.test.ts --reporter=dot` — 16 tests passed. - `pnpm --filter @paperclipai/ui exec vitest run src/components/WorkspaceFileBrowser.test.tsx src/lib/page-visibility.test.ts --reporter=dot` — 38 tests passed. - `pnpm --filter @paperclipai/adapter-utils exec vitest run src/git-workspace-sync.test.ts --reporter=dot` — 16 tests passed. - Existing file-resource, workspace-runtime, and execution-workspace regression selections passed. - Two cleanup safety regressions prove failed scans preserve the worktree before archive and at the final deletion fence. - Before: the incident produced about 270 Git children and health requests timed out. - After: 500 concurrent requests across 500 issue keys, 73 actors, and two roots started two underlying scans. Peak scan concurrency was 2. All 500 requests succeeded. Health p99 was 4.94 ms. The harness found zero unreaped children. - The full local Vitest run passed 4,267 tests. Ten existing fixed-port HTTPS exposure tests could not run because this host already owns Tailnet listeners on ports 42000 and 52000. Clean GitHub CI is the final full-suite result. - Latest-head GitHub CI passed all required test, typecheck, build, canary, e2e, policy, and security gates. - Greptile completed at 5/5 with zero unresolved comments, recommendations, or follow-ups. ## Risks - Changed-file results can be up to 10 seconds old by default. Explicit refresh remains available. - A full queue returns a retryable `503` instead of waiting without a bound. - A scan that exceeds the default 8-second deadline returns a retryable `504` and terminates its process group. - Operators can tune all limits with documented environment variables. Safe defaults protect local and shared servers. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 family. The runtime does not expose the exact deployment ID or context-window size. High reasoning, tool use, and code execution were enabled. ## 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>	2026-08-17 22:11:30 -05:00
Dotta	4c349fe6b7	feat(runtime): managed Tailscale HTTPS lifecycle, durable runtime leases, and bounded control recovery (#11525) ... <!-- Simplified Technical English (ASD-STE100). --> > **Stacked pull request.** This targets #11524. Merge #11524 first. Review only the second commit, `feat(runtime): managed Tailscale HTTPS lifecycle...`. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Paperclip starts and supervises managed runtime services, so an agent's branch can be previewed while the agent works > - The previous pull request added the host broker, the shared contract, and the database columns, but no code used them > - A managed runtime can only be exposed over HTTPS if it holds a stable loopback port pair for the whole life of the service. The current control path cannot promise this: two controls can race the same execution workspace, a stranded control can stay `running` forever, and a start can adopt a port it does not own > - This pull request adds the HTTPS lifecycle and the control-path hardening that the lifecycle depends on > - The benefit is that a managed preview becomes reachable from another device, and a managed control now always reaches a terminal state ## Linked Issues or Issue Description No public GitHub issue exists. The change follows the feature request template. **Subsystem affected** Managed workspace runtime services, workspace operations, the execution workspace routes, and the workspace runtime UI. **Problem or motivation** A managed runtime service is reachable only on loopback, so a preview cannot be opened from a phone or a second computer. Exposing it safely needs an exclusively held port pair. Three existing gaps block that. Overlapping controls can race the same workspace. A control whose owner dies stays `running` and blocks the lane forever. Port allocation does not confirm that the process holding a port is the process Paperclip spawned. **Proposed solution** Add the exposure lifecycle on top of the broker from #11524: reserve before spawn, expose after readiness, validate the public URL, and remove on stop. In the same change, make managed controls mutually exclusive per workspace, give each control a durable issue-owned lease and a terminal state, and verify port ownership before use. **Alternatives considered** - Add HTTPS exposure without the control hardening. This was rejected because a raced or stranded control makes exposure point at the wrong process. - Guard the lane with an in-memory lock only. This was rejected because the lock does not survive a server restart, so the lane can be lost or double-claimed. - Trust the requested bind address. This was rejected because a checkout that predates managed HTTPS overwrites `PAPERCLIP_BIND` from its own `--bind` argument, and then binds the wildcard address. **Roadmap alignment** This completes the managed workspace runtime capability that already exists. It adds no new product surface beyond the HTTPS link. **Additional context** This is the second of three pull requests. The third adds central mediation of leased port pairs. ## What Changed Exposure lifecycle: - Add the server-side broker client and the exposure lifecycle manager. The manager reserves the mapping before spawn, exposes after backend readiness, validates the public URL, and removes the mapping on stop. - Default managed worktree runtimes to `tailscale_https`, read exposure intent from legacy `expose` blocks, and backfill runtimes that are still HTTP-only. - Verify listener ownership for the app port and its Vite HMR companion before the broker is asked to expose anything. An unrelated listener on either port fails the start closed. - Force the loopback bind through argv instead of environment hints. Leave a non-Paperclip service's `--bind` argument alone. - Probe loopback for readiness instead of the public URL, and give Vite HMR its own loopback-bound server in middleware mode. - Preserve operator-declared Serve mappings across the managed lifecycle, so cleanup never removes a mapping that Paperclip did not create. - Name which listener predicate denied an expose, so an operator can act on the message. Control-path hardening: - Make `start`, `stop`, `restart`, and job `run` mutually exclusive per execution workspace. An overlap gets `409 workspace_runtime_control_in_progress`, and authorization is still checked first. - Take a durable exclusivity lease on the execution workspace, owned by the controlling issue. A different issue gets `409 workspace_runtime_lease_conflict` before any operation is recorded. Board and operator actions bypass the lease. - Give every control a terminal state. Each control stamps its owning process and pid, heartbeats while it runs, and has a wall-clock ceiling. Recovery of a stranded control uses a compare-and-swap on `updated_at`, so a live owner is never stolen. - Bound readiness probes, verify allocated port ownership on POSIX and Windows, harden sibling port allocation, and reconcile desired runtimes on server startup. - Surface exposure state and bounded runtime errors in the workspace runtime UI. - Record the new behavior in `doc/DEVELOPING.md`. ## Verification Focused checks, all run on this branch: - `npx tsc --noEmit -p server/tsconfig.json` — 139 errors, exactly the count on `master`. All 139 come from the unbuilt `@paperclipai/plugin-sdk` package. - `pnpm --filter @paperclipai/ui typecheck` — clean. - Server suites, 177 tests pass across 9 files: `workspace-runtime.test.ts`, `workspace-runtime-leases.test.ts`, `workspace-runtime-control-recovery.test.ts`, `execution-workspace-runtime-control-conflict.test.ts`, `execution-workspace-runtime-lease-route.test.ts`, `workspace-operations-reconciliation.test.ts`, `workspace-runtime-start-terminality.test.ts`, `app-hmr-port.test.ts`, and `workspace-runtime-ready-comment.test.ts`. - Exposure unit suites, 77 tests pass: `src/services/runtime-exposure/` and `workspace-runtime-exposure-backfill.test.ts`. - UI: `WorkspaceRuntimeControls.test.tsx` and `WorkspaceServiceControlBar.test.tsx` — 34 tests pass. **One suite is red on the development host and is expected to be green in CI.** `server/src/services/workspace-runtime-exposure.test.ts` has 10 failures on the machine used to write this branch. The cause is host contamination, not the code. That machine already runs an HTTPS canary that holds ports 42000, 42001, 52000, and 52001 on a tailnet address. The suite allocates from the same range, so the new listener-ownership check correctly reports: ``` listener_ownership_mismatch — port 42000 is bound to 100.123.243.20, 127.0.0.1, fd7a:115c:a1e0:0:0:0:dd3a:f314 ... instead of loopback only ``` A CI runner has no listener on those ports, so the check sees loopback only and the suite passes. Please confirm this from the CI result on this pull request rather than from a local run on a host that already exposes a managed runtime. This is a real weakness of the current test fixture, and the third pull request in the series removes it by allocating the pair through a central mediator instead of a stubbed availability check. `workspace-runtime-https-live-exercise.test.ts` needs a live `tailscale` host and was not run locally. ## Risks - This is the behavior-bearing pull request of the three, so it carries the most risk. - Two new `409` responses appear on managed control routes. A caller that assumed a control always starts must handle a conflict. Board and operator actions are deliberately exempt, so an agent lease cannot lock an operator out. - Managed worktree runtimes now default to `tailscale_https`. If the host has no working broker, the start fails closed and reports the exposure failure instead of silently serving plain HTTP. This is intended, and it is the reason the failure message names the denying predicate. - Startup reconciliation touches persisted runtime rows. It is scoped to desired state and does not resurrect a service that never came up. - The lease has a 30-minute time to live and explicit release paths, so a crashed owner cannot hold a lane forever. - No migration runs in this pull request. The tables and columns land in #11524. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. ## Model Used Claude Opus 5 (`claude-opus-5`), 1M context window, extended thinking, with tool use and code 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, with the one host-contaminated suite explained above - [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	2026-08-17 06:23:33 -04:00
Nicky LeachandPaperclip	69027cbaae	fix(workspaces): reopen archived git worktree for managed_checkout projects (#11395) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Execution workspaces give agent tasks isolated Git worktrees > - Archived isolated workspaces must reopen against a live project checkout > - A managed_checkout project has no project workspace directory in its row > - The reopen path used the removed archived worktree as the Git working directory > - This pull request resolves the live managed checkout and reports a clear error when it is unavailable > - The benefit is reliable workspace reopen behavior after archive cleanup ## Linked Issues or Issue Description Related public pull request: [#6164](https://github.com/paperclipai/paperclip/pull/6164) clears archive state during un-archive. This pull request fixes the separate reopen failure that occurs after archive cleanup. **What happened?** An archived isolated `git_worktree` workspace under a `managed_checkout` project failed to reopen after cleanup. The route attempted to run Git in the removed archived worktree and returned a generic service error. **Expected behavior** The reopen path should use the live managed checkout as the Git base directory and should return a clear error when that directory is unavailable. **Steps to reproduce** 1. Create a project with `managed_checkout` source control. 2. Create and archive an isolated `git_worktree` execution workspace. 3. Let archive cleanup remove the worktree. 4. Reopen the workspace for an issue. **Paperclip version or commit** `cab0c31dc61310106caef42ca244e9f7b0f19460` **Deployment mode** Local dev with the default embedded database. **Agent adapter(s) involved** Not adapter-specific. This issue affects core workspace handling. ## What Changed - Resolve the live managed checkout when a managed project reopens an archived Git worktree. - Keep local-folder projects on their project workspace directory. - Validate the Git base directory before `git rev-parse` and return a scrubbed error. - Add nine regression tests for workspace reopen behavior. ## Verification - `server` TypeScript check passes with `tsc --noEmit`. - `server/src/__tests__/execution-workspace-reopen.test.ts` passes with 9 tests. - GitHub Actions must pass all required PR checks. ## Risks Low risk. The change affects only archived isolated workspace reopen behavior. It reuses the existing managed checkout and Git authentication helpers. It adds no new credential path, endpoint, or telemetry. ## Model Used OpenAI GPT-5 assisted with review and GitHub operations. The implementation author supplied the code and test results. ## 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>	2026-08-14 16:44:31 -07:00
Nicky LeachandPaperclip	d0d242e843	feat(server): reopen an archived isolated execution workspace in place (#11322) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Issue execution uses isolated workspaces that hold the issue worktree > - A terminal issue can leave its isolated workspace archived and unable to resume > - The existing closed-workspace guards returned a conflict and gave the user no self-serve recovery > - This pull request reopens the same isolated workspace row and rebuilds its worktree > - The benefit is that resume, checkout, and comment actions can continue without a new workspace row ## Linked Issues or Issue Description **Problem or motivation** A terminal issue can point to an archived isolated execution workspace. Resume, checkout, and comment actions then stop with a conflict. **What happened?** A terminal issue kept its issue-to-workspace link after the isolated workspace reached a closed status. The guarded actions returned HTTP 409 instead of restoring access. **Expected behavior** The next authorized resume, checkout, or comment action reopens the same isolated workspace row. The action rebuilds the worktree and then continues. **Steps to reproduce** 1. Create an issue that uses an isolated execution workspace. 2. Move the issue to a terminal state and let the workspace archive. 3. Try to resume the issue or add a comment. 4. Observe the closed-workspace conflict. **Paperclip version or commit** e6e79f458e **Deployment mode** Built from source with pnpm. **Proposed solution** Reopen the closed isolated workspace in place. Rebuild the worktree before the route reports success. **Alternatives considered** Create a new workspace row. This would require repointing the issue link and would not preserve access for issues that share the original row. **Roadmap alignment** ROADMAP.md has no matching reopen item. ## What Changed - Reopen closed isolated workspace rows in place and rebuild their worktrees. - Use the reopen path from resume, checkout, and comment guards. - Return a clear error when the rebuild fails and keep the workspace closed. - Fence terminal reaping and archive cleanup while a reopen is in flight. - Update the comment composer to allow the next action to reopen the workspace. - Add service and route tests for reopen, scope, failure, and lifecycle races. ## Verification - Server TypeScript check passes with the tsc --noEmit command. - UI TypeScript check passes with the tsc --noEmit command. - Seventy-two server tests pass across the affected test files. - The isolated worktree UI test suite has a dependency mismatch and fails before tests run with the error TypeError: act is not a function. - CI confirms the UI test job after a clean dependency install. ## Risks The reopen path changes behavior for closed isolated workspaces. A rebuild failure returns an error and keeps the row closed. Lifecycle locks and generation checks protect the worktree from stale cleanup. The UI test mismatch needs CI confirmation. ## Model Used OpenAI Codex, GPT-5, with tool use and code review assistance. The runtime did not provide the 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 references) - [x] My branch name describes the change 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>	2026-08-13 07:44:19 -07:00
Nicky LeachandPaperclip	f9bd0438e1	fix(server): stop terminal workspace reaper starving on oldest candidates (#11238) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The server runs a scheduled reaper that archives terminal workspaces after it checks their state. > - The reaper reads candidates in `updatedAt` order and skips candidates that do not qualify for archive. > - The fixed page kept the same skipped candidates at the front, so the reaper did not inspect later eligible workspaces. > - This pull request adds a keyset cursor and a throttled log for sweeps that archive no workspace. > - The benefit is that the reaper inspects all candidates over time and reports an inert sweep. ## Linked Issues or Issue Description **What happened?** The terminal workspace reaper inspected a fixed page of old candidates. Ineligible candidates stayed in that page, so the reaper skipped later eligible workspaces on every sweep. **Expected behavior** The reaper must inspect each candidate over time and archive every eligible terminal workspace. **Steps to reproduce** 1. Create more than 50 terminal workspace candidates. 2. Keep the oldest page ineligible for archive. 3. Place an eligible workspace after that page. 4. Run repeated reaper sweeps. 5. Observe that the later eligible workspace remains unarchived. **Paperclip version or commit** Commit `3efdf555e6e14a46747c796c3c554438bfc03261`. **Deployment mode** Built from source with the server test suite. **Installation method** Built from source. **Agent adapter(s) involved** Not adapter-specific (core bug). **Database mode** Not database-related. ## What Changed - Add a keyset cursor that uses `(updatedAt, id)` order across reaper pages. - Reset the cursor at the end of the candidate set so the next sweep starts at the beginning. - Add a throttled log when a sweep inspects candidates but archives none. - Add regression tests for archive delivery and starvation. ## Verification - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/execution-workspaces-service.test.ts` — 45 tests pass. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/server-startup-feedback-export.test.ts` — 16 tests pass. - `pnpm --filter @paperclipai/server typecheck` — clean. ## Risks Low risk. The change affects only candidate paging and the related reaper log. The cursor resets after the candidate set, so the sweep remains periodic. ## Model Used Codex, OpenAI GPT-5, extended reasoning, tool use, and code 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 (no exact duplicate found; related scheduler PR #10911 is distinct) - [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 (no documentation applies; this is an internal reaper behavior change) - [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>	2026-08-12 10:21:00 -07:00
DottaandPaperclip	72b509c895	Recognize delivered workspaces and reap terminal worktrees (#10908) ... ## Thinking Path > - Paperclip separates workspace provisioning lifecycle from whether the work was actually delivered. > - Git ancestry alone cannot recognize squash merges or deliveries into a branch other than the workspace base. > - A merged pull request linked from a terminal issue is stronger delivery evidence for those cases. > - The read contract should expose that evidence without changing persisted workspace schema. > - Cleanup must remain conservative: terminal descendants, delivered work, and no active run checkout are all required. > - Reusing the existing cleanup primitives keeps service shutdown, lease cleanup, activity logging, and archival behavior consistent. > - Focused regression coverage locks in both the honest read signal and the fail-closed reaper guards. ## Linked Issues or Issue Description **What existing behavior does this improve?** Execution workspace close-readiness payloads and terminal workspace cleanup. **Current behavior** Delivered squash-merged or cross-branch workspaces can remain `active` and report a permanent “not merged” warning because git ancestry does not contain their original commits. **Proposed behavior** Read payloads distinguish PR-confirmed delivery, ancestry delivery, unmerged work, and unknown state. Fully terminal delivered workspace trees are archived only when no active run holds the checkout. **Reason and benefit** Operators and automation receive an honest delivery signal, while shipped worktrees stop looking active forever and genuinely unmerged work retains its warning. **Breaking changes** The workspace payload gains a derived field. Existing fields and persistence remain unchanged; no database migration is required. **What happened?** A delivered workspace can remain `active` and warn that it is not merged forever after its issue ships through a squash or cross-branch pull request. **Expected behavior** Pull-request delivery should be represented honestly, and a fully terminal delivered workspace should become cleanup-eligible when no run holds its checkout. **Steps to reproduce** 1. Create an issue workspace with commits ahead of its configured base. 2. Deliver those commits with a squash merge or into a different target branch. 3. Mark the source issue and descendants done, then read workspace close readiness. Before this change, the workspace remains active with a “not merged” warning indefinitely. ## What Changed - Added the derived `deliveryState` workspace contract: `merged_via_pr`, `merged_by_ancestry`, `unmerged`, or `unknown`. - Extracted a shared GitHub pull-request merge classifier and reused it for merge confirmations and workspace delivery checks. - Suppressed false ancestry warnings when a terminal issue has ground-truth merged-PR evidence. - Added an idempotent terminality reaper with descendant-terminal, active-run, and delivered-work guards. - Restricted PR delivery evidence to the source issue, then required live merged state plus matching GitHub repository, head branch, and current workspace HEAD; persisted status, stale PRs, lexical mentions, inbound references, and descendant PRs cannot authorize cleanup. - Preserved workspaces with modified or untracked files even when their committed HEAD was delivered. - Bounded both long-lived pull-request state caches to 1,000 entries with oldest-entry eviction. - Routed eligible workspaces through existing runtime shutdown, lease cleanup, activity logging, and archival machinery with exclusive Git index, HEAD, and branch-ref locks plus non-forced removal. - Added regression coverage for delivery derivation, warning behavior, reaper guards, scheduler wiring, and squash/cross-branch delivery. ## Verification - `pnpm -r typecheck` - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/execution-workspaces-service.test.ts src/__tests__/merged-pr-confirmation-sweep.test.ts src/__tests__/server-startup-feedback-export.test.ts --reporter=verbose` — 63 passed - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/execution-workspaces-service.test.ts --reporter=verbose` after review hardening — 43 passed - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/execution-workspaces-service.test.ts src/__tests__/merged-pr-confirmation-sweep.test.ts src/__tests__/external-objects-service.test.ts --reporter=dot` on the final local head — 73 passed - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/heartbeat-workspace-busy.test.ts --reporter=verbose` — 15 passed - `env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY pnpm test:run` — server 3,662 passed (4 skipped), UI 3,599 passed, CLI 327 passed, shared 415 passed, and skills catalog 20 passed; the aggregate DB stage ran both source and built copies of one unrelated embedded-Postgres migration test and both reached its 5-second timeout - `pnpm --filter @paperclipai/db exec vitest run src/status-card-migrations.test.ts --reporter=verbose` — isolated aggregate-timeout verification passed in 3.99 seconds - `NODE_ENV=production pnpm build` - `pnpm check:token-gates` ## Risks The reaper intentionally fails closed when issue terminality, pull-request state, git ancestry, or checkout ownership cannot be proven. GitHub lookups can delay classification and cleanup but cannot cause an unproven workspace to be archived. Automated terminal archival holds exclusive Git index, HEAD, and branch-ref locks across validation and removal, skips configured destructive hooks, and uses non-forced removal so dirty writes fail closed. Reopening a source issue does not restore an archived workspace; it emits an audit event so a human or agent can re-provision explicitly. ## Model Used OpenAI Codex, GPT-5. The runtime did not expose a more specific model ID or context-window size. Reasoning, tool use, repository editing, test execution, and GitHub CLI access were enabled. ## 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 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: Paperclip <noreply@paperclip.ing>	2026-08-05 16:34:04 -05:00
DottaandPaperclip	f91a6e27c0	feat(issues): contain cross-issue agent side effects (#10837) ... ## Thinking Path > - Paperclip is the control plane that coordinates autonomous agent work. > - Agents need to collaborate on issues beyond their current assignment. > - Cross-issue comments and updates are useful, but an unbounded run can create cascading side effects. > - The control plane must preserve company-wide collaboration while containing each run's influence. > - Comment attribution must also show the responsible user and the acting agent in audits. > - This pull request adds run-bound cross-issue containment, attribution, and agent-class wake rules. > - The benefit is safer collaboration without restoring issue-assignee ownership restrictions. ## Linked Issues or Issue Description **What existing behavior does this improve?** Agent-authenticated issue comments, updates, reopen behavior, and assignee wake routing. **Subsystem affected** Cross-cutting: server routes and services, shared contracts, database schema and migration, and implementation documentation. **Current behavior** An authenticated agent can collaborate across company issues, but one heartbeat run has no per-run side-effect boundary. Comment records also do not persist the responsible user separately from the acting agent. **Proposed behavior** Require a valid heartbeat run for agent cross-issue comments and updates. Audit each attempt and cap a run at 20 cross-issue effects. Keep the cap in log-only mode until it automatically changes to enforcement at 2026-08-11 00:00 UTC. Preserve same-issue writes. Use agent-class wakes for agent comments. Keep same-run completion comments from reopening completed work. Record the responsible user on agent-authored comments and activity. **Reason and benefit** Agents can collaborate on other issues without an assignment gate, while each run has an atomic and inspectable side-effect limit. Operators can identify both the acting agent and the responsible user. **Breaking changes** After 2026-08-11 00:00 UTC, the twenty-first cross-issue comment or update from one heartbeat run returns a containment error. Agent cross-issue writes without valid run context are rejected. The migration is additive and backfills existing agent-authored comment attribution where the source data is available. ## What Changed - Added an atomic per-run counter for cross-issue agent comments and updates. - Added audit events for allowed and rejected cross-issue effects. - Added the automatic log-only to enforcement flip at 2026-08-11 00:00 UTC. - Added responsible-user attribution to agent-authored comments, activity records, shared types, and validators. - Added an additive migration and migration coverage for existing comments. - Updated reopen, resume, and wake behavior so agent comments create agent-class wakes and same-run completion comments remain inert. - Updated the implementation specification and regression coverage. ## Verification - `pnpm exec vitest run server/src/__tests__/cross-issue-influence-limit.test.ts server/src/__tests__/issue-comment-attribution-audit-routes.test.ts server/src/__tests__/issue-comment-reopen-routes.test.ts packages/db/src/issue-comment-on-behalf-migration.test.ts` — 97 tests passed. - `pnpm -r typecheck` — passed, including migration safety checks. - `pnpm test:run` — server batch: 3,364 passed and 2 skipped; UI batch: 3,504 passed. One unrelated CLI doctor test warned because this agent runtime injects static AWS credentials. - `env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY pnpm exec vitest run cli/src/__tests__/secrets.test.ts` — 8 tests passed and confirmed the CLI failure was ambient-environment sensitive. - `pnpm build` — passed. ## Risks - The fixed enforcement timestamp changes production behavior automatically on 2026-08-11 00:00 UTC. Audit logs before that time provide rollout visibility. - The per-run counter serializes on the heartbeat-run row. This prevents concurrent attempts from racing past the cap but adds a small lock scope for cross-issue writes. - Existing comments can only be backfilled when their acting run or agent attribution is recoverable. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI GPT-5 in the Codex agent runtime. The runtime did not expose a context-window size. Reasoning, shell tools, code editing, and test execution were enabled. ## 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>	2026-08-04 13:17:49 -05:00
3 people	dcac49a4fd	feat(workspaces): defer isolated setup until runtime start (#10653) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Isolated workspaces give each task a safe and reproducible checkout. > - The existing setup cloned the development database before an agent needed to run the app. > - This made worktree creation slower and heavier for tasks that never start a service. > - Runtime services already use one server start path for heartbeat, operator, and startup recovery flows. > - This pull request moves heavy setup to that start path and keeps worktree creation lean. > - The benefit is faster isolated workspace creation with the same reliable runtime setup when a service starts. ## Linked Issues or Issue Description Related pull request: #10652 covers the initial deferred database-seeding slice. This pull request supersedes it with end-to-end runtime provisioning and safe cleanup. **What existing behavior does this improve?** This improves isolated worktree creation, runtime service startup, and isolated instance cleanup. **Subsystem affected** Cross-cutting: CLI worktree setup, server runtime orchestration, shared workspace contracts, and development scripts. **Current behavior** Paperclip seeds an isolated development database during worktree creation. It can also leave an isolated instance directory after workspace teardown. This work happens even when no runtime service starts. **Proposed behavior** Paperclip creates the worktree with a lean eager setup. It runs an idempotent runtime provision command before the first managed service spawn. Concurrent starts share one provision attempt. Teardown removes the isolated instance safely. **Reason and benefit** Many agent tasks only edit and test code. They do not need a running Paperclip instance. Deferring the database seed reduces workspace startup cost while preserving automatic setup for tasks that start the app. **Breaking changes** None. The new runtime provision command is optional. Existing workspace behavior is unchanged when it is absent. ## What Changed - Split Paperclip worktree setup into a lean eager script and an idempotent runtime provision script. - Added `runtimeProvisionCommand` to project, issue, realized workspace, and persisted workspace contracts. - Added a per-workspace provision mutex before local service spawn for heartbeat, operator, and startup recovery flows. - Added a persisted `provisioning` service state and the `workspace_runtime_provision` operation phase. - Kept provision time outside the service readiness timeout and made failed attempts visible and retryable. - Reclaimed isolated instance data during safe workspace teardown. - Serialized deferred database seeding across processes and bound teardown to the instance root captured in persisted workspace metadata. - Added tests for config flow, concurrency, retry, no-op behavior, readiness timing, scripts, CLI commands, and cleanup. - Documented the eager and runtime provisioning contracts. ## Verification - `pnpm -r typecheck` - `pnpm build` - `pnpm test:run` (server: 3,201 passed; UI: 3,345 passed; the CLI phase exposed one environment-sensitive AWS doctor assertion because the agent runtime injects static AWS credentials) - `env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY pnpm exec vitest run cli/src/__tests__/secrets.test.ts -t 'passes AWS doctor checks when non-secret provider config is present'` - Focused runtime tests cover serialized provisioning, retry after stderr failure, absent-command no-op behavior, operation logging, persisted state order, and readiness timeout exclusion. - Focused CLI and cleanup tests cover concurrent seed serialization, stale-lock fail-closed behavior, persisted instance ownership, and rewritten sibling pointers. ## Risks - A faulty runtime provision script blocks service startup. Paperclip records stderr, marks the service failed, and retries on the next start. - Concurrent service requests share an in-process provision attempt, while the seed command uses an atomic filesystem lock across processes. A stale lock fails closed and requires an operator to verify no seed is running before removing it. - Isolated instance cleanup is destructive. The cleanup service validates ownership and path containment before removal. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, `gpt-5.6-sol`, with agentic reasoning, tool use, and code execution. The service does not expose the 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> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>	2026-08-02 10:37:10 -05:00
DottaandPaperclip	a29b10510c	fix(server): bound inherited workspace runtime services (#10589) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Execution workspaces can inherit runtime services from a project workspace > - A project workspace keeps current and historical runtime service rows > - The execution workspace read path returned all current rows, including services removed from the current configuration > - This pull request matches inherited rows to the current service definitions > - The benefit is bounded workspace payloads and accurate service summaries ## Linked Issues or Issue Description **What happened?** Shared execution workspaces returned current historical service rows that no longer matched the project workspace configuration. The response size multiplied across every shared execution workspace. **Expected behavior** Shared execution workspaces must return only the newest runtime service row for each service in the current project workspace configuration. **Steps to reproduce** 1. Create one project workspace with many historical runtime service rows. 2. Create many shared execution workspaces that inherit that project workspace. 3. List the execution workspaces and inspect each `runtimeServices` array. **Paperclip version or commit** `7301fae942c3d5826974335cb40d6f1e0d95d1e0` **Deployment mode** Built from source. The defect is in the server read model and is not deployment-specific. No duplicate or related public issue or pull request was found. ## What Changed - Select only runtime service rows that match the current project workspace service definitions. - Preserve each matched service definition index in the API result. - Avoid loading direct execution service rows for workspaces that inherit project services. - Add unit, integration, and volume regression coverage. ## Verification - `pnpm --dir server exec vitest run src/services/workspace-runtime-read-model.test.ts src/__tests__/execution-workspaces-service.test.ts -t 'selectConfiguredRuntimeServiceRows|returns full details at the observed volume|inherits only runtime-service rows'` - `pnpm --filter @paperclipai/server typecheck` The focused test run passed 4 tests and skipped 27 unrelated tests. ## Risks The read path now omits service rows that do not match the current configuration. This is the intended behavior for inherited runtime services. The change does not alter service persistence or lifecycle transitions. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex with model ID `gpt-5`. The context-window size is not exposed to this run. The run used reasoning, repository tools, code execution, and GitHub tools. ## 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>	2026-07-31 18:54:11 -07:00
3 people	32c1a8576c	fix(server): self-heal execution workspaces whose recorded branch no longer exists (#10578) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Each agent task gets an execution workspace (a git worktree) with a recorded branch name; workspace validation compares that record to the worktree before every run > - Agents sometimes rename their task branch (for example to a `feat/*` PR branch), so the recorded branch never existed or was deleted > - Validation then fails every run with "expected branch does not exist" — a deterministic `workspace_validation_failed` loop with no self-heal path > - A recorded branch with no resolvable commit has nothing to lose, so adopting a clean, registered checked-out branch is trivially forward-only > - This pull request routes that exact case through the existing audited forward-reconciliation path, in both the runtime and the manual board reconcile endpoint > - The benefit is that these stranded workspaces heal themselves while dirty worktrees, detached HEADs, unregistered paths, and ambiguous git states all stay fail-closed ## Linked Issues or Issue Description No public GitHub issue exists; the underlying bug is described here per `bug_report.yml`. Related PR: #10574 self-heals the sibling provisioning failure loop uncovered by the same incident diagnosis. **What happened?** An execution workspace whose recorded branch was renamed away failed every subsequent run with `workspace_validation_failed` ("expected branch does not exist"). The safe-repair matrix refused the case, so the task stayed blocked until a human intervened. **Expected behavior** When the recorded branch is confirmed absent and the worktree is clean and registered with its checked-out branch matching HEAD, Paperclip adopts the checked-out branch through the audited forward-reconciliation path and the next run proceeds. **Steps to reproduce** In an isolated workspace, rename the task branch (`git branch -m <recorded> feat/something`) or delete the recorded branch, leave the worktree clean, then start a new run on the task. Validation fails on every retry. **Paperclip version or commit** master as of the branch point of this PR. **Deployment mode** Local trusted deployment with git-worktree isolated workspaces. ## What Changed - `ensureGitWorktreeBranchCoherent` (workspace runtime): a missing recorded branch with a clean worktree, an existing checked-out branch, and a registered branch matching HEAD now goes through audited forward reconciliation instead of failing closed. Gated behind `enableWorkspaceBranchReconcileForward`. - `reconcileExecutionWorkspaceBranch` mode `forward` (service): accepts the same case so the board reconcile endpoint can repair it manually. - The service inspection now classifies each branch ref as `resolved` / `missing` / `error` (`git rev-parse --verify --quiet`, distinguishing an absent ref from git failing to inspect the repo). Adoption requires a confirmed-missing recorded ref **and** a resolved target ref, so a git error can never bypass ancestry validation and a nonexistent branch name is never persisted. - Removed the test that asserted this case fails closed; it is superseded by tests that assert the new behavior. - New tests: successful adoption, dirty-worktree refusal, refusal when the checked-out branch ref does not resolve either, and disabled-flag behavior. ## Verification - `server`: `npx vitest run src/__tests__/execution-workspaces-service.test.ts -t "reconcil"` — 11 passed. - `server`: `npx vitest run src/__tests__/workspace-runtime.test.ts -t "adopt"` — 7 passed. - `npx tsc --noEmit` in `server/` is clean. - Manually validated the underlying repair on a live stranded workspace before automating it: creating the recorded branch at the clean HEAD ended the validation-failure loop without touching the agent's PR branch. ## Risks - The change relaxes a fail-closed gate, so the main risk is over-adoption. Mitigations: the exception requires flag-on, clean worktree, registered worktree path, registered branch matching HEAD, a confirmed-missing (not merely unreadable) recorded ref, and a resolvable target ref; everything else still fails closed. Every adoption goes through the audited reconcile path with an issue comment trail. - No migrations, no API surface changes (the reconcile route returns the same hand-picked fields). ## Model Used Claude Fable 5 (Anthropic, model ID `claude-fable-5`), extended thinking, agentic tool use (Claude Code harness). ## 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: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-07-31 16:19:13 -07:00
DottaandPaperclip	e4e12bfb89	fix(workspaces): persist readiness state and validate ports (#9408) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Execution workspaces can run managed services that must report reliable lifecycle and readiness state > - Service startup previously waited for readiness before committing the starting row, making concurrent control actions see stale state > - Fixed service ports also needed clearer configuration and ownership diagnostics to avoid cross-workspace collisions > - This pull request persists startup state before readiness, validates port ownership, and exposes configurable service ports in the workspace UI > - The benefit is dependable service controls and actionable diagnostics when workspace runtimes start slowly or compete for ports ## Linked Issues or Issue Description ### What happened? Slow-starting workspace services could remain invisible to concurrent stop/restart controls until readiness completed, and fixed-port conflicts lacked enough ownership context for safe repair. ### Expected behavior A starting service is persisted immediately, control operations can observe it, configured ports are editable, and conflicts identify the owning process/workspace. ### Steps to reproduce 1. Configure a workspace service that delays binding its HTTP port. 2. Start the service and immediately request another control action. 3. Observe stale persisted state before this change. 4. Configure two workspaces for the same fixed port and observe limited conflict diagnostics. ### Paperclip version or commit `origin/master` at `02e2dd271` ### Deployment mode Local dev; built from source; not adapter-specific; database-backed workspace runtime state. ## What Changed - Commit the `starting` runtime-service row before waiting for readiness and transition it after the probe completes. - Add port-owner inspection and cross-workspace conflict details to local service supervision. - Preserve configurable runtime service ports through workspace configuration updates. - Surface service-port editing and validation in the execution workspace details UI. - Add server and UI regression coverage for slow readiness, concurrent controls, port persistence, and conflict diagnostics. ## Verification - `vitest --project @paperclipai/server src/__tests__/workspace-runtime.test.ts src/__tests__/execution-workspaces-service.test.ts` — 118 tests passed. - `vitest --project @paperclipai/ui src/pages/ExecutionWorkspaceDetail.service-ports.test.ts` — 4 tests passed. - `node scripts/check-token-gates.mjs` — all token gates clean. ## Risks - Moderate risk: changes touch workspace service lifecycle persistence and local process/port inspection. - No schema migration is required; tests exercise slow readiness, concurrent control, persisted ports, and cross-workspace conflicts. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5.3 Codex, reasoning with repository tool use and code execution; context-window size was not exposed by the runtime. ## 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>	2026-07-11 03:02:21 -05:00
3 people	f3ca4d24bc	fix: repair dirty/foreign-branch execution worktrees (#9297) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Execution workspaces are the bridge between Paperclip's control plane and a local agent's checked-out repository state. > - When a workspace is restored after a failed or interrupted run, the recorded branch can disagree with the branch currently checked out on disk. > - A clean branch mismatch can be reconciled safely, but a dirty mismatch needs a lossless path that does not discard uncommitted agent work. > - This pull request adds a quarantine-and-restore path that saves dirty work to a rescue branch, restores the recorded branch, and exposes the repair from the board UI and run page. > - The benefit is that operators can recover wedged execution workspaces without losing work or moving another live branch unexpectedly. ## Linked Issues or Issue Description No public GitHub issue exists for this workspace-recovery failure, so this PR includes the bug report inline. **What happened** A git worktree-backed execution workspace could become wedged when Paperclip expected one branch but found a different checked-out branch with dirty tracked or untracked files. The existing safe repair path refused the restore, leaving the source task blocked with no lossless one-click recovery path. **Expected behavior** Paperclip should preserve dirty work before restoring the recorded workspace branch. If another live workspace claims the checked-out branch, or an attached runtime service is active, the repair should refuse with clear operator-facing evidence instead of risking work loss or file contention. **Steps to reproduce** Create a git worktree execution workspace whose persisted branch name differs from the checked-out branch, add dirty tracked or untracked files in that worktree, then trigger workspace validation or use the branch reconcile endpoint. Before this change, the dirty mismatch remained blocked because Paperclip had no quarantine restore mode. **Paperclip version or commit** Observed on the pre-fix workspace-recovery implementation. Verified on this PR head after rebasing onto current `master`. **Deployment mode** Local trusted development/worktree deployments using git worktree execution workspaces and optional workspace runtime services. ## What Changed - Added dirty-worktree quarantine repair that creates a rescue branch, commits dirty tracked and untracked files there, restores the recorded branch, writes audit comments/activity, and preserves the live foreign branch ref. - Added `quarantine_restore` branch reconcile API support, recovery-action resolution, source-task wake behavior, execution-review preservation, claimant refusal, runtime-service refusal, and coverage for the non-transactional git ordering. - Added board UI controls for the repair action in the recovery card plus a compact failed-run workspace recovery surface that uses the same reconcile handlers. - Hardened Greptile follow-up cases by best-effort restoring the recorded branch after a mid-sequence rescue commit failure and by refusing quarantine restore while attached runtime services are active. ## Verification - `pnpm exec vitest run server/src/__tests__/execution-workspaces-service.test.ts -t "quarantine_restore"` - `pnpm exec vitest run server/src/__tests__/workspace-runtime.test.ts -t "workspace dirty quarantine branch repair"` - `pnpm exec vitest run server/src/__tests__/heartbeat-workspace-finalize-branch.test.ts -t "repairs clean unrecorded branch drift|adopts unrecorded forward branch drift"` - `pnpm exec vitest run server/src/__tests__/workspace-runtime-routes-authz.test.ts` - `pnpm --filter @paperclipai/server typecheck` - Earlier PR verification covered the route, service, heartbeat, UI component, and run-page recovery surfaces; Cutter posted public preview screenshots for the repair popover and run-page panel at https://github.com/paperclipai/paperclip/pull/9297#issuecomment-4926934211. - GitHub PR checks are green on `dcac76b05f4cf6e1ee16544c2831d83c7857e475`. - Greptile is 5/5 with zero annotations and no unresolved review threads on `dcac76b05f4cf6e1ee16544c2831d83c7857e475`. ## Risks - Moderate risk because the change intentionally runs git commands against local worktrees; the implementation refuses dirty repair when another claimant or active runtime service is detected and records rescue refs for auditability. - Compatibility / release-note callout for self-hosted operators: existing instances that left `enableWorkspaceBranchReconcileForward` unset now get automatic forward branch reconciliation during heartbeat workspace recovery. Operators who want the previous advisory-only behavior can set `experimental.enableWorkspaceBranchReconcileForward` to `false`; dirty quarantine repair can likewise be disabled with `experimental.enableWorkspaceDirtyQuarantineRepair: false`. - If the git rescue succeeds but a later database write fails, the worktree may already be restored while the recovery action remains open; this ordering is documented in code because git side effects cannot participate in the database transaction. - UI risk is limited to the workspace recovery surfaces and covered by component tests plus the existing Cutter visual preview. ## Model Used OpenAI Codex coding agent based on GPT-5, with repository tool use, shell execution, and local test execution. Earlier preserved commits on this branch also show Claude Code / Claude Opus 4.8 assistance in their commit metadata. ## 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] Branch naming exception documented: this PR preserves the existing worktree branch requested for publication while keeping the PR title and body public-facing - [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: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-09 18:19:49 -05:00
3 people	b13eb5b2b5	Skill Studio: three-pane skill IDE with sandboxed test runs (#9241) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The Skills Manager gives operators a reusable skill layer, but iteration still required manual edits, ad hoc prompts, and indirect run inspection. > - Skill authors need a focused workflow for editing skill files, saving representative test inputs, and running those inputs through an agent without exposing harness tasks as normal company work. > - The backend therefore needs durable test inputs, reusable run templates, hidden harness issues, scoped run execution, retention metadata, and read-containment rules around hidden work. > - The frontend needs a three-pane Studio that keeps skill files, saved inputs/templates, and run output/history visible together while preserving the existing design system and token rules. > - This pull request ships that Skill Studio surface end to end: database migrations, shared contracts, server APIs/services, hidden harness execution behavior, UI routes/components, and focused tests. > - The benefit is faster and safer skill iteration, with inspectable outputs and fewer ways for internal harness work to leak into normal task lists, costs, or adjacent read APIs. ## Linked Issues or Issue Description No public GitHub issue exists for this feature. Feature request summary: - Problem: Skill authors need to edit and test company skills in one place instead of switching between the skill detail page, task creation, run output, and manual prompt history. - Proposed solution: Add a Skill Studio workbench with saved inputs, reusable templates, hidden sandboxed test runs, live run status, output inspection, run history, rerun/delete controls, and frontmatter-aware editing. - Expected users: Paperclip operators and agent-company maintainers who create, fork, import, and tune skills. - Related public PRs: Supersedes #9205, which was replaced so the public PR branch name follows contributor policy. - Duplicate search: searched public GitHub issues and PRs for "Skill Studio"; no other active public issue or PR directly covers this feature. ## What Changed - Added database migrations for Skill Studio test inputs, test runs, test run retention, and reusable run templates. - Added shared Skill Studio types, validators, route helpers, frontmatter utilities, and status handling. - Added server services and routes for saved inputs, test runs, templates, reruns, terminal-run deletion, hidden harness issue execution, and run-detail hydration. - Strengthened hidden-issue read containment across issue-adjacent routes and cost rollups used by skill test harness work. - Added the Skill Studio UI with skill file editing, frontmatter editing, saved inputs, templates, run creation/cancel/rerun/delete flows, output rendering, history, route support, and responsive pane behavior. - Added focused backend, shared, and UI tests for the new APIs, routing logic, editor/run behavior, hidden-issue containment, and migration safety. - Rebased onto current `master`, removed the generated lockfile diff from the PR, and verified no workflow files are changed. ## Verification - [x] `pnpm --filter @paperclipai/db check:migrations` - [x] `pnpm check:token-gates` - [x] `pnpm exec vitest run server/src/__tests__/company-skills-service.test.ts server/src/__tests__/company-skills-routes.test.ts server/src/__tests__/company-skill-test-runs-service.test.ts ui/src/lib/skill-studio.test.ts ui/src/pages/SkillStudio.test.tsx` — 5 files, 132 tests passed - [x] Greptile review on the latest PR head - [x] GitHub PR checks on the latest PR head ## Risks - Medium risk because this is a broad feature touching database schema, server orchestration, issue visibility, and a large UI surface. - Hidden harness issue containment is security-sensitive; this PR includes regression coverage for adjacent read paths and cost rollups. - The new migrations are additive and use idempotent guards where applicable, but deployed databases that previously tested draft migration numbers should still be checked carefully. - The UI depends on a new resizable panels package in `ui/package.json`; the lockfile is intentionally left to repository automation. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, GPT-5 coding agent with shell, git, and GitHub CLI tool use. Earlier feature commits include assistance from other Paperclip coding agents; this PR preparation, rebase, cleanup commit, and PR body were completed by OpenAI Codex in a Paperclip worktree. ## 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: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-09 13:08:56 -05:00
Nicky LeachandPaperclip	bb87047fe6	Add auto-forward execution workspace branch reconciliation (#9172) ... ## Thinking Path > - Paperclip manages execution workspaces for AI agent runs, each associated with a git branch so the agent always works in a known code state. > - Workspace runtime reconciles an agent's checkout branch against the workspace's recorded branch when a heartbeat resumes; without forward-ancestry detection, any divergence fails closed and blocks the run. > - When the workspace branch has moved forward (e.g. after a feature merge), the recorded branch is an ancestor of the current HEAD — a safe, forward-only case that the previous implementation refused even though it carries no safety risk. > - The gap means legitimate forward-advancing deployments require manual operator intervention to unblock agents every time, creating operational friction and interrupting automated workflows. > - This pull request adds a flag-gated reconcile-forward path that detects when the current branch is a strict forward descendant of the workspace branch and auto-reconciles, while preserving fail-closed behavior for all non-forward or flag-off cases. > - It also threads the active execution workspace id through restore and finalize call sites so the reconcile verdict can be persisted durably across heartbeats. > - The benefit is that agents resume automatically from forward-advancing workspace branches without operator intervention, while adversarial and backward branch changes continue to fail closed. ## Linked Issues or Issue Description This PR adds an auto-forward reconcile path for execution workspace branch tracking. When a workspace's recorded branch is a strict ancestor of the current HEAD (a forward-only advancement), the runtime now auto-reconciles rather than hard-blocking. The feature is gated behind an explicit runtime flag, defaults to off, and falls back to fail-closed behavior for all non-forward or flag-off cases. The prior implementation treated all branch divergences identically: any mismatch between the recorded workspace branch and the current HEAD failed closed. This prevented agents from resuming after routine forward deployments (e.g. after a feature branch merges into the workspace branch), requiring manual operator action to unblock every affected run. ## What Changed - Added `reconcileForward` flag-gated path in workspace runtime reconciliation logic that allows auto-reconciliation when the workspace branch is a strict ancestor of the current HEAD. - Threaded active execution workspace id through `restore` and `finalize` call sites so reconcile verdicts are persisted durably. - Added `plainLanguageReason` and `ancestryVerdict` evidence fields to the reconciliation result structure for operator visibility. - Stabilized a branch containment test that exposed a late run-linked activity FK cleanup race during the focused Vitest rerun. - All new paths remain fail-closed when the flag is off or when the branch relationship is not strictly forward. ## Verification ```bash pnpm --filter @paperclipai/shared typecheck pnpm --filter @paperclipai/server typecheck pnpm exec vitest run \ server/src/__tests__/workspace-runtime.test.ts \ server/src/__tests__/heartbeat-workspace-branch-containment.test.ts \ server/src/__tests__/execution-workspaces-service.test.ts git diff --check origin/master..HEAD ``` All 3 test files / 98 tests pass. Typecheck passes for both shared and server packages. > **Note:** This is a stacked PR on top of PR #9170 (Add execution workspace branch reconciliation route). The diff shown targets that branch; the combined change builds on the reconciliation route infrastructure it provides. ## Risks - **Flag-off default:** The reconcile-forward path is off by default. No behavior change for existing workspaces unless the flag is explicitly enabled by an operator. - **Ancestry check correctness:** The forward-only guard uses git ancestry verification; a branch that is not a strict ancestor of HEAD remains fail-closed. Adversarial or concurrent branch resets are not auto-reconciled. - **FK cleanup race (stabilized):** A late run-linked activity FK cleanup race in the containment test was exposed during the Vitest rerun. The stabilization commit addresses the non-deterministic ordering without changing production behavior. - **Stacking dependency:** This PR must not be merged before PR #9170 merges, as it is built on top of the reconciliation route infrastructure. ## Model Used - Provider: Anthropic - Model: Claude Sonnet 4.6 (`claude-sonnet-4-6`) - Context: 200k token context window - Mode: Agentic tool use with code execution and git operations ## 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>	2026-07-07 14:12:17 -07:00
Nicky LeachandPaperclip	f17202b571	Add execution workspace branch reconciliation route (#9170) ... ## Thinking Path > - Paperclip is an open-source app that lets teams run AI agents for work tasks; each agent session uses an execution workspace — a git checkout — to track the agent's active code state. > - Every execution workspace has an expected target branch (`PAPERCLIP_WORKSPACE_BRANCH`). The workspace git HEAD should always point to that branch so agents commit in the right place. > - When workspace git HEAD diverges from the expected branch — for example after a harness branch-name fix or an accidental `checkout -b` during a CI-retrigger — the discrepancy must be corrected before agents can continue safely. > - Operators (board users) need a controlled, audited path to reconcile a workspace's live branch back to the expected target, with an override escape-hatch for cases where the normal forward path is blocked. > - This pull request adds a board-only `POST /api/execution-workspaces/:id/reconcile-branch` service operation and route that validates safety preconditions, resolves matching recovery-action fingerprints, posts source-issue audit comments, and records the reconciliation outcome. > - The benefit is that operators can correct branch divergence through the API with a full audit trail, instead of via raw database edits. ## Linked Issues or Issue Description No public GitHub issue exists for this change. Context below follows the feature-request template format. **Subsystem affected** server/ — REST API & orchestration services; packages/shared — request validation. **Problem or motivation** Execution workspaces have an expected branch record that must match the checked-out worktree branch. When the live git branch and stored branch record drift apart, operators currently lack a first-class, audited API to reconcile the record. The fallback is manual database repair or workspace replacement, both of which are risky and hard to audit. **Proposed solution** Add a board-only execution workspace branch reconciliation operation. `forward` mode re-inspects the server-side git state and only updates the branch record when the stored branch is an ancestor of the checked-out branch. `override` mode is a break-glass path that requires board access and an operator reason. Both modes require a clean, idle workspace, write audit details, post a source-issue audit comment, and resolve the matching workspace-validation recovery action. **Alternatives considered** Manual database edit (no durable audit trail and easy to mistype), recreating the workspace (heavier operational disruption), or trusting client-supplied ancestry evidence (unsafe because the server must verify the git state itself). **Roadmap alignment** This is incremental hardening for execution-workspace recovery and operator controls. It does not duplicate a public roadmap item. **Additional context** The endpoint is intended for operator recovery, not normal agent control flow, so the generated OpenAPI metadata and runtime route both classify it as board-only. ## What Changed - Added `reconcileExecutionWorkspaceBranchSchema` discriminated-union validator (`forward` with optional reason, `override` requiring a non-empty reason string) to `packages/shared/src/validators/execution-workspace.ts` - Exported `ReconcileExecutionWorkspaceBranch` type and the new schema from the shared package index - Added board-only reconcile-branch service operation in the execution workspaces service: safety checks, recovery-action fingerprint resolution, source-issue audit comment, and outcome recording - Added clean-worktree and stopped-runtime-service preconditions before branch-record mutation. - Marked the reconcile route as board-only in OpenAPI generated auth metadata. - Added `POST /api/execution-workspaces/:id/reconcile-branch` route wired to the new service operation with board-permission gate - Extended `execution-workspaces-routes.test.ts` and `execution-workspaces-service.test.ts` to cover: safety-check rejection, override-reason validation, audit-comment posting, and recovery-action fingerprint resolution (2 files / 19 tests) ## Verification ```sh pnpm --filter @paperclipai/shared typecheck pnpm --filter @paperclipai/server typecheck pnpm exec vitest run server/src/__tests__/execution-workspaces-routes.test.ts server/src/__tests__/execution-workspaces-service.test.ts pnpm exec vitest run server/src/__tests__/execution-workspaces-service.test.ts server/src/__tests__/openapi-routes.test.ts ``` ## Risks - **Board-only gate:** the operation is gated behind the board permission; no agent can trigger it without operator authorization. - **Override requires reason:** the `override` mode requires a non-empty reason string so every bypass is audited. - **Idempotent recovery-action resolution:** re-running with the same fingerprint is safe; duplicate resolution is a no-op. - **No execution-state mutation:** the route records a reconciliation intent and updates the branch record; it does not restart the workspace or modify running agent state. - Overall risk: **low**. ## Model Used - Provider: Anthropic - Model ID: `claude-sonnet-4-6` (Claude Sonnet 4.6) - Context window: 200 K tokens - Capabilities: tool use, code execution, multi-turn context Follow-up safety commit: - Provider: OpenAI - Model ID: `codex` / GPT-5 with tool use and code 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 (`feat/execution-workspace-branch-reconciliation-route`) 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>	2026-07-07 13:41:23 -07:00
DottaandPaperclip	569b7affc4	[codex] Add bounded workspace overview (#8627) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The execution workspace subsystem powers project and workspace views by listing runtime state, branch metadata, issue links, and status summaries. > - The existing workspace views relied on broad list data that can grow expensive as a company accumulates many workspaces and linked issues. > - That makes the Workspaces page and project workspace cards slower than necessary because the UI does not always need the full workspace detail payload up front. > - This pull request adds a bounded overview contract for workspace listings and moves the relevant UI surfaces to that cheaper path. > - The benefit is faster workspace loading while preserving detail fetches for pages that actually need full workspace data. ## Linked Issues or Issue Description No public GitHub issue exists for this change. Inline bug report follows the repository bug template. ### What happened? Workspace index-style screens can load too much execution workspace detail before the user asks for it. Several UI surfaces used fuller workspace data paths for summary displays, which can make workspace loading slower as workspace history grows. ### Expected behavior Overview screens should request a bounded summary payload, while detail screens should keep using the full workspace detail endpoint. ### Steps to reproduce 1. Run Paperclip from source with enough execution workspace history to make workspace lists non-trivial. 2. Open the Workspaces page or a project workspace summary card. 3. Observe that summary UI needs only bounded workspace metadata but can depend on broader workspace payloads. ### Paperclip version or commit `master` at the time this branch was prepared. ### Deployment mode Local dev (`pnpm dev`) ## What Changed - Added shared types, validators, and path constants for bounded execution workspace overviews. - Added server service and route support for overview queries with bounded linked issue/runtime metadata. - Updated workspace overview UI API calls, query keys, breadcrumbs, quicklooks, close dialogs, project summaries, and detail links to consume the cheaper overview shape where appropriate. - Added regression coverage for the new server route/service behavior and the UI overview consumers. - Registered the new workspace overview route in the generated OpenAPI spec. - Kept overview totals aligned with the project join and preserved project slug links in workspace headers. ## Verification - `pnpm exec vitest run server/src/__tests__/execution-workspaces-service.test.ts server/src/__tests__/execution-workspaces-routes.test.ts ui/src/api/execution-workspaces.test.ts ui/src/components/ProjectWorkspaceSummaryCard.test.tsx ui/src/pages/Workspaces.test.tsx` - `pnpm --filter @paperclipai/shared typecheck && pnpm --filter @paperclipai/server typecheck && pnpm --filter @paperclipai/ui typecheck` - `pnpm exec vitest run server/src/__tests__/openapi-routes.test.ts server/src/__tests__/execution-workspaces-routes.test.ts server/src/__tests__/execution-workspaces-service.test.ts` - `pnpm test:run:serialized -- --shard-index 1 --shard-count 4` ## Risks Low to medium risk. The change introduces a new overview contract across shared/server/ui layers, so the main risk is a mismatch between summary and detail payload expectations. The added route/service/UI tests cover the intended split, and full detail pages continue using the detail path. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, GPT-5-based coding agent with repository tool use and local command execution. Exact served model identifier and context window were not exposed in this session. ## 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>	2026-06-25 21:38:14 -05:00
4 people	ece8a51e22	[codex] Bundle local branch fixes from PAP-10032 (#6604) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - This branch accumulated multiple already-tested control-plane, adapter runtime, invite, workspace, plugin, and UI quality fixes on the primary Paperclip checkout. > - `origin/master` advanced while those commits were still local, so the branch needed to be preserved and reconciled before review. > - Splitting the branch commit-by-commit against the new base produced overlapping conflicts with recently merged upstream PRs. > - This pull request keeps the remaining branch as one standalone PR because the final diff is 38 files after removing screenshot artifacts, under Greptile's 100-file cap, and can be merged independently after review. > - The benefit is that none of the local work is lost, the branch is now based on current `origin/master`, and reviewers can evaluate the reconciled changes in one place. ## What Changed - Merged the local accumulated branch with current `origin/master` and resolved the invite-flow overlaps from the newer upstream companies query helper. - Preserved the local fixes for invite existing-member behavior, invite link copy fallback, reusable workspace selection, worktree auth, static SPA fallback, markdown wrapping, plugin slot registration, cloud upstream UX/server polish, project sorting, and related tests. - Removed screenshot artifacts from the PR per review request. - Kept the PR under the requested file limit: 38 files changed, with no `pnpm-lock.yaml` or `.github/workflows/*` changes. ## Verification - `NODE_ENV=test pnpm exec vitest run ui/src/pages/CompanyInvites.test.tsx ui/src/pages/InviteLanding.test.tsx ui/src/pages/Projects.test.tsx ui/src/plugins/slots.test.ts ui/src/components/MarkdownBody.test.tsx server/src/__tests__/invite-accept-existing-member.test.ts server/src/__tests__/static-index-html.test.ts server/src/__tests__/execution-workspaces-service.test.ts server/src/__tests__/better-auth.test.ts server/src/__tests__/worktree-config.test.ts` - `NODE_ENV=test pnpm --filter @paperclipai/ui typecheck` - `NODE_ENV=test pnpm --filter @paperclipai/server typecheck` - Confirmed `git diff --name-only origin/master...HEAD | wc -l` is `38`. - Confirmed no PR diff entries match `pnpm-lock.yaml`, `.github/workflows/*`, or `screenshots/*`. ## Risks - Medium review risk because this is a bundled rescue PR rather than several narrow feature PRs. - Invite flow and company cache behavior overlapped with newer upstream changes; the merge resolution intentionally keeps the shared `companiesListQueryOptions` helper while preserving local existing-member invite behavior. - Visual review evidence is no longer attached in-repo because screenshots were removed from this PR per review request. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5-based coding agent, with repository tool access, terminal execution, and git/GitHub CLI operations. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] UI screenshots were intentionally removed from this PR per review request - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> Co-authored-by: CodexCoder <codexcoder@paperclip.local>	2026-05-25 07:25:26 -05:00