@devries-cameron20 / t3code-1 / commits / 4013183171
Fork 0

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" &&