@devries-cameron20 / t3code-1 / commits / 13e940a4e3
Fork 0

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 );