The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(workspaces): persist readiness state and validate ports (#9408)
Dottae4e12bfb890a
diff --git a/server/src/__tests__/execution-workspaces-service.test.ts b/server/src/__tests__/execution-workspaces-service.test.tsindex e7fc8db03f..858ed344f2 100644--- a/server/src/__tests__/execution-workspaces-service.test.ts+++ b/server/src/__tests__/execution-workspaces-service.test.ts@@ -1901,7 +1901,7 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {),]);- const reconcilePromise = svc.reconcileExecutionWorkspaceBranch(executionWorkspaceId, {+ const reconcileErrorPromise = svc.reconcileExecutionWorkspaceBranch(executionWorkspaceId, {mode: "override",reason: "operator override still requires stopped services",actor: {@@ -1910,10 +1910,15 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {agentId: null,runId: null,},- });+ }).then(+ () => {+ throw new Error("Branch reconciliation unexpectedly succeeded while a runtime service was starting");+ },+ (error) => error,+ );startedServices = await startPromise;- await expect(reconcilePromise).rejects.toMatchObject({+ await expect(reconcileErrorPromise).resolves.toMatchObject({status: 422,message: "Execution workspace branch reconciliation requires all runtime services to be stopped",details: {@@ -1926,7 +1931,7 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {expect.objectContaining({id: startedServices[0]?.id,serviceName: "web",- status: "running",+ status: "starting",}),],},diff --git a/server/src/__tests__/workspace-runtime.test.ts b/server/src/__tests__/workspace-runtime.test.tsindex 0bfc8dd562..aa20eadf3d 100644--- a/server/src/__tests__/workspace-runtime.test.ts+++ b/server/src/__tests__/workspace-runtime.test.ts@@ -42,7 +42,13 @@ import {stopRuntimeServicesForExecutionWorkspace,type RealizedExecutionWorkspace,} from "../services/workspace-runtime.ts";-import { readLocalServicePortOwner, writeLocalServiceRegistryRecord } from "../services/local-service-supervisor.ts";+import {+ findAdoptableLocalService,+ isLocalServiceRegistryCwdCompatible,+ isLocalServiceProcessInWorkspace,+ readLocalServicePortOwner,+ writeLocalServiceRegistryRecord,+} from "../services/local-service-supervisor.ts";import { resolvePaperclipConfigPath } from "../paths.ts";import type { WorkspaceOperation } from "@paperclipai/shared";import type { WorkspaceOperationRecorder } from "../services/workspace-operations.ts";@@ -4069,6 +4075,12 @@ describe("resolveShell (shell fallback)", () => {});describe("readLocalServicePortOwner", () => {+ const originalPlatform = process.platform;++ afterEach(() => {+ Object.defineProperty(process, "platform", { value: originalPlatform });+ });+it("detects the owner of a listening TCP port", async () => {try {await execFileAsync("lsof", ["-v"]);@@ -4094,6 +4106,167 @@ describe("readLocalServicePortOwner", () => {});}});++ it("accepts service cwd nested within the requested workspace", async () => {+ const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-workspace-"));+ const serviceCwd = path.join(workspace, "server");+ await fs.mkdir(serviceCwd);++ await expect(isLocalServiceProcessInWorkspace(serviceCwd, workspace)).resolves.toBe(true);+ });++ it("keeps a live registry record adoptable when cwd inspection is unsupported", async () => {+ try {+ await execFileAsync("lsof", ["-v"]);+ } catch {+ return;+ }++ const server = net.createServer();+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));+ const address = server.address();+ const port = typeof address === "object" && address ? address.port : null;+ const serviceKey = `unsupported-cwd-${randomUUID()}`;+ const paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-home-"));+ process.env.PAPERCLIP_HOME = paperclipHome;+ process.env.PAPERCLIP_INSTANCE_ID = `unsupported-cwd-${randomUUID()}`;+ expect(port).toBeTypeOf("number");++ try {+ await writeLocalServiceRegistryRecord({+ version: 1,+ serviceKey,+ profileKind: "workspace-runtime",+ serviceName: "node",+ command: "node",+ cwd: process.cwd(),+ envFingerprint: "",+ port,+ url: null,+ pid: process.pid,+ processGroupId: null,+ provider: "local_process",+ runtimeServiceId: null,+ reuseKey: null,+ startedAt: new Date().toISOString(),+ lastSeenAt: new Date().toISOString(),+ metadata: null,+ });+ Object.defineProperty(process, "platform", { value: "darwin" });++ await expect(findAdoptableLocalService({+ serviceKey,+ cwd: process.cwd(),+ port,+ })).resolves.toMatchObject({ pid: expect.any(Number), port });+ } finally {+ await new Promise<void>((resolve, reject) => {+ server.close((error) => error ? reject(error) : resolve());+ });+ await fs.rm(paperclipHome, { recursive: true, force: true });+ }+ });++ it("trusts unavailable cwd for registry records only off Linux", async () => {+ Object.defineProperty(process, "platform", { value: "darwin" });+ await expect(isLocalServiceRegistryCwdCompatible(null, process.cwd())).resolves.toBe(true);++ Object.defineProperty(process, "platform", { value: "linux" });+ await expect(isLocalServiceRegistryCwdCompatible(null, process.cwd())).resolves.toBe(false);+ });++ it("refuses to adopt a listener whose real cwd belongs to another workspace", async () => {+ if (process.platform !== "linux") return;+ try {+ await execFileAsync("lsof", ["-v"]);+ } catch {+ return;+ }++ const targetWorkspace = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-target-"));+ const ownerWorkspace = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-owner-"));+ const paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-home-"));+ process.env.PAPERCLIP_HOME = paperclipHome;+ process.env.PAPERCLIP_INSTANCE_ID = `cross-workspace-${randomUUID()}`;+ const serviceKey = `cross-workspace-${randomUUID()}`;+ const child = spawn(+ process.execPath,+ [+ "-e",+ "const server=require('node:http').createServer((req,res)=>res.end('ok')); server.listen(0, '127.0.0.1', () => console.log(server.address().port));",+ ],+ { cwd: ownerWorkspace, stdio: ["ignore", "pipe", "inherit"] },+ );+ const port = await new Promise<number>((resolve, reject) => {+ let output = "";+ child.stdout?.on("data", (chunk) => {+ output += String(chunk);+ const value = Number.parseInt(output.trim(), 10);+ if (Number.isInteger(value) && value > 0) resolve(value);+ });+ child.once("error", reject);+ child.once("exit", (code) => reject(new Error(`Port owner exited before listening: ${code ?? "unknown"}`)));+ });++ try {+ await expect(findAdoptableLocalService({+ serviceKey,+ serviceName: "node",+ command: "node",+ cwd: targetWorkspace,+ port,+ })).resolves.toBeNull();++ await writeLocalServiceRegistryRecord({+ version: 1,+ serviceKey,+ profileKind: "workspace-runtime",+ serviceName: "node",+ command: "node",+ cwd: targetWorkspace,+ envFingerprint: "",+ port,+ url: null,+ pid: child.pid!,+ processGroupId: null,+ provider: "local_process",+ runtimeServiceId: null,+ reuseKey: null,+ startedAt: new Date().toISOString(),+ lastSeenAt: new Date().toISOString(),+ metadata: null,+ });+ await expect(findAdoptableLocalService({+ serviceKey,+ serviceName: "node",+ command: "node",+ cwd: targetWorkspace,+ port,+ })).resolves.toBeNull();++ await expect(startRuntimeServicesForWorkspaceControl({+ actor: { id: "agent-1", name: "Codex Coder", companyId: "company-1" },+ issue: null,+ workspace: buildWorkspace(targetWorkspace),+ config: {+ workspaceRuntime: {+ services: [{+ name: "web",+ command: "node",+ cwd: ".",+ port,+ lifecycle: "shared",+ }],+ },+ },+ adapterEnv: {},+ })).rejects.toThrow(new RegExp(`cross-workspace port conflict.*pid ${child.pid}.*${ownerWorkspace.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "i"));+ } finally {+ child.kill("SIGTERM");+ await new Promise<void>((resolve) => child.once("exit", () => resolve()));+ await fs.rm(paperclipHome, { recursive: true, force: true });+ }+ });});describeEmbeddedPostgres("workspace dirty quarantine branch repair", () => {@@ -4738,6 +4911,214 @@ describeEmbeddedPostgres("workspace dirty quarantine branch repair", () => {}, 20_000);});+describeEmbeddedPostgres("workspace runtime service control persistence", () => {+ let db!: ReturnType<typeof createDb>;+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-workspace-runtime-control-");+ db = createDb(tempDb.connectionString);+ }, 20_000);++ afterAll(async () => {+ await tempDb?.cleanup();+ });++ afterEach(async () => {+ await resetRuntimeServicesForTests();+ await db.delete(workspaceRuntimeServices);+ await db.delete(executionWorkspaces);+ await db.delete(projectWorkspaces);+ await db.delete(issues);+ await db.delete(projects);+ await db.delete(agents);+ await db.delete(companies);+ });++ it("commits a starting service row before waiting for slow readiness", async () => {+ const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-slow-control-"));+ const paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-control-home-"));+ const previousPaperclipHome = process.env.PAPERCLIP_HOME;+ const previousPaperclipInstanceId = process.env.PAPERCLIP_INSTANCE_ID;+ process.env.PAPERCLIP_HOME = paperclipHome;+ process.env.PAPERCLIP_INSTANCE_ID = `runtime-control-${randomUUID()}`;++ const companyId = randomUUID();+ const projectId = randomUUID();+ const projectWorkspaceId = randomUUID();+ const issueId = randomUUID();+ const executionWorkspaceId = randomUUID();+ const markerPath = path.join(workspaceRoot, "runtime-spawned.marker");+ const serverScript = [+ `require("node:fs").writeFileSync(${JSON.stringify(markerPath)}, "spawned");`,+ "setTimeout(() => {",+ " require(\"node:http\")",+ " .createServer((_req, res) => { res.end(\"ok\"); })",+ " .listen(Number(process.env.PORT), \"127.0.0.1\");",+ "}, 700);",+ "setInterval(() => {}, 1000);",+ ].join(" ");+ const command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(serverScript)}`;++ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,+ requireBoardApprovalForNewAgents: false,+ });+ await db.insert(projects).values({+ id: projectId,+ companyId,+ name: "Runtime control",+ status: "in_progress",+ });+ await db.insert(projectWorkspaces).values({+ id: projectWorkspaceId,+ companyId,+ projectId,+ name: "Primary",+ sourceType: "local_path",+ cwd: workspaceRoot,+ isPrimary: true,+ });+ await db.insert(issues).values({+ id: issueId,+ companyId,+ projectId,+ title: "Source task",+ status: "in_progress",+ priority: "high",+ });+ await db.insert(executionWorkspaces).values({+ id: executionWorkspaceId,+ companyId,+ projectId,+ projectWorkspaceId,+ sourceIssueId: issueId,+ mode: "isolated_workspace",+ strategyType: "git_worktree",+ name: "Runtime control workspace",+ status: "active",+ providerType: "git_worktree",+ cwd: workspaceRoot,+ providerRef: workspaceRoot,+ branchName: "feature/runtime-control",+ baseRef: "main",+ });++ const waitForMarker = async () => {+ const deadline = Date.now() + 5_000;+ while (Date.now() < deadline) {+ if (existsSync(markerPath)) return;+ await new Promise((resolve) => setTimeout(resolve, 25));+ }+ throw new Error("Timed out waiting for runtime service process marker");+ };+ const waitForPersistedStatus = async (status: string) => {+ const deadline = Date.now() + 5_000;+ while (Date.now() < deadline) {+ const row = await db+ .select()+ .from(workspaceRuntimeServices)+ .where(eq(workspaceRuntimeServices.executionWorkspaceId, executionWorkspaceId))+ .then((rows) => rows[0] ?? null);+ if (row?.status === status) return row;+ await new Promise((resolve) => setTimeout(resolve, 25));+ }+ throw new Error(`Timed out waiting for persisted runtime service status ${status}`);+ };++ const startPromise = startRuntimeServicesForWorkspaceControl({+ db,+ invocationId: randomUUID(),+ actor: {+ id: null,+ name: "Board",+ companyId,+ },+ issue: {+ id: issueId,+ identifier: null,+ title: "Source task",+ },+ workspace: {+ baseCwd: workspaceRoot,+ source: "task_session",+ projectId,+ workspaceId: projectWorkspaceId,+ repoUrl: null,+ repoRef: "main",+ strategy: "git_worktree",+ cwd: workspaceRoot,+ branchName: "feature/runtime-control",+ worktreePath: workspaceRoot,+ warnings: [],+ created: false,+ },+ executionWorkspaceId,+ config: {+ workspaceRuntime: {+ services: [+ {+ name: "web",+ command,+ lifecycle: "shared",+ reuseScope: "execution_workspace",+ port: { type: "auto", envKey: "PORT" },+ expose: { urlTemplate: "http://127.0.0.1:{{port}}" },+ readiness: { type: "http", intervalMs: 50, timeoutSec: 10 },+ stopPolicy: { type: "manual" },+ },+ ],+ },+ },+ adapterEnv: {},+ });+ startPromise.catch(() => undefined);++ try {+ await waitForMarker();+ const startingRow = await waitForPersistedStatus("starting");+ expect(startingRow).toMatchObject({+ companyId,+ projectId,+ projectWorkspaceId,+ executionWorkspaceId,+ issueId,+ serviceName: "web",+ status: "starting",+ healthStatus: "unknown",+ });+ expect(startingRow.providerRef).toMatch(/^\d+$/);+ expect(startingRow.port).toEqual(expect.any(Number));++ const services = await startPromise;+ expect(services).toHaveLength(1);+ expect(services[0]).toMatchObject({+ id: startingRow.id,+ status: "running",+ healthStatus: "healthy",+ });++ const runningRow = await waitForPersistedStatus("running");+ expect(runningRow.id).toBe(startingRow.id);+ await expect(fetch(services[0]!.url!)).resolves.toMatchObject({ ok: true });+ } finally {+ await startPromise.catch(() => undefined);+ await stopRuntimeServicesForExecutionWorkspace({+ db,+ executionWorkspaceId,+ workspaceCwd: workspaceRoot,+ });+ await fs.rm(paperclipHome, { recursive: true, force: true });+ if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;+ else process.env.PAPERCLIP_HOME = previousPaperclipHome;+ if (previousPaperclipInstanceId === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;+ else process.env.PAPERCLIP_INSTANCE_ID = previousPaperclipInstanceId;+ }+ }, 15_000);+});+describeEmbeddedPostgres("workspace runtime startup reconciliation", () => {let db!: ReturnType<typeof createDb>;let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;diff --git a/server/src/services/execution-workspaces.ts b/server/src/services/execution-workspaces.tsindex c1dc1426b4..d47d81801e 100644--- a/server/src/services/execution-workspaces.ts+++ b/server/src/services/execution-workspaces.ts@@ -1667,7 +1667,7 @@ export function executionWorkspaceService(db: Db) {return db.transaction(async (tx) => {const txDb = tx as unknown as Db;// Runtime-service activation takes this same row lock before spawning- // local services and holds it until the running service row is persisted.+ // local services and persists a `starting` row before releasing it.const lockedRow = await tx.select().from(executionWorkspaces)diff --git a/server/src/services/local-service-supervisor.ts b/server/src/services/local-service-supervisor.tsindex 86d270e37a..b459ad3cff 100644--- a/server/src/services/local-service-supervisor.ts+++ b/server/src/services/local-service-supervisor.ts@@ -207,6 +207,10 @@ export async function findLocalServiceRegistryRecordByRuntimeServiceId(input: {await removeLocalServiceRegistryRecord(record.serviceKey);return null;}+ if (!(await doesLocalServiceRecordMatchCwd(candidate))) {+ await removeLocalServiceRegistryRecord(record.serviceKey);+ return null;+ }return candidate;}@@ -270,6 +274,10 @@ export async function findAdoptableLocalService(input: {await removeLocalServiceRegistryRecord(input.serviceKey);return null;}+ if (!(await doesLocalServiceRecordMatchCwd(record))) {+ await removeLocalServiceRegistryRecord(input.serviceKey);+ return null;+ }if (input.command && record.command !== input.command) return null;if (input.cwd && path.resolve(record.cwd) !== path.resolve(input.cwd)) return null;if (input.envFingerprint && record.envFingerprint !== input.envFingerprint) return null;@@ -302,6 +310,13 @@ async function adoptLocalServiceFromPortOwner(input: {const ownerPid = await readLocalServicePortOwner(input.port);if (!ownerPid) return null;+ if (input.cwd) {+ const ownerCwd = await readLocalServiceProcessCwd(ownerPid);+ if (!ownerCwd || !(await isLocalServiceProcessInWorkspace(ownerCwd, input.cwd))) {+ return null;+ }+ }+const processGroupId = await readProcessGroupId(ownerPid);const pid = processGroupId && isPidAlive(processGroupId) ? processGroupId : ownerPid;const now = new Date().toISOString();@@ -402,3 +417,38 @@ export async function readLocalServicePortOwner(port: number) {return null;}}++export async function readLocalServiceProcessCwd(pid: number) {+ if (!Number.isInteger(pid) || pid <= 0 || process.platform !== "linux") return null;+ try {+ return await fs.readlink(`/proc/${pid}/cwd`);+ } catch {+ return null;+ }+}++export async function isLocalServiceProcessInWorkspace(processCwd: string, workspaceCwd: string) {+ try {+ const [resolvedProcessCwd, resolvedWorkspaceCwd] = await Promise.all([+ fs.realpath(processCwd),+ fs.realpath(workspaceCwd),+ ]);+ const relativePath = path.relative(resolvedWorkspaceCwd, resolvedProcessCwd);+ return relativePath === "" || (!relativePath.startsWith(`..${path.sep}`) && relativePath !== "..");+ } catch {+ return false;+ }+}++export async function isLocalServiceRegistryCwdCompatible(processCwd: string | null, workspaceCwd: string) {+ if (!processCwd) return process.platform !== "linux";+ return isLocalServiceProcessInWorkspace(processCwd, workspaceCwd);+}++async function doesLocalServiceRecordMatchCwd(record: LocalServiceRegistryRecord) {+ if (!record.port) return true;+ const ownerPid = await readLocalServicePortOwner(record.port);+ if (!ownerPid) return false;+ const ownerCwd = await readLocalServiceProcessCwd(ownerPid);+ return isLocalServiceRegistryCwdCompatible(ownerCwd, record.cwd);+}diff --git a/server/src/services/workspace-runtime.ts b/server/src/services/workspace-runtime.tsindex 3960116769..7e56da6bd5 100644--- a/server/src/services/workspace-runtime.ts+++ b/server/src/services/workspace-runtime.ts@@ -24,6 +24,8 @@ import {createLocalServiceKey,findLocalServiceRegistryRecordByRuntimeServiceId,findAdoptableLocalService,+ isLocalServiceProcessInWorkspace,+ readLocalServiceProcessCwd,readLocalServicePortOwner,removeLocalServiceRegistryRecord,terminateLocalService,@@ -127,6 +129,11 @@ interface RuntimeServiceRecord extends RuntimeServiceRef {processGroupId: number | null;}+type LocalRuntimeServiceStart = {+ record: RuntimeServiceRecord;+ readiness: Promise<void>;+};+type StoppedRuntimeServiceReuseCandidate = {id: string;port: number | null;@@ -3785,7 +3792,7 @@ export function normalizeAdapterManagedRuntimeServices(input: {});}-async function startLocalRuntimeService(input: {+type StartLocalRuntimeServiceInput = {db?: Db;runId: string;leaseRunId?: string | null;@@ -3800,7 +3807,9 @@ async function startLocalRuntimeService(input: {reuseKey: string | null;scopeType: "project_workspace" | "execution_workspace" | "run" | "agent";scopeId: string | null;-}): Promise<RuntimeServiceRecord> {+};++async function spawnLocalRuntimeService(input: StartLocalRuntimeServiceInput): Promise<LocalRuntimeServiceStart> {const leaseRunId = input.leaseRunId === undefined ? input.runId : input.leaseRunId;const startedByRunId = input.startedByRunId === undefined ? input.runId : input.startedByRunId;const identity = resolveRuntimeServiceReuseIdentity({@@ -3899,48 +3908,61 @@ async function startLocalRuntimeService(input: {await removeLocalServiceRegistryRecord(adoptedRecord.serviceKey);} else {return {- id: adoptedRecord.runtimeServiceId ?? randomUUID(),- companyId: input.agent.companyId,- projectId: input.workspace.projectId,- projectWorkspaceId: input.workspace.workspaceId,- executionWorkspaceId: input.executionWorkspaceId ?? null,- issueId: input.issue?.id ?? null,- serviceName,- status: "running",- lifecycle,- scopeType: input.scopeType,- scopeId: input.scopeId,- reuseKey: input.reuseKey,- command,- cwd: serviceCwd,- port: adoptedRecord.port ?? port,- url: adoptedRecord.url ?? url,- provider: "local_process",- providerRef: String(adoptedRecord.pid),- ownerAgentId: input.agent.id ?? null,- startedByRunId,- lastUsedAt: new Date().toISOString(),- startedAt: adoptedRecord.startedAt,- stoppedAt: null,- stopPolicy,- healthStatus: "healthy",- reused: true,- db: input.db,- child: null,- leaseRunIds: leaseRunId ? new Set([leaseRunId]) : new Set(),- idleTimer: null,- envFingerprint,- serviceKey,- profileKind: "workspace-runtime",- processGroupId: adoptedRecord.processGroupId ?? null,+ record: {+ id: adoptedRecord.runtimeServiceId ?? randomUUID(),+ companyId: input.agent.companyId,+ projectId: input.workspace.projectId,+ projectWorkspaceId: input.workspace.workspaceId,+ executionWorkspaceId: input.executionWorkspaceId ?? null,+ issueId: input.issue?.id ?? null,+ serviceName,+ status: "running",+ lifecycle,+ scopeType: input.scopeType,+ scopeId: input.scopeId,+ reuseKey: input.reuseKey,+ command,+ cwd: serviceCwd,+ port: adoptedRecord.port ?? port,+ url: adoptedRecord.url ?? url,+ provider: "local_process",+ providerRef: String(adoptedRecord.pid),+ ownerAgentId: input.agent.id ?? null,+ startedByRunId,+ lastUsedAt: new Date().toISOString(),+ startedAt: adoptedRecord.startedAt,+ stoppedAt: null,+ stopPolicy,+ healthStatus: "healthy",+ reused: true,+ db: input.db,+ child: null,+ leaseRunIds: leaseRunId ? new Set([leaseRunId]) : new Set(),+ idleTimer: null,+ envFingerprint,+ serviceKey,+ profileKind: "workspace-runtime",+ processGroupId: adoptedRecord.processGroupId ?? null,+ },+ readiness: Promise.resolve(),};}}if (identityPort) {- const ownerPid = await readLocalServicePortOwner(identityPort);+ const ownerPid = await readLocalServicePortOwner(identityPort);if (ownerPid) {+ const ownerCwd = await readLocalServiceProcessCwd(ownerPid);+ const ownerIsInWorkspace = ownerCwd+ ? await isLocalServiceProcessInWorkspace(ownerCwd, serviceCwd)+ : null;+ const ownerDescription = ownerCwd ? `pid ${ownerPid} (cwd: ${ownerCwd})` : `pid ${ownerPid} (cwd unavailable)`;+ if (ownerIsInWorkspace === false) {+ throw new Error(+ `Runtime service "${serviceName}" could not start because port ${identityPort} has a cross-workspace port conflict with ${ownerDescription}; requested workspace: ${serviceCwd}. Stop the other service or configure a different port.`,+ );+ }throw new Error(- `Runtime service "${serviceName}" could not start because port ${identityPort} is already in use by pid ${ownerPid}`,+ `Runtime service "${serviceName}" could not start because port ${identityPort} is already in use by ${ownerDescription}`,);}}@@ -3974,18 +3996,7 @@ async function startLocalRuntimeService(input: {if (input.onLog) await input.onLog("stderr", `[service:${serviceName}] ${text}`);});- try {- await Promise.race([- waitForReadiness({ service: input.service, serviceName, command, url }),- spawnErrorPromise,- ]);- } catch (err) {- terminateChildProcess(child);- throw new Error(- `Failed to start runtime service "${serviceName}": ${err instanceof Error ? err.message : String(err)}${stderrExcerpt ? ` | stderr: ${stderrExcerpt.trim()}` : ""}`,- );- }-+ const nowIso = new Date().toISOString();const record: RuntimeServiceRecord = {id: stoppedReuseCandidate?.id ?? randomUUID(),companyId: input.agent.companyId,@@ -3994,7 +4005,7 @@ async function startLocalRuntimeService(input: {executionWorkspaceId: input.executionWorkspaceId ?? null,issueId: input.issue?.id ?? null,serviceName,- status: "running",+ status: "starting",lifecycle,scopeType: input.scopeType,scopeId: input.scopeId,@@ -4007,11 +4018,11 @@ async function startLocalRuntimeService(input: {providerRef: child.pid ? String(child.pid) : null,ownerAgentId: input.agent.id ?? null,startedByRunId,- lastUsedAt: new Date().toISOString(),- startedAt: new Date().toISOString(),+ lastUsedAt: nowIso,+ startedAt: nowIso,stoppedAt: null,stopPolicy,- healthStatus: "healthy",+ healthStatus: "unknown",reused: false,db: input.db,child,@@ -4052,7 +4063,37 @@ async function startLocalRuntimeService(input: {});}- return record;+ const readinessPromise = Promise.race([+ waitForReadiness({ service: input.service, serviceName, command, url }),+ spawnErrorPromise,+ ]).then(async () => {+ record.status = "running";+ record.healthStatus = "healthy";+ record.lastUsedAt = new Date().toISOString();+ record.stoppedAt = null;+ await touchLocalServiceRegistryRecord(record.serviceKey, {+ runtimeServiceId: record.id,+ lastSeenAt: record.lastUsedAt,+ });+ }).catch(async (err) => {+ terminateChildProcess(child);+ record.status = "stopped";+ record.healthStatus = "unhealthy";+ record.lastUsedAt = new Date().toISOString();+ record.stoppedAt = new Date().toISOString();+ await removeLocalServiceRegistryRecord(record.serviceKey).catch(() => undefined);+ throw new Error(+ `Failed to start runtime service "${serviceName}": ${err instanceof Error ? err.message : String(err)}${stderrExcerpt ? ` | stderr: ${stderrExcerpt.trim()}` : ""}`,+ );+ });++ return { record, readiness: readinessPromise };+}++async function startLocalRuntimeService(input: StartLocalRuntimeServiceInput): Promise<RuntimeServiceRecord> {+ const started = await spawnLocalRuntimeService(input);+ await started.readiness;+ return started.record;}function scheduleIdleStop(record: RuntimeServiceRecord) {@@ -4332,14 +4373,23 @@ type StartRuntimeServicesForWorkspaceControlInput = {respectDesiredStates?: boolean;};+type WorkspaceControlStartBatch = {+ refs: RuntimeServiceRef[];+ pendingReadiness: LocalRuntimeServiceStart[];+ startedServiceIds: string[];+};+async function startRuntimeServicesForWorkspaceControlUnlocked(input: StartRuntimeServicesForWorkspaceControlInput,rawServices: Record<string, unknown>[],invocationId: string,persistenceDb = input.db,registryDb = input.db,-): Promise<RuntimeServiceRef[]> {+ options?: { deferReadiness?: boolean },+): Promise<WorkspaceControlStartBatch> {const refs: RuntimeServiceRef[] = [];+ const pendingReadiness: LocalRuntimeServiceStart[] = [];+ const startedServiceIds: string[] = [];for (const service of rawServices) {const { scopeType, scopeId } = resolveServiceScopeId({@@ -4377,9 +4427,7 @@ async function startRuntimeServicesForWorkspaceControlUnlocked(}}- // Manually controlled services are not tied to a heartbeat run lifecycle, so they do not- // retain a run lease and never persist a startedByRunId foreign key.- const record = await startLocalRuntimeService({+ const startInput: StartLocalRuntimeServiceInput = {db: persistenceDb,runId: invocationId,leaseRunId: null,@@ -4394,13 +4442,30 @@ async function startRuntimeServicesForWorkspaceControlUnlocked(reuseKey,scopeType,scopeId,- });- registerRuntimeService(registryDb, record);- await persistRuntimeServiceRecord(persistenceDb, record);- refs.push(toRuntimeServiceRef(record));+ };++ // Manually controlled services are not tied to a heartbeat run lifecycle, so they do not+ // retain a run lease and never persist a startedByRunId foreign key.+ const started = options?.deferReadiness+ ? await spawnLocalRuntimeService(startInput)+ : {+ record: await startLocalRuntimeService(startInput),+ readiness: Promise.resolve(),+ };+ registerRuntimeService(registryDb, started.record);+ await persistRuntimeServiceRecord(persistenceDb, started.record);+ refs.push(toRuntimeServiceRef(started.record));++ if (options?.deferReadiness && !started.record.reused) {+ // Attach a rejection handler immediately; the caller awaits the same promise after+ // the DB transaction commits, but transaction failures may skip that wait path.+ started.readiness.catch(() => undefined);+ pendingReadiness.push(started);+ startedServiceIds.push(started.record.id);+ }}- return refs;+ return { refs, pendingReadiness, startedServiceIds };}export async function startRuntimeServicesForWorkspaceControl(@@ -4416,12 +4481,17 @@ export async function startRuntimeServicesForWorkspaceControl(const invocationId = input.invocationId ?? randomUUID();if (rawServices.length === 0 || !input.db || (!input.executionWorkspaceId && !input.workspace.workspaceId)) {- return startRuntimeServicesForWorkspaceControlUnlocked(input, rawServices, invocationId);+ const batch = await startRuntimeServicesForWorkspaceControlUnlocked(input, rawServices, invocationId);+ return batch.refs;}- let startedRefs: RuntimeServiceRef[] = [];+ let startBatch: WorkspaceControlStartBatch = {+ refs: [],+ pendingReadiness: [],+ startedServiceIds: [],+ };try {- return await input.db.transaction(async (tx) => {+ await input.db.transaction(async (tx) => {const txDb = tx as unknown as Db;if (input.executionWorkspaceId) {@@ -4453,20 +4523,35 @@ export async function startRuntimeServicesForWorkspaceControl(}// Branch reconciliation takes these same parent row locks before mutating- // a recorded branch. Holding them until the running service row is- // persisted closes the process-start window before the FK insert.- startedRefs = await startRuntimeServicesForWorkspaceControlUnlocked(+ // a recorded branch. Persisting a `starting` service row before commit closes+ // the process-start window without holding the DB transaction for readiness.+ startBatch = await startRuntimeServicesForWorkspaceControlUnlocked({ ...input, db: txDb },rawServices,invocationId,txDb,input.db,+ { deferReadiness: true },);- return startedRefs;+ });++ for (const pending of startBatch.pendingReadiness) {+ try {+ await pending.readiness;+ await persistRuntimeServiceRecord(input.db, pending.record);+ } catch (error) {+ await persistRuntimeServiceRecord(input.db, pending.record).catch(() => undefined);+ throw error;+ }+ }++ return startBatch.refs.map((ref) => {+ const record = runtimeServicesById.get(ref.id);+ return record ? toRuntimeServiceRef(record, { reused: ref.reused }) : ref;});} catch (error) {- for (const ref of startedRefs) {- await stopRuntimeService(ref.id).catch(() => undefined);+ for (const serviceId of startBatch.startedServiceIds) {+ await stopRuntimeService(serviceId).catch(() => undefined);}throw error;}diff --git a/ui/src/pages/ExecutionWorkspaceDetail.service-ports.test.ts b/ui/src/pages/ExecutionWorkspaceDetail.service-ports.test.tsnew file mode 100644index 0000000000..81ddb08726--- /dev/null+++ b/ui/src/pages/ExecutionWorkspaceDetail.service-ports.test.ts@@ -0,0 +1,75 @@+import { describe, expect, it } from "vitest";+import {+ getConfiguredRuntimeServicePortWarnings,+ readConfiguredRuntimeServicePorts,+ updateConfiguredRuntimeServicePort,+} from "./ExecutionWorkspaceDetail";++describe("execution workspace service port configuration", () => {+ it("reads commands and legacy services, then saves a fixed port without mutating the source config", () => {+ const runtimeConfig = {+ commands: [+ { id: "web", name: "Web app", kind: "service", command: "pnpm dev", port: { type: "auto" } },+ { id: "migrate", name: "Migrate", kind: "job", command: "pnpm db:migrate" },+ ],+ services: [{ name: "Legacy", command: "pnpm legacy", port: 3100 }],+ };++ const services = readConfiguredRuntimeServicePorts(runtimeConfig);+ expect(services).toEqual([+ { collection: "commands", index: 0, name: "Web app", port: null, invalidPort: false },+ { collection: "services", index: 0, name: "Legacy", port: 3100, invalidPort: false },+ ]);++ expect(updateConfiguredRuntimeServicePort({+ runtimeConfig,+ service: services[0]!,+ port: "4200",+ })).toEqual({+ commands: [+ { id: "web", name: "Web app", kind: "service", command: "pnpm dev", port: { type: "fixed", value: 4200 } },+ { id: "migrate", name: "Migrate", kind: "job", command: "pnpm db:migrate" },+ ],+ services: [{ name: "Legacy", command: "pnpm legacy", port: 3100 }],+ });+ expect(runtimeConfig.commands[0]?.port).toEqual({ type: "auto" });+ });++ it("warns when fixed ports collide in the same workspace configuration", () => {+ expect(getConfiguredRuntimeServicePortWarnings([+ { collection: "commands", index: 0, name: "Web", port: 3100, invalidPort: false },+ { collection: "commands", index: 1, name: "Admin", port: 3100, invalidPort: false },+ { collection: "services", index: 0, name: "Worker", port: 3200, invalidPort: false },+ ])).toEqual(["Port 3100 is assigned to multiple services: Web, Admin."]);+ });++ it("preserves auto-port metadata when switching between automatic and fixed ports", () => {+ const runtimeConfig = {+ commands: [{ name: "Web", kind: "service", command: "pnpm dev", port: { type: "auto", envKey: "APP_PORT" } }],+ };+ const [service] = readConfiguredRuntimeServicePorts(runtimeConfig);++ const fixed = updateConfiguredRuntimeServicePort({ runtimeConfig, service: service!, port: "4200" });+ expect(fixed.commands).toEqual([+ { name: "Web", kind: "service", command: "pnpm dev", port: { type: "fixed", envKey: "APP_PORT", value: 4200 } },+ ]);++ expect(updateConfiguredRuntimeServicePort({ runtimeConfig: fixed, service: service!, port: "" }).commands).toEqual([+ { name: "Web", kind: "service", command: "pnpm dev", port: { type: "auto", envKey: "APP_PORT" } },+ ]);+ });++ it("marks malformed and out-of-range configured ports as invalid", () => {+ expect(readConfiguredRuntimeServicePorts({+ commands: [+ { name: "Too high", kind: "service", port: { type: "fixed", value: 70000 } },+ { name: "Fractional", kind: "service", port: 3100.5 },+ { name: "String", kind: "service", port: { type: "fixed", value: "3100" } },+ ],+ })).toEqual([+ { collection: "commands", index: 0, name: "Too high", port: 70000, invalidPort: true },+ { collection: "commands", index: 1, name: "Fractional", port: 3100.5, invalidPort: true },+ { collection: "commands", index: 2, name: "String", port: null, invalidPort: true },+ ]);+ });+});diff --git a/ui/src/pages/ExecutionWorkspaceDetail.tsx b/ui/src/pages/ExecutionWorkspaceDetail.tsxindex 7c01d66526..e130cf1b21 100644--- a/ui/src/pages/ExecutionWorkspaceDetail.tsx+++ b/ui/src/pages/ExecutionWorkspaceDetail.tsx@@ -58,6 +58,14 @@ type WorkspaceFormState = {workspaceRuntime: string;};+type ConfiguredRuntimeServicePort = {+ collection: "commands" | "services";+ index: number;+ name: string;+ port: number | null;+ invalidPort: boolean;+};+type ExecutionWorkspaceBaseTab = "services" | "configuration" | "runtime_logs" | "issues" | "routines";type ExecutionWorkspacePluginTab = `plugin:${string}`;type ExecutionWorkspaceTab = ExecutionWorkspaceBaseTab | ExecutionWorkspacePluginTab;@@ -164,6 +172,93 @@ function parseWorkspaceRuntimeJson(value: string) {}}+export function readConfiguredRuntimeServicePorts(runtimeConfig: Record<string, unknown> | null) {+ if (!runtimeConfig) return [] as ConfiguredRuntimeServicePort[];++ const entries: ConfiguredRuntimeServicePort[] = [];+ const addServices = (collection: ConfiguredRuntimeServicePort["collection"], services: unknown, commandsRequireServiceKind: boolean) => {+ if (!Array.isArray(services)) return;+ services.forEach((service, index) => {+ if (!service || typeof service !== "object" || Array.isArray(service)) return;+ const config = service as Record<string, unknown>;+ if (commandsRequireServiceKind && config.kind !== "service") return;+ const portConfig = config.port;+ const hasObjectPortValue = Boolean(+ portConfig+ && typeof portConfig === "object"+ && !Array.isArray(portConfig)+ && Object.hasOwn(portConfig, "value"),+ );+ const portValue =+ typeof portConfig === "number"+ ? portConfig+ : hasObjectPortValue+ ? (portConfig as Record<string, unknown>).value+ : null;+ entries.push({+ collection,+ index,+ name: typeof config.name === "string" && config.name.trim() ? config.name : `Service ${index + 1}`,+ port: typeof portValue === "number" ? portValue : null,+ invalidPort: (typeof portConfig === "number" || hasObjectPortValue)+ && (typeof portValue !== "number" || !Number.isInteger(portValue) || portValue < 1 || portValue > 65535),+ });+ });+ };++ addServices("commands", runtimeConfig.commands, true);+ addServices("services", runtimeConfig.services, false);+ return entries;+}++export function updateConfiguredRuntimeServicePort(input: {+ runtimeConfig: Record<string, unknown>;+ service: ConfiguredRuntimeServicePort;+ port: string;+}) {+ const runtimeConfig = structuredClone(input.runtimeConfig);+ const entries = runtimeConfig[input.service.collection];+ if (!Array.isArray(entries)) return runtimeConfig;+ const entry = entries[input.service.index];+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) return runtimeConfig;+ const config = entry as Record<string, unknown>;+ const existingPort = config.port && typeof config.port === "object" && !Array.isArray(config.port)+ ? config.port as Record<string, unknown>+ : null;++ const trimmedPort = input.port.trim();+ if (!trimmedPort) {+ if (existingPort) {+ const autoPort: Record<string, unknown> = { ...existingPort, type: "auto" };+ delete autoPort.value;+ config.port = autoPort;+ } else {+ delete config.port;+ }+ return runtimeConfig;+ }+ const port = Number(trimmedPort);+ if (!Number.isInteger(port) || port < 1 || port > 65535) return runtimeConfig;+ config.port = { ...existingPort, type: "fixed", value: port };+ return runtimeConfig;+}++export function getConfiguredRuntimeServicePortWarnings(services: ConfiguredRuntimeServicePort[]) {+ const servicesByPort = new Map<number, ConfiguredRuntimeServicePort[]>();+ for (const service of services) {+ if (service.invalidPort || !service.port) continue;+ const servicesForPort = servicesByPort.get(service.port) ?? [];+ servicesForPort.push(service);+ servicesByPort.set(service.port, servicesForPort);+ }++ return Array.from(servicesByPort.entries())+ .filter(([, servicesForPort]) => servicesForPort.length > 1)+ .map(([port, servicesForPort]) =>+ `Port ${port} is assigned to multiple services: ${servicesForPort.map((service) => service.name).join(", ")}.`,+ );+}+function formStateFromWorkspace(workspace: ExecutionWorkspace): WorkspaceFormState {return {name: workspace.name,@@ -235,6 +330,8 @@ function validateForm(form: WorkspaceFormState) {if (!runtimeJson.ok) {return runtimeJson.error;}+ const invalidPort = readConfiguredRuntimeServicePorts(runtimeJson.value).find((service) => service.invalidPort);+ if (invalidPort) return `${invalidPort.name} has an invalid fixed port.`;}return null;@@ -678,6 +775,20 @@ export function ExecutionWorkspaceDetail() {? "project_workspace": "none";+ const configuredRuntimeConfig = useMemo(() => {+ if (!form || form.inheritRuntime) return inheritedRuntimeConfig;+ const parsed = parseWorkspaceRuntimeJson(form.workspaceRuntime);+ return parsed.ok ? parsed.value : null;+ }, [form, inheritedRuntimeConfig]);+ const configuredRuntimeServicePorts = useMemo(+ () => readConfiguredRuntimeServicePorts(configuredRuntimeConfig),+ [configuredRuntimeConfig],+ );+ const configuredRuntimeServicePortWarnings = useMemo(+ () => getConfiguredRuntimeServicePortWarnings(configuredRuntimeServicePorts),+ [configuredRuntimeServicePorts],+ );+const initialState = useMemo(() => (workspace ? formStateFromWorkspace(workspace) : null), [workspace]);const isDirty = Boolean(form && initialState && JSON.stringify(form) !== JSON.stringify(initialState));const projectRef = project ? projectRouteRef(project) : workspace?.projectId ?? "";@@ -1064,6 +1175,56 @@ export function ExecutionWorkspaceDetail() {</Field></div></details>++ {configuredRuntimeServicePorts.length > 0 ? (+ <div className="space-y-3 rounded-md border border-border bg-muted/20 p-4">+ <div>+ <div className="text-sm font-medium">Service ports</div>+ <p className="mt-1 text-sm text-muted-foreground">+ Set a fixed port for a service or leave it blank to use its configured automatic behavior. Editing an inherited service creates an execution-workspace runtime override.+ </p>+ </div>+ <div className="grid gap-3 sm:grid-cols-2">+ {configuredRuntimeServicePorts.map((service) => (+ <Field key={`${service.collection}-${service.index}`} label={service.name} hint="Fixed port">+ <Input+ type="number"+ min="1"+ max="65535"+ inputMode="numeric"+ value={service.port ?? ""}+ onChange={(event) => {+ setForm((current) => {+ if (!current) return current;+ const parsed = current.inheritRuntime+ ? { ok: true as const, value: inheritedRuntimeConfig }+ : parseWorkspaceRuntimeJson(current.workspaceRuntime);+ if (!parsed.ok || !parsed.value) return current;+ return {+ ...current,+ inheritRuntime: false,+ workspaceRuntime: formatJson(updateConfiguredRuntimeServicePort({+ runtimeConfig: parsed.value,+ service,+ port: event.target.value,+ })),+ };+ });+ }}+ />+ </Field>+ ))}+ </div>+ {configuredRuntimeServicePortWarnings.length > 0 ? (+ <div className="rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-sm text-destructive">+ {configuredRuntimeServicePortWarnings.map((warning) => <p key={warning}>{warning}</p>)}+ </div>+ ) : null}+ <p className="text-sm text-muted-foreground">+ Paperclip checks fixed ports again when a service starts and rejects cross-workspace conflicts.+ </p>+ </div>+ ) : null}</div></div>