mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 06:01:49 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Before each run, the heartbeat compares a fingerprint of the workspace config with the fingerprint saved on the reused execution workspace > - An environment change is replacement-class drift. When the task asks to reuse its workspace, the "replace" decision does not replace the workspace. It only keeps the old fingerprint, so the drift stays visible > - A workspace-provider plugin owns the files of the workspaces it prepares. The environment only decides where the runner executes, so an environment change cannot make those files wrong > - A managed sandbox environment can change its template id with each release. Each existing plugin workspace then logs a "replace" freshness notice on every later run, and nothing ever clears it > - This pull request records environment drift as a refresh for plugin-owned workspaces, and makes Core's fingerprint win over the provider row's stale copy > - The benefit is that the notice appears once after a real change and then stops. Reuse does not change ## Linked Issues or Issue Description Refs #19349. That PR stopped cosmetic sandbox updates from advancing the environment revision. This PR covers real config changes on plugin-owned workspaces. **What happened?** A managed plugin environment changed its `driverConfig` (a new sandbox template id after a release). After that, every run on an existing plugin workspace printed: ``` [paperclip] Execution workspace reuse freshness action "replace" because execution workspace configuration changed: environment. ``` The run result showed `workspaceReused: true`, with the same workspace id before and after. The stored fingerprint stayed the same on every run, so the notice repeated forever. **Expected behavior** The workspace is reused, as it is now. The new fingerprint is saved, the drift is reported once, and later runs report no drift. **Steps to reproduce** 1. Prepare a plugin-owned workspace with a plugin environment. 2. Change the environment's `driverConfig`. 3. Run the task twice more with workspace reuse. Both runs report `replace` for `environment`, and the stored `configFingerprint` does not change. ## What Changed - `server/src/services/heartbeat/workspaces.ts`: `resolveExecutionWorkspaceConfigFreshness` takes an optional `providerOwnedStorage` flag. With the flag, `environment` drift does not require replacement. Other replacement-class drift (repo, strategy, mode, project workspace, realization) still gives `replace`. - `server/src/services/heartbeat/workspace-preparation.ts`: - Pass `providerOwnedStorage: Boolean(pluginPrepared)`. - The plugin path spread the provider row's metadata over Core's metadata. That row still holds the fingerprint it was prepared with, so a refresh could never save the new one. Core's `configFingerprint` now wins. The rest of the provider metadata, including its `config` snapshot, is unchanged. - `doc/heartbeat-internals.md`: describe the provider-owned storage rule. The freshness decision never controls reuse here. With reuse requested, restore is `requestedShouldReuseExisting` for every action, and the plugin picks the workspace before the decision is made. This change only alters what Core saves on the workspace row and what it reports. ## Verification - Red first. Without the fix, both new tests failed: the decision was `replace`, not `refresh`. - With only the resolver change, the preparation test still failed because the stored fingerprint did not change. This shows the metadata merge fix is necessary. - `npx vitest run src/__tests__/heartbeat-workspace-session.test.ts src/services/heartbeat/workspace-preparation.test.ts` (in `server/`): 2 files, 333 tests pass. - `npx tsc --noEmit -p tsconfig.json` (in `server/`): passes. - New tests: - `heartbeat-workspace-session.test.ts`: environment drift on provider-owned storage gives `refresh` and persists the fingerprint. The same drift on Core-owned storage still gives `replace`. Environment plus repo drift on provider-owned storage still gives `replace`. - `workspace-preparation.test.ts`: a new `environmentDrift` case runs three preparations on one plugin workspace. Run 2 records one `refresh` freshness operation for `environment` with `workspaceReused: true` and saves a new fingerprint. Run 3 records no freshness operation. - Not run locally: `pnpm verify` and the full suite. CI supplies that coverage. ## Risks - Low risk. Reuse does not change, and no schema changes. - Behavioral shift: a plugin-owned workspace whose environment changed now saves the new fingerprint. A later return to the old environment config is reported as drift again, as for any other refresh. - If a future plugin environment change does affect the files of a provider-owned workspace, this rule would hide it. The provider owns those files, so the provider is responsible for that check. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, test runs) and extended thinking. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>