DottaandPaperclip
f7ad1dc7ca
## Thinking Path > - Paperclip lets people assign work to AI agents and inspect the result. > - A task can use repositories from more than one project. > - Remote workspace preparation treated every additional project as a read-only source. > - This rejected valid Git repositories before the provider started, even when no source was read-only. > - The task page then hid the preparation reason behind a generic failed-attempt notice. > - This pull request prepares authorized repositories as writable task copies and shows redacted workspace validation errors. > - People can work across both projects and see the reason if folder preparation fails. ## Linked Issues or Issue Description **What happened?** A remote task with a selected Git-backed project and another mentioned Git-backed project failed before provider execution. It reported `remote_workspace_readonly_sources_unsupported`. Neither project had a read-only setting. The task notice showed only that the attempt failed. **Expected behavior** Each attached repository should be writable inside the task workspace. This should preserve source access checks and saved work. A workspace validation failure should explain its cause on the task page. **Steps to reproduce** 1. Configure remote workspace storage and a native sandbox environment. 2. Select a Git-backed project for a task. 3. Mention another authorized Git-backed project in the task. 4. Start the task. Preparation rejects the additional source before it starts the provider. **Paperclip version or commit** Reproduced against `dc9f387edc`, before this change. **Deployment mode** Managed remote workspace storage. Local regression checks use disposable PostgreSQL and independent filesystem processes. Related merged work: Refs #18403 and #18504. Those changes established remote storage and metadata-only references. They still reject configured cross-project repositories. No duplicate writable-repository repair was found. Refs #18774 for the test-only retention-fixture repair reused to unblock CI. ## What Changed - Add every configured Git repository of an authorized referenced project to `.paperclip-repositories/` as an editable task copy. - Retain saved paths, refs, pins and files. Recheck retained project access and source trust. Keep explicit read-only, local-source import and remote feature gates. - Keep committed snapshot repository coverage separate from later requests. Honor configured default refs, resolve remote branch names, and publish secondary checkouts only after checkout succeeds. Share configured-ref resolution between root and attached-repository scripts. - Include redacted workspace validation messages in the task interruption projection and existing failure notice. Preserve Retry permissions and render messages as plain text. Explain retained-folder access and trust denials while preserving the dedicated low-trust project-access path. - Add source, authorization, redaction, UI and save/restore regressions. Update the implementation contract and workspace maps. - Reuse the reviewed test-only repair from #18774. Batch the shared-workspace history fixture, verify its complete privacy-source map, and drain owned test bodies before cleanup. Production retention behavior is unchanged. ## Verification - Red before repair: four source-resolution cases failed with the reported read-only error. The task-error projection test also failed because it omitted the cause. - Green: 49 source and transport tests, 16 task projection and redaction tests, and 10 UI tests. The assembled preparation check passes. All 48 remote workspace lifecycle tests pass. The full preparation suite passed all 126 assertions but its cleanup hook exceeded 30 seconds. The unchanged base reproduces the same cleanup timeout with all 126 assertions passing. The focused preparation check finishes cleanly. - The real PostgreSQL/Git lifecycle checks cover both first-turn and later project attachments. They verify the configured release branch, saved edits, replacement allocations, unchanged source folders, committed archive contents, and released writers. - Review regressions were red before repair: the default ref became null, later attachment failed during restore, non-default remote branch checkout failed, and invalid secondary refs left partial checkouts. They now pass. - The local browser shows the workspace validation explanation and Retry action. The fixture uses a saved failed run; this proves the error display, not a successful live sandbox run. - `pnpm -r typecheck` and `pnpm build` pass. Map, module-boundary and token checks pass. - A local two-turn acceptance probe repeated at `17ed67eaa7` used real Codex CLI 0.165.0, `gpt-6-astra`, and `xhigh` effort. Codex wrote files in both task repositories. The services saved them, removed the first allocation and its Git sources, restored another allocation, and Codex read the saved files and wrote a follow-up in both folders. This uses the real source resolver and persistence services with a local command-runner stand-in for sandbox transport. It does not qualify Daytona, managed subscription forwarding, or the original task. The first probe waited for stdin; closing the test harness pipe fixed that setup error before provider work. - `pnpm test:run` passed the first chat shard, then failed one chat response concurrency assertion in the second shard. That case passes in isolation on this head. The same isolated chat case passes on the unchanged base. Both corresponding unchanged-base chat shards also pass (351 and 324 tests). The cause of the earlier wider-suite chat failure is not established. The preparation cleanup timeout and chat failure remain part of this record. - CI at `17ed67eaa7`: all other verification jobs passed. Browser shard 6 initially reported a request callback from the preceding test after teardown; its single unchanged-code retry passed. Server shard 10 timed out the 2,100-row retention confirmation fixture at 15 seconds on both attempts. That exact case passes locally, but the repeated CI failure required a repair. Its setup repeatedly rebuilt a shared-workspace privacy map. The logs and failures remain part of this record. - Reused the test-only repair from #18774 without changing its source file. At `ab774e9418`, all 54 retention tests and all 25 ordinary production privacy tests pass locally (79 total). Full CI [41650626903](https://github.com/paperclipai/paperclip/actions/runs/41650626903) passed on that commit, and its exact-head Greptile review was 5/5. The fixture preserves its 2,100 rows, query-bound assertions, privacy-source map, and completed-history test deadlines. - The additional review identified retained-source access/trust denials that still bypassed the workspace explanation. Real-resolver regressions reproduced both plain-403 failures before the correction. Both now yield a safe workspace validation explanation, while the dedicated low-trust denial and saved workspace remain unchanged. The optional duplicate ref-resolution block is also consolidated. - Final review corrections: 65 source, transport and error-projection tests passed, followed by all 48 lifecycle cases against an owned disposable PostgreSQL database (113 total). The initial combined command skipped the explicitly gated lifecycle suite; the subsequent dedicated invocation enabled and passed all 48. Full workspace typecheck and build pass. The first standalone lifecycle launcher lacked the repository TypeScript loader; rerunning with that loader resolved its import setup error. At previous head `7be02ea09c4ac76df560e8b517050cdf398f33f0`, full CI [41654422329, attempt 2](https://github.com/paperclipai/paperclip/actions/runs/41654422329/attempts/2) passed, Greptile is 5/5 on that exact head, and all review threads are resolved. The first attempt timed out the unchanged voice-session report/history case at 15 seconds; 3,027 cases in its shard passed. That exact case passed locally, then its single unchanged-code shard retry passed. The wider-suite timeout cause remains unproven. The completed Paperclip advisory check is neutral; its earlier findings are corrected. No staging deployment or original-task recovery is claimed. - Master advanced while checks ran, producing conflicts in two adjacent test additions. Merged `27d35314be` into this branch as `d5c8d552939c86056abf8fe10833881b2ade41a4`, preserving both workspace-error tests and the audited Stop/receipt tests. Kept workspace maps to minimal corrections under the updated map rule. All 82 source, transport and interruption cases, all 48 real-database save/restore lifecycle cases, full typecheck, build, and map checks pass locally on the combined code. Current-head [CI 41660719214](https://github.com/paperclipai/paperclip/actions/runs/41660719214) and Greptile are pending; the earlier verified head has not been merged. ## Risks - Additional remote project repositories are now editable task copies. Shared source folders and upstream push permissions do not change. - Snapshot coverage uses existing workspace metadata. Older workspaces capture their previous inventory at reservation; successful save publication advances coverage and snapshot identity in one transaction. No SQL migration is needed. - A retained copy can contain files from a project that is no longer mentioned. Preparation rechecks that project's current access and trust policy before reuse. - Explicit read-only descriptors still fail. Source-less projects remain metadata-only. Local folders still require import. No migration or provider-pack update is needed. - Error display reads only workspace validation errors. The existing run-secret registry and username censor run before display truncation. A redaction failure omits the explanation. - The retained fixture repair pauses its row trigger only within the isolated seed transaction, rebuilds the exact source map, and restores the trigger before commit. A rollback regression and 25 ordinary privacy cases pass. Its paged-case test budget honors the existing bounded inner waits; production deadlines are unchanged. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, tool use and code execution. The exact serving model ID and context-window size are not exposed by this session. The test-only fixture changes are reused from #18774, whose model record identifies OpenAI GPT-6.1 Sol. The optional live acceptance probe uses `gpt-6-astra` with `xhigh` effort through Codex CLI 0.165.0. ## 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>
15 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Workspaces, services, and files
A project or task can use a managed workspace with inspectable files, Git state, services, and runtime controls. Operators can follow its lifecycle through provisioning, use, and closure.
Feature ID: workspaces.
Implementation: workspace list, execution workspace, project workspace.
Agent access: companion.
Sub-features
binding:workspaces/binding— identify the workspace actually bound to a task/run.provisioning:workspaces/provisioning— observe readiness and failures instead of inferring readiness from a created record.services:workspaces/services— start/stop supported services and inspect logs and exposed endpoints.files-git:workspaces/files-git— inspect workspace files and repository state used for the deliverable.closure:workspaces/closure— close/reopen or reconcile through permitted controls without losing work.
For a historical failed export whose exact sandbox was destroyed, the task recovery notice offers Continue from saved sources to an authorized board operator. Select surviving task attachments, record lost work and external action outcomes, then rebuild through fresh-session admission. The old failed run remains failed. Bounded bootstrap retries retain this decision and recheck their system wake, predecessors, saved files and current execution gates before provider startup. Later cancelled runs require their own confirmed stop and board file repair. Their evidence is preserved with the reconstruction and rechecked before dispatch. Stop retains unfinished native files; startup also repairs missing historical retention without replaying the cancelled turn. Daytona stop-only cleanup confirms retention and accepts an already archived source. Cancelled native file recovery can record a verified no-action outcome. Its confirmation stays optional and resets when the source changes. Retained sandboxes keep their existing export recovery path. Automated coverage: reconstruction. Live staging acceptance remains separate from these regression tests.
How to get to it (user POV)
task-workspace
Use the task’s workspace card or Files panel and follow its workspace link.
workspace-management
Open /workspaces, a project workspace, or /execution-workspaces/:workspaceId and its Services/Configuration/Runtime logs views.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Enable isolated-workspace UI where needed. Use an owned disposable repository and environment; record workspace ID and branch.
task-workspace
Automated: workspace card and task binding cover host/binding contracts.
Manual: Run a task that writes a small file, follow the bound workspace, and inspect the file and revision. Reload and verify links still refer to the same workspace, not another checkout or a stale run.
For experimental native remote storage, follow the
deployment prerequisites and explicit local import.
With durable Postgres, S3, and a stable key configured, a new disposable
Paperclip Runner sandbox task with a supported fresh source enrolls by default.
Verify an explicit remoteWorkspaceStorageEnabled: false disables new enrollment,
and an existing host workspace or configured local folder stays on its legacy
path until explicitly imported. An enrolled workspace must keep remote authority
when enrollment is disabled and fail admission if persistence prerequisites are
lost. Write ordinary/binary files and, for Git, staged, unstaged, and unpushed
work. Finish the run and inspect its saved version. Replace the webserver and
verify the next task turn uses the same remote folder without a controller
checkout. Then release the saved allocation and verify a new one restores the
files, Git state, and managed same-project repositories without the old sandbox
or original Git remote. Authorized referenced Git repositories must be editable
task copies; explicitly read-only sources must fail admission. Separate workspaces
may run concurrently; shared concurrent writers
must be rejected.
The Files panel must label Live workspace or Saved copy with its save time. Confirm browse, preview, and download agree. A missing allocation with unsaved work must report unavailability rather than show an old save as current. Close must retain dirty/unfinished work and reject custom cleanup/teardown commands; a clean saved workspace can release compute while retaining files. Manual runtime commands, jobs, repairs, and service starts must reject remote workspaces before local filesystem access; agent task execution remains supported. The archive, storage, migration, retention, and lifecycle regression suites exercise these contracts separately. This recipe records required deployment checks; it does not claim a live provider or webserver replacement passed.
For a repository-free isolated task, complete an explicitly fresh retry, save a marker, then send ordinary new input. It must retain the bound attempt directory and marker. A later explicitly fresh retry must use a separate clean sibling. The production preparation regression uses PostgreSQL and real private directories; it also rejects changed bindings. The directory boundary suite checks namespace, missing-directory and symlink refusal. Neither suite proves a hosted provider turn.
For slow source preparation, configure a short PostgreSQL idle-transaction timeout in a disposable instance. Hold preparation beyond that interval and verify it retains its source lock, rejects competing preparation, and leaves ordinary reads available. The source-lock regression uses real PostgreSQL; it does not prove provider startup or deployed recovery.
Create an authorized task whose selected checkout is also used by private historical
tasks and many old workspace records. Start and reuse it without a historical-source
permission failure or remote-clone fallback. Verify task-bound file browsing works,
while private historical task content and operation logs remain denied through app
APIs. Root traversal and symlink escapes must remain rejected. The OS and execution
environment own isolation between agents; Paperclip does not classify existing bytes
by the task that wrote them. Existing workspace_source_restricted failures remain
inspectable and recoverable, but new preparation does not produce that failure from
filesystem history. Current trust, credential, binding, and publication checks still
apply. The preparation-history benchmark supplies local service measurements, not
provider deployment qualification.
For reconstructable Git expiration, finish a disposable task tree, run the internal lifecycle sweep after its 24-hour grace, and inspect candidate/reclaimed bytes. Advance its upstream first; use the ordinary task/workspace reopen control and verify the original commit, file contents, and subsequent persisted work. Current runs, previews, recovery, unique files and shared base clones must stay. The expiration tests exercise real local Git and database paths, interruption and concurrent reopening; cloud credentials and the deployed user journey require separate live evidence.
For task workspace selection, use the authorized task workspace API to choose a task directory, project source, or existing workspace. Verify that a change made during a run stays pending until the next normal admission. Submit another choice using the returned revision, then retry the superseded request; it must fail without replacing the newer pending choice. A projectless task must retain its files across resume and reassignment. Use the repository preparation API to add an authorized repository beneath that workspace; repeat the request and verify that it reuses the checkout and pinned revision. See task binding tests and repository access tests.
For native unfinished work, yield after preparation is staged and verify that normal admission prepares the repository and continues the same task without a timer or user message. A staging-only task that finishes must not wake again. The saved continuation must disappear when the repository is ready or belongs to another task. Source regressions cover those eligibility checks; a live provider journey is required to qualify the complete automatic resume.
An existing projectless folder alias of a sandbox-restricted project must be rejected for a standard local task before its adapter executes. Repeat after relocating the configured source; retained ownership must still enforce the boundary. This is separate from ordinary authorized file preview/download. For a registered worktree selected for a sandbox or SSH environment, configured and built-in provision scripts must not run on the controller during fresh creation, reuse, or rebuild, including host runtime provisioning. Repeat with standard trust and a protected read-only source, then with source write grants; permissions must not change execution placement. Verify isolated source copying and selected-environment dispatch still work. Repeat an explicit local isolated source choice: copying remains available but controller scripts must stay absent, including after binding or metadata changes and closed-worktree reopening. An implicit trusted local project default remains a positive provisioning control. Repeat with a newer configured default overriding an older primary source, then with a newer primary overriding an older nonprimary source. Both configured and built-in hooks must run for the implicit local default. Task creation and controller classification share configured-default, primary, creation-time and ID precedence. Explicit choices and saved copy-only markers still suppress hooks; changing the default must not rotate an existing binding or clear its marker. SSH keeps its explicit remote provision-command path; these checks do not claim a new sandbox provision transport. Low-trust closed-worktree reopening, including a board-comment reopen of a projectless task, must also suppress both kinds of host provision script. Returned checkpoints must reject file, symlink or missing parents before host writes, even if a nested file is marked unchanged. The retained host file and recovery evidence must survive rejection. These are automated safety contracts, not new live runtime acceptance.
An unchanged returned snapshot skips the host scan after acquiring the writer lock and checking authority. Concurrent host edits remain untouched; changed files, modes, symlinks and deletions still take the conflict path. The unchanged restore regression checks both hooks under the lock. This is source-level coverage, not a cloud latency result.
For a child created by an admitted agent with an explicit existing workspace, verify that a matching sandbox boundary permits creation before the child has an ID. A changed child policy, unrelated parent, or forged creator run must fail. See the child workspace trust regression. This automated contract does not add live acceptance evidence.
workspace-management
Automated: workspace detail and runtime service cover UI and runtime contracts separately.
Manual: Provision a disposable workspace, wait for readiness, start an available service, open its endpoint, and inspect a real response and logs. Stop it and verify it actually stops. Exercise close/reopen only after inspecting pending changes and active runs.
Gotchas
-
UI visibility, default isolation policy, the local environment row, a workspace record, and a running service are distinct prerequisites. A fresh instance still needs an owned cwd/repository and runtime commands;
/workspaceslists existing work. Reopening depends on lifecycle, not a generic detail action. -
A link or running badge does not prove the service is reachable from the user’s browser.
-
Workspace IDs, runtime leases, and repository paths are not interchangeable.
-
Remote workspace snapshots require external Postgres, S3, and the original encryption key. Edits after the last save still depend on the sandbox; there is no periodic workspace backup. The experiment does not remove the instance volume or establish zero-outage deployment for other data paths.
-
Terminal workspace cleanup wakes after committed task/workspace/PR changes and restores cooldown deadlines at startup. Empty lanes stop scanning. Metadata reads do not inspect storage. Compatible records share one advisory Git inspection per bounded page, while each record keeps its own delivery check. Destructive cleanup starts a separate Git scan even if an older scan is running. The worker tests cover quiet lanes and deadlines. The service tests cover real PostgreSQL signals and retained worktrees. These tests do not qualify an external wake alarm or a live provider deployment.
-
Organizational project, source project, task files, personal
AGENT_HOME, and provider home have separate meanings. Private source ownership remains attached to copied files after source configuration changes or workspace closure. -
Use recovery for divergence/export repair and CLI operations for local worktree tooling.
Storybook verification
closure
Capability ID: workspaces/closure.
Scope: ui Storybook: Close-readiness checks, pending changes/active runs, blocked/pending/error close, retry close and eligible reopening. Production: Confirm owned workspace shutdown, preserved files/Git state and permitted lifecycle transition/reopening; Browser Use session closure is unrelated. Sources: Source: ExecutionWorkspaceDetail.tsx, ExecutionWorkspaceCloseDialog.tsx, execution-workspaces.ts. Tests: execution-workspaces-routes.test.ts, execution-workspaces-service.test.ts, execution-workspace-reopen.test.ts