The best way to control Claude Code, Codex and more from any computer or phone
fix(cli): keep managed T3 Connect tunnels across service updates and restarts (#39819)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Matias Mora Valero committed
Nov 20, 2026 at 19:57 UTC
13e940a4e30c18d40feddf7034e5087232e38590
2 files changed
+194
-33
apps/server/src/cloud/bootService.test.ts
+126
-4
@@ -1,3 +1,4 @@
1
+import { DESKTOP_UPDATE_RESTART_MARKER_FILE } from "@t3tools/contracts";
2
// @effect-diagnostics-next-line nodeBuiltinImport:off -- Cross-process launcher contention uses real filesystem leases and IPC barriers.
3
import * as NodeChildProcess from "node:child_process";
4
import * as NodeSqlite from "node:sqlite";
@@ -204,11 +205,14 @@ const makeHarness = Effect.fn("test.make_boot_service_harness")(function* (
205
yield* fs.writeFileString(runtime.entryPath, "#!/bin/sh\n");
206
yield* fs.writeFileString(runtime.sentinelPath, "1.2.3\n");
207
208
+ const markersAtStop: boolean[] = [];
209
+ const markersAtPreparation: boolean[] = [];
210
const commands: string[] = [];
211
const invocations: ProcessRunner.ProcessRunInput[] = [];
212
const timeouts = new Map<string, unknown>();
213
const control: {
214
failCommand: string | undefined;
215
+ interruptCommand?: string;
216
stateAfterStop?: string;
217
/** `undefined` makes `loginctl show-user` fail, as when logind does not know the user. */
218
linger: string | undefined;
@@ -240,6 +244,23 @@ const makeHarness = Effect.fn("test.make_boot_service_harness")(function* (
244
) {
245
const command = `${input.command} ${input.args.join(" ")}`;
246
commands.push(command);
247
+ const marker = path.join(baseDir, "runtime", DESKTOP_UPDATE_RESTART_MARKER_FILE);
248
+ if (
249
+ command === "systemctl --user stop t3code.service" ||
250
+ command === "systemctl --user disable --now t3code.service" ||
251
+ command === "systemctl --user restart --no-block t3code.service" ||
252
+ command.startsWith("launchctl bootout --wait ") ||
253
+ (input.command === "schtasks" && input.args[0] === "/End")
254
+ ) {
255
+ markersAtStop.push(yield* fs.exists(marker));
256
+ }
257
+ if (
258
+ command === "systemctl --user daemon-reload" ||
259
+ (input.command === "schtasks" && input.args[0] === "/Create")
260
+ ) {
261
+ markersAtPreparation.push(yield* fs.exists(marker));
262
+ }
263
+ if (command === control.interruptCommand) return yield* Effect.interrupt;
264
invocations.push(input);
265
timeouts.set(command, input.timeout);
266
if (command === "systemctl --user reset-failed t3code.service") control.startLimitHit = false;
@@ -403,12 +424,51 @@ const makeHarness = Effect.fn("test.make_boot_service_harness")(function* (
424
commands,
425
invocations,
426
timeouts,
427
+ markersAtStop,
428
+ markersAtPreparation,
429
control,
430
runtime,
431
};
432
});
433
434
it.layer(NodeServices.layer)("boot service install", (it) => {
435
+ it.effect(
436
+ "marks immediate and deferred service restarts without blocking on a marker error",
437
+ () =>
438
+ Effect.gen(function* () {
439
+ const { service, fs, baseDir, control, markersAtStop, makeService } = yield* makeHarness();
440
+ const path = yield* Path.Path;
441
+ const marker = path.join(baseDir, "runtime", DESKTOP_UPDATE_RESTART_MARKER_FILE);
442
+ yield* service.install();
443
+ expect(markersAtStop).toEqual([]);
444
+ expect(yield* fs.exists(marker)).toBe(false);
445
+
446
+ const newer = yield* makeService(undefined, "1.2.4");
447
+ yield* newer.install();
448
+ expect(markersAtStop).toEqual([true]);
449
+ expect(yield* fs.exists(marker)).toBe(false);
450
+
451
+ const next = yield* makeService(undefined, "1.2.5");
452
+ yield* next.install({ start: false });
453
+ expect(markersAtStop).toEqual([true]);
454
+ expect(yield* fs.exists(marker)).toBe(false);
455
+ yield* next.restart;
456
+ expect(markersAtStop).toEqual([true, true]);
457
+ expect(yield* fs.exists(marker)).toBe(false);
458
+
459
+ control.failCommand = "systemctl --user stop t3code.service";
460
+ const error = yield* next.restart.pipe(Effect.flip);
461
+ expect(error._tag).toBe("BootServiceCommandError");
462
+ expect(markersAtStop).toEqual([true, true, true]);
463
+ expect(yield* fs.exists(marker)).toBe(false);
464
+
465
+ control.failCommand = undefined;
466
+ yield* fs.makeDirectory(marker);
467
+ expect(yield* next.restart).toBe("restarted");
468
+ expect((yield* fs.stat(marker)).type).toBe("Directory");
469
+ }),
470
+ );
471
+
472
it.effect(
473
"fails before installing files or validating a runtime when lingering needs an administrator",
474
() =>
@@ -1158,12 +1218,13 @@ process.disconnect();
1218
1219
it.effect("pauses only this home's running service for maintenance, even when it fails", () =>
1220
Effect.gen(function* () {
1161
- const { service, commands, control, makeService } = yield* makeHarness();
1221
+ const { service, commands, control, makeService, markersAtStop } = yield* makeHarness();
1222
yield* service.install();
1223
const failure = yield* service
1224
.withStopped(Effect.failSync(() => (control.active ? "running" : "repair failed")))
1225
.pipe(Effect.flip);
1226
expect(failure).toBe("repair failed");
1227
+ expect(markersAtStop).toEqual([false]);
1228
expect(control.active).toBe(true);
1229
1230
control.failCommand = "systemctl --user stop t3code.service";
@@ -1299,9 +1360,19 @@ process.disconnect();
1360
"queues an in-service restart without stopping the caller, even on handoff failure",
1361
() =>
1362
Effect.gen(function* () {
1302
- const { service, fs, statePath, commands, control, makeService } = yield* makeHarness();
1363
+ const {
1364
+ service,
1365
+ fs,
1366
+ statePath,
1367
+ commands,
1368
+ control,
1369
+ makeService,
1370
+ markersAtStop,
1371
+ markersAtPreparation,
1372
+ } = yield* makeHarness();
1373
const plan = yield* service.install();
1374
const state = yield* fs.readFileString(statePath);
1375
+ const relayMarker = `${plan.baseDir}/runtime/${DESKTOP_UPDATE_RESTART_MARKER_FILE}`;
1376
const marker = `${plan.baseDir}/runtime/${SERVICE_RESTART_PENDING_FILE}`;
1377
yield* fs.writeFileString(marker, "1.2.3\n");
1378
const inside = yield* makeService(undefined, "1.2.3", undefined, true);
@@ -1312,6 +1383,23 @@ process.disconnect();
1383
expect(error).toMatchObject({ _tag: "BootServiceCommandError", exitCode: 1 });
1384
expect(commands).toEqual(["systemctl --user daemon-reload"]);
1385
expect(control.active).toBe(true);
1386
+ expect(yield* fs.exists(relayMarker)).toBe(false);
1387
+ expect(markersAtPreparation.at(-1)).toBe(false);
1388
+ expect(markersAtStop).toEqual([]);
1389
+
1390
+ const queueCommand = "systemctl --user restart --no-block t3code.service";
1391
+ control.failCommand = queueCommand;
1392
+ expect((yield* inside.restart.pipe(Effect.flip))._tag).toBe("BootServiceCommandError");
1393
+ expect(markersAtStop).toEqual([true]);
1394
+ expect(yield* fs.exists(relayMarker)).toBe(false);
1395
+
1396
+ control.failCommand = undefined;
1397
+ control.interruptCommand = queueCommand;
1398
+ const interrupted = yield* inside.restart.pipe(Effect.forkScoped);
1399
+ expect((yield* Fiber.await(interrupted))._tag).toBe("Failure");
1400
+ expect(markersAtStop).toEqual([true, true]);
1401
+ expect(yield* fs.exists(relayMarker)).toBe(false);
1402
+ delete control.interruptCommand;
1403
1404
control.failCommand = undefined;
1405
commands.length = 0;
@@ -1323,6 +1411,9 @@ process.disconnect();
1411
"systemctl --user restart --no-block t3code.service",
1412
]);
1413
expect(outcome).toBe("queued");
1414
+ expect(markersAtStop).toEqual([true, true, true]);
1415
+ expect(markersAtPreparation).not.toContain(true);
1416
+ expect(yield* fs.exists(relayMarker)).toBe(true);
1417
expect(yield* fs.readFileString(statePath)).toBe(state);
1418
expect(yield* fs.readFileString(marker)).toBe("1.2.3\n");
1419
}),
@@ -1406,7 +1497,8 @@ process.disconnect();
1497
1498
it.effect("installs, reports current state, and uninstalls on macOS", () =>
1499
Effect.gen(function* () {
1409
- const { service, fs, statePath, commands, timeouts, runtime } = yield* makeHarness("darwin");
1500
+ const { service, fs, statePath, commands, timeouts, runtime, markersAtStop } =
1501
+ yield* makeHarness("darwin");
1502
const path = yield* Path.Path;
1503
const plan = yield* service.install();
1504
@@ -1429,7 +1521,13 @@ process.disconnect();
1521
current: true,
1522
installedVersion: "1.2.3",
1523
});
1524
+ const relayMarker = path.join(plan.baseDir, "runtime", DESKTOP_UPDATE_RESTART_MARKER_FILE);
1525
+ expect(yield* service.restart).toBe("restarted");
1526
+ expect(markersAtStop).toEqual([true]);
1527
+ expect(yield* fs.exists(relayMarker)).toBe(false);
1528
expect(yield* service.uninstall).toBe(true);
1529
+ expect(markersAtStop).toEqual([true, false]);
1530
+ expect(yield* fs.exists(relayMarker)).toBe(false);
1531
expect((yield* service.status).installed).toBe(false);
1532
expect(commands.some((command) => command.startsWith("systemctl "))).toBe(false);
1533
// launchd can take 90s to bootout; the runner's 60s default could let bootstrap race it.
@@ -1532,9 +1630,19 @@ process.disconnect();
1630
1631
it.effect("hands an in-service install and restart to Task Scheduler on Windows", () =>
1632
Effect.gen(function* () {
1535
- const { service, fs, statePath, commands, makeService } = yield* makeHarness("win32");
1633
+ const {
1634
+ service,
1635
+ fs,
1636
+ statePath,
1637
+ commands,
1638
+ control,
1639
+ makeService,
1640
+ markersAtStop,
1641
+ markersAtPreparation,
1642
+ } = yield* makeHarness("win32");
1643
const plan = yield* service.install();
1644
const inside = yield* makeService(undefined, "1.2.4", undefined, true);
1645
+ const relayMarker = `${plan.baseDir}/runtime/${DESKTOP_UPDATE_RESTART_MARKER_FILE}`;
1646
const handoff = [
1647
`schtasks /Create /XML ${plan.unitPath} /TN t3code-PC-theo /F`,
1648
"schtasks /End /TN t3code-PC-theo",
@@ -1549,9 +1657,23 @@ process.disconnect();
1657
yield* fs.readFileString(`${plan.baseDir}/runtime/${SERVICE_RESTART_PENDING_FILE}`),
1658
).toBe("1.2.4\n");
1659
1660
+ expect(markersAtStop).toEqual([true]);
1661
+ expect(yield* fs.exists(relayMarker)).toBe(true);
1662
+ yield* fs.remove(relayMarker);
1663
+
1664
commands.length = 0;
1665
expect(yield* inside.restart).toBe("queued");
1666
expect(commands).toEqual(handoff);
1667
+ expect(markersAtStop).toEqual([true, true]);
1668
+ expect(yield* fs.exists(relayMarker)).toBe(true);
1669
+ yield* fs.remove(relayMarker);
1670
+
1671
+ expect(markersAtPreparation).not.toContain(true);
1672
+ control.failCommand = handoff[0];
1673
+ expect((yield* inside.restart.pipe(Effect.flip))._tag).toBe("BootServiceCommandError");
1674
+ expect(yield* fs.exists(relayMarker)).toBe(false);
1675
+ expect(markersAtPreparation.at(-1)).toBe(false);
1676
+ expect(markersAtStop).toEqual([true, true]);
1677
}),
1678
);
1679
apps/server/src/cloud/bootService.ts
+68
-29
@@ -1,3 +1,4 @@
1
+import { DESKTOP_UPDATE_RESTART_MARKER_FILE } from "@t3tools/contracts";
2
import * as HostProcess from "@t3tools/shared/HostProcess";
3
import * as Config from "effect/Config";
4
import * as Context from "effect/Context";
@@ -285,6 +286,11 @@ export type BootServiceStep = {
286
/** Must exceed systemd TimeoutStopSec and launchd ExitTimeOut (both 90s) to avoid shutdown races. */
287
const STOP_STEP_TIMEOUT = Duration.seconds(120);
288
289
+interface BootServiceHandoff {
290
+ readonly prepare: ReadonlyArray<BootServiceStep>;
291
+ readonly restart: ReadonlyArray<BootServiceStep>;
292
+}
293
+
294
export interface BootServiceManager {
295
readonly kind: "systemd" | "launchd" | "schtasks";
296
readonly unitPath: string;
@@ -293,7 +299,7 @@ export interface BootServiceManager {
299
readonly activate: ReadonlyArray<BootServiceStep>;
300
readonly restart: ReadonlyArray<BootServiceStep>;
301
/** Queue a restart owned by the manager, since stopping would kill the caller. */
296
- readonly handoff?: ReadonlyArray<BootServiceStep>;
302
+ readonly handoff?: BootServiceHandoff;
303
readonly deactivate: ReadonlyArray<BootServiceStep>;
304
readonly finalize: ReadonlyArray<BootServiceStep>;
305
}
@@ -364,14 +370,16 @@ function systemdManager(input: {
370
args: ["--user", "restart", BOOT_SERVICE_UNIT_FILE],
371
},
372
],
367
- handoff: [
368
- ...prepareActivation,
369
- {
370
- step: "restarting the service",
371
- command: "systemctl",
372
- args: ["--user", "restart", "--no-block", BOOT_SERVICE_UNIT_FILE],
373
- },
374
- ],
373
+ handoff: {
374
+ prepare: prepareActivation,
375
+ restart: [
376
+ {
377
+ step: "restarting the service",
378
+ command: "systemctl",
379
+ args: ["--user", "restart", "--no-block", BOOT_SERVICE_UNIT_FILE],
380
+ },
381
+ ],
382
+ },
383
deactivate: [
384
{
385
step: "stopping the service",
@@ -514,16 +522,18 @@ function schtasksManager(input: {
522
],
523
// Ending the task kills only its console host; the launcher sees the console close and
524
// stops gracefully while the replacement waits for its lock.
517
- handoff: [
518
- register,
519
- {
520
- step: "ending the scheduled task",
521
- command: "schtasks",
522
- args: ["/End", ...task],
523
- optional: true,
524
- },
525
- { ...run, step: "restarting the service" },
526
- ],
525
+ handoff: {
526
+ prepare: [register],
527
+ restart: [
528
+ {
529
+ step: "ending the scheduled task",
530
+ command: "schtasks",
531
+ args: ["/End", ...task],
532
+ optional: true,
533
+ },
534
+ { ...run, step: "restarting the service" },
535
+ ],
536
+ },
537
deactivate: [...stop, { step: "removing the scheduled task", run: input.steps.remove }],
538
finalize: [],
539
};
@@ -1211,6 +1221,29 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
1221
return problems;
1222
});
1223
1224
+ // Reuse the desktop marker so already released servers recognize the restart.
1225
+ const restartMarker = path.join(input.baseDir, "runtime", DESKTOP_UPDATE_RESTART_MARKER_FILE);
1226
+ const markRestart = fs.writeFileString(restartMarker, "", { mode: 0o600 }).pipe(
1227
+ Effect.as(true),
1228
+ Effect.catch((error) =>
1229
+ Effect.logWarning("Could not mark the service restart to preserve its relay tunnel", {
1230
+ errorTag: error._tag,
1231
+ }).pipe(Effect.as(false)),
1232
+ ),
1233
+ );
1234
+ const stopForRestart = (steps: ReadonlyArray<BootServiceStep>, queued = false) =>
1235
+ Effect.acquireUseRelease(
1236
+ markRestart,
1237
+ () => runSteps(steps),
1238
+ (marked, exit) =>
1239
+ // When a restart is queued, the outgoing server still needs to read the marker.
1240
+ marked && (!queued || Exit.isFailure(exit))
1241
+ ? fs.remove(restartMarker, { force: true }).pipe(Effect.ignore)
1242
+ : Effect.void,
1243
+ );
1244
+ const handOffRestart = (handoff: BootServiceHandoff) =>
1245
+ runSteps(handoff.prepare).pipe(Effect.andThen(stopForRestart(handoff.restart, true)));
1246
+
1247
const install = Effect.fn("cloud.boot_service.install")(function* (options?: {
1248
readonly allowDowngrade?: boolean;
1249
readonly start?: boolean;
@@ -1334,9 +1367,12 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
1367
}
1368
// Task Scheduler restarts the task itself, so the files are written as for a deferred
1369
// restart while this launcher keeps running, then the restart is handed to the manager.
1337
- const handOff = installed && start && runningInsideService && manager.kind === "schtasks";
1338
- if (installed && start && !handOff) {
1339
- yield* runSteps(manager.stop);
1370
+ const handoff =
1371
+ installed && start && runningInsideService && manager.kind === "schtasks"
1372
+ ? manager.handoff
1373
+ : undefined;
1374
+ if (installed && start && handoff === undefined) {
1375
+ yield* stopForRestart(manager.stop);
1376
}
1377
1378
// State first, then unit. The launcher acquires only one at a time, and a
@@ -1396,7 +1432,10 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
1432
2,
1433
)}\n`,
1434
);
1399
- if ((!start || handOff) && (currentlyInstalled || Option.isSome(previousStateText))) {
1435
+ if (
1436
+ (!start || handoff !== undefined) &&
1437
+ (currentlyInstalled || Option.isSome(previousStateText))
1438
+ ) {
1439
const written = yield* fs.readFileString(statePath);
1440
if (serviceStateActiveVersion(written) !== input.cliVersion) {
1441
return yield* new BootServiceUpdatePendingError();
@@ -1414,8 +1453,8 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
1453
).pipe(
1454
Effect.tap(
1455
Effect.gen(function* () {
1417
- if (handOff) {
1418
- yield* runSteps(manager.handoff ?? []);
1456
+ if (handoff !== undefined) {
1457
+ yield* handOffRestart(handoff);
1458
} else if (start) {
1459
yield* runSteps(manager.activate);
1460
yield* withSelectionLock(
@@ -1435,12 +1474,12 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
1474
cause._tag === "PlatformError" ? new BootServiceInstallError({ cause }) : cause,
1475
),
1476
Effect.tapError(() =>
1438
- installed && start && !handOff
1477
+ installed && start && handoff === undefined
1478
? runSteps(manager.restart).pipe(Effect.ignore)
1479
: Effect.void,
1480
),
1481
);
1443
- return handOff ? { ...installedPlan, handedOff: true } : installedPlan;
1482
+ return handoff !== undefined ? { ...installedPlan, handedOff: true } : installedPlan;
1483
});
1484
1485
const restart: BootService["Service"]["restart"] = Effect.gen(function* () {
@@ -1457,10 +1496,10 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
1496
// Writes no state, and the launcher lets an update transition in flight
1497
// finish before the queued stop tears it down.
1498
if (runningInsideService && manager.handoff !== undefined) {
1460
- yield* runSteps(manager.handoff);
1499
+ yield* handOffRestart(manager.handoff);
1500
return "queued" as const;
1501
}
1463
- yield* runSteps(manager.stop);
1502
+ yield* stopForRestart(manager.stop);
1503
yield* runSteps(manager.activate).pipe(
1504
Effect.tapError(() => runSteps(manager.restart).pipe(Effect.ignore)),
1505
);