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 353945c86d. 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 <noreply@paperclip.ing>

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));
+  }
+});

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),

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<Db, "select">) {
+  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),
+  );
+}

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();

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));