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 21, 18:30 UTC
fix(web): hand-started t3 servers get an update command that updates them (#29462)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Hieu Le committed
Nov 12, 2026 at 22:17 UTC
7eca0ed8859a0616cf7cbbca8c43f7d2be009196
13 files changed
+153
-40
apps/server/src/cli/invocation.test.ts
+37
@@ -291,6 +291,43 @@ it.layer(NodeServices.layer)("manual server installation ownership", (it) => {
291
}),
292
);
293
294
+ it.effect("names the launcher symlink that started a downloaded runtime", () =>
295
+ Effect.gen(function* () {
296
+ const fs = yield* FileSystem.FileSystem;
297
+ const path = yield* Path.Path;
298
+ const root = yield* fs.realPath(yield* fs.makeTempDirectoryScoped());
299
+ // The install script's launcher names ~/.t3, which here links to a home elsewhere.
300
+ const executable = path.join(root, "data/t3/runtime/versions/1.0.0/t3");
301
+ const launcher = path.join(root, "bin/t3");
302
+ const copy = path.join(root, "bin/t3-copy");
303
+ yield* fs.makeDirectory(path.dirname(executable), { recursive: true });
304
+ yield* fs.makeDirectory(path.dirname(launcher), { recursive: true });
305
+ yield* fs.writeFileString(executable, "", { mode: 0o755 });
306
+ yield* fs.writeFileString(copy, "", { mode: 0o755 });
307
+ yield* fs.symlink(path.join(root, "data/t3"), path.join(root, ".t3"));
308
+ yield* fs.symlink(path.join(root, ".t3/runtime/versions/1.0.0/t3"), launcher);
309
+ // Earlier PATH entries hold a directory and a non-executable file named t3.
310
+ yield* fs.makeDirectory(path.join(root, "shadow-dir/t3"), { recursive: true });
311
+ yield* fs.makeDirectory(path.join(root, "shadow-file"));
312
+ yield* fs.writeFileString(path.join(root, "shadow-file/t3"), "");
313
+ const resolve = (invokedAs: string) =>
314
+ resolveServerInstallation.pipe(
315
+ Effect.provideService(HostProcess.ExecutablePath, executable),
316
+ Effect.provideService(HostProcess.IsExecutable, true),
317
+ Effect.provideService(HostProcess.InvokedAs, invokedAs),
318
+ Effect.provideService(HostProcess.WorkingDirectory, root),
319
+ Effect.provideService(HostProcess.Environment, { PATH: "shadow-dir:shadow-file:bin" }),
320
+ Effect.provideService(HostProcess.Platform, "linux"),
321
+ );
322
+ const baseDir = path.join(root, ".t3");
323
+
324
+ expect(yield* resolve("t3")).toEqual({ kind: "t3-launcher", launcher, baseDir });
325
+ expect(yield* resolve(launcher)).toEqual({ kind: "t3-launcher", launcher, baseDir });
326
+ expect(yield* resolve(executable)).toBeNull();
327
+ expect(yield* resolve(copy)).toBeNull();
328
+ }),
329
+ );
330
+
331
it.effect("leaves local, standalone, missing and unreadable installs unknown", () =>
332
Effect.gen(function* () {
333
const fs = yield* FileSystem.FileSystem;
apps/server/src/cli/invocation.ts
+18
@@ -9,6 +9,9 @@ import * as HostProcess from "@t3tools/shared/HostProcess";
9
import { resolveCommandPath } from "@t3tools/shared/shell";
10
11
import packageJson from "../../package.json" with { type: "json" };
12
+import { resolveLauncherPath } from "../cloud/pinnedRuntime.ts";
13
+
14
+const PINNED_RUNTIME_ENTRY = /^(.*)\/runtime\/versions\/[^/]+\/t3$/;
15
16
export type CliRunner = "npx" | "pnpm dlx" | "bunx";
17
@@ -67,6 +70,21 @@ export const resolveServerInstallation = Effect.gen(function* () {
70
const path = yield* Path.Path;
71
const platform = yield* HostProcess.Platform;
72
const entry = yield* fs.realPath(yield* resolveEntryPath);
73
+ const runtime = PINNED_RUNTIME_ENTRY.exec(entry);
74
+ if (runtime) {
75
+ const launcher = yield* resolveLauncherPath;
76
+ if (launcher === undefined) return null;
77
+ // Fails for a runtime started directly, as SSH launches do, or through a copy.
78
+ const link = yield* fs.readLink(launcher);
79
+ // Keep the home as the link spells it; `t3 update` only repoints links into that spelling.
80
+ const linked = PINNED_RUNTIME_ENTRY.exec(path.resolve(path.dirname(launcher), link));
81
+ if (!linked || (yield* fs.realPath(linked[1] || "/")) !== (runtime[1] || "/")) return null;
82
+ return {
83
+ kind: "t3-launcher",
84
+ launcher,
85
+ baseDir: linked[1] || "/",
86
+ } satisfies ServerInstallation;
87
+ }
88
const match = /^(.*)\/lib\/node_modules\/t3\/(?:dist\/bin\.mjs|bin\/t3\.mjs)$/.exec(entry);
89
if (!match) {
90
const runner = detectCliRunner(entry);
apps/server/src/cli/uninstall.ts
+2
-1
@@ -16,10 +16,11 @@ import {
16
generatedWindowsShimTarget,
17
isVersionExecutable,
18
pinnedRuntimeVersionsDir,
19
+ resolveLauncherPath,
20
} from "../cloud/pinnedRuntime.ts";
21
import { projectLocationFlags, resolveCliAuthConfig } from "./config.ts";
22
import * as CliService from "./service.ts";
22
-import { findWindowsShim, resolveLauncherPath } from "./update.ts";
23
+import { findWindowsShim } from "./update.ts";
24
25
export class CliUninstallError extends Schema.TaggedError<CliUninstallError>()(
26
"CliUninstallError",
apps/server/src/cli/update.test.ts
+6
-3
@@ -17,12 +17,15 @@ import { afterEach, vi } from "vite-plus/test";
17
18
import packageJson from "../../package.json" with { type: "json" };
19
import * as BootService from "../cloud/bootService.ts";
20
-import { pinnedRuntimePaths, prunePinnedRuntimes } from "../cloud/pinnedRuntime.ts";
20
+import {
21
+ pinnedRuntimePaths,
22
+ prunePinnedRuntimes,
23
+ resolveLauncherPath,
24
+} from "../cloud/pinnedRuntime.ts";
25
import * as ManagedPolicy from "../policy/ManagedPolicy.ts";
26
import * as ProcessRunner from "../processRunner.ts";
27
import {
28
repointLauncher,
25
- resolveLauncherPath,
29
resolveMirrorVersion,
30
resolveNewestVersion,
31
runUpdate,
@@ -411,7 +414,7 @@ it.layer(NodeServices.layer)("t3 update launcher", (it) => {
414
const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-update-" });
415
const launcher = path.join(root, "bin/t3");
416
yield* fs.makeDirectory(path.dirname(launcher), { recursive: true });
414
- yield* fs.writeFileString(launcher, "");
417
+ yield* fs.writeFileString(launcher, "", { mode: 0o755 });
418
419
const bare = yield* resolveLauncherPath.pipe(
420
Effect.provideService(HostProcess.InvokedAs, "t3"),
apps/server/src/cli/update.ts
+1
-22
@@ -32,6 +32,7 @@ import {
32
pinnedRuntimeVersionsDir,
33
prunePinnedRuntimes,
34
recordPinnedRuntimeLauncher,
35
+ resolveLauncherPath,
36
windowsShimTarget,
37
} from "../cloud/pinnedRuntime.ts";
38
import { compareExactServiceVersions, isExactServiceVersion } from "../cloud/serviceProtocol.ts";
@@ -194,28 +195,6 @@ export const repointLauncher = Effect.fn("cli.update.repoint_launcher")(function
195
return Option.some(input.launchedAs);
196
});
197
197
-/** Node preserves argv0's spelling; resolve bare names on PATH to find the launcher symlink. */
198
-export const resolveLauncherPath = Effect.gen(function* () {
199
- const path = yield* Path.Path;
200
- const fs = yield* FileSystem.FileSystem;
201
- const invokedAs = yield* HostProcess.InvokedAs;
202
- const cwd = yield* HostProcess.WorkingDirectory;
203
- const environment = yield* HostProcess.Environment;
204
- const platform = yield* HostProcess.Platform;
205
- if (invokedAs.includes("/") || invokedAs.includes("\\")) {
206
- return path.resolve(cwd, invokedAs);
207
- }
208
- const delimiter = platform === "win32" ? ";" : ":";
209
- for (const directory of (environment["PATH"] ?? "").split(delimiter)) {
210
- if (directory.length === 0) continue;
211
- const candidate = path.join(directory, invokedAs);
212
- if (yield* fs.exists(candidate).pipe(Effect.orElseSucceed(() => false))) {
213
- return candidate;
214
- }
215
- }
216
- return undefined;
217
-});
218
-
198
/** Windows executables see their own path, so find the installer shim by matching t3.cmd targets on PATH. */
199
export const findWindowsShim = Effect.fn("cli.update.find_windows_shim")(function* (
200
executablePath: string,
apps/server/src/cloud/pinnedRuntime.ts
+28
@@ -447,6 +447,34 @@ export function launcherOwnsVersionsDir(
447
return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
448
}
449
450
+/** Node preserves argv0's spelling; resolve bare names on PATH to find the launcher symlink. */
451
+export const resolveLauncherPath = Effect.gen(function* () {
452
+ const path = yield* Path.Path;
453
+ const fs = yield* FileSystem.FileSystem;
454
+ const invokedAs = yield* HostProcess.InvokedAs;
455
+ const cwd = yield* HostProcess.WorkingDirectory;
456
+ const environment = yield* HostProcess.Environment;
457
+ const platform = yield* HostProcess.Platform;
458
+ if (invokedAs.includes("/") || invokedAs.includes("\\")) {
459
+ return path.resolve(cwd, invokedAs);
460
+ }
461
+ const delimiter = platform === "win32" ? ";" : ":";
462
+ for (const directory of (environment["PATH"] ?? "").split(delimiter)) {
463
+ if (directory.length === 0) continue;
464
+ const candidate = path.resolve(cwd, directory, invokedAs);
465
+ const info = yield* fs.stat(candidate).pipe(Effect.option);
466
+ // Like the shell, pass over directories and non-executable files named the same.
467
+ if (
468
+ Option.isSome(info) &&
469
+ info.value.type === "File" &&
470
+ (platform === "win32" || (info.value.mode & 0o111) !== 0)
471
+ ) {
472
+ return candidate;
473
+ }
474
+ }
475
+ return undefined;
476
+});
477
+
478
/**
479
* `t3 update` repoints the launcher it was started through, which may be on neither PATH nor the
480
* default bin dir. Unrecorded, the next prune would remove the runtime it now points at.
apps/server/src/server.ts
+5
@@ -16,6 +16,7 @@ import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
16
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
17
import * as NodeServices from "@effect/platform-node/NodeServices";
18
import { EnvironmentHttpApi, type RepositoryIdentity } from "@t3tools/contracts";
19
+import * as HostProcess from "@t3tools/shared/HostProcess";
20
import * as Cause from "effect/Cause";
21
import * as Duration from "effect/Duration";
22
import * as Deferred from "effect/Deferred";
@@ -36,6 +37,7 @@ import {
37
keepIdleConnections,
38
rejectRequestsUntilServing,
39
} from "./httpResponseErrorGuard.ts";
40
+import { resolveLauncherPath } from "./cloud/pinnedRuntime.ts";
41
import { fixPath } from "./os-jank.ts";
42
import * as Ws from "./ws.ts";
43
import * as AgentScopeLive from "./process/agentScope.ts";
@@ -877,6 +879,8 @@ const layerMakeServer = Layer.unwrap(
879
const routesReady = yield* Deferred.make<void>();
880
const layerLauncher = ServiceLauncherClient.layer;
881
882
+ // fixPath rewrites PATH, so pin the launcher the shell chose before it does.
883
+ const invokedAs = (yield* resolveLauncherPath) ?? (yield* HostProcess.InvokedAs);
884
yield* fixPath({ shellEnvironmentPrepared: config.shellEnvironmentPrepared });
885
886
const layerHttpListening = Layer.effectDiscard(
@@ -1290,6 +1294,7 @@ const layerMakeServer = Layer.unwrap(
1294
Layer.provide(VcsProcess.layer),
1295
Layer.provideMerge(AgentScopeLive.layer),
1296
Layer.provideMerge(layerPlatformServices),
1297
+ Layer.provide(Layer.succeed(HostProcess.InvokedAs, invokedAs)),
1298
);
1299
}),
1300
).pipe(Layer.provide(ProcessRunner.layer));
apps/web/src/components/ServerUpdateAction.tsx
+8
-8
@@ -276,17 +276,17 @@ export function ServerUpdateAction({
276
const canUpdate = useAtomValue(sessionStateAtom, canUpdateServer);
277
const updatesDenial = managedUpdatesDenial(useManagedPolicy(environmentId));
278
const update = useServerUpdate();
279
+ const updatesInstall =
280
+ installation?.kind === "npm-global" || installation?.kind === "t3-launcher";
281
const { copyToClipboard } = useCopyToClipboard<{ command: string }>({
280
- target: installation?.kind === "npm-global" ? "update command" : "relaunch command",
282
+ target: updatesInstall ? "update command" : "relaunch command",
283
onCopy: ({ command }) => {
284
toastManager.add({
285
type: "success",
284
- title:
285
- installation?.kind === "npm-global" ? "Update command copied" : "Relaunch command copied",
286
- description:
287
- installation?.kind === "npm-global"
288
- ? `Run \`${command}\` on ${serverLabel}, then restart t3 with your usual options.`
289
- : `Stop t3 on ${serverLabel}, then relaunch with \`${command}\` using the same subcommand and options. This does not update an installed t3 command.`,
286
+ title: updatesInstall ? "Update command copied" : "Relaunch command copied",
287
+ description: updatesInstall
288
+ ? `Run \`${command}\` on ${serverLabel}, then restart t3 with your usual options.`
289
+ : `Stop t3 on ${serverLabel}, then relaunch with \`${command}\` using the same subcommand and options. This does not update an installed t3 command.`,
290
});
291
},
292
onError: (error) => {
@@ -353,7 +353,7 @@ export function ServerUpdateAction({
353
selfUpdate === null ? manualServerUpdateCommand(targetVersion, installation) : null;
354
const actionLabel =
355
manualCommand !== null
356
- ? installation?.kind === "npm-global"
356
+ ? updatesInstall
357
? "Copy update command"
358
: "Copy relaunch command"
359
: label;
apps/web/src/versionSkew.test.ts
+15
-1
@@ -20,13 +20,27 @@ const MISMATCH_HINT =
20
"Version mismatch. Try syncing the client and server to the same T3 Code version.";
21
22
describe("versionSkew", () => {
23
- it("updates only the proven npm prefix and safely quotes its path", () => {
23
+ it("updates only the proven install and safely quotes its paths", () => {
24
expect(manualServerUpdateCommand("0.0.45", { kind: "npm-global", prefix: "/opt/node" })).toBe(
25
"npm install --global --prefix '/opt/node' t3@0.0.45",
26
);
27
expect(
28
manualServerUpdateCommand("0.0.45", { kind: "npm-global", prefix: "/opt/maria's node" }),
29
).toBe("npm install --global --prefix '/opt/maria'\\''s node' t3@0.0.45");
30
+ expect(
31
+ manualServerUpdateCommand("0.0.45", {
32
+ kind: "t3-launcher",
33
+ launcher: "t3",
34
+ baseDir: "/home/u/.t3",
35
+ }),
36
+ ).toBe("'t3' update --base-dir '/home/u/.t3' 0.0.45");
37
+ expect(
38
+ manualServerUpdateCommand("0.0.45", {
39
+ kind: "t3-launcher",
40
+ launcher: "/opt/maria's bin/t3",
41
+ baseDir: "/data/t3 home",
42
+ }),
43
+ ).toBe("'/opt/maria'\\''s bin/t3' update --base-dir '/data/t3 home' 0.0.45");
44
});
45
beforeEach(() => {
46
branding.APP_VERSION = "0.0.34";
apps/web/src/versionSkew.ts
+6
-2
@@ -99,9 +99,13 @@ export function manualServerUpdateCommand(
99
targetVersion: string,
100
installation?: ServerInstallation,
101
): string {
102
+ const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
103
if (installation?.kind === "npm-global") {
103
- const prefix = `'${installation.prefix.replaceAll("'", "'\\''")}'`;
104
- return `npm install --global --prefix ${prefix} t3@${targetVersion}`;
104
+ return `npm install --global --prefix ${quote(installation.prefix)} t3@${targetVersion}`;
105
+ }
106
+ if (installation?.kind === "t3-launcher") {
107
+ // An inherited T3CODE_HOME would otherwise send the update to a home the launcher is not in.
108
+ return `${quote(installation.launcher)} update --base-dir ${quote(installation.baseDir)} ${targetVersion}`;
109
}
110
const runner =
111
installation?.kind === "pnpm-dlx" ? "pnpm dlx" : installation?.kind === "bunx" ? "bunx" : "npx";
docs/user/updating.md
+1
-1
@@ -103,7 +103,7 @@ The offered action depends on how the server runs:
103
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104
| **Update server** | Keep the client open while it installs and reconnects. Supported background services update remotely. For a desktop-hosted server, this also closes and relaunches the desktop app on the host. |
105
| **Update the desktop app** | Update the desktop app on the machine running the server, then reopen it if needed. |
106
-| **Copy update command** | Run the command on the named host to update the detected global npm install, then restart the server with your usual options. |
106
+| **Copy update command** | Run the command on the named host to update the detected global npm install or installed `t3` command, then restart the server with your usual options. |
107
| **Copy relaunch command** | Stop the command-line server on its host and relaunch with the copied command, keeping your usual subcommand and options. This does not update an installed `t3` command. |
108
109
On the host, run:
packages/contracts/src/environment.test.ts
+17
-2
@@ -16,7 +16,11 @@ const descriptor = {
16
describe("ExecutionEnvironmentDescriptor", () => {
17
it("decodes old, recognized and future manual installation descriptors", () => {
18
expect(decodeDescriptor(descriptor).capabilities.serverInstallation).toBeUndefined();
19
- for (const installation of [{ kind: "npx" }, { kind: "npm-global", prefix: "/opt/node" }]) {
19
+ for (const installation of [
20
+ { kind: "npx" },
21
+ { kind: "npm-global", prefix: "/opt/node" },
22
+ { kind: "t3-launcher", launcher: "/opt/bin/t3", baseDir: "/data/t3" },
23
+ ]) {
24
expect(
25
decodeDescriptor({
26
...descriptor,
@@ -24,7 +28,18 @@ describe("ExecutionEnvironmentDescriptor", () => {
28
}).capabilities.serverInstallation,
29
).toEqual(installation);
30
}
27
- for (const installation of [{ kind: "future-manager" }, { kind: "npm-global" }]) {
31
+ const spaced = { kind: "t3-launcher", launcher: "/opt/bin/t3 ", baseDir: " /data/t3 " };
32
+ expect(
33
+ decodeDescriptor({
34
+ ...descriptor,
35
+ capabilities: { ...descriptor.capabilities, serverInstallation: spaced },
36
+ }).capabilities.serverInstallation,
37
+ ).toEqual(spaced);
38
+ for (const installation of [
39
+ { kind: "future-manager" },
40
+ { kind: "npm-global" },
41
+ { kind: "t3-launcher", launcher: "t3" },
42
+ ]) {
43
expect(
44
decodeDescriptor({
45
...descriptor,
packages/contracts/src/environment.ts
+9
@@ -61,9 +61,18 @@ export type ExecutionEnvironmentPlatform = typeof ExecutionEnvironmentPlatform.T
61
export const ServerSelfUpdateMethod = Schema.Literals(["boot-service", "respawn", "desktop-app"]);
62
export type ServerSelfUpdateMethod = typeof ServerSelfUpdateMethod.Type;
63
64
+// Not trimmed: a path that differs from the installed one would update the wrong home.
65
+const InstalledPath = Schema.String.check(Schema.isNonEmpty());
66
+
67
export const ServerInstallation = Schema.Union([
68
Schema.Struct({ kind: Schema.Literals(["npx", "pnpm-dlx", "bunx"]) }),
69
Schema.Struct({ kind: Schema.Literal("npm-global"), prefix: TrimmedNonEmptyString }),
70
+ // A launcher symlink into a downloaded runtime, as the install script and `t3 update` leave.
71
+ Schema.Struct({
72
+ kind: Schema.Literal("t3-launcher"),
73
+ launcher: InstalledPath,
74
+ baseDir: InstalledPath,
75
+ }),
76
]);
77
export type ServerInstallation = typeof ServerInstallation.Type;
78