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, 22:15 UTC
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