From aa2a7be8b4772d72f785d3732a19a392e8f6a459 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Tue, 10 Nov 2026 17:22:01 -0600 Subject: [PATCH] fix: recognize provider-owned Runner workspace storage (#20663) ## Thinking Path > - Paperclip manages agent work and preserves its execution state. > - A server replacement must retain every workspace that depends on the old server disk. > - Runner task environments can own their workspace outside the Core server. > - These environments save an adapter-managed workspace with a runnerTaskWorkspaceOwner binding. > - Readiness and maintenance treated that provider path as a Core filesystem dependency. > - This change validates the saved owner and shares that classification between both paths. > - Local, malformed, and foreign workspace bindings still block enrollment. ## Linked Issues or Issue Description Related enrollment safeguards: #18835. A GitHub search found no duplicate fix for this provider-owned class. **What happened?** Volume-free readiness returned workspaces_require_migration for an adapter-managed Runner workspace owned by a plugin task environment. Maintenance also selected it and failed with workspace_provider_unsupported. The provider owned the path, which did not exist on the Core server. **Expected behavior** A valid provider-owned workspace does not require migration from the Core server disk. Ordinary local workspaces and invalid ownership bindings remain blockers. **Steps to reproduce** 1. Run a paperclip_runner agent in a plugin task environment. 2. Retain its adapter-managed workspace and complete runnerTaskWorkspaceOwner binding. 3. Read startup eligibility for volume-free enrollment. 4. Observe the workspace blocker before this fix. 5. Run workspace maintenance and observe workspace_provider_unsupported for the same row. **Paperclip version or commit** Reproduced on 353945c86daedc13de0f23bdf8baf1e35f718e71. The regression also fails on the branch base a3b34a9d88. **Deployment mode** Docker with external PostgreSQL. Local regression coverage uses disposable PostgreSQL. ## What Changed - Share one metadata predicate between startup eligibility and offline workspace migration selection. - Validate a complete saved owner against a same-company paperclip_runner agent and a plugin environment with matching nonempty keys. Per-run environment overrides remain supported. - Keep ordinary local workspaces and invalid ownership bindings in the migration set. - Add real PostgreSQL coverage for provider-owned readiness, zero-import maintenance selection, unchanged retained rows, and local/foreign/malformed ownership controls. ## Verification - Readiness RED: the provider-owned fixture failed with workspaces_require_migration on unchanged source. - Maintenance RED: the provider-owned fixture failed with workspace_provider_unsupported before the shared selector was applied. - GREEN: 29 selected tests passed across three files. This covers 8 eligibility/configuration tests and 21 migration/offline-admission cases, including eleven invalid/local owner controls inside the eligibility test. The affected migration file has 207 cases; broad coverage remains with required CI. - Commands: `pnpm exec vitest run server/src/__tests__/ephemeral-server-data.test.ts server/src/__tests__/ephemeral-server-contract.test.ts` plus focused selections in `server/src/services/remote-workspace-migration.test.ts` for provider ownership, offline admission, local imports, interrupted-batch resume, and unresolved workspace semantics. - Server layered typecheck passed after the final source change. - Final head `2fb98dbc664da14e6f60d812e1e10877b2b7f00a`: [required CI](https://github.com/paperclipai/paperclip/actions/runs/42920262773) completed with 55 successful checks, 1 neutral review, and 4 intended skips. Greptile and Paperclip Review both rated this head 5/5. No unresolved review threads remain. - No hosted data migration or metadata rewrite was performed. ## Risks - This changes a readiness classification. Incomplete, foreign, non-Runner, or mismatched environment bindings remain conservative blockers. - The check validates saved ownership through current database bindings. It does not inspect provider files or grant execution authority. - Existing saved rows retain their shape. No migration or archive format changes are required. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, repository tools, code editing, and real PostgreSQL tests. The host does not expose the exact model ID or 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 --- .../__tests__/ephemeral-server-data.test.ts | 71 ++++++++++++++++++- .../src/services/ephemeral-server-contract.ts | 7 +- .../services/local-workspace-dependencies.ts | 27 +++++++ .../remote-workspace-migration-batch.ts | 9 ++- .../remote-workspace-migration.test.ts | 21 ++++++ 5 files changed, 125 insertions(+), 10 deletions(-) create mode 100644 server/src/services/local-workspace-dependencies.ts diff --git a/server/src/__tests__/ephemeral-server-data.test.ts b/server/src/__tests__/ephemeral-server-data.test.ts index 0baadc1068c..fdb0c119dd5 100644 --- a/server/src/__tests__/ephemeral-server-data.test.ts +++ b/server/src/__tests__/ephemeral-server-data.test.ts @@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto"; import { beforeAll, afterAll, afterEach, expect, it, vi } from "vitest"; import { eq } from "drizzle-orm"; import type { Db } from "@paperclipai/db"; -import { agentFileRoots, agentInstructionWorkingCopies, agents, companies, companySkills, companySkillVersions, executionWorkspaces, heartbeatRuns, providerTraceRecords, createDb } from "@paperclipai/db"; +import { agentFileRoots, agentInstructionWorkingCopies, agents, companies, companySkills, companySkillVersions, environments, executionWorkspaces, heartbeatRuns, providerTraceRecords, createDb } from "@paperclipai/db"; import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js"; import { assertEphemeralServerData, readEphemeralServerDataEligibility } from "../services/ephemeral-server-contract.js"; import { initializeDurableAgentFiles } from "../services/agent-file-durability.js"; @@ -85,3 +85,72 @@ it("keeps an unsettled local instruction copy visible after its canonical files expect((await readEphemeralServerDataEligibility(db, { purpose: "startup" })).blockers) .not.toContain("local_instruction_copies_require_settlement"); }); + +it("recognizes a Runner workspace owned by its selected plugin environment", async () => { + vi.stubEnv("PAPERCLIP_DURABLE_AGENT_FILES", "true"); + const companyId = randomUUID(), agentId = randomUUID(), environmentId = randomUUID(); + const owner = { agentId, environmentId, pluginKey: "fixture.task-storage", driverKey: "tasks" }; + await db.insert(companies).values({ id: companyId, name: "Provider-owned workspace", issuePrefix: "PROV" }); + await db.insert(environments).values({ id: environmentId, name: `Task provider ${environmentId}`, + driver: "plugin", config: { pluginKey: owner.pluginKey, driverKey: owner.driverKey } }); + await db.insert(agents).values({ id: agentId, companyId, name: "Provider Runner", adapterType: "paperclip_runner" }); + await db.transaction(tx => initializeDurableAgentFiles(tx as unknown as Db, { id: agentId, companyId })); + const [workspace] = await db.insert(executionWorkspaces).values({ companyId, name: "Provider task", + mode: "shared_workspace", strategyType: "project_primary", providerType: "adapter_managed", + cwd: `/workspaces/provider-only-${randomUUID()}`, metadata: { runnerTaskWorkspaceOwner: owner } }).returning(); + try { + expect((await readEphemeralServerDataEligibility(db, { purpose: "startup" })).blockers) + .not.toContain("workspaces_require_migration"); + expect((await db.select().from(executionWorkspaces).where(eq(executionWorkspaces.id, workspace.id)))[0]).toEqual(workspace); + } finally { + await db.delete(executionWorkspaces).where(eq(executionWorkspaces.id, workspace.id)); + } +}); + +it("keeps local workspaces and invalid provider ownership as migration blockers", async () => { + vi.stubEnv("PAPERCLIP_DURABLE_AGENT_FILES", "true"); + const companyId = randomUUID(), foreignCompanyId = randomUUID(), agentId = randomUUID(), foreignAgentId = randomUUID(); + const localAgentId = randomUUID(), environmentId = randomUUID(), localEnvironmentId = randomUUID(), emptyEnvironmentId = randomUUID(); + const owner = { agentId, environmentId, pluginKey: "fixture.task-storage", driverKey: "tasks" }; + await db.insert(companies).values([{ id: companyId, name: "Workspace guards", issuePrefix: "OWNR" }, + { id: foreignCompanyId, name: "Foreign owner", issuePrefix: "OTHR" }]); + await db.insert(environments).values([ + { id: environmentId, name: `Provider ${environmentId}`, driver: "plugin", config: { pluginKey: owner.pluginKey, driverKey: owner.driverKey } }, + { id: localEnvironmentId, name: `Sandbox ${localEnvironmentId}`, driver: "sandbox", config: { pluginKey: owner.pluginKey, driverKey: owner.driverKey } }, + { id: emptyEnvironmentId, name: `Empty ${emptyEnvironmentId}`, driver: "plugin", config: { pluginKey: "", driverKey: "" } }, + ]); + await db.insert(agents).values([ + { id: agentId, companyId, name: "Runner owner", adapterType: "paperclip_runner" }, + { id: foreignAgentId, companyId: foreignCompanyId, name: "Foreign Runner", adapterType: "paperclip_runner" }, + { id: localAgentId, companyId, name: "Local process", adapterType: "process" }, + ]); + for (const agent of [{ id: agentId, companyId }, { id: foreignAgentId, companyId: foreignCompanyId }, { id: localAgentId, companyId }]) { + await db.transaction(tx => initializeDurableAgentFiles(tx as unknown as Db, agent)); + } + const [workspace] = await db.insert(executionWorkspaces).values({ companyId, name: "Retained local dependency", + mode: "shared_workspace", strategyType: "project_primary", providerType: "adapter_managed", + cwd: `/workspaces/provider-only-${randomUUID()}` }).returning(); + const invalidOwners: { name: string; providerType?: string; owner: unknown }[] = [ + { name: "ordinary local storage", providerType: "local_fs", owner }, + { name: "unmarked adapter storage", owner: undefined }, + { name: "empty marker", owner: {} }, + { name: "array marker", owner: [owner] }, + { name: "foreign company", owner: { ...owner, agentId: foreignAgentId } }, + { name: "local adapter", owner: { ...owner, agentId: localAgentId } }, + { name: "non-plugin environment", owner: { ...owner, environmentId: localEnvironmentId } }, + { name: "missing environment", owner: { ...owner, environmentId: "not-a-uuid" } }, + { name: "different plugin", owner: { ...owner, pluginKey: "fixture.other-storage" } }, + { name: "different driver", owner: { ...owner, driverKey: "other" } }, + { name: "empty provider binding", owner: { ...owner, environmentId: emptyEnvironmentId, pluginKey: "", driverKey: "" } }, + ]; + try { + for (const invalid of invalidOwners) { + await db.update(executionWorkspaces).set({ providerType: invalid.providerType ?? "adapter_managed", + metadata: invalid.owner === undefined ? {} : { runnerTaskWorkspaceOwner: invalid.owner } }).where(eq(executionWorkspaces.id, workspace.id)); + expect((await readEphemeralServerDataEligibility(db, { purpose: "startup" })).blockers, invalid.name) + .toContain("workspaces_require_migration"); + } + } finally { + await db.delete(executionWorkspaces).where(eq(executionWorkspaces.id, workspace.id)); + } +}); diff --git a/server/src/services/ephemeral-server-contract.ts b/server/src/services/ephemeral-server-contract.ts index c4d9ebc9daa..f68ad9bc816 100644 --- a/server/src/services/ephemeral-server-contract.ts +++ b/server/src/services/ephemeral-server-contract.ts @@ -8,6 +8,7 @@ import { hasLocalNativeHarnessObligations } from "./native-runtime/native-harnes import { hasLocalNativeControllerObligations } from "./native-runtime/native-controller-migration.js"; import { hasUnsettledLocalInstructionCopies } from "./agent-instruction-copy-preservation.js"; import { hasLocalRuntimeSkillObligations } from "./native-runtime/runtime-skill-preservation.js"; +import { localWorkspaceDependencyWhere } from "./local-workspace-dependencies.js"; import { ephemeralServerEnabled } from "./ephemeral-server-mode.js"; @@ -58,10 +59,8 @@ export async function readEphemeralServerDataEligibility(db: Db, options: { purp // empty directory on the replacement machine as the old server's content. const configured = await db.select({ id: agents.id, companyId: agents.companyId, name: agents.name, adapterConfig: agents.adapterConfig }).from(agents); if (configured.some(agent => agentInstructionsBundleMode(agent) === "external")) blockers.push("external_agent_instructions"); - const [localWorkspace] = await db.select({ id: executionWorkspaces.id }).from(executionWorkspaces).where(and( - isNotNull(executionWorkspaces.cwd), sql`${executionWorkspaces.providerType} <> 'plugin'`, - sql`coalesce(${executionWorkspaces.metadata}->'remoteWorkspace'->>'schema', '') <> 'paperclip.remote-workspace.v1'`, - )).limit(1); + const [localWorkspace] = await db.select({ id: executionWorkspaces.id }).from(executionWorkspaces) + .where(localWorkspaceDependencyWhere(db)).limit(1); if (localWorkspace) blockers.push("workspaces_require_migration"); const [localLog] = await db.select({ id: heartbeatRuns.id }).from(heartbeatRuns).where(and( eq(heartbeatRuns.logStore, "local_file"), isNotNull(heartbeatRuns.logRef), diff --git a/server/src/services/local-workspace-dependencies.ts b/server/src/services/local-workspace-dependencies.ts new file mode 100644 index 00000000000..e145204c0e3 --- /dev/null +++ b/server/src/services/local-workspace-dependencies.ts @@ -0,0 +1,27 @@ +import { and, eq, isNotNull, notExists, sql } from "drizzle-orm"; +import { agents, environments, executionWorkspaces, type Db } from "@paperclipai/db"; + +export function localWorkspaceDependencyWhere(db: Pick) { + const taskOwner = sql`${executionWorkspaces.metadata}->'runnerTaskWorkspaceOwner'`; + const pluginTaskWorkspace = db.select({ id: agents.id }).from(agents).innerJoin(environments, + sql`${environments.id}::text = ${taskOwner}->>'environmentId'`).where(and( + eq(executionWorkspaces.providerType, "adapter_managed"), + eq(agents.companyId, executionWorkspaces.companyId), eq(agents.adapterType, "paperclip_runner"), + sql`${agents.id}::text = ${taskOwner}->>'agentId'`, eq(environments.driver, "plugin"), + sql`jsonb_typeof(${taskOwner}) = 'object'`, + sql`jsonb_typeof(${taskOwner}->'agentId') = 'string'`, + sql`jsonb_typeof(${taskOwner}->'environmentId') = 'string'`, + sql`jsonb_typeof(${taskOwner}->'pluginKey') = 'string'`, + sql`jsonb_typeof(${taskOwner}->'driverKey') = 'string'`, + sql`jsonb_typeof(${environments.config}->'pluginKey') = 'string'`, + sql`jsonb_typeof(${environments.config}->'driverKey') = 'string'`, + sql`btrim(${taskOwner}->>'pluginKey') <> ''`, sql`btrim(${taskOwner}->>'driverKey') <> ''`, + sql`${environments.config}->>'pluginKey' = ${taskOwner}->>'pluginKey'`, + sql`${environments.config}->>'driverKey' = ${taskOwner}->>'driverKey'`, + )); + return and( + isNotNull(executionWorkspaces.cwd), sql`${executionWorkspaces.providerType} <> 'plugin'`, + sql`coalesce(${executionWorkspaces.metadata}->'remoteWorkspace'->>'schema', '') <> 'paperclip.remote-workspace.v1'`, + notExists(pluginTaskWorkspace), + ); +} diff --git a/server/src/services/remote-workspace-migration-batch.ts b/server/src/services/remote-workspace-migration-batch.ts index baa3f090739..55a529b7bba 100644 --- a/server/src/services/remote-workspace-migration-batch.ts +++ b/server/src/services/remote-workspace-migration-batch.ts @@ -1,8 +1,9 @@ -import { and, asc, desc, isNotNull, sql } from "drizzle-orm"; +import { asc, desc, sql } from "drizzle-orm"; import { executionWorkspaces, type Db } from "@paperclipai/db"; import type { StorageService } from "../storage/types.js"; import { offlineWorkspaceMigrationBlockers } from "./remote-workspace-migration-tree.js"; import { migrateRemoteWorkspace } from "./remote-workspace-migration.js"; +import { localWorkspaceDependencyWhere } from "./local-workspace-dependencies.js"; /** The Cloud maintenance process owns the stop-all-deployments precondition. * Imported records leave the pending set, so a restart resumes the same owner @@ -19,10 +20,8 @@ export async function migrateWorkspaceTrees(db: Db, input: { // supported subset. Silently skipping an unsupported provider or unsettled // lifecycle state would abandon files when the original volume is detached. const rows = await db.select({ companyId: executionWorkspaces.companyId, workspaceId: executionWorkspaces.id }) - .from(executionWorkspaces).where(and(isNotNull(executionWorkspaces.cwd), - sql`${executionWorkspaces.providerType} <> 'plugin'`, - sql`coalesce(${executionWorkspaces.metadata}->'remoteWorkspace'->>'schema', '') <> 'paperclip.remote-workspace.v1'`, - )).orderBy(desc(sql`length(${executionWorkspaces.cwd})`), asc(executionWorkspaces.id)).limit(25); + .from(executionWorkspaces).where(localWorkspaceDependencyWhere(db)) + .orderBy(desc(sql`length(${executionWorkspaces.cwd})`), asc(executionWorkspaces.id)).limit(25); if (!rows.length) return migrated; for (const workspace of rows) { input.signal.throwIfAborted(); diff --git a/server/src/services/remote-workspace-migration.test.ts b/server/src/services/remote-workspace-migration.test.ts index 892f33ab272..482f18a2802 100644 --- a/server/src/services/remote-workspace-migration.test.ts +++ b/server/src/services/remote-workspace-migration.test.ts @@ -81,6 +81,27 @@ describe.skipIf(!support.supported)("remote workspace migration", () => { return { companyId, workspaceId, issueId: issue!.id, cwd }; } async function workspace(id: string) { return (await db.select().from(executionWorkspaces).where(eq(executionWorkspaces.id, id)))[0]!; } + it("keeps provider-owned Runner task paths out of offline workspace migration", async () => { + vi.stubEnv("PAPERCLIP_EPHEMERAL_MIGRATION", "true"); + const companyId = randomUUID(), agentId = randomUUID(), environmentId = randomUUID(); + const owner = { agentId, environmentId, pluginKey: "fixture.task-storage", driverKey: "tasks" }; + await db.insert(companies).values({ id: companyId, name: "Provider-owned migration", issuePrefix: "PROV" }); + await db.insert(environments).values({ id: environmentId, name: `Provider ${environmentId}`, driver: "plugin", + config: { pluginKey: owner.pluginKey, driverKey: owner.driverKey } }); + await db.insert(agents).values({ id: agentId, companyId, name: "Provider Runner", adapterType: "paperclip_runner" }); + const [issue] = await db.insert(issues).values({ companyId, title: "Provider task" }).returning(); + const [retained] = await db.insert(executionWorkspaces).values({ companyId, sourceIssueId: issue.id, + name: "Provider path", mode: "shared_workspace", strategyType: "project_primary", providerType: "adapter_managed", + cwd: `/workspaces/provider-only-${randomUUID()}`, metadata: { runnerTaskWorkspaceOwner: owner } }).returning(); + await db.update(issues).set({ executionWorkspaceId: retained.id }).where(eq(issues.id, issue.id)); + const phase = vi.fn(); + await expect(migrateWorkspaceTrees(db, { storage, signal: new AbortController().signal, phase })).resolves.toBe(0); + expect(phase).not.toHaveBeenCalled(); + expect(await workspace(retained.id)).toEqual(retained); + await db.update(executionWorkspaces).set({ metadata: { runnerTaskWorkspaceOwner: {} } }).where(eq(executionWorkspaces.id, retained.id)); + await expect(migrateWorkspaceTrees(db, { storage, signal: new AbortController().signal, phase })) + .rejects.toThrow("workspace_provider_unsupported"); + }); async function queuedFixture() { const original = await seed(); vi.stubEnv("PAPERCLIP_HOME", await fs.realpath(root));