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

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

fix(server): Update server works again on services installed before the launcher protocol bump (#34603)

Co-authored-by: Julius Marminge <julius0216@outlook.com>

Theo Browne committed Nov 11, 2026 at 15:10 UTC e805ce371253688a01ca6013bd83d61cd9332c5c
11 files changed +120 -66
apps/server/src/cloud/selfUpdate.test.ts
+19 -7
@@ -26,6 +26,7 @@ import * as ServerSelfUpdate from "./selfUpdate.ts";
26 interface HarnessOptions {
27 readonly mode?: "web" | "desktop";
28 readonly managed?: boolean;
29 + readonly launcherProtocol?: 3 | typeof SERVICE_LAUNCHER_PROTOCOL;
30 readonly preflight?: "ready" | "blocked";
31 readonly preflightDuration?: Duration.Input;
32 readonly preflightStarted?: Deferred.Deferred<void>;
@@ -65,6 +66,7 @@ const makeHarness = Effect.fn("test.make_self_update_harness")(function* (
66 const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-self-update-test-" });
67 const order: string[] = [];
68 const urls: string[] = [];
69 + const preflightProtocols: Array<string | undefined> = [];
70 const runner = ProcessRunner.ProcessRunner.of({
71 run: (input) =>
72 Effect.gen(function* () {
@@ -113,14 +115,13 @@ const makeHarness = Effect.fn("test.make_self_update_harness")(function* (
115 }
116 }
117 order.push("preflight");
118 + // Like a release, report back the launcher protocol the server named.
119 + const named = input.args[input.args.indexOf("--launcher-protocol") + 1];
120 + preflightProtocols.push(named);
121 const result =
122 options.preflight === "blocked"
123 ? { status: "blocked", version: "1.1.0", reason: "local update required" }
119 - : {
120 - status: "ready",
121 - version: "1.1.0",
122 - launcherProtocol: SERVICE_LAUNCHER_PROTOCOL,
123 - };
124 + : { status: "ready", version: "1.1.0", launcherProtocol: Number(named) };
125 return {
126 stdout: JSON.stringify(result),
127 stderr: "",
@@ -133,8 +134,10 @@ const makeHarness = Effect.fn("test.make_self_update_harness")(function* (
134 };
135 }),
136 });
137 + const managed = options.managed ?? true;
138 const launcher = ServiceLauncherClient.ServiceLauncherClient.of({
137 - managed: options.managed ?? true,
139 + managed,
140 + protocol: managed ? (options.launcherProtocol ?? SERVICE_LAUNCHER_PROTOCOL) : undefined,
141 requestUpdate:
142 options.requestUpdate ??
143 (() =>
@@ -170,7 +173,7 @@ const makeHarness = Effect.fn("test.make_self_update_harness")(function* (
173 ),
174 ),
175 );
173 - return { selfUpdate, order, urls, baseDir };
176 + return { selfUpdate, order, urls, baseDir, preflightProtocols };
177 });
178
179 it.layer(NodeServices.layer)("server self update", (it) => {
@@ -209,6 +212,15 @@ it.layer(NodeServices.layer)("server self update", (it) => {
212 }),
213 );
214
215 + // regression: #34502 a remote update never replaces the launcher, so it can be older than the server
216 + it.effect("names its launcher's protocol to the staged preflight, not its own", () =>
217 + Effect.gen(function* () {
218 + const { selfUpdate, preflightProtocols } = yield* makeHarness({ launcherProtocol: 3 });
219 + expect((yield* selfUpdate.update({ targetVersion: "1.1.0" })).updateId).toBe("launcher-id");
220 + expect(preflightProtocols).toEqual(["3"]);
221 + }),
222 + );
223 +
224 // regression: #5181 make remote updates rollback-safe
225 it.effect("rejects invalid versions and desktop-managed servers before staging", () =>
226 Effect.gen(function* () {
apps/server/src/cloud/selfUpdate.ts
+6 -4
@@ -45,7 +45,7 @@ import {
45 import { bootServiceProgramOf, bootServiceUnitPath } from "./bootService.ts";
46 import { decodeServicePreflightResult } from "./servicePreflight.ts";
47 import * as ServiceLauncherClient from "./serviceLauncherClient.ts";
48 -import { isExactServiceVersion, SERVICE_LAUNCHER_PROTOCOL } from "./serviceProtocol.ts";
48 +import { isExactServiceVersion } from "./serviceProtocol.ts";
49
50 // A staged runtime's cold start can take over a minute on a loaded, swapping host.
51 const PREFLIGHT_TIMEOUT = Duration.minutes(3);
@@ -199,7 +199,9 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* () {
199 "This server is managed by the T3 Code desktop app on its machine; update the desktop app to update it.",
200 );
201 }
202 - if (capability === null) {
202 + // The target must accept the launcher that will run it, which can be older than this server.
203 + const launcherProtocol = launcher.protocol;
204 + if (capability === null || launcherProtocol === undefined) {
205 return yield* failWith(
206 "Remote updates require the T3 Code background service. Run `t3 service install` on the server machine.",
207 );
@@ -238,7 +240,7 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* () {
240 "--database-path",
241 serverConfig.dbPath,
242 "--launcher-protocol",
241 - String(SERVICE_LAUNCHER_PROTOCOL),
243 + String(launcherProtocol),
244 ],
245 timeout: PREFLIGHT_TIMEOUT,
246 })
@@ -278,7 +280,7 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* () {
280 }),
281 );
282 }
281 - const preflight = decodeServicePreflightResult(parsed);
283 + const preflight = decodeServicePreflightResult(parsed, launcherProtocol);
284 if (preflight === undefined || preflight.version !== targetVersion) {
285 return Effect.fail(
286 new PinnedRuntimeInstallError({
apps/server/src/cloud/serviceLauncherClient.test.ts
+26 -27
@@ -49,34 +49,33 @@ const makeClient = (host: FakeLauncherProcess, currentVersion: string) =>
49 Effect.provideService(HostProcess.Environment, host.env),
50 );
51
52 -it.effect("waits for the launcher to durably commit the trial update ID", () =>
53 - Effect.gen(function* () {
54 - const pending = {
55 - id: "update-1",
56 - fromVersion: "1.0.0",
57 - targetVersion: "1.1.0",
58 - dbPath: "/tmp/state.sqlite",
59 - status: "pending" as const,
60 - };
61 - const host = new FakeLauncherProcess({
62 - protocol: SERVICE_LAUNCHER_PROTOCOL,
63 - childVersion: "1.1.0",
64 - update: pending,
65 - });
66 - const client = yield* makeClient(host, "1.1.0");
67 - const prepared = yield* Effect.forkChild(client.prepareTrial, { startImmediately: true });
68 - yield* Effect.yieldNow;
69 - expect(host.sent).toEqual([{ type: "prepared", updateId: "update-1" }]);
52 +// regression: #34502 a remote update never replaces the launcher, so an installed one stays protocol 3
53 +it.effect.each([3, SERVICE_LAUNCHER_PROTOCOL])(
54 + "waits for a protocol-%i launcher to durably commit the trial update ID",
55 + (protocol) =>
56 + Effect.gen(function* () {
57 + const pending = {
58 + id: "update-1",
59 + fromVersion: "1.0.0",
60 + targetVersion: "1.1.0",
61 + dbPath: "/tmp/state.sqlite",
62 + status: "pending" as const,
63 + };
64 + const host = new FakeLauncherProcess({ protocol, childVersion: "1.1.0", update: pending });
65 + const client = yield* makeClient(host, "1.1.0");
66 + const prepared = yield* Effect.forkChild(client.prepareTrial, { startImmediately: true });
67 + yield* Effect.yieldNow;
68 + expect(host.sent).toEqual([{ type: "prepared", updateId: "update-1" }]);
69
71 - const committed = {
72 - id: pending.id,
73 - fromVersion: pending.fromVersion,
74 - targetVersion: pending.targetVersion,
75 - status: "committed" as const,
76 - };
77 - host.emit({ type: "committed", updateId: committed.id });
78 - expect(yield* Fiber.join(prepared)).toEqual(committed);
79 - }),
70 + const committed = {
71 + id: pending.id,
72 + fromVersion: pending.fromVersion,
73 + targetVersion: pending.targetVersion,
74 + status: "committed" as const,
75 + };
76 + host.emit({ type: "committed", updateId: committed.id });
77 + expect(yield* Fiber.join(prepared)).toEqual(committed);
78 + }),
79 );
80
81 it.effect("returns the launcher-generated ID only after update acceptance", () =>
apps/server/src/cloud/serviceLauncherClient.ts
+5
@@ -12,6 +12,7 @@ import {
12 SERVICE_LAUNCHER_CONTEXT_ENV,
13 type ServiceLauncherChildMessage,
14 type ServiceLauncherParentMessage,
15 + type SupportedLauncherProtocol,
16 } from "./serviceProtocol.ts";
17
18 export class ServiceLauncherClientError extends Schema.TaggedError<ServiceLauncherClientError>()(
@@ -97,6 +98,9 @@ export class ServiceLauncherClient extends Context.Service<
98 ServiceLauncherClient,
99 {
100 readonly managed: boolean;
101 + /** The supervising launcher's protocol. A remote update never replaces the launcher,
102 + so it can be older than this runtime's own. */
103 + readonly protocol: SupportedLauncherProtocol | undefined;
104 readonly requestUpdate: (input: {
105 readonly targetVersion: string;
106 readonly dbPath: string;
@@ -240,6 +244,7 @@ export const make = Effect.fn("cloud.service_launcher_client.make")(function* (o
244
245 return ServiceLauncherClient.of({
246 managed,
247 + protocol: context?.protocol,
248 requestUpdate,
249 prepareTrial,
250 });
apps/server/src/cloud/servicePreflight.test.ts
+15
@@ -33,6 +33,21 @@ it.each([1])("blocks legacy launcher protocol %i with exact recovery steps", (la
33 expect(reason).toContain("which -a t3");
34 });
35
36 +// regression: #34502 every installed launcher was protocol 3, so protocol 4 blocked every remote update
37 +it.each([3, SERVICE_LAUNCHER_PROTOCOL])(
38 + "is ready under launcher protocol %i and reports it back",
39 + (launcherProtocol) => {
40 + // A released server accepts a ready result only when it names that server's own protocol.
41 + expect(
42 + runServicePreflight({
43 + databasePath: "/missing/state.sqlite",
44 + launcherProtocol,
45 + version: "9.8.7",
46 + }),
47 + ).toEqual({ status: "ready", version: "9.8.7", launcherProtocol });
48 + },
49 +);
50 +
51 it.layer(NodeServices.layer)("service preflight database", (it) => {
52 it.effect("blocks a database that a newer build migrated", () =>
53 Effect.gen(function* () {
apps/server/src/cloud/servicePreflight.ts
+17 -12
@@ -1,12 +1,17 @@
1 import packageJson from "../../package.json" with { type: "json" };
2 import { BUILD_MIGRATION_HEAD, recordedMigrations } from "../persistence/databaseMigrationHead.ts";
3 -import { SERVICE_LAUNCHER_PROTOCOL } from "./serviceProtocol.ts";
3 +import {
4 + isSupportedLauncherProtocol,
5 + SERVICE_LAUNCHER_PROTOCOL,
6 + type SupportedLauncherProtocol,
7 +} from "./serviceProtocol.ts";
8
9 export type ServicePreflightResult =
10 | {
11 readonly status: "ready";
12 readonly version: string;
9 - readonly launcherProtocol: typeof SERVICE_LAUNCHER_PROTOCOL;
13 + /** The launcher protocol the server named; it accepts no other in reply. */
14 + readonly launcherProtocol: SupportedLauncherProtocol;
15 }
16 | {
17 readonly status: "blocked";
@@ -20,14 +25,15 @@ export function runServicePreflight(input: {
25 readonly version?: string;
26 }): ServicePreflightResult {
27 const version = input.version ?? packageJson.version;
23 - if (input.launcherProtocol !== SERVICE_LAUNCHER_PROTOCOL) {
28 + const { launcherProtocol } = input;
29 + if (!isSupportedLauncherProtocol(launcherProtocol)) {
30 return {
31 status: "blocked",
32 version,
33 // A stale `t3` earlier on PATH (an old npm/nvm global) makes `t3 service install`
34 // reinstall itself and report success, so name the exact install and the path check.
35 reason: [
30 - `The installed service launcher speaks protocol ${input.launcherProtocol}, but t3@${version} requires protocol ${SERVICE_LAUNCHER_PROTOCOL}.`,
36 + `The installed service launcher speaks protocol ${launcherProtocol}, but t3@${version} requires protocol ${SERVICE_LAUNCHER_PROTOCOL}.`,
37 `On the server machine, install this exact CLI: \`curl -fsSL https://t3.codes/install.sh | T3CODE_VERSION=${version} sh\`.`,
38 `Check that \`t3 --version\` prints ${version} and that \`which -a t3\` lists no older t3 (such as an npm or nvm install) first, then run \`~/.local/bin/t3 service install\` (the installer's default path).`,
39 "Updating the desktop app does not update this CLI, and `t3 service update` only repairs the service with whichever CLI runs it.",
@@ -51,7 +57,7 @@ export function runServicePreflight(input: {
57 };
58 }
59
54 - return { status: "ready", version, launcherProtocol: SERVICE_LAUNCHER_PROTOCOL };
60 + return { status: "ready", version, launcherProtocol };
61 }
62
63 /** Migrations a newer build recorded, or null when the database exists but cannot be read.
@@ -63,21 +69,20 @@ function newerRecordedMigrations(databasePath: string): ReadonlyArray<string> |
69 : recorded.filter(({ id }) => id > BUILD_MIGRATION_HEAD).map(({ id, name }) => `${id}_${name}`);
70 }
71
66 -export function decodeServicePreflightResult(value: unknown): ServicePreflightResult | undefined {
72 +export function decodeServicePreflightResult(
73 + value: unknown,
74 + launcherProtocol: SupportedLauncherProtocol,
75 +): ServicePreflightResult | undefined {
76 if (typeof value !== "object" || value === null) {
77 return undefined;
78 }
79 const record = value as Record<string, unknown>;
80 if (
81 record.status === "ready" &&
73 - record.launcherProtocol === SERVICE_LAUNCHER_PROTOCOL &&
82 + record.launcherProtocol === launcherProtocol &&
83 typeof record.version === "string"
84 ) {
76 - return {
77 - status: "ready",
78 - version: record.version,
79 - launcherProtocol: SERVICE_LAUNCHER_PROTOCOL,
80 - };
85 + return { status: "ready", version: record.version, launcherProtocol };
86 }
87 if (
88 record.status === "blocked" &&
apps/server/src/cloud/serviceProtocol.ts
+15 -8
@@ -1,9 +1,16 @@
1 import type { ServerSelfUpdateOutcome } from "@t3tools/contracts";
2
3 -// Protocol 4 requires coordinated selection writes and unit reconciliation. An
4 -// installed protocol-3 launcher needs one local update or service install with a restart:
5 -// remote updates replace its child, so cannot add these launcher guarantees.
3 +// Protocol 4 launchers coordinate selection writes and reconcile the unit. A remote update
4 +// replaces only the child, so an installed protocol-3 launcher stays until a local update or
5 +// service install restarts the service.
6 export const SERVICE_LAUNCHER_PROTOCOL = 4 as const;
7 +/** Launchers this runtime runs under. Protocol 3 has the same IPC and durable format, and
8 + refusing it stops every remote update until someone opens a shell on the host. */
9 +export type SupportedLauncherProtocol = 3 | typeof SERVICE_LAUNCHER_PROTOCOL;
10 +export const isSupportedLauncherProtocol = (
11 + protocol: unknown,
12 +): protocol is SupportedLauncherProtocol =>
13 + protocol === 3 || protocol === SERVICE_LAUNCHER_PROTOCOL;
14 export const SERVICE_LAUNCHER_CONTEXT_ENV = "T3_SERVICE_LAUNCHER_CONTEXT";
15 export const SERVICE_ENV_FILE = "service.env";
16 export const SERVICE_STATE_FILE = "service-state.json";
@@ -58,7 +65,7 @@ export interface ServiceState {
65 }
66
67 export interface ServiceLauncherContext {
61 - readonly protocol: typeof SERVICE_LAUNCHER_PROTOCOL;
68 + readonly protocol: SupportedLauncherProtocol;
69 readonly childVersion: string;
70 readonly update?: ServiceUpdateRecord;
71 }
@@ -174,8 +181,8 @@ export function decodeServiceState(value: unknown): ServiceState | undefined {
181 if (!isRecord(value)) return undefined;
182 const update = value.update === undefined ? undefined : decodeServiceUpdate(value.update);
183 if (
177 - // Protocol 3 has the same durable format; its installer can select a protocol-4 runtime.
178 - (value.protocol !== 3 && value.protocol !== SERVICE_LAUNCHER_PROTOCOL) ||
184 + // A protocol-3 installer can select a protocol-4 runtime.
185 + !isSupportedLauncherProtocol(value.protocol) ||
186 typeof value.activeVersion !== "string" ||
187 !isExactServiceVersion(value.activeVersion) ||
188 (value.update !== undefined && update === undefined) ||
@@ -252,7 +259,7 @@ export function decodeServiceLauncherContext(value: string): ServiceLauncherCont
259 }
260 if (
261 !isRecord(parsed) ||
255 - parsed.protocol !== SERVICE_LAUNCHER_PROTOCOL ||
262 + !isSupportedLauncherProtocol(parsed.protocol) ||
263 typeof parsed.childVersion !== "string" ||
264 !isExactServiceVersion(parsed.childVersion)
265 ) {
@@ -270,7 +277,7 @@ export function decodeServiceLauncherContext(value: string): ServiceLauncherCont
277 return undefined;
278 }
279 return {
273 - protocol: SERVICE_LAUNCHER_PROTOCOL,
280 + protocol: parsed.protocol,
281 childVersion: parsed.childVersion,
282 ...(update === undefined ? {} : { update }),
283 };
apps/server/src/serverRuntimeStartup.autoPull.test.ts
+2
@@ -13,6 +13,7 @@ import * as NetAddress from "effect/net/NetAddress";
13
14 import * as EnvironmentAuth from "./auth/EnvironmentAuth.ts";
15 import * as ServiceLauncherClient from "./cloud/serviceLauncherClient.ts";
16 +import { SERVICE_LAUNCHER_PROTOCOL } from "./cloud/serviceProtocol.ts";
17 import * as ServerConfig from "./config.ts";
18 import * as ServerEnvironment from "./environment/ServerEnvironment.ts";
19 import * as Keybindings from "./keybindings.ts";
@@ -146,6 +147,7 @@ it.effect("parks automatic pull until activation without delaying command readin
147 Layer.mock(ThreadLaunch.ThreadLaunchService)({}),
148 Layer.mock(ServiceLauncherClient.ServiceLauncherClient)({
149 managed: true,
150 + protocol: SERVICE_LAUNCHER_PROTOCOL,
151 prepareTrial: Deferred.succeed(prepared, undefined).pipe(
152 Effect.andThen(Deferred.await(commitTrial)),
153 Effect.as(undefined),
apps/server/src/serverRuntimeStartup.test.ts
+1
@@ -201,6 +201,7 @@ it.effect.each([
201 }),
202 Layer.mock(ServiceLauncherClient.ServiceLauncherClient)({
203 managed: false,
204 + protocol: undefined,
205 prepareTrial: Effect.undefined,
206 }),
207 Layer.mock(GitVcsDriver.GitVcsDriver)({}),
docs/internals/server-updates.md
+11 -4
@@ -13,21 +13,28 @@ takes the state lease before the unit lease; the launcher never holds both, so a
13 unit failure cannot block a durable commit. Manager stop/start commands run outside
14 both leases, since stopping a launcher that waits on a lease would deadlock. A
15 running launcher refuses further updates once a local command changes its selection.
16 +A protocol-3 launcher takes no lease, so a local command can still race its updates.
17
18 Exact-version installs keep restarts independent of npm cache eviction or a moving
19 release tag. Installation and preflight happen in staging before publishing an
20 immutable runtime. Preflight checks the launcher protocol because a target that
21 needs new rollback guarantees cannot safely run under an older launcher. A remote
22 update replaces only the child, so upgrading the launcher requires a local service
22 -update with a restart.
23 +update with a restart. Every installed launcher is therefore one protocol behind
24 +after a bump, and a target that refuses the previous protocol stops remote updates
25 +for every existing service. Refuse it only when the child cannot work under it.
26 +Protocol 4 changed the launcher alone, so its runtime still runs under protocol 3.
27 +The server names its launcher's protocol to preflight, not its own, since the two differ
28 +after the first such update.
29
30 After a commit or rollback the launcher points the unit at the selected runtime and
31 reloads the manager, so the next service start runs that version's launcher; the
32 protocol check is what makes that safe. Each start after a finished update retries this, because
33 a previous reload may have failed, and leaves a unit naming a newer runtime or another
28 -T3 home alone. Until a deferred local upgrade restarts, systemd (before daemon-reload)
29 -and launchd (before bootstrap) can respawn the old launcher, which the new runtime
30 -refuses to run under.
34 +T3 home alone. A protocol-3 launcher does none of this: its unit keeps naming the
35 +runtime that installed it. Until a deferred local upgrade restarts, systemd (before
36 +daemon-reload) and launchd (before bootstrap) can respawn the old launcher, which
37 +rejects the state the new installer wrote.
38
39 ## Commit boundary
40
docs/user/updating.md
+3 -4
@@ -118,10 +118,9 @@ asks before restarting the background service; if you decline, run
118 stop it and start it again afterwards with your usual options such as `--host`
119 or `--tailscale-serve`.
120
121 -A background service installed by an older release refuses **Update server**
122 -until you update it once on the host and let that update restart it. If you
123 -decline the restart, the service can stay down after a crash or reboot until you
124 -run `t3 service restart`.
121 +If you decline the restart for a background service installed by an older
122 +release, the service can stay down after a crash or reboot until you run
123 +`t3 service restart`.
124
125 If you run the server with `npx` rather than an installed `t3`, there is
126 nothing to update on the host: stop the server and relaunch it as