PaperClipAI/doc/project-environment-compatibility.md

Project environments and repository storage

A repository project belongs to one storage owner. Creation shows Available in when the configured environments require more than one owner. Each choice names all environments that use that owner. An environment choice saves both the storage owner and the project's environmentId. This is a project-owned execution target, not a company or agent setting. Compatible environments can share its repository storage.

Compatibility rule

Use the existing workspace execution contract, not environment names, driver names alone, images, operating systems, endpoints, or complete config equality:

• Local, SSH, and sandbox environments use core repository staging. They can use the same repository project even across driver types and sandbox providers.
• Plugin-managed storage belongs to an installed plugin ID. It can be consumed only by that plugin's registered environment_driver with supportsTasks: true. Its manifest must declare environment.drivers.register, workspaces.manage, a workspace provider, and the project resource lifecycle.
• Two task environments from that installed plugin share its project storage contract, even when their other settings differ. Storage operations are scoped by company, project, and plugin; they do not take an environment configuration. Separate installed storage plugins remain incompatible even when both use the plugin driver. Core cannot transfer their managed bindings between them.
• Unknown plugin drivers and the probe-only fake sandbox do not establish a compatible project storage contract. They are excluded from creation choices.

These are project repository compatibility rules. They do not assert that arbitrary local paths exist remotely, that a retained task workspace can switch hosts, or that an adapter, credential, image, or running worker is ready. Existing run-time validation still checks those conditions. Cross-plugin storage sharing would require a new execution/storage contract; matching config fields cannot establish it.

Defaults and validation

For an agent API request, use that agent's default environment. For a person, use their primary agent's default environment when present. Fall back to the instance default, then local execution. There is no separate user or company defaultEnvironmentId setting today. Managed-only and forced Kubernetes policies retain their execution restrictions and default redirection.

GET /api/companies/:companyId/project-environments returns environment IDs and names grouped by storage owner, plus the caller's effective default. It excludes archived environments, disabled/uninstalled storage plugins, and managed environments bound only to another company. It does not contact workers or return provider configs, credentials, endpoints, or host paths. A cold worker does not change a durable storage choice.

POST /api/companies/:companyId/projects accepts an optional environmentId. The server validates the choice again and stores its storage owner and environment on that project. Creation saves the effective default once; changing the instance or primary agent later does not rewrite existing projects. Compatible environments share repository storage; the saved environment is the run target. An explicit executionWorkspacePolicy.storageProviderPluginId continues to work. The UI sends both the environment and its observed storage owner in expectedStorageProviderPluginId, so a changed environment cannot silently select different storage. This guard does not create a workspace-mode policy; instance task-isolation defaults remain inherited. An explicit policy and environment must agree when both are supplied. Without either, storage follows the caller's effective environment. A plugin's defaultForProjects claim alone no longer attaches a project to that plugin.

The hidden repository-free “My private tasks” project is independent of environment/storage availability, so creating a private note never requires repairing an environment.

An unavailable configured default produces an error and permits an explicit available choice. It does not silently select another storage owner. Existing projects keep their stored owner. This change does not migrate managed storage or detach projects that contain existing work. A managed project run in an incompatible environment fails with project_environment_incompatible before a workspace provider operation, with a message naming the storage and environment.

Project Configuration

PATCH /api/projects/:id accepts environmentId and the optional expectedStorageProviderPluginId precondition. The Environment selector reads and writes this project field, independently of checkout/isolation settings. Changing one project never changes another project, the agent, or instance settings. Only environments compatible with the project's current storage are offered. Changing storage ownership is subject to the existing retained-data safeguards.

Ordinary run selection uses the project's saved target before the agent default, instance default, and local fallback. A null project target explicitly inherits those defaults. An operator-selected low-trust task sandbox and enforced sandbox policies retain precedence. Provider API execution keeps its existing placement.

The migration preserves existing valid project-policy environment selections in the new project field. Older clients may still write the policy field; the service normalizes it into the project association. Existing projects with no selection remain unset. Environment deletion counts and clears only matching associations.

Changing or clearing placement requires project workspace-write authority. A saved selection is checked against company bindings before runtime admission and again during lease creation. Recovery uses the admitted run's owned environment lease; a later project edit affects new admissions. The task's organizational project owns placement even when its files come from another project.