Replace pm2 with homegrown process manager daemon by fredrikekelund · Pull Request #2712 · Automattic/studio

fredrikekelund · 2026-03-05T15:32:36Z

Related issues

Fixes STU-1349

How AI was used in this PR

Codex wrote most of the code in this PR, starting from a detailed list of requirements I shared (based on our experience with pm2). I iterated on this over multiple days, both with Codex and by hand. I've touched all major files in the PR. process-manager-ipc.ts is a standout example – I made many manual edits there. I've reviewed all the code. The code I've spent the least time editing or reviewing is the tests.

Proposed Changes

Tip

I'm happy to pair for a review of this PR. I know it's a big one. Also, please note that this PR builds upon the changes in #2690. That PR should be reviewed first.

See STU-1349 for the "why" of removing pm2. This PR implements the following:

A process-manager-daemon.ts that manages child processes. This involves forking them, tracking them in-memory, forwarding child IPC messages as typed daemon events, and writing stdout/stderr to PM2-compatible log files under ~/.studio/pm2/logs. This file is the PM2 replacement.
daemon-client.ts replaces pm2-manager.ts. It talks to the daemon over a control socket for request/response commands and an events socket for receiving messages from child processes and process events (online/exit, etc.).

The architecture largely follows PM2's example, and process-manager-daemon.ts implements the same functionality. A few notes to get reviewers started:

Starting/stopping processes are relatively easy to understand from the code.
IPC is a little trickier, but the gist is that daemon-client exports a sendMessageToProcess function that uses the process manager "control socket" to send a message with a processId target. When process-manager-daemon.ts receives the message, it uses the standard Node.js IPC mechanism to forward it to the child process. Child processes cannot respond directly to these messages, but they can emit events through Node.js standard IPC, which process-manager-daemon.ts picks up and broadcasts on the "events socket". daemonBus listens on the events socket, and the subscribeSiteEvents function picks up the process-message and process-event events, which are ultimately picked up by _events.ts.

Testing Instructions

Run npm start
Ensure that starting and stopping sites works as expected
Try creating a new site, too
While Studio is still running, run node apps/cli/dist/cli/main.js site start --skip-browser --path PATH_TO_SITE in your terminal
Ensure that the site is immediately marked as started in Studio

Pre-merge Checklist

Have you checked for TypeScript, React or other console errors?

This reverts commit 24cdda5.

wpmobilebot · 2026-03-09T07:48:10Z

📊 Performance Test Results

Comparing c649e82 vs trunk

site-editor

Metric	trunk	`c649e82`	Diff	Change
load	1752.00 ms	1805.00 ms	+53.00 ms	🔴 3.0%

site-startup

Metric	trunk	`c649e82`	Diff	Change
siteCreation	6116.00 ms	6087.00 ms	-29.00 ms	⚪ 0.0%
siteStartup	3931.00 ms	3942.00 ms	+11.00 ms	⚪ 0.0%

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

bcotrim

While testing this I found some weird behaviors:

Killing a site process (kill pid) didn't reflect on Studio. Site was still running in the UI and stop operation didn't work (CLI worked fine). I could only replicate this once
Doing Stop all from the Studio UI button, seems to break the UI. After doing stop all starting any other sites would not be reflected in the UI. I was able to replicate this consistently.

Added some minor comments to the code that aren't blockers, but we should look into these 2 issues.

bcotrim · 2026-03-09T11:19:02Z

+} from 'cli/lib/types/wordpress-server-ipc';
+
+// Zod schema for process descriptions
+export const processDescriptionSchema = z.object( {


Should we be more intentional about the status + pid options?
I believe an online process will always have a pid, and the optional scenario is only for stopped processes. We could use an union to be more intentional about this type, what do you think?

Good call! 👍 I'm all for well-defined types. I've updated the code accordingly.

bcotrim · 2026-03-09T12:26:50Z

+			const socket = await this.connect();
+			return this.sendAndReadFromSocket( socket, payload );
+		} );
+		this.queue = responsePromise.then(


This pattern is odd, I wonder if there's a better approach to it.

I agree it's kind of an odd pattern. I also reacted to it previously and chatted with Codex about it.

Really, it's deceptively simple. It works because each send call reassigns the queue promise, so the result is a chain of promises. See https://jsfiddle.net/vjpdy7q4/1/ for a clearer proof of concept

bcotrim · 2026-03-09T12:33:44Z

+import path from 'path';
+
+export const PROCESS_MANAGER_HOME =
+	process.env.STUDIO_PROCESS_MANAGER_HOME ?? path.join( os.homedir(), '.studio', 'pm2' );


I'm assuming you decided keeping the pm2 name for backwards compatibility reasons, but I wonder if we should just rename it and handle existing folder content in a migration script or similar?

I'm assuming you decided keeping the pm2 name for backwards compatibility reasons

Yep, that's right. Seems reasonable to change the path and remove all pm2 naming, but I'd rather do it in a follow-up PR. I've added STU-1390 to track

fredrikekelund · 2026-03-10T09:07:47Z

Thanks for the review, @bcotrim! 🙏 I should've caught the "Stop all" thing sooner…

Killing a site process (kill pid) didn't reflect on Studio. Site was still running in the UI and stop operation didn't work (CLI worked fine). I could only replicate this once

I'll test this some more. There's no obvious reason why this would happen…

Doing Stop all from the Studio UI button, seems to break the UI. After doing stop all starting any other sites would not be reflected in the UI. I was able to replicate this consistently.

That was because SocketClient wouldn't reconnect when the underlying socket closed (which it did when the process manager daemon shut down and closed its eventsServer).

I've refactored socket.ts so the socket client automatically reconnects and verified that this has the desired effect in the app. I also took the opportunity to add an E2E test that clicks the Stop all button and then restarts a site. Seems like a useful thing to have in the test suite.

bcotrim · 2026-03-10T11:18:11Z

+const processDescriptionSchemaStopped = processDescriptionSchemaBase.extend( {
+	status: z.literal( 'stopped' ),
+} );
+export const processDescriptionSchema = z.discriminatedUnion( 'status', [


bcotrim

LGTM 👍
I can no longer replicate any of the issues I mentioned, thanks for making the changes

fredrikekelund and others added 17 commits March 3, 2026 09:37

Replace pm2-axon with homegrown solution

8f4e1f5

Use SocketClient instead of canConnect function

ccd1428

Tweak tests

1ff4737

Merge branch 'trunk' into stu-1301-replace-pm2-axon-with-homegrown

fbd360c

Get logs when process fails

24cdda5

Merge branch 'trunk' into stu-1301-replace-pm2-axon-with-homegrown

a9d79c7

Revert "Get logs when process fails"

2eb9aed

This reverts commit 24cdda5.

Merge branch 'trunk' into stu-1301-replace-pm2-axon-with-homegrown

7b314fe

Replace pm2 with homegrown process manager

3c14c79

Simplify schemas and types

0040ebf

Rename events

d273070

Move files around

3e35626

More file renaming

5d3d444

Conditionally enable JSPI

b91836e

Cleanup

d38a76b

Stronger types, cleanup

154d849

Clean up socket path on close

776af2b

fredrikekelund requested review from a team and bcotrim March 5, 2026 15:32

fredrikekelund self-assigned this Mar 5, 2026

fredrikekelund added 3 commits March 6, 2026 08:34

Remove managedProcessesByName dict

689ac48

Create PROCESS_MANAGER_HOME on Windows, too

e2d48ba

Fix unit tests

48e3330

bcotrim mentioned this pull request Mar 6, 2026

Replace pm2-axon with homegrown solution #2690

Merged

1 task

Base automatically changed from stu-1301-replace-pm2-axon-with-homegrown to trunk March 9, 2026 07:27

Merge branch 'trunk' into stu-1349-replace-pm2-with-homegrown

8da6a52

Merge branch 'trunk' into stu-1349-replace-pm2-with-homegrown

b9212c6

bcotrim requested changes Mar 9, 2026

View reviewed changes

Reconnect functionality for SocketClient

2cc30b9

fredrikekelund added 5 commits March 10, 2026 09:18

Separate SocketStreamClient and SocketRequestClient

dc98906

Log _events bind failure

18e4ad0

Add E2E test for stopping all sites and starting again

aeeb8cb

Discriminated union types for running/stopped processes

593f53e

Fix type errors

483ef1c

bcotrim reviewed Mar 10, 2026

View reviewed changes

bcotrim approved these changes Mar 10, 2026

View reviewed changes

fredrikekelund added 3 commits March 10, 2026 13:31

Listen on eventsServer first

ed563f0

Synchronous forceCleanupChildren method

c649e82

Minor tweaks

244af3f

fredrikekelund enabled auto-merge (squash) March 10, 2026 13:41

fredrikekelund merged commit 7d2b52f into trunk Mar 10, 2026
8 of 10 checks passed

fredrikekelund deleted the stu-1349-replace-pm2-with-homegrown branch March 10, 2026 13:50

bcotrim mentioned this pull request Apr 20, 2026

CLI: Rename process manager home from .studio/pm2 to .studio/daemon #3143

Merged

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace pm2 with homegrown process manager daemon#2712

Replace pm2 with homegrown process manager daemon#2712
fredrikekelund merged 31 commits into
trunkfrom
stu-1349-replace-pm2-with-homegrown

fredrikekelund commented Mar 5, 2026 •

edited

Loading

Uh oh!

wpmobilebot commented Mar 9, 2026 •

edited

Loading

Uh oh!

bcotrim left a comment

Uh oh!

bcotrim Mar 9, 2026

Uh oh!

fredrikekelund Mar 10, 2026

Uh oh!

bcotrim Mar 9, 2026

Uh oh!

fredrikekelund Mar 10, 2026

Uh oh!

bcotrim Mar 9, 2026

Uh oh!

fredrikekelund Mar 10, 2026

Uh oh!

fredrikekelund commented Mar 10, 2026

Uh oh!

bcotrim Mar 10, 2026

Uh oh!

bcotrim left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

fredrikekelund commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues

How AI was used in this PR

Proposed Changes

Testing Instructions

Pre-merge Checklist

Uh oh!

wpmobilebot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Performance Test Results

site-editor

site-startup

Uh oh!

bcotrim left a comment

Choose a reason for hiding this comment

Uh oh!

bcotrim Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

bcotrim Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

bcotrim Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

fredrikekelund commented Mar 10, 2026

Uh oh!

bcotrim Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

bcotrim left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fredrikekelund commented Mar 5, 2026 •

edited

Loading

wpmobilebot commented Mar 9, 2026 •

edited

Loading