The best way to control Claude Code, Codex and more from any computer or phone
perf(desktop): speed up cold Linux x64 backend startup (#32987)
Co-authored-by: GPT 6.1 Sol <codex@openai.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Grok 4.7 <noreply@x.ai>
Wout Stiens committed
Nov 8, 2026 at 20:15 UTC
401318317177a375f064d4fabd18d49fb4b5231f
4 files changed
+234
-47
docs/operations/development.md
+9
-8
@@ -270,13 +270,14 @@ options.
270
271
### Prepared server bytecode
272
273
-Native macOS and Windows desktop artifact builds generate server bytecode with the packaged
274
-Electron executable, after ASAR creation and before signing. Linux builds skip generation until
275
-native packaging and relocated AppImage reuse have been validated. macOS x64 builds on ARM64
276
-hosts run the packaged x64 Electron under Rosetta to generate the cache. Other cross-platform and
277
-cross-architecture builds skip generation explicitly. CLI, SEA and WSL runtimes keep their
278
-existing behavior; only desktop backend imports covered by generation receive prepared bytecode.
279
-Worker-only modules compile normally.
273
+Native macOS and Windows desktop artifact builds, and native Linux x64 builds, generate server
274
+bytecode with the packaged Electron executable, after ASAR creation and before signing. Generation imports the CLI and server
275
+module declarations without launching server services; worker-only modules compile normally.
276
+AppImage backends use temporary links for each mount and remove them on normal exit. Later launches
277
+reclaim abandoned cache directories whose links point to gone mounts; AppImage main-process caching
278
+stays disabled. macOS x64 builds on ARM64 hosts run the packaged x64 Electron
279
+under Rosetta to generate the cache. Other cross-platform and cross-architecture builds skip
280
+generation explicitly. CLI, SEA and WSL runtimes keep their existing behavior.
281
282
Electron's Node 24 cache has no read-only option and includes the producer UID in its directory
283
name. The backend links individual prepared files into its writable cache with keys for the
@@ -286,7 +287,7 @@ differ or resource permissions prevent linking. Protected installations therefor
287
prepared bytecode. No cache bytes are copied during startup.
288
289
The key calculation follows Node's internal portable ESM format. Generation checks that the
289
-packaged engine produced the expected CLI entry and fails the build if that format changes.
290
+packaged engine produced the expected CLI and server entries and fails the build if that format changes.
291
The manifest also checks Electron, Node, OS, architecture and V8's flags-sensitive version tag.
292
Missing or rejected entries compile from the shipped JavaScript. Prepared backends skip the
293
explicit startup flush; Node can persist missing entries on normal exit. The writable fallback
scripts/lib/server-compile-cache.test.ts
+171
-34
@@ -6,38 +6,54 @@ import * as NodeURL from "node:url";
6
import { expect, it } from "vite-plus/test";
7
import { cacheKey, seedPreparedCache } from "./server-compile-cache.ts";
8
9
-it.each(["x64", "arm64"])("skips prepared bytecode generation on Linux %s", async (arch) => {
10
- const { spawnSync } = await import("node:child_process");
11
- const hook = NodeURL.fileURLToPath(
12
- new URL("../prepare-server-compile-cache.cjs", import.meta.url),
13
- );
14
- const result = spawnSync(
15
- process.execPath,
16
- [
17
- "-e",
18
- `Object.defineProperty(process, "platform", { value: "linux" });
19
- Object.defineProperty(process, "arch", { value: ${JSON.stringify(arch)} });
20
- require(${JSON.stringify(hook)})({ electronPlatformName: "linux", arch: ${arch === "x64" ? 1 : 3} }).catch(error => { console.error(error); process.exitCode = 1; });`,
21
- ],
22
- { encoding: "utf8" },
23
- );
24
- expect(result.status, result.stderr).toBe(0);
25
- expect(result.stdout).toContain("Skipping unsupported target linux");
26
-});
9
+it.each([
10
+ { platform: "freebsd", hostArch: "x64", arch: 1, reason: "unsupported target freebsd" },
11
+ { platform: "linux", hostArch: "arm64", arch: 3, reason: "unsupported Linux architecture arm64" },
12
+])(
13
+ "skips unsupported $platform/$hostArch cache generation",
14
+ async ({ platform, hostArch, arch, reason }) => {
15
+ const { spawnSync } = await import("node:child_process");
16
+ const hook = NodeURL.fileURLToPath(
17
+ new URL("../prepare-server-compile-cache.cjs", import.meta.url),
18
+ );
19
+ const result = spawnSync(
20
+ process.execPath,
21
+ [
22
+ "-e",
23
+ `Object.defineProperty(process, "platform", { value: ${JSON.stringify(platform)} });
24
+ Object.defineProperty(process, "arch", { value: ${JSON.stringify(hostArch)} });
25
+ require(${JSON.stringify(hook)})({ electronPlatformName: ${JSON.stringify(platform)}, arch: ${arch} }).catch(error => { console.error(error); process.exitCode = 1; });`,
26
+ ],
27
+ { encoding: "utf8" },
28
+ );
29
+ expect(result.status, result.stderr).toBe(0);
30
+ expect(result.stdout).toContain(`Skipping ${reason}`);
31
+ },
32
+);
33
28
-it("prepares macOS x64 cache on an ARM64 build host", async () => {
34
+// macOS runs on an ARM64 host to exercise the Rosetta build-host check.
35
+it.each([
36
+ {
37
+ platform: "darwin",
38
+ hostArch: "arm64",
39
+ resources: "Fixture.app/Contents/Resources",
40
+ executable: "Fixture.app/Contents/MacOS/Fixture",
41
+ },
42
+ { platform: "linux", hostArch: "x64", resources: "resources", executable: "fixture" },
43
+])("prepares $platform x64 cache", async ({ platform, hostArch, ...layout }) => {
44
const { spawnSync } = await import("node:child_process");
45
const root = NodeFS.realpathSync(
31
- NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-rosetta-cache-")),
46
+ NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-hook-cache-")),
47
);
48
try {
34
- const resources = NodePath.join(root, "Fixture.app", "Contents", "Resources");
49
+ const resources = NodePath.join(root, layout.resources);
50
const archive = NodePath.join(resources, "app.asar");
51
const dist = NodePath.join(archive, "apps/server/dist");
52
const helper = NodePath.join(archive, "apps/desktop/dist-electron/serverCompileCache.cjs");
53
NodeFS.mkdirSync(dist, { recursive: true });
54
NodeFS.mkdirSync(NodePath.dirname(helper), { recursive: true });
55
NodeFS.writeFileSync(NodePath.join(dist, "binCli-fixture.mjs"), "export const answer = 42;");
56
+ NodeFS.writeFileSync(NodePath.join(dist, "server-fixture.mjs"), "export const answer = 43;");
57
NodeFS.writeFileSync(
58
helper,
59
`module.exports = require(${JSON.stringify(NodeURL.fileURLToPath(new URL("./server-compile-cache.ts", import.meta.url)))});`,
@@ -45,7 +61,7 @@ it("prepares macOS x64 cache on an ARM64 build host", async () => {
61
const hook = NodeURL.fileURLToPath(
62
new URL("../prepare-server-compile-cache.cjs", import.meta.url),
63
);
48
- // The fixture uses Node for generation; the hook still sees an ARM64 macOS build host.
64
+ // Node stands in for the packaged engine.
65
const result = spawnSync(
66
process.execPath,
67
[
@@ -54,14 +70,14 @@ it("prepares macOS x64 cache on an ARM64 build host", async () => {
70
const childProcess = require("node:child_process");
71
const spawn = childProcess.spawnSync;
72
childProcess.spawnSync = (executable, args, options) => {
57
- require("node:assert/strict").equal(executable, ${JSON.stringify(NodePath.join(root, "Fixture.app", "Contents", "MacOS", "Fixture"))});
73
+ require("node:assert/strict").equal(executable, ${JSON.stringify(NodePath.join(root, layout.executable))});
74
return spawn(process.execPath, args, options);
75
};
60
- Object.defineProperty(process, "platform", { value: "darwin" });
61
- Object.defineProperty(process, "arch", { value: "arm64" });
76
+ Object.defineProperty(process, "platform", { value: ${JSON.stringify(platform)} });
77
+ Object.defineProperty(process, "arch", { value: ${JSON.stringify(hostArch)} });
78
require(${JSON.stringify(hook)})({
63
- appOutDir: ${JSON.stringify(root)}, electronPlatformName: "darwin", arch: 1,
64
- packager: { appInfo: { productFilename: "Fixture" } }
79
+ appOutDir: ${JSON.stringify(root)}, electronPlatformName: ${JSON.stringify(platform)}, arch: 1,
80
+ packager: { appInfo: { productFilename: "Fixture" }, executableName: "fixture" }
81
}).catch(error => { console.error(error); process.exitCode = 1; });
82
`,
83
],
@@ -71,11 +87,19 @@ it("prepares macOS x64 cache on an ARM64 build host", async () => {
87
const manifest = JSON.parse(
88
NodeFS.readFileSync(NodePath.join(resources, "server-compile-cache/manifest.json"), "utf8"),
89
);
74
- expect(manifest.entries).toEqual([
90
+ expect(
91
+ manifest.entries.sort((a: { module: string }, b: { module: string }) =>
92
+ a.module.localeCompare(b.module),
93
+ ),
94
+ ).toEqual([
95
{
96
module: "app.asar/apps/server/dist/binCli-fixture.mjs",
97
file: expect.stringMatching(/^[a-f0-9]{8}$/),
98
},
99
+ {
100
+ module: "app.asar/apps/server/dist/server-fixture.mjs",
101
+ file: expect.stringMatching(/^[a-f0-9]{8}$/),
102
+ },
103
]);
104
expect(
105
NodeFS.statSync(NodePath.join(resources, "server-compile-cache", manifest.entries[0].file))
@@ -86,6 +110,107 @@ it("prepares macOS x64 cache on an ARM64 build host", async () => {
110
}
111
});
112
113
+it("rejects ambiguous bundled server entries before importing them", async () => {
114
+ const { spawnSync } = await import("node:child_process");
115
+ const root = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-cache-ambiguous-"));
116
+ try {
117
+ const dist = NodePath.join(root, "app.asar/apps/server/dist");
118
+ NodeFS.mkdirSync(dist, { recursive: true });
119
+ for (const file of ["binCli-fixture.mjs", "server-fixture.mjs", "server-unrelated.mjs"]) {
120
+ NodeFS.writeFileSync(NodePath.join(dist, file), "throw Error('Unexpected import');");
121
+ }
122
+ const result = spawnSync(
123
+ process.execPath,
124
+ [
125
+ "--input-type=module",
126
+ "-e",
127
+ `import {generatePreparedServerCache} from ${JSON.stringify(new URL("./server-compile-cache.ts", import.meta.url).href)}; await generatePreparedServerCache(${JSON.stringify(root)});`,
128
+ ],
129
+ {
130
+ encoding: "utf8",
131
+ env: {
132
+ ...process.env,
133
+ NODE_COMPILE_CACHE: undefined,
134
+ NODE_DISABLE_COMPILE_CACHE: undefined,
135
+ },
136
+ },
137
+ );
138
+ expect(result.status).not.toBe(0);
139
+ expect(result.stderr).toContain("Ambiguous bundled server entry");
140
+ expect(NodeFS.existsSync(NodePath.join(root, "server-compile-cache/manifest.json"))).toBe(
141
+ false,
142
+ );
143
+ } finally {
144
+ NodeFS.rmSync(root, { recursive: true, force: true });
145
+ }
146
+});
147
+
148
+it("reclaims only AppImage cache directories linked to gone mounts", async () => {
149
+ const { spawnSync } = await import("node:child_process");
150
+ const root = NodeFS.realpathSync(
151
+ NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-cache-reclaim-")),
152
+ );
153
+ try {
154
+ const resources = NodePath.join(root, ".mount_live/resources");
155
+ const prepared = NodePath.join(resources, "server-compile-cache");
156
+ const cacheRoot = NodePath.join(root, "cache");
157
+ const server = NodePath.join(cacheRoot, "server");
158
+ NodeFS.mkdirSync(prepared, { recursive: true });
159
+ NodeFS.writeFileSync(NodePath.join(prepared, "manifest.json"), "{}");
160
+ NodeFS.writeFileSync(NodePath.join(prepared, "12345678"), "live bytes");
161
+ const gone = NodePath.join(root, ".mount_gone/resources/server-compile-cache/12345678");
162
+ for (const [name, targets] of [
163
+ ["appimage-stale", [gone]],
164
+ ["appimage-live", [NodePath.join(prepared, "12345678")]],
165
+ ["appimage-live-damaged", [NodePath.join(prepared, "87654321")]],
166
+ ["appimage-mixed", [gone, NodePath.join(prepared, "12345678")]],
167
+ ["appimage-unrelated", [NodePath.join(root, "unrelated-missing")]],
168
+ ["other-cache", [gone]],
169
+ ["appimage-initializing", []],
170
+ ] as const) {
171
+ const active = NodePath.join(server, name, "v24-engine-uid");
172
+ NodeFS.mkdirSync(active, { recursive: true });
173
+ targets.forEach((target, index) =>
174
+ NodeFS.symlinkSync(target, NodePath.join(active, index === 0 ? "12345678" : "87654321")),
175
+ );
176
+ NodeFS.writeFileSync(NodePath.join(active, "abcdef01"), "runtime replacement");
177
+ }
178
+ NodeFS.symlinkSync(
179
+ NodePath.join(server, "other-cache"),
180
+ NodePath.join(server, "appimage-directory-link"),
181
+ );
182
+ const result = spawnSync(
183
+ process.execPath,
184
+ [
185
+ "--input-type=module",
186
+ "-e",
187
+ `process.env.APPIMAGE = "fixture"; import {enablePreparedServerCache} from ${JSON.stringify(new URL("./server-compile-cache.ts", import.meta.url).href)}; if (!enablePreparedServerCache(${JSON.stringify(NodePath.join(resources, "app.asar/apps/server/dist/binCli-fixture.mjs"))}, ${JSON.stringify(cacheRoot)})) throw Error("cache disabled");`,
188
+ ],
189
+ {
190
+ encoding: "utf8",
191
+ env: {
192
+ ...process.env,
193
+ NODE_COMPILE_CACHE: undefined,
194
+ NODE_DISABLE_COMPILE_CACHE: undefined,
195
+ },
196
+ },
197
+ );
198
+ expect(result.status, result.stderr).toBe(0);
199
+ expect(NodeFS.readdirSync(server).sort()).toEqual([
200
+ "appimage-directory-link",
201
+ "appimage-initializing",
202
+ "appimage-live",
203
+ "appimage-live-damaged",
204
+ "appimage-mixed",
205
+ "appimage-unrelated",
206
+ "other-cache",
207
+ ]);
208
+ expect(NodeFS.readFileSync(NodePath.join(prepared, "12345678"), "utf8")).toBe("live bytes");
209
+ } finally {
210
+ NodeFS.rmSync(root, { recursive: true, force: true });
211
+ }
212
+});
213
+
214
it("seeds relocated cache entries without allowing writes into shipped resources", () => {
215
const root = NodeFS.realpathSync(
216
NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-prepared-test-")),
@@ -158,21 +283,33 @@ it.each(["app", "server"])(
283
const consumer = NodePath.join(root, "relocated", "resources");
284
const relative = `${archive}.asar/apps/server/dist/binCli-fixture.mjs`;
285
NodeFS.mkdirSync(NodePath.dirname(NodePath.join(producer, relative)), { recursive: true });
161
- NodeFS.writeFileSync(NodePath.join(producer, relative), "export const answer = 42;");
286
+ NodeFS.writeFileSync(
287
+ NodePath.join(producer, relative),
288
+ "export const answer = 42; export const loadServer = () => import('./server-fixture.mjs');",
289
+ );
290
+ NodeFS.writeFileSync(
291
+ NodePath.join(producer, `${archive}.asar/apps/server/dist/server-fixture.mjs`),
292
+ "export const answer = 43;",
293
+ );
294
run(
295
`import {generatePreparedServerCache} from ${JSON.stringify(helper)}; await generatePreparedServerCache(${JSON.stringify(producer)});`,
296
);
297
NodeFS.cpSync(producer, consumer, { recursive: true });
298
const consume = (home: string, appImage = false) =>
299
run(
168
- `if (${appImage}) process.env.APPIMAGE = "fixture"; import {enablePreparedServerCache} from ${JSON.stringify(helper)}; import {pathToFileURL} from 'node:url'; if(!enablePreparedServerCache(${JSON.stringify(NodePath.join(consumer, relative))},${JSON.stringify(NodePath.join(root, home))})) throw Error('cache disabled'); const m = await import(pathToFileURL(${JSON.stringify(NodePath.join(consumer, relative))}).href); if(m.answer!==42) throw Error('source fallback failed');`,
300
+ `if (${appImage}) process.env.APPIMAGE = "fixture"; import {enablePreparedServerCache} from ${JSON.stringify(helper)}; import {pathToFileURL} from 'node:url'; if(!enablePreparedServerCache(${JSON.stringify(NodePath.join(consumer, relative))},${JSON.stringify(NodePath.join(root, home))})) throw Error('cache disabled'); const m = await import(pathToFileURL(${JSON.stringify(NodePath.join(consumer, relative))}).href); if(m.answer!==42 || (await m.loadServer()).answer!==43) throw Error('source fallback failed');`,
301
);
302
const prepared = NodePath.join(consumer, "server-compile-cache");
303
NodeFS.chmodSync(prepared, 0o555);
172
- expect(consume("first-user")).toContain("was accepted");
173
- expect(consume("appimage-user", true)).toContain("was accepted");
174
- expect(NodeFS.readdirSync(NodePath.join(root, "appimage-user", "server"))).toEqual([]);
175
- NodeFS.chmodSync(prepared, 0o755);
304
+ try {
305
+ const first = consume("first-user");
306
+ expect(first).toMatch(/binCli-fixture\.mjs was accepted/);
307
+ expect(first).toMatch(/server-fixture\.mjs was accepted/);
308
+ expect(consume("appimage-user", true)).toContain("was accepted");
309
+ expect(NodeFS.readdirSync(NodePath.join(root, "appimage-user", "server"))).toEqual([]);
310
+ } finally {
311
+ NodeFS.chmodSync(prepared, 0o755);
312
+ }
313
for (const file of NodeFS.readdirSync(prepared).filter((file) => file !== "manifest.json")) {
314
NodeFS.writeFileSync(NodePath.join(prepared, file), "broken");
315
}
scripts/lib/server-compile-cache.ts
+49
-3
@@ -77,6 +77,45 @@ export function enablePreparedServerCache(entry: string, cacheRoot: string): boo
77
return false;
78
const identity = NodeZlib.crc32(resources).toString(16);
79
NodeFS.mkdirSync(NodePath.join(cacheRoot, "server"), { recursive: true });
80
+ if (process.env.APPIMAGE) {
81
+ try {
82
+ for (const candidate of NodeFS.readdirSync(NodePath.join(cacheRoot, "server"), {
83
+ withFileTypes: true,
84
+ })) {
85
+ if (!candidate.isDirectory() || !candidate.name.startsWith("appimage-")) continue;
86
+ const abandoned = NodePath.join(cacheRoot, "server", candidate.name);
87
+ let hasStaleLink = false;
88
+ // Node nests files under an engine/UID directory and can replace links with regular files.
89
+ const removable = NodeFS.readdirSync(abandoned, { withFileTypes: true }).every(
90
+ (engine) =>
91
+ engine.isDirectory() &&
92
+ NodeFS.readdirSync(NodePath.join(abandoned, engine.name), {
93
+ withFileTypes: true,
94
+ }).every((file) => {
95
+ if (!/^[a-f0-9]{8}$/.test(file.name)) return false;
96
+ if (!file.isSymbolicLink()) return file.isFile();
97
+ const target = NodeFS.readlinkSync(
98
+ NodePath.join(abandoned, engine.name, file.name),
99
+ );
100
+ const mount = target.match(/^(.*[\\/]\.mount_[^/\\]+)[\\/]/)?.[1];
101
+ if (
102
+ !mount ||
103
+ !NodePath.isAbsolute(target) ||
104
+ NodePath.basename(NodePath.dirname(target)) !== "server-compile-cache" ||
105
+ !/^[a-f0-9]{8}$/.test(NodePath.basename(target))
106
+ )
107
+ return false;
108
+ if (NodeFS.lstatSync(mount, { throwIfNoEntry: false })) return false;
109
+ hasStaleLink = true;
110
+ return true;
111
+ }),
112
+ );
113
+ if (removable && hasStaleLink) NodeFS.rmSync(abandoned, { recursive: true, force: true });
114
+ }
115
+ } catch {
116
+ // Concurrent removal or restricted permissions must not prevent enabling this launch's cache.
117
+ }
118
+ }
119
const directory = process.env.APPIMAGE
120
? NodeFS.mkdtempSync(NodePath.join(cacheRoot, "server", "appimage-"))
121
: NodePath.join(cacheRoot, "server", identity);
@@ -113,12 +152,19 @@ export async function generatePreparedServerCache(resourcesInput: string): Promi
152
const result = NodeModule.enableCompileCache({ directory: prepared, portable: true });
153
if (result.status !== NodeModule.constants.compileCacheStatus.ENABLED)
154
throw new Error("Cannot enable release compile cache");
116
- const cli = NodeFS.readdirSync(dist).find((file) => /^binCli-.*\.mjs$/.test(file));
155
+ const files = NodeFS.readdirSync(dist);
156
+ const cli = files.find((file) => /^binCli-.*\.mjs$/.test(file));
157
if (!cli) throw new Error("Missing bundled server CLI");
158
+ const servers = files.filter((file) => /^server-.*\.mjs$/.test(file));
159
+ if (servers.length > 1) throw new Error("Ambiguous bundled server entry");
160
+ const server = servers[0];
161
+ if (!server) throw new Error("Missing bundled server entry");
162
await import(NodeURL.pathToFileURL(NodePath.join(dist, cli)).href);
163
+ // The CLI loads the server dynamically; importing its declarative layers does not launch them.
164
+ await import(NodeURL.pathToFileURL(NodePath.join(dist, server)).href);
165
NodeModule.flushCompileCache();
166
const active = NodeModule.getCompileCacheDir()!;
121
- const entries = NodeFS.readdirSync(dist)
167
+ const entries = files
168
.filter((file) => file.endsWith(".mjs"))
169
.flatMap((file) => {
170
const key = cacheKey(active, NodePath.join(dist, file));
@@ -126,7 +172,7 @@ export async function generatePreparedServerCache(resourcesInput: string): Promi
172
NodeFS.copyFileSync(NodePath.join(active, key), NodePath.join(prepared, key));
173
return [{ module: `${archive}/apps/server/dist/${file}`, file: key }];
174
});
129
- if (!entries.some((entry) => entry.module.endsWith(`/${cli}`)))
175
+ if (![cli, server].every((file) => entries.some((entry) => entry.module.endsWith(`/${file}`))))
176
throw new Error("Packaged engine cache key format is unsupported");
177
NodeFS.writeFileSync(
178
NodePath.join(prepared, "manifest.json"),
scripts/prepare-server-compile-cache.cjs
+5
-2
@@ -6,12 +6,15 @@ const os = require("node:os");
6
7
// afterPack runs before signing and installer creation, against the final ASAR layout.
8
module.exports = async ({ appOutDir, electronPlatformName, arch, packager }) => {
9
- // Linux packaging and relocated AppImage cache reuse still need native validation.
10
- if (electronPlatformName !== "darwin" && electronPlatformName !== "win32") {
9
+ if (!["darwin", "win32", "linux"].includes(electronPlatformName)) {
10
console.log(`[server-compile-cache] Skipping unsupported target ${electronPlatformName}`);
11
return;
12
}
13
const targetArch = ["ia32", "x64", "armv7l", "arm64", "universal"][arch];
14
+ if (electronPlatformName === "linux" && targetArch !== "x64") {
15
+ console.log(`[server-compile-cache] Skipping unsupported Linux architecture ${targetArch}`);
16
+ return;
17
+ }
18
const runsWithRosetta =
19
electronPlatformName === "darwin" &&
20
process.platform === "darwin" &&