Stabilize serialized server route tests (#4448)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - The server route suite is a core confidence layer for auth, issue
context, and workspace runtime behavior
> - Some route tests were doing extra module/server isolation work that
made local runs slower and more fragile
> - The stable Vitest runner also needs to pass server-relative exclude
paths to avoid accidentally re-including serialized suites
> - This pull request tightens route test isolation and runner
serialization behavior
> - The benefit is more reliable targeted and stable-route test
execution without product behavior changes

## What Changed

- Updated `run-vitest-stable.mjs` to exclude serialized server tests
using server-relative paths.
- Forced the server Vitest config to use a single worker in addition to
isolated forks.
- Simplified agent permission route tests to create per-request test
servers without shared server lifecycle state.
- Stabilized issue goal context route mocks by using static mocked
services and a sequential suite.
- Re-registered workspace runtime route mocks before cache-busted route
imports.

## Verification

- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/agent-permissions-routes.test.ts
server/src/__tests__/issues-goal-context-routes.test.ts
server/src/__tests__/workspace-runtime-routes-authz.test.ts --pool=forks
--poolOptions.forks.isolate=true`
- `node --check scripts/run-vitest-stable.mjs`

## Risks

- Low risk. This is test infrastructure only.
- The stable runner path fix changes which tests are excluded from the
non-serialized server batch, matching the server project root that
Vitest applies internally.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5 coding agent, tool-enabled with
shell/GitHub/Paperclip API access. Context window was not reported by
the runtime.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

scripts/run-vitest-stable.mjs

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 
 const repoRoot = process.cwd();
+const serverRoot = path.join(repoRoot, "server");
 const serverTestsDir = path.join(repoRoot, "server", "src", "__tests__");
 const nonServerProjects = [
   "@paperclipai/shared",
@@ -63,6 +64,10 @@ function toRepoPath(file) {
   return path.relative(repoRoot, file).split(path.sep).join("/");
 }
 
+function toServerPath(file) {
+  return path.relative(serverRoot, file).split(path.sep).join("/");
+}
+
 function isRouteOrAuthzTest(file) {
   if (routeTestPattern.test(file)) {
     return true;
@@ -99,10 +104,13 @@ function runVitest(args, label) {
 
 const routeTests = walk(serverTestsDir)
   .filter((file) => isRouteOrAuthzTest(toRepoPath(file)))
-  .map((file) => ({ repoPath: toRepoPath(file) }))
+  .map((file) => ({
+    repoPath: toRepoPath(file),
+    serverPath: toServerPath(file),
+  }))
   .sort((a, b) => a.repoPath.localeCompare(b.repoPath));
 
-const excludeRouteArgs = routeTests.flatMap((file) => ["--exclude", file.repoPath]);
+const excludeRouteArgs = routeTests.flatMap((file) => ["--exclude", file.serverPath]);
 for (const project of nonServerProjects) {
   runVitest(["--project", project], `non-server project ${project}`);
 }

server/src/__tests__/issues-goal-context-routes.test.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { errorHandler } from "../middleware/index.js";
+import { issueRoutes } from "../routes/issues.js";
 
 const mockIssueService = vi.hoisted(() => ({
   getById: vi.fn(),
@@ -32,72 +34,86 @@ const mockExecutionWorkspaceService = vi.hoisted(() => ({
   getById: vi.fn(),
 }));
 
-function registerModuleMocks() {
+const mockAccessService = vi.hoisted(() => ({
-  vi.doMock("../services/index.js", () => ({
+  canUser: vi.fn(),
-    accessService: () => ({
+  hasPermission: vi.fn(),
-      canUser: vi.fn(),
+}));
-      hasPermission: vi.fn(),
-    }),
-    agentService: () => ({
-      getById: vi.fn(),
-    }),
-    documentService: () => mockDocumentsService,
-    environmentService: () => ({}),
-    executionWorkspaceService: () => mockExecutionWorkspaceService,
-    feedbackService: () => ({
-      listIssueVotesForUser: vi.fn(async () => []),
-      saveIssueVote: vi.fn(async () => ({ vote: null, consentEnabledNow: false, sharingEnabled: false })),
-    }),
-    goalService: () => mockGoalService,
-    heartbeatService: () => ({
-      wakeup: vi.fn(async () => undefined),
-      reportRunActivity: vi.fn(async () => undefined),
-    }),
-    instanceSettingsService: () => ({
-      get: vi.fn(async () => ({
-        id: "instance-settings-1",
-        general: {
-          censorUsernameInLogs: false,
-          feedbackDataSharingPreference: "prompt",
-        },
-      })),
-      listCompanyIds: vi.fn(async () => ["company-1"]),
-    }),
-    issueApprovalService: () => ({}),
-    issueReferenceService: () => ({
-      deleteDocumentSource: async () => undefined,
-      diffIssueReferenceSummary: () => ({
-        addedReferencedIssues: [],
-        removedReferencedIssues: [],
-        currentReferencedIssues: [],
-      }),
-      emptySummary: () => ({ outbound: [], inbound: [] }),
-      listIssueReferenceSummary: async () => ({ outbound: [], inbound: [] }),
-      syncComment: async () => undefined,
-      syncDocument: async () => undefined,
-      syncIssue: async () => undefined,
-    }),
-    issueService: () => mockIssueService,
-    logActivity: vi.fn(async () => undefined),
-    projectService: () => mockProjectService,
-    routineService: () => ({
-      syncRunStatusForIssue: vi.fn(async () => undefined),
-    }),
-    workProductService: () => ({
-      listForIssue: vi.fn(async () => []),
-    }),
-  }));
 
-  vi.doMock("../services/execution-workspaces.js", () => ({
+const mockAgentService = vi.hoisted(() => ({
-    executionWorkspaceService: () => mockExecutionWorkspaceService,
+  getById: vi.fn(),
-  }));
+}));
-}
 
-async function createApp() {
+const mockFeedbackService = vi.hoisted(() => ({
-  const [{ issueRoutes }, { errorHandler }] = await Promise.all([
+  listIssueVotesForUser: vi.fn(async () => []),
-    vi.importActual<typeof import("../routes/issues.js")>("../routes/issues.js"),
+  saveIssueVote: vi.fn(async () => ({ vote: null, consentEnabledNow: false, sharingEnabled: false })),
-    vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),
+}));
-  ]);
+
+const mockHeartbeatService = vi.hoisted(() => ({
+  wakeup: vi.fn(async () => undefined),
+  reportRunActivity: vi.fn(async () => undefined),
+}));
+
+const mockInstanceSettingsService = vi.hoisted(() => ({
+  get: vi.fn(async () => ({
+    id: "instance-settings-1",
+    general: {
+      censorUsernameInLogs: false,
+      feedbackDataSharingPreference: "prompt",
+    },
+  })),
+  listCompanyIds: vi.fn(async () => ["company-1"]),
+}));
+
+const mockIssueReferenceService = vi.hoisted(() => ({
+  deleteDocumentSource: vi.fn(async () => undefined),
+  diffIssueReferenceSummary: vi.fn(() => ({
+    addedReferencedIssues: [],
+    removedReferencedIssues: [],
+    currentReferencedIssues: [],
+  })),
+  emptySummary: vi.fn(() => ({ outbound: [], inbound: [] })),
+  listIssueReferenceSummary: vi.fn(async () => ({ outbound: [], inbound: [] })),
+  syncComment: vi.fn(async () => undefined),
+  syncDocument: vi.fn(async () => undefined),
+  syncIssue: vi.fn(async () => undefined),
+}));
+
+const mockLogActivity = vi.hoisted(() => vi.fn(async () => undefined));
+
+const mockRoutineService = vi.hoisted(() => ({
+  syncRunStatusForIssue: vi.fn(async () => undefined),
+}));
+
+const mockWorkProductService = vi.hoisted(() => ({
+  listForIssue: vi.fn(async () => []),
+}));
+
+const mockEnvironmentService = vi.hoisted(() => ({}));
+
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  documentService: () => mockDocumentsService,
+  environmentService: () => mockEnvironmentService,
+  executionWorkspaceService: () => mockExecutionWorkspaceService,
+  feedbackService: () => mockFeedbackService,
+  goalService: () => mockGoalService,
+  heartbeatService: () => mockHeartbeatService,
+  instanceSettingsService: () => mockInstanceSettingsService,
+  issueApprovalService: () => ({}),
+  issueReferenceService: () => mockIssueReferenceService,
+  issueService: () => mockIssueService,
+  logActivity: mockLogActivity,
+  projectService: () => mockProjectService,
+  routineService: () => mockRoutineService,
+  workProductService: () => mockWorkProductService,
+}));
+
+vi.mock("../services/execution-workspaces.js", () => ({
+  executionWorkspaceService: () => mockExecutionWorkspaceService,
+}));
+
+function createApp() {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -147,16 +163,9 @@ const projectGoal = {
   updatedAt: new Date("2026-03-20T00:00:00Z"),
 };
 
-describe("issue goal context routes", () => {
+describe.sequential("issue goal context routes", () => {
   beforeEach(() => {
-    vi.resetModules();
+    vi.clearAllMocks();
-    vi.doUnmock("../services/index.js");
-    vi.doUnmock("../services/execution-workspaces.js");
-    vi.doUnmock("../routes/issues.js");
-    vi.doUnmock("../routes/authz.js");
-    vi.doUnmock("../middleware/index.js");
-    registerModuleMocks();
-    vi.resetAllMocks();
     mockIssueService.getById.mockResolvedValue(legacyProjectLinkedIssue);
     mockIssueService.getAncestors.mockResolvedValue([]);
     mockIssueService.getRelationSummaries.mockResolvedValue({ blockedBy: [], blocks: [] });
@@ -213,7 +222,7 @@ describe("issue goal context routes", () => {
   });
 
   it("surfaces the project goal from GET /issues/:id when the issue has no direct goal", async () => {
-    const res = await request(await createApp()).get("/api/issues/11111111-1111-4111-8111-111111111111");
+    const res = await request(createApp()).get("/api/issues/11111111-1111-4111-8111-111111111111");
 
     expect(res.status).toBe(200);
     expect(res.body.goalId).toBe(projectGoal.id);
@@ -231,7 +240,7 @@ describe("issue goal context routes", () => {
   });
 
   it("surfaces the project goal from GET /issues/:id/heartbeat-context", async () => {
-    const res = await request(await createApp()).get(
+    const res = await request(createApp()).get(
       "/api/issues/11111111-1111-4111-8111-111111111111/heartbeat-context",
     );
 
@@ -257,7 +266,7 @@ describe("issue goal context routes", () => {
       updatedAt: new Date("2026-04-19T12:00:00.000Z"),
     });
 
-    const res = await request(await createApp()).get(
+    const res = await request(createApp()).get(
       "/api/issues/11111111-1111-4111-8111-111111111111/heartbeat-context",
     );
 
@@ -288,7 +297,7 @@ describe("issue goal context routes", () => {
       blocks: [],
     });
 
-    const res = await request(await createApp()).get(
+    const res = await request(createApp()).get(
       "/api/issues/11111111-1111-4111-8111-111111111111/heartbeat-context",
     );
 
@@ -323,7 +332,7 @@ describe("issue goal context routes", () => {
       ],
     });
 
-    const res = await request(await createApp()).get(
+    const res = await request(createApp()).get(
       "/api/issues/11111111-1111-4111-8111-111111111111/heartbeat-context",
     );
 

server/src/__tests__/workspace-runtime-routes-authz.test.ts

@@ -56,9 +56,37 @@ vi.mock("../routes/workspace-runtime-service-authz.js", () => ({
   assertCanManageExecutionWorkspaceRuntimeServices: mockAssertCanManageExecutionWorkspaceRuntimeServices,
 }));
 
+function registerWorkspaceRouteMocks() {
+  vi.doMock("../telemetry.js", () => ({
+    getTelemetryClient: mockGetTelemetryClient,
+  }));
+
+  vi.doMock("../services/index.js", () => ({
+    environmentService: () => mockEnvironmentService,
+    executionWorkspaceService: () => mockExecutionWorkspaceService,
+    logActivity: mockLogActivity,
+    projectService: () => mockProjectService,
+    secretService: () => mockSecretService,
+    workspaceOperationService: () => mockWorkspaceOperationService,
+  }));
+
+  vi.doMock("../services/workspace-runtime.js", () => ({
+    cleanupExecutionWorkspaceArtifacts: vi.fn(),
+    startRuntimeServicesForWorkspaceControl: vi.fn(),
+    stopRuntimeServicesForExecutionWorkspace: vi.fn(),
+    stopRuntimeServicesForProjectWorkspace: vi.fn(),
+  }));
+
+  vi.doMock("../routes/workspace-runtime-service-authz.js", () => ({
+    assertCanManageProjectWorkspaceRuntimeServices: mockAssertCanManageProjectWorkspaceRuntimeServices,
+    assertCanManageExecutionWorkspaceRuntimeServices: mockAssertCanManageExecutionWorkspaceRuntimeServices,
+  }));
+}
+
 let appImportCounter = 0;
 
 async function createProjectApp(actor: Record<string, unknown>) {
+  registerWorkspaceRouteMocks();
   appImportCounter += 1;
   const routeModulePath = `../routes/projects.js?workspace-runtime-routes-authz-${appImportCounter}`;
   const middlewareModulePath = `../middleware/index.js?workspace-runtime-routes-authz-${appImportCounter}`;
@@ -78,6 +106,7 @@ async function createProjectApp(actor: Record<string, unknown>) {
 }
 
 async function createExecutionWorkspaceApp(actor: Record<string, unknown>) {
+  registerWorkspaceRouteMocks();
   appImportCounter += 1;
   const routeModulePath = `../routes/execution-workspaces.js?workspace-runtime-routes-authz-${appImportCounter}`;
   const middlewareModulePath = `../middleware/index.js?workspace-runtime-routes-authz-${appImportCounter}`;

server/vitest.config.ts

@@ -5,6 +5,8 @@ export default defineConfig({
     environment: "node",
     isolate: true,
     maxConcurrency: 1,
+    maxWorkers: 1,
+    minWorkers: 1,
     pool: "forks",
     poolOptions: {
       forks: {