The best way to control Claude Code, Codex and more from any computer or phone
fix(build): TEMPORARY workaround so linux-arm64 builds run on 16/64 KiB page kernels (#25825)
TEMPORARY workaround for an upstream Node bug: https://github.com/nodejs/node/issues/67048 Node 26.9+ --build-sea writes linux-arm64 executables that 16/64 KiB page kernels cannot load. linux-arm64 now injects with postject, and the archive build rejects incompatible ELF layouts. One-time exception. Revert once Node ships a fix: grep for the Node issue URL and drop postject from scripts/package.json. Fixes #23433. Replaces #23443. Co-authored-by: Lakshmi Tanmay <lakshmi@voltcrash.com> Co-authored-by: maria-rcks <maria@kuuro.net> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 27, 2026 at 01:45 UTC
c175e5737eddeef1b7376a6761f29da926f53ea3
8 files changed
+228
-14
apps/server/scripts/cli.ts
+20
-6
@@ -11,7 +11,9 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process";
11
12
import { DEVELOPMENT_ICON_OVERRIDES } from "../../../scripts/lib/brand-assets.ts";
13
import { findEsmImportsOfExternalPackages } from "../../../scripts/lib/cli-executable-imports.ts";
14
+import { injectLinuxArm64Sea } from "../../../scripts/lib/linux-arm64-sea.ts";
15
import rootPackageJson from "../../../package.json" with { type: "json" };
16
+import * as HostProcess from "@t3tools/shared/HostProcess";
17
import { resolveSpawnCommand } from "@t3tools/shared/shell";
18
import {
19
ServerCliBuildAssetMissingError,
@@ -118,17 +120,20 @@ const buildExeCmd = Command.make(
120
const serverDir = path.join(repoRoot, "apps/server");
121
122
yield* Effect.log("[cli] Building single-executable...");
123
+ const target = Option.getOrUndefined(config.target);
124
+ // TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
125
+ const linuxArm64 =
126
+ !target &&
127
+ (yield* HostProcess.Platform) === "linux" &&
128
+ (yield* HostProcess.Architecture) === "arm64";
129
const spawnCommand = yield* resolveSpawnCommand("vp", ["pack"]);
130
yield* runCommand(
131
ChildProcess.make(spawnCommand.command, spawnCommand.args, {
132
cwd: serverDir,
133
env: {
134
...process.env,
127
- T3CODE_PACK_EXE: "1",
128
- ...Option.match(config.target, {
129
- onNone: () => ({}),
130
- onSome: (target) => ({ T3CODE_PACK_EXE_TARGET: target }),
131
- }),
135
+ T3CODE_PACK_EXE: linuxArm64 ? "bundle" : "1",
136
+ T3CODE_PACK_EXE_TARGET: target ?? "",
137
},
138
stdout: config.verbose ? "inherit" : "ignore",
139
stderr: "inherit",
@@ -142,13 +147,22 @@ const buildExeCmd = Command.make(
147
if (specifiers.length > 0) {
148
return yield* new ServerCliExecutableImportError({ bundlePath, specifiers });
149
}
150
+ // TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
151
+ if (linuxArm64) {
152
+ yield* injectLinuxArm64Sea({
153
+ bundlePath,
154
+ outputPath: path.join(serverDir, "dist-exe/t3"),
155
+ nodeVersion: rootPackageJson.engines.node,
156
+ verbose: config.verbose,
157
+ });
158
+ }
159
yield* Effect.log(
160
"[cli] Built dist-exe/t3 (expects client/, resource-monitor/, and the runtime-external node_modules beside it; scripts/build-cli-archive.ts assembles that tree)",
161
);
162
}),
163
).pipe(
164
Command.withDescription(
151
- `Build the server as a Node single-executable. Native builds require Node ${rootPackageJson.engines.node}; explicit cross-target builds need a Node 25.7+ host for --build-sea. The binary still resolves native packages from a node_modules tree beside it.`,
165
+ `Build the server as a Node single-executable. Native builds require Node ${rootPackageJson.engines.node}; explicit cross-target builds need a Node 25.7+ host for --build-sea. Linux ARM64 builds only on a Linux ARM64 host. The binary still resolves native packages from a node_modules tree beside it.`,
166
),
167
);
168
apps/server/vite.config.ts
+10
-3
@@ -29,11 +29,15 @@ if (!TELEMETRY_CHANNELS.includes(telemetryChannel)) {
29
}
30
31
// tsdown SEA needs one chunk (sourcemaps count) and Node >=25.7, so package separately.
32
-const packExecutable = process.env.T3CODE_PACK_EXE === "1";
32
+// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
33
+// "1" builds dist-exe/t3 here; "bundle" stops at bin.mjs for scripts/cli.ts to inject (linux-arm64).
34
+const packMode = process.env.T3CODE_PACK_EXE;
35
+const packExecutable = packMode === "1" || packMode === "bundle";
36
+// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
37
+// No linux-arm64: --build-sea output cannot load on 16/64 KiB page kernels, so it builds natively.
38
const SEA_TARGETS = {
39
"darwin-arm64": { platform: "darwin", arch: "arm64" },
40
"darwin-x64": { platform: "darwin", arch: "x64" },
36
- "linux-arm64": { platform: "linux", arch: "arm64" },
41
"linux-x64": { platform: "linux", arch: "x64" },
42
"win-arm64": { platform: "win", arch: "arm64" },
43
"win-x64": { platform: "win", arch: "x64" },
@@ -83,7 +87,10 @@ export default mergeConfig(
87
outDir: packExecutable ? "dist-exe" : "dist",
88
sourcemap: !packExecutable,
89
clean: true,
86
- ...(packExecutable
90
+ // TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
91
+ // SEA can only resolve built-ins; keep dynamic imports inside its one module.
92
+ ...(packExecutable ? { outputOptions: { codeSplitting: false } } : {}),
93
+ ...(packMode === "1"
94
? {
95
exe: {
96
fileName: "t3",
docs/operations/release.md
+1
-1
@@ -44,7 +44,7 @@ the version.
44
- Includes Electron auto-update metadata (for example `latest*.yml`, `nightly*.yml`, and `*.blockmap`) in release assets.
45
- Builds a self-contained CLI archive per platform (`t3-<version>-<platform>-<arch>.tar.gz`, `.zip` on Windows) in the same job as that target's desktop artifact and attaches them to the GitHub Release with a `SHA256SUMS` file, on every channel, for five targets: macOS arm64, Linux x64 and arm64, Windows x64 and arm64. Every archive is smoke-tested on hardware of its own architecture, and every one but the Windows archives is also built and signed there. There is no macOS x64 archive: Node single-executables are unsupported on x64 macOS (the SEA docs list macOS as arm64 only) and the binary segfaults on start; the x64 desktop app is Electron and unaffected.
46
- The archive holds the server as a Node single-executable (`scripts/build-cli-archive.ts`), so unpacking it needs neither Node, npm, nor a compiler. It is the only form in which T3 Code manages a runtime: the desktop's SSH environments, the boot service, `t3 update`, and the install scripts all download and verify this archive against `SHA256SUMS`. The `t3` npm package exists for people who run `npx t3` or `npm install -g t3` themselves, and it downloads this same archive too; nothing in the product installs from npm. The `curl | sh` installers are `scripts/install.sh` and `scripts/install.ps1`; the marketing site copies them into its `public/` at build time (`apps/marketing/scripts/stage-install-scripts.mjs`) and serves them at `t3.codes/install.sh` and `/install.ps1`.
47
- - The root `package.json` pins `engines.node` to the exact Node version used by development, CI and standalone executables. Keep it exact: cross-target builds download that version, and native executable builds reject a different host Node version. Runtime changes need a new T3 release version because installed runtimes are cached by that version.
47
+ - The root `package.json` pins `engines.node` to the exact Node version used by development, CI and standalone executables. Keep it exact: cross-target builds download that version, and native executable builds reject a different host Node version. TEMPORARY: Linux arm64 executables build only on a Linux arm64 host and are injected with postject, because Node's `--build-sea` output cannot load on 16 or 64 KiB page kernels. Revert when [nodejs/node#67048](https://github.com/nodejs/node/issues/67048) is fixed. Runtime changes need a new T3 release version because installed runtimes are cached by that version.
48
- macOS archives are signed with the Developer ID certificate and notarized when the Apple secrets are present (ad hoc otherwise, which still runs from `curl`/`tar` installs). Windows executables use the same Azure Trusted Signing setup as the installer. Every native addon in the macOS archive is signed too, since the hardened runtime refuses unsigned libraries.
49
- Each archive is extracted and executed (`scripts/smoke-cli-archive.ts`) on its build runner, or on the `verify_runner` for Windows.
50
- After the GitHub Release is published, publishes the `t3` npm package with OIDC trusted publishing from the same workflow file. It is only a launcher (`scripts/npm-launcher/t3.mjs`): on first run it downloads its exact version's CLI archive from the GitHub Release, verifies it against `SHA256SUMS`, and unpacks it into `<T3 home>/runtime/versions/<version>`, the layout the install scripts and `t3 update` share. The executables are not on npm. They used to be, as `@t3code/t3-<platform>-<arch>` optional dependencies, but npm's publish-time scanning held those 80-250 MB packages back for up to an hour after the launcher was live, and every install in that window got a launcher with no executable. Those packages stay on npm at their old versions and get no new ones. Because the launcher reads from the release, `publish_cli` runs after `release`, never before.
pnpm-lock.yaml
+4
-3
@@ -2298,6 +2298,9 @@ importers:
2298
esbuild:
2299
specifier: 0.28.2
2300
version: 0.28.2
2301
+ postject:
2302
+ specifier: 1.0.0-alpha.6
2303
+ version: 1.0.0-alpha.6
2304
typescript:
2305
specifier: 'catalog:'
2306
version: '@tsc-rs/typescript@0.8.0'
@@ -17966,8 +17969,7 @@ snapshots:
17969
17970
commander@8.3.0: {}
17971
17969
- commander@9.5.0:
17970
- optional: true
17972
+ commander@9.5.0: {}
17973
17974
common-ancestor-path@2.0.0: {}
17975
@@ -21189,7 +21191,6 @@ snapshots:
21191
postject@1.0.0-alpha.6:
21192
dependencies:
21193
commander: 9.5.0
21192
- optional: true
21194
21195
preact-render-to-string@6.6.5(preact@11.0.0-beta.0):
21196
dependencies:
scripts/build-cli-archive.ts
+7
-1
@@ -26,6 +26,7 @@ import {
26
resolveFffNativeDependencies,
27
STAGE_INSTALL_ARGS,
28
} from "./build-desktop-artifact.ts";
29
+import { assertLinuxArm64PageCompatibility } from "./lib/linux-arm64-sea.ts";
30
import { selectCliRuntimeExternalDependencies } from "./lib/cli-external-packages.ts";
31
import { signWithJsign } from "./lib/windows-jsign.ts";
32
import { windowsSystemTar } from "./lib/windows-tar.ts";
@@ -441,8 +442,13 @@ const buildCliArchive = Effect.fn("buildCliArchive")(function* (input: {
442
443
yield* requireInput(
444
builtExecutable,
444
- `Run \`node apps/server/scripts/cli.ts build-exe --target ${targetKey}\` first.`,
445
+ `Run \`node apps/server/scripts/cli.ts build-exe${targetKey === hostKey ? "" : ` --target ${targetKey}`}\` first.`,
446
);
447
+ // TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
448
+ if (input.platform === "linux" && input.arch === "arm64") {
449
+ const bytes = yield* fs.readFile(builtExecutable);
450
+ yield* Effect.try(() => assertLinuxArm64PageCompatibility(bytes));
451
+ }
452
yield* requireInput(path.join(webClient, "index.html"), "Run `vp run --filter t3 build` first.");
453
yield* requireInput(
454
resourceMonitorDir,
scripts/lib/linux-arm64-sea.test.ts
new
+64
@@ -0,0 +1,64 @@
1
+// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
2
+import { describe, expect, it } from "@effect/vitest";
3
+import { assertLinuxArm64PageCompatibility } from "./linux-arm64-sea.ts";
4
+
5
+function elf(loads: Array<{ offset: bigint; address: bigint; size: bigint }>) {
6
+ const bytes = new Uint8Array(64 + loads.length * 56);
7
+ const view = new DataView(bytes.buffer);
8
+ bytes.set([0x7f, 0x45, 0x4c, 0x46, 2, 1]);
9
+ view.setUint16(18, 183, true);
10
+ view.setBigUint64(32, 64n, true);
11
+ view.setUint16(54, 56, true);
12
+ view.setUint16(56, loads.length, true);
13
+ loads.forEach((load, index) => {
14
+ const start = 64 + index * 56;
15
+ view.setUint32(start, 1, true);
16
+ view.setBigUint64(start + 8, load.offset, true);
17
+ view.setBigUint64(start + 16, load.address, true);
18
+ view.setBigUint64(start + 40, load.size, true);
19
+ view.setBigUint64(start + 48, 0x1000n, true);
20
+ });
21
+ return bytes;
22
+}
23
+
24
+describe("Linux ARM64 SEA page compatibility", () => {
25
+ it("rejects the relocated SEA note from nightly 3512", () => {
26
+ expect(() =>
27
+ assertLinuxArm64PageCompatibility(
28
+ elf([{ offset: 0x8faf000n, address: 0x1015d000n, size: 0x1003000n }]),
29
+ ),
30
+ ).toThrow(/64 KiB/);
31
+ });
32
+
33
+ it("accepts congruent offsets even with a smaller declared alignment", () => {
34
+ expect(() =>
35
+ assertLinuxArm64PageCompatibility(
36
+ elf([
37
+ { offset: 0n, address: 0x400000n, size: 0x10000n },
38
+ { offset: 0x20000n, address: 0x420000n, size: 0x10000n },
39
+ ]),
40
+ ),
41
+ ).not.toThrow();
42
+ });
43
+
44
+ it("rejects segments that share a 64 KiB page", () => {
45
+ expect(() =>
46
+ assertLinuxArm64PageCompatibility(
47
+ elf([
48
+ { offset: 0n, address: 0x400000n, size: 0x11000n },
49
+ { offset: 0x11000n, address: 0x411000n, size: 0x1000n },
50
+ ]),
51
+ ),
52
+ ).toThrow(/overlap/);
53
+ });
54
+
55
+ it("rejects missing or malformed program headers", () => {
56
+ expect(() => assertLinuxArm64PageCompatibility(elf([]))).toThrow();
57
+ expect(() => assertLinuxArm64PageCompatibility(new Uint8Array(64))).toThrow();
58
+ expect(() =>
59
+ assertLinuxArm64PageCompatibility(
60
+ elf([{ offset: 0n, address: 0x400000n, size: 1n }]).subarray(0, 70),
61
+ ),
62
+ ).toThrow();
63
+ });
64
+});
scripts/lib/linux-arm64-sea.ts
new
+121
@@ -0,0 +1,121 @@
1
+// TEMPORARY one-time workaround for a Node --build-sea bug on Linux arm64.
2
+// It breaks kernels with 16 KiB or 64 KiB pages. Revert when Node ships a fix.
3
+// Node issue: https://github.com/nodejs/node/issues/67048
4
+// Workaround PR: https://github.com/pingdotgg/t3code/pull/25825
5
+import * as NodeModule from "node:module";
6
+import * as Effect from "effect/Effect";
7
+import * as FileSystem from "effect/FileSystem";
8
+import * as Path from "effect/Path";
9
+import * as Schema from "effect/Schema";
10
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
11
+
12
+class LinuxArm64SeaError extends Schema.TaggedError<LinuxArm64SeaError>()("LinuxArm64SeaError", {
13
+ message: Schema.String,
14
+}) {}
15
+
16
+const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
17
+
18
+const run = Effect.fn("LinuxArm64Sea.run")(function* (args: Array<string>, verbose: boolean) {
19
+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
20
+ const child = yield* spawner.spawn(
21
+ ChildProcess.make(process.execPath, args, {
22
+ stdout: verbose ? "inherit" : "ignore",
23
+ stderr: "inherit",
24
+ }),
25
+ );
26
+ const exitCode = yield* child.exitCode;
27
+ if (exitCode !== 0) {
28
+ return yield* new LinuxArm64SeaError({ message: `${args[0]} exited with code ${exitCode}.` });
29
+ }
30
+});
31
+
32
+// Builds the SEA blob with this Node and injects it into a copy of this Node with postject.
33
+export const injectLinuxArm64Sea = Effect.fn("LinuxArm64Sea.inject")(function* (input: {
34
+ bundlePath: string;
35
+ outputPath: string;
36
+ nodeVersion: string;
37
+ verbose: boolean;
38
+}) {
39
+ // The copied execPath is the shipped runtime; vp pack only checks its own Node.
40
+ if (process.versions.node !== input.nodeVersion) {
41
+ return yield* new LinuxArm64SeaError({
42
+ message: `Linux ARM64 executables must be built with Node ${input.nodeVersion}; running ${process.versions.node}.`,
43
+ });
44
+ }
45
+ const fs = yield* FileSystem.FileSystem;
46
+ const path = yield* Path.Path;
47
+ const temp = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sea-" });
48
+ const blobPath = path.join(temp, "sea.blob");
49
+ const configPath = path.join(temp, "sea.json");
50
+ yield* fs.writeFileString(
51
+ configPath,
52
+ yield* encodeJson({
53
+ main: input.bundlePath,
54
+ output: blobPath,
55
+ mainFormat: "module",
56
+ disableExperimentalSEAWarning: true,
57
+ // Node SEA useCodeCache breaks import(), which the server needs.
58
+ useCodeCache: false,
59
+ }),
60
+ );
61
+ yield* run(["--experimental-sea-config", configPath], input.verbose);
62
+ yield* fs.copyFile(process.execPath, input.outputPath);
63
+ yield* fs.chmod(input.outputPath, 0o755);
64
+ const require = NodeModule.createRequire(import.meta.url);
65
+ yield* run(
66
+ [
67
+ require.resolve("postject/dist/cli.js"),
68
+ input.outputPath,
69
+ "NODE_SEA_BLOB",
70
+ blobPath,
71
+ "--sentinel-fuse",
72
+ "NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2",
73
+ ],
74
+ input.verbose,
75
+ );
76
+}, Effect.scoped);
77
+
78
+// Kernels map LOAD segments in whole pages. Checking at 64 KiB covers 4, 16, and 64 KiB kernels.
79
+export function assertLinuxArm64PageCompatibility(bytes: Uint8Array) {
80
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
81
+ if (
82
+ bytes.length < 64 ||
83
+ view.getUint32(0, false) !== 0x7f454c46 ||
84
+ bytes[4] !== 2 ||
85
+ bytes[5] !== 1 ||
86
+ view.getUint16(18, true) !== 183
87
+ ) {
88
+ throw new Error("Expected a little-endian ELF64 ARM64 executable.");
89
+ }
90
+ const tableOffset = Number(view.getBigUint64(32, true));
91
+ const entrySize = view.getUint16(54, true);
92
+ const count = view.getUint16(56, true);
93
+ if (
94
+ !Number.isSafeInteger(tableOffset) ||
95
+ entrySize < 56 ||
96
+ count === 0 ||
97
+ tableOffset + entrySize * count > bytes.length
98
+ ) {
99
+ throw new Error("Invalid ELF program header table.");
100
+ }
101
+ const pageSize = 0x10000n;
102
+ const ranges: Array<{ start: bigint; end: bigint }> = [];
103
+ for (let index = 0; index < count; index++) {
104
+ const header = tableOffset + index * entrySize;
105
+ if (view.getUint32(header, true) !== 1) continue;
106
+ const offset = view.getBigUint64(header + 8, true);
107
+ const address = view.getBigUint64(header + 16, true);
108
+ const size = view.getBigUint64(header + 40, true);
109
+ if (offset % pageSize !== address % pageSize) {
110
+ throw new Error(`ARM64 LOAD segment ${index} is incompatible with 64 KiB pages.`);
111
+ }
112
+ if (size === 0n) continue;
113
+ const start = address / pageSize;
114
+ const end = (address + size + pageSize - 1n) / pageSize;
115
+ if (ranges.some((range) => start < range.end && range.start < end)) {
116
+ throw new Error(`ARM64 LOAD segments overlap on a 64 KiB page (segment ${index}).`);
117
+ }
118
+ ranges.push({ start, end });
119
+ }
120
+ if (ranges.length === 0) throw new Error("ELF executable has no LOAD segments.");
121
+}
scripts/package.json
+1
@@ -23,6 +23,7 @@
23
"@types/plist": "catalog:",
24
"@types/pngjs": "6.0.5",
25
"esbuild": "0.28.2",
26
+ "postject": "1.0.0-alpha.6",
27
"typescript": "catalog:",
28
"typescript-legacy": "npm:typescript@~6.0.3",
29
"vite-plus": "catalog:"