PaperClipAI/maps/feature-map/workspaces.md

Execution 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.

Implementation: workspace list, execution workspace, project workspace.

Agent access: companion.

Sub-features

• binding: identify the workspace actually bound to a task/run.
• provisioning: observe readiness and failures instead of inferring readiness from a created record.
• services: start/stop supported services and inspect logs and exposed endpoints.
• files-git: inspect workspace files and repository state used for the deliverable.
• closure: close/reopen or reconcile through permitted controls without losing work.

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 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. 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.

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; /workspaces lists 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.

• 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.