@devries-cameron20 / t3code Mirror · read-only / commits / c175e5737e
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 14:30 UTC

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