The best way to control Claude Code, Codex and more from any computer or phone
fix(desktop): an SSH reconnect during a desktop update no longer locks the updated app out of its T3 home (#26191)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
AJ committed
Nov 12, 2026 at 16:49 UTC
79daf43c1cab9c9e74733eaf7b95e1926f237d96
15 files changed
+923
-45
.gitignore
+2
@@ -49,3 +49,5 @@ node_modules/
49
50
# pnpm content-addressable store; never belongs in the repo.
51
.pnpm-store/
52
+
53
+/packages/ssh/.ssh-launcher-test-*/
apps/desktop/src/backend/DesktopBackendManager.ts
+6
-6
@@ -205,7 +205,7 @@ interface RunBackendProcessOptions extends DesktopBackendStartConfig {
205
readonly outputDrainTimeout?: Duration.Duration;
206
readonly onStarted?: (pid: number) => Effect.Effect<void>;
207
readonly onExitObserved?: () => Effect.Effect<void>;
208
- readonly onReady?: () => Effect.Effect<void>;
208
+ readonly onReady?: (pid: number) => Effect.Effect<void>;
209
readonly onReadinessFailure?: (error: BackendReadinessTimeoutError) => Effect.Effect<void>;
210
readonly onOutput?: (
211
streamName: BackendProcessOutputStream,
@@ -252,8 +252,8 @@ export interface BackendInstanceSpec {
252
readonly id: BackendInstanceId;
253
readonly label: Effect.Effect<string>;
254
readonly configResolve: Effect.Effect<DesktopBackendStartConfig, PlatformError.PlatformError>;
255
- /** Receives the ready run's resolved URL; reading current config could race a subsequent restart. */
256
- readonly onReady?: (httpBaseUrl: URL) => Effect.Effect<void>;
255
+ /** Receives the ready run's URL and pid; reading current config could race a subsequent restart. */
256
+ readonly onReady?: (httpBaseUrl: URL, pid: number) => Effect.Effect<void>;
257
readonly onShutdown?: () => Effect.Effect<void>;
258
readonly onPreflightFailed?: (failure: PreflightFailure) => Effect.Effect<boolean>;
259
readonly onStateDirOwned?: () => Effect.Effect<void>;
@@ -578,7 +578,7 @@ export const runBackendProcess = Effect.fn("runBackendProcess")(function* (
578
httpBaseUrl: options.httpBaseUrl,
579
timeout: options.readinessTimeout ?? DEFAULT_BACKEND_READINESS_TIMEOUT,
580
}).pipe(
581
- Effect.flatMap(() => options.onReady?.() ?? Effect.void),
581
+ Effect.flatMap(() => options.onReady?.(handle.pid) ?? Effect.void),
582
Effect.as(true),
583
Effect.catchTags({
584
BackendReadinessTimeoutError: (error) =>
@@ -939,7 +939,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
939
...run,
940
exitObserved: true,
941
})),
942
- onReady: Effect.fn("desktop.backendInstance.onReady")(function* () {
942
+ onReady: Effect.fn("desktop.backendInstance.onReady")(function* (pid) {
943
const isCurrentRun = yield* SubscriptionRef.modify(state, (latest) => {
944
const activeRun = Option.getOrUndefined(latest.active);
945
if (activeRun?.id !== runId) {
@@ -959,7 +959,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
959
return;
960
}
961
962
- yield* spec.onReady?.(config.value.httpBaseUrl) ?? Effect.void;
962
+ yield* spec.onReady?.(config.value.httpBaseUrl, pid) ?? Effect.void;
963
if (
964
config.value.runningDistro !== undefined &&
965
config.value.wslRuntimeId !== undefined
apps/desktop/src/backend/DesktopBackendPool.test.ts
+234
-29
@@ -1,5 +1,5 @@
1
-import * as NodeServices from "@effect/platform-node/NodeServices";
1
import { assert, describe, it } from "@effect/vitest";
2
+import { DESKTOP_UPDATE_IN_PROGRESS_TTL_MS } from "@t3tools/contracts";
3
import * as Deferred from "effect/Deferred";
4
import * as Duration from "effect/Duration";
5
import * as Effect from "effect/Effect";
@@ -110,27 +110,52 @@ const runningConfig = {
110
111
function layerPool(
112
labelRef: Ref.Ref<string>,
113
- backend?: Effect.Success<ReturnType<typeof makeFakeBackendProcess>>,
113
+ options: {
114
+ readonly config?: DesktopBackendStartConfig;
115
+ readonly fileSystem?: Partial<FileSystem.FileSystem>;
116
+ readonly spawner?: ChildProcessSpawner.ChildProcessSpawner["Service"];
117
+ readonly httpClient?: HttpClient.HttpClient;
118
+ readonly onReady?: Effect.Effect<void>;
119
+ readonly backend?: Effect.Success<ReturnType<typeof makeFakeBackendProcess>>;
120
+ } = {},
121
): Layer.Layer<DesktopBackendPool.DesktopBackendPool> {
122
return DesktopBackendPool.layer.pipe(
123
Layer.provideMerge(
124
Layer.mergeAll(
118
- FileSystem.layerNoop({ exists: () => Effect.succeed(true) }),
125
+ DesktopEnvironment.layer({
126
+ dirname: "/repo/apps/desktop/src",
127
+ homeDirectory: "/test-home",
128
+ platform: "linux",
129
+ processArch: "x64",
130
+ appVersion: "1.2.3",
131
+ appPath: "/repo",
132
+ isPackaged: true,
133
+ resourcesPath: "/missing/resources",
134
+ runningUnderArm64Translation: false,
135
+ }).pipe(
136
+ Layer.provide(
137
+ Layer.mergeAll(Path.layer, DesktopConfig.layerTest({ T3CODE_HOME: "/test-home" })),
138
+ ),
139
+ Layer.orDie,
140
+ ),
141
+ FileSystem.layerNoop(options.fileSystem ?? { exists: () => Effect.succeed(true) }),
142
Path.layer,
120
- backend?.layer ??
143
+ options.backend?.layer ??
144
Layer.succeed(
145
ChildProcessSpawner.ChildProcessSpawner,
123
- ChildProcessSpawner.make(() => Effect.die("unexpected child process spawn")),
146
+ options.spawner ??
147
+ ChildProcessSpawner.make(() => Effect.die("unexpected child process spawn")),
148
),
149
Layer.succeed(
150
HttpClient.HttpClient,
127
- HttpClient.make((request) =>
128
- backend === undefined
129
- ? Effect.die("unexpected HTTP request")
130
- : Effect.succeed(
131
- HttpClientResponse.fromWeb(request, new Response(null, { status: 200 })),
132
- ),
133
- ),
151
+ options.httpClient ??
152
+ HttpClient.make((request) =>
153
+ options.backend === undefined
154
+ ? Effect.die("unexpected HTTP request")
155
+ : Effect.succeed(
156
+ HttpClientResponse.fromWeb(request, new Response(null, { status: 200 })),
157
+ ),
158
+ ),
159
),
160
Layer.succeed(DesktopObservability.DesktopBackendOutputLogFactory, {
161
forInstance: () =>
@@ -155,26 +180,14 @@ function layerPool(
180
}),
181
DesktopBrowserHost.layer,
182
Layer.succeed(DesktopBackendConfiguration.DesktopBackendConfiguration, {
158
- resolvePrimary: Effect.die("unexpected primary config resolve"),
183
+ resolvePrimary: options.config
184
+ ? Effect.succeed(options.config)
185
+ : Effect.die("unexpected primary config resolve"),
186
resolvePrimaryLabel: Ref.get(labelRef),
187
resolveWsl: () => Effect.die("unexpected WSL config resolve"),
188
currentBootstrapToken: Effect.die("unexpected bootstrap token read"),
189
} satisfies DesktopBackendConfiguration.DesktopBackendConfiguration["Service"]),
190
DesktopAppSettings.layerTest(),
164
- DesktopEnvironment.layer({
165
- dirname: "/repo/apps/desktop/src",
166
- homeDirectory: "/home/test",
167
- platform: "linux",
168
- processArch: "x64",
169
- appVersion: "0.0.0",
170
- appPath: "/repo",
171
- isPackaged: true,
172
- resourcesPath: "/missing/resources",
173
- runningUnderArm64Translation: false,
174
- }).pipe(
175
- Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({}))),
176
- Layer.orDie,
177
- ),
191
DesktopState.layer,
192
DesktopWslEnvironment.layerTest(),
193
ElectronDialog.layer,
@@ -186,7 +199,7 @@ function layerPool(
199
activate: Effect.die("unexpected window activate"),
200
createMainIfBackendReady: Effect.die("unexpected window create"),
201
showConnectingSplash: Effect.void,
189
- handleBackendReady: () => Effect.void,
202
+ handleBackendReady: () => options.onReady ?? Effect.void,
203
handleBackendNotReady: Effect.void,
204
flushMainWindowBounds: Effect.void,
205
prepareCaptureReveal: Effect.void,
@@ -201,7 +214,199 @@ function layerPool(
214
);
215
}
216
217
+const markerPath = "/test-home/runtime/desktop-update-in-progress";
218
+const runtimePath = "/test-home/userdata/server-runtime.json";
219
+
220
+const makeUpdateMarkerFixture = () =>
221
+ Effect.gen(function* () {
222
+ const allowReady = yield* Deferred.make<void>();
223
+ const runtimeChecked = yield* Deferred.make<void>();
224
+ const markerRemoved = yield* Deferred.make<void>();
225
+ const readyRuns = yield* Queue.unbounded<void>();
226
+ let nextPid = 123;
227
+ const files = new Map([[markerPath, JSON.stringify({ startedAt: 0, expiresAt: 60_000 })]]);
228
+ const removed: string[] = [];
229
+ const config: DesktopBackendStartConfig = {
230
+ executablePath: "/electron",
231
+ args: [],
232
+ entryPath: "/server/bin.mjs",
233
+ cwd: "/server",
234
+ env: {},
235
+ bootstrap: {
236
+ mode: "desktop",
237
+ noBrowser: true,
238
+ port: 3774,
239
+ t3Home: "/test-home",
240
+ host: "127.0.0.1",
241
+ desktopBootstrapToken: "token",
242
+ tailscaleServeEnabled: false,
243
+ tailscaleServePort: 443,
244
+ },
245
+ bootstrapDelivery: "fd3",
246
+ extendEnv: true,
247
+ httpBaseUrl: new URL("http://127.0.0.1:3774"),
248
+ captureOutput: false,
249
+ preflightFailure: Option.none(),
250
+ };
251
+ const layer = layerPool(Ref.makeUnsafe("Local"), {
252
+ config,
253
+ fileSystem: {
254
+ exists: (path) => Effect.succeed(files.has(path) || path === config.entryPath),
255
+ readFileString: (path) =>
256
+ (path === runtimePath ? Deferred.succeed(runtimeChecked, undefined) : Effect.void).pipe(
257
+ Effect.andThen(Effect.sync(() => files.get(path) ?? "")),
258
+ ),
259
+ remove: (path) =>
260
+ Effect.sync(() => {
261
+ removed.push(path);
262
+ files.delete(path);
263
+ }).pipe(
264
+ Effect.andThen(
265
+ path === markerPath ? Deferred.succeed(markerRemoved, undefined) : Effect.void,
266
+ ),
267
+ Effect.asVoid,
268
+ ),
269
+ },
270
+ spawner: ChildProcessSpawner.make(() =>
271
+ Effect.gen(function* () {
272
+ const exited = yield* Deferred.make<ChildProcessSpawner.ExitCode>();
273
+ const exit = Deferred.succeed(exited, ChildProcessSpawner.ExitCode(0)).pipe(
274
+ Effect.asVoid,
275
+ );
276
+ // Like the real spawner, closing the run's scope ends the process.
277
+ yield* Effect.addFinalizer(() => exit);
278
+ return ChildProcessSpawner.makeHandle({
279
+ pid: ChildProcessSpawner.ProcessId(nextPid++),
280
+ stdout: Stream.empty,
281
+ stderr: Stream.empty,
282
+ all: Stream.empty,
283
+ exitCode: Deferred.await(exited),
284
+ isRunning: Effect.succeed(true),
285
+ kill: () => exit,
286
+ stdin: Sink.drain,
287
+ getInputFd: () => Sink.drain,
288
+ getOutputFd: () => Stream.empty,
289
+ unref: Effect.succeed(Effect.void),
290
+ });
291
+ }),
292
+ ),
293
+ httpClient: HttpClient.make((request) =>
294
+ Deferred.await(allowReady).pipe(
295
+ Effect.as(HttpClientResponse.fromWeb(request, new Response(null, { status: 200 }))),
296
+ ),
297
+ ),
298
+ onReady: Queue.offer(readyRuns, undefined).pipe(Effect.asVoid),
299
+ });
300
+ const publishRuntime = (pid: number) =>
301
+ files.set(
302
+ runtimePath,
303
+ JSON.stringify({
304
+ version: 1,
305
+ pid,
306
+ port: 3774,
307
+ origin: "http://127.0.0.1:3774",
308
+ startedAt: "2026-10-27T00:00:00.000Z",
309
+ }),
310
+ );
311
+ return {
312
+ layer,
313
+ files,
314
+ removed,
315
+ allowReady,
316
+ readyRuns,
317
+ runtimeChecked,
318
+ markerRemoved,
319
+ publishRuntime,
320
+ };
321
+ });
322
+
323
describe("DesktopBackendPool", () => {
324
+ it.effect(
325
+ "keeps the update marker after HTTP readiness until the backend publishes its runtime",
326
+ () =>
327
+ Effect.scoped(
328
+ Effect.gen(function* () {
329
+ const fixture = yield* makeUpdateMarkerFixture();
330
+ yield* Effect.gen(function* () {
331
+ const pool = yield* DesktopBackendPool.DesktopBackendPool;
332
+ const primary = yield* pool.primary;
333
+ yield* primary.start;
334
+ yield* Deferred.succeed(fixture.allowReady, undefined);
335
+ yield* Queue.take(fixture.readyRuns);
336
+ assert.isTrue(
337
+ fixture.files.has(markerPath),
338
+ "a launcher could neither wait nor adopt between readiness and publication",
339
+ );
340
+ yield* Deferred.await(fixture.runtimeChecked);
341
+ yield* TestClock.adjust(Duration.seconds(5));
342
+ assert.isTrue(fixture.files.has(markerPath));
343
+ fixture.publishRuntime(456);
344
+ yield* TestClock.adjust(Duration.seconds(1));
345
+ assert.isTrue(
346
+ fixture.files.has(markerPath),
347
+ "another process's runtime is not the replacement",
348
+ );
349
+ fixture.publishRuntime(123);
350
+ yield* TestClock.adjust(Duration.seconds(1));
351
+ yield* Deferred.await(fixture.markerRemoved);
352
+ assert.deepEqual(fixture.removed, [markerPath]);
353
+ }).pipe(Effect.provide(fixture.layer));
354
+ }),
355
+ ),
356
+ );
357
+
358
+ it.effect("leaves a replacement update marker written while an earlier wait is pending", () =>
359
+ Effect.scoped(
360
+ Effect.gen(function* () {
361
+ const fixture = yield* makeUpdateMarkerFixture();
362
+ yield* Effect.gen(function* () {
363
+ const pool = yield* DesktopBackendPool.DesktopBackendPool;
364
+ const primary = yield* pool.primary;
365
+ yield* primary.start;
366
+ yield* Deferred.succeed(fixture.allowReady, undefined);
367
+ yield* Queue.take(fixture.readyRuns);
368
+ yield* Deferred.await(fixture.runtimeChecked);
369
+ yield* TestClock.adjust(Duration.millis(DESKTOP_UPDATE_IN_PROGRESS_TTL_MS - 1_000));
370
+ const replacement = JSON.stringify({ startedAt: 59_000, expiresAt: 119_000 });
371
+ fixture.files.set(markerPath, replacement);
372
+ yield* TestClock.adjust(Duration.millis(DESKTOP_UPDATE_IN_PROGRESS_TTL_MS));
373
+ assert.equal(fixture.files.get(markerPath), replacement);
374
+ assert.deepEqual(fixture.removed, []);
375
+ }).pipe(Effect.provide(fixture.layer));
376
+ }),
377
+ ),
378
+ );
379
+
380
+ it.effect("a later backend run's readiness supersedes the earlier run's marker wait", () =>
381
+ Effect.scoped(
382
+ Effect.gen(function* () {
383
+ const fixture = yield* makeUpdateMarkerFixture();
384
+ yield* Effect.gen(function* () {
385
+ const pool = yield* DesktopBackendPool.DesktopBackendPool;
386
+ const primary = yield* pool.primary;
387
+ yield* primary.start;
388
+ yield* Deferred.succeed(fixture.allowReady, undefined);
389
+ yield* Queue.take(fixture.readyRuns);
390
+ yield* Deferred.await(fixture.runtimeChecked);
391
+ yield* TestClock.adjust(Duration.seconds(30));
392
+ yield* primary.stop();
393
+ yield* primary.start;
394
+ yield* Queue.take(fixture.readyRuns);
395
+ yield* TestClock.adjust(Duration.seconds(31));
396
+ assert.isTrue(
397
+ fixture.files.has(markerPath),
398
+ "the earlier run's wait must not end the later run's handoff",
399
+ );
400
+ assert.deepEqual(fixture.removed, []);
401
+ fixture.publishRuntime(124);
402
+ yield* TestClock.adjust(Duration.millis(100));
403
+ yield* Deferred.await(fixture.markerRemoved);
404
+ assert.deepEqual(fixture.removed, [markerPath]);
405
+ }).pipe(Effect.provide(fixture.layer));
406
+ }),
407
+ ),
408
+ );
409
+
410
it.effect("unregister during pool quit does not interrupt sibling stops", () =>
411
Effect.scoped(
412
Effect.gen(function* () {
@@ -253,7 +458,7 @@ describe("DesktopBackendPool", () => {
458
assert.isFalse(yield* backend.isRunning);
459
assert.isTrue(Option.isNone((yield* instance.snapshot).activePid));
460
assert.isTrue(Option.isNone(yield* pool.get(id)));
256
- }).pipe(Effect.provide(layerPool(Ref.makeUnsafe("Windows"), backend)));
461
+ }).pipe(Effect.provide(layerPool(Ref.makeUnsafe("Windows"), { backend })));
462
}),
463
),
464
);
apps/desktop/src/backend/DesktopBackendPool.ts
+55
-3
@@ -1,10 +1,17 @@
1
+import {
2
+ DESKTOP_UPDATE_IN_PROGRESS_MARKER_FILE,
3
+ DESKTOP_UPDATE_IN_PROGRESS_TTL_MS,
4
+} from "@t3tools/contracts";
5
import * as Context from "effect/Context";
6
import * as Deferred from "effect/Deferred";
7
+import * as Duration from "effect/Duration";
8
import * as Effect from "effect/Effect";
9
import * as Exit from "effect/Exit";
10
+import * as FiberHandle from "effect/FiberHandle";
11
import * as Layer from "effect/Layer";
12
import * as Option from "effect/Option";
13
import * as Path from "effect/Path";
14
+import * as Schedule from "effect/Schedule";
15
import * as Schema from "effect/Schema";
16
import * as Scope from "effect/Scope";
17
import * as SubscriptionRef from "effect/SubscriptionRef";
@@ -31,6 +38,10 @@ import * as ElectronApp from "../electron/ElectronApp.ts";
38
const { logWarning: logBackendPoolWarning } =
39
DesktopObservability.makeComponentLogger("desktop-backend-pool");
40
41
+const decodeServerRuntime = Schema.decodeUnknownEffect(
42
+ Schema.fromJsonString(Schema.Struct({ pid: Schema.Number, port: Schema.Number })),
43
+);
44
+
45
export type BackendInstanceId = DesktopBackendManager.BackendInstanceId;
46
export const BackendInstanceId = DesktopBackendManager.BackendInstanceId;
47
export const PRIMARY_INSTANCE_ID = DesktopBackendManager.PRIMARY_INSTANCE_ID;
@@ -106,6 +117,8 @@ type UnregisterAction =
117
export const layer = Layer.effect(
118
DesktopBackendPool,
119
Effect.gen(function* () {
120
+ const environment = yield* DesktopEnvironment.DesktopEnvironment;
121
+ const fileSystem = yield* FileSystem.FileSystem;
122
const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
123
const desktopWindow = yield* DesktopWindow.DesktopWindow;
124
const electronDialog = yield* ElectronDialog.ElectronDialog;
@@ -119,6 +132,41 @@ export const layer = Layer.effect(
132
FileSystem.FileSystem | Path.Path | DesktopEnvironment.DesktopEnvironment
133
>();
134
135
+ const updateMarkerPath = environment.path.join(
136
+ environment.baseDir,
137
+ "runtime",
138
+ DESKTOP_UPDATE_IN_PROGRESS_MARKER_FILE,
139
+ );
140
+ const serverRuntimePath = environment.path.join(environment.stateDir, "server-runtime.json");
141
+ // The server publishes its runtime after HTTP readiness. Until then an SSH launcher
142
+ // finds nothing to adopt, so dropping the marker earlier lets it start a competing server.
143
+ const releaseUpdateMarker = Effect.fn("desktop.backendPool.releaseUpdateMarker")(function* (
144
+ httpBaseUrl: URL,
145
+ pid: number,
146
+ ) {
147
+ const marker = yield* fileSystem.readFileString(updateMarkerPath).pipe(Effect.option);
148
+ if (Option.isNone(marker)) {
149
+ return;
150
+ }
151
+ yield* fileSystem.readFileString(serverRuntimePath).pipe(
152
+ Effect.flatMap(decodeServerRuntime),
153
+ Effect.map((runtime) => runtime.pid === pid && runtime.port === Number(httpBaseUrl.port)),
154
+ Effect.orElseSucceed(() => false),
155
+ Effect.repeat({
156
+ until: (published) => published,
157
+ schedule: Schedule.spaced(Duration.millis(100)),
158
+ }),
159
+ Effect.timeoutOption(Duration.millis(DESKTOP_UPDATE_IN_PROGRESS_TTL_MS)),
160
+ );
161
+ // A later update may have replaced the marker; that handoff is not ours to end.
162
+ const current = yield* fileSystem.readFileString(updateMarkerPath).pipe(Effect.option);
163
+ if (Option.isSome(current) && current.value === marker.value) {
164
+ yield* fileSystem.remove(updateMarkerPath, { force: true }).pipe(Effect.ignore);
165
+ }
166
+ });
167
+ // One wait at a time: each run's shutdown or readiness ends the previous run's wait.
168
+ const updateMarkerWait = yield* FiberHandle.make<void>();
169
+
170
// Persist fatal Windows fallbacks; transient transport failures must preserve the user's WSL preference.
171
const handlePrimaryPreflightFailure = Effect.fn("desktop.backendPool.primaryPreflightFailed")(
172
function* (failure: DesktopBackendManager.PreflightFailure) {
@@ -165,8 +213,9 @@ export const layer = Layer.effect(
213
label: configuration.resolvePrimaryLabel,
214
configResolve: configuration.resolvePrimary,
215
// Absorb window errors so readiness can reset restartAttempt.
168
- onReady: (httpBaseUrl) =>
169
- desktopWindow.handleBackendReady(httpBaseUrl).pipe(
216
+ onReady: (httpBaseUrl, pid) =>
217
+ FiberHandle.run(updateMarkerWait, releaseUpdateMarker(httpBaseUrl, pid)).pipe(
218
+ Effect.andThen(desktopWindow.handleBackendReady(httpBaseUrl)),
219
// Only once the main window exists, so the recovery window never closes into nothing.
220
Effect.andThen(SubscriptionRef.set(primaryBackendStartup, { _tag: "Ready" })),
221
Effect.catch((error) =>
@@ -177,7 +226,10 @@ export const layer = Layer.effect(
226
),
227
onStartupFailure: (failure) =>
228
SubscriptionRef.set(primaryBackendStartup, { _tag: "Failing", ...failure }),
180
- onShutdown: () => desktopWindow.handleBackendNotReady,
229
+ onShutdown: () =>
230
+ FiberHandle.clear(updateMarkerWait).pipe(
231
+ Effect.andThen(desktopWindow.handleBackendNotReady),
232
+ ),
233
onPreflightFailed: handlePrimaryPreflightFailure,
234
onStateDirOwned: () =>
235
DesktopHomeOwner.readLiveHomeOwner().pipe(
apps/desktop/src/updates/DesktopUpdates.test.ts
+12
@@ -544,14 +544,17 @@ describe("DesktopUpdates", () => {
544
545
it.effect("marks the backend stop for an install as an update restart", () => {
546
let markersAtStop: ReadonlyArray<string> = [];
547
+ let inProgressAtStop: string | undefined;
548
const harness = makeHarness({
549
stopBackend: Effect.sync(() => {
550
markersAtStop = [...harness.updateRestartMarkers];
551
+ inProgressAtStop = harness.updateInProgressMarker();
552
}),
553
});
554
555
return Effect.scoped(
556
Effect.gen(function* () {
557
+ yield* TestClock.setTime(1_000);
558
const environment = yield* DesktopEnvironment.DesktopEnvironment;
559
const updates = yield* DesktopUpdates.DesktopUpdates;
560
yield* updates.configure;
@@ -562,6 +565,12 @@ describe("DesktopUpdates", () => {
565
assert.deepEqual(markersAtStop, [
566
environment.path.join(environment.baseDir, "runtime", DESKTOP_UPDATE_RESTART_MARKER_FILE),
567
]);
568
+ // SSH launchers wait on this until the replacement backend publishes its runtime.
569
+ assert.deepEqual(JSON.parse(inProgressAtStop ?? "null"), {
570
+ startedAt: 1_000,
571
+ expiresAt: 61_000,
572
+ });
573
+ assert.isDefined(harness.updateInProgressMarker());
574
}),
575
).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
576
});
@@ -644,9 +653,11 @@ describe("DesktopUpdates", () => {
653
const installFiber = yield* updates.install.pipe(Effect.forkScoped);
654
yield* Deferred.await(stopping);
655
assert.equal(harness.updateRestartMarkers.size, 1);
656
+ assert.isDefined(harness.updateInProgressMarker());
657
658
yield* Fiber.interrupt(installFiber);
659
assert.equal(harness.updateRestartMarkers.size, 0);
660
+ assert.isUndefined(harness.updateInProgressMarker());
661
}),
662
).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
663
}),
@@ -681,6 +692,7 @@ describe("DesktopUpdates", () => {
692
"startBackend",
693
]);
694
assert.equal(harness.updateRestartMarkers.size, 0);
695
+ assert.isUndefined(harness.updateInProgressMarker());
696
assert.equal(harness.installRecords.size, 0);
697
}),
698
).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
apps/desktop/src/updates/DesktopUpdates.ts
+33
@@ -1,5 +1,7 @@
1
import {
2
DESKTOP_UPDATE_RESTART_MARKER_FILE,
3
+ DESKTOP_UPDATE_IN_PROGRESS_MARKER_FILE,
4
+ DESKTOP_UPDATE_IN_PROGRESS_TTL_MS,
5
DesktopUpdateChannelSchema,
6
type DesktopRuntimeInfo,
7
type DesktopUpdateActionResult,
@@ -669,6 +671,34 @@ export const make = Effect.gen(function* () {
671
),
672
);
673
674
+ const updateInProgressMarkerPath = environment.path.join(
675
+ updateRestartMarkerDir,
676
+ DESKTOP_UPDATE_IN_PROGRESS_MARKER_FILE,
677
+ );
678
+ const encodeUpdateMarker = Schema.encodeEffect(
679
+ Schema.fromJsonString(Schema.Struct({ startedAt: Schema.Number, expiresAt: Schema.Number })),
680
+ );
681
+ const updateInProgressTempPath = `${updateInProgressMarkerPath}.tmp`;
682
+ const writeUpdateInProgressMarker = Effect.gen(function* () {
683
+ const startedAt = DateTime.toEpochMillis(yield* DateTime.now);
684
+ const contents = yield* encodeUpdateMarker({
685
+ startedAt,
686
+ expiresAt: startedAt + DESKTOP_UPDATE_IN_PROGRESS_TTL_MS,
687
+ });
688
+ yield* fileSystem.writeFileString(updateInProgressTempPath, contents);
689
+ yield* fileSystem.rename(updateInProgressTempPath, updateInProgressMarkerPath);
690
+ }).pipe(
691
+ Effect.ensuring(
692
+ fileSystem.remove(updateInProgressTempPath, { force: true }).pipe(Effect.ignore),
693
+ ),
694
+ Effect.catch((error) =>
695
+ logUpdaterWarning("Could not write the update-in-progress marker.", { errorTag: error._tag }),
696
+ ),
697
+ );
698
+ const removeUpdateInProgressMarker = fileSystem
699
+ .remove(updateInProgressMarkerPath, { force: true })
700
+ .pipe(Effect.ignore);
701
+
702
// Failed or interrupted installs leave no replacement backend; later quits must release the tunnel.
703
const removeUpdateRestartMarker = fileSystem
704
.remove(updateRestartMarkerPath, { force: true })
@@ -724,6 +754,7 @@ export const make = Effect.gen(function* () {
754
Ref.set(desktopState.quitting, false),
755
Ref.set(installRunningBackendsRef, []),
756
removeUpdateRestartMarker,
757
+ removeUpdateInProgressMarker,
758
removeInstallRecord,
759
],
760
{ discard: true },
@@ -741,6 +772,7 @@ export const make = Effect.gen(function* () {
772
773
yield* Ref.set(desktopState.quitting, false);
774
yield* removeUpdateRestartMarker;
775
+ yield* removeUpdateInProgressMarker;
776
yield* removeInstallRecord;
777
yield* Effect.gen(function* () {
778
const runningInstances = yield* Ref.getAndSet(installRunningBackendsRef, []);
@@ -816,6 +848,7 @@ export const make = Effect.gen(function* () {
848
849
return yield* Effect.gen(function* () {
850
yield* writeUpdateRestartMarker;
851
+ yield* writeUpdateInProgressMarker;
852
const { downloadedVersion } = yield* Ref.get(updateStateRef);
853
if (downloadedVersion !== null) yield* writeInstallRecord(downloadedVersion);
854
// Stop pooled backends and SSH tunnels before quitAndInstall can outrun their scope finalizers.
apps/desktop/src/updates/updatesTestHarness.ts
+14
-1
@@ -244,6 +244,7 @@ export function makeHarness(options: UpdatesHarnessOptions = {}) {
244
: DesktopAppSettings.layer;
245
246
const updateRestartMarkers = new Set<string>();
247
+ const updateMarkerContents = new Map<string, string>();
248
const installRecords = new Map<string, string>();
249
let previousInstallRecord = options.installRecord;
250
const isInstallRecord = (path: string) =>
@@ -269,11 +270,21 @@ export function makeHarness(options: UpdatesHarnessOptions = {}) {
270
writeFileString: (path, data) =>
271
Effect.sync(() => {
272
if (isInstallRecord(path)) installRecords.set(path, data);
272
- else updateRestartMarkers.add(path);
273
+ else {
274
+ if (path.endsWith("/desktop-update-restart")) updateRestartMarkers.add(path);
275
+ updateMarkerContents.set(path, data);
276
+ }
277
+ }),
278
+ rename: (from, to) =>
279
+ Effect.sync(() => {
280
+ const contents = updateMarkerContents.get(from);
281
+ if (contents !== undefined) updateMarkerContents.set(to, contents);
282
+ updateMarkerContents.delete(from);
283
}),
284
remove: (path) =>
285
Effect.sync(() => {
286
updateRestartMarkers.delete(path);
287
+ updateMarkerContents.delete(path);
288
installRecords.delete(path);
289
if (isInstallRecord(path)) previousInstallRecord = undefined;
290
}),
@@ -306,6 +317,8 @@ export function makeHarness(options: UpdatesHarnessOptions = {}) {
317
quitAndInstalls: () => quitAndInstallCount,
318
installSteps,
319
updateRestartMarkers,
320
+ updateInProgressMarker: () =>
321
+ [...updateMarkerContents].find(([path]) => path.endsWith("/desktop-update-in-progress"))?.[1],
322
installRecords,
323
previousInstallRecord: () => previousInstallRecord,
324
downloadCount: () => downloadCount,
apps/desktop/src/wsl/DesktopWslBackend.test.ts
+1
-1
@@ -154,7 +154,7 @@ describe("DesktopWslBackend", () => {
154
assert.equal(startCount, 1);
155
assert.deepEqual(yield* backend.lastPreflightError, refusal);
156
157
- yield* clearFailure(new URL("http://127.0.0.1:41773"));
157
+ yield* clearFailure(new URL("http://127.0.0.1:41773"), 123);
158
assert.deepEqual(yield* backend.lastPreflightError, Option.none());
159
yield* recordOwnershipFailure();
160
const settings = yield* DesktopAppSettings.DesktopAppSettings;
apps/server/src/cli/sshHelper.ts
+19
-1
@@ -6,8 +6,11 @@ import * as NodeHttp from "node:http";
6
import * as NodeNet from "node:net";
7
8
import * as Effect from "effect/Effect";
9
+import * as Option from "effect/Option";
10
import { Argument, Command } from "effect/cli";
11
12
+import * as DesktopUpdateMarker from "../desktopUpdate/DesktopUpdateMarker.ts";
13
+
14
const canBind = (port: number) =>
15
new Promise<boolean>((resolve) => {
16
const server = NodeNet.createServer();
@@ -124,7 +127,22 @@ const runtimePort = Command.make("runtime-port", {
127
),
128
);
129
130
+const updateRemaining = Command.make("update-remaining", {
131
+ markerFile: Argument.String("marker-file"),
132
+}).pipe(
133
+ Command.withHandler(({ markerFile }) =>
134
+ DesktopUpdateMarker.DesktopUpdateMarker.use((marker) => marker.remainingWait(markerFile)).pipe(
135
+ Effect.flatMap((remaining) =>
136
+ Effect.sync(() => {
137
+ process.stdout.write(Option.match(remaining, { onNone: () => "", onSome: String }));
138
+ }),
139
+ ),
140
+ ),
141
+ ),
142
+ Command.provide(DesktopUpdateMarker.layer),
143
+);
144
+
145
export const sshHelperCommand = Command.make("__ssh-helper").pipe(
146
Command.unlisted,
129
- Command.withSubcommands([pickPort, waitReady, runtimePort]),
147
+ Command.withSubcommands([pickPort, waitReady, runtimePort, updateRemaining]),
148
);
apps/server/src/desktopUpdate/DesktopUpdateMarker.test.ts
new
+57
@@ -0,0 +1,57 @@
1
+import { assert, describe, it } from "@effect/vitest";
2
+import * as Effect from "effect/Effect";
3
+import * as FileSystem from "effect/FileSystem";
4
+import * as Layer from "effect/Layer";
5
+import * as Option from "effect/Option";
6
+import * as TestClock from "effect/testing/TestClock";
7
+
8
+import * as DesktopUpdateMarker from "./DesktopUpdateMarker.ts";
9
+
10
+const remainingWait = (fileSystem: Partial<FileSystem.FileSystem>) =>
11
+ DesktopUpdateMarker.DesktopUpdateMarker.use((marker) => marker.remainingWait("/marker")).pipe(
12
+ Effect.provide(DesktopUpdateMarker.layer.pipe(Layer.provide(FileSystem.layerNoop(fileSystem)))),
13
+ );
14
+
15
+describe("DesktopUpdateMarker", () => {
16
+ it.effect.each([
17
+ ["fresh", '{"startedAt":0,"expiresAt":60000}', 0, Option.some(60000)],
18
+ ["partly elapsed", '{"startedAt":0,"expiresAt":60000}', 8000, Option.some(52000)],
19
+ ["expired", '{"startedAt":0,"expiresAt":60000}', 60000, Option.none()],
20
+ ["future", '{"startedAt":1000,"expiresAt":61000}', 0, Option.none()],
21
+ ["long host TTL", '{"startedAt":0,"expiresAt":600000}', 0, Option.some(60000)],
22
+ ["reversed", '{"startedAt":1000,"expiresAt":0}', 0, Option.none()],
23
+ ["missing fields", "{}", 0, Option.none()],
24
+ ["malformed", "not json", 0, Option.none()],
25
+ ] as const)("%s", ([name, contents, now, expected]) =>
26
+ Effect.gen(function* () {
27
+ let removed = false;
28
+ yield* TestClock.setTime(now);
29
+ const remaining = yield* remainingWait({
30
+ readFileString: () => Effect.succeed(contents),
31
+ remove: () =>
32
+ Effect.sync(() => {
33
+ removed = true;
34
+ }),
35
+ });
36
+ assert.deepStrictEqual(remaining, expected);
37
+ assert.isFalse(removed, `${name}: the launcher must never delete the shared marker`);
38
+ }),
39
+ );
40
+
41
+ it.effect("honours a marker published while it is being read", () =>
42
+ Effect.gen(function* () {
43
+ yield* TestClock.setTime(0);
44
+ const remaining = yield* remainingWait({
45
+ readFileString: () =>
46
+ TestClock.adjust(1000).pipe(Effect.as('{"startedAt":1000,"expiresAt":61000}')),
47
+ });
48
+ assert.deepStrictEqual(remaining, Option.some(60000));
49
+ }),
50
+ );
51
+
52
+ it.effect("a missing marker allows launch", () =>
53
+ Effect.gen(function* () {
54
+ assert.isTrue(Option.isNone(yield* remainingWait({})));
55
+ }),
56
+ );
57
+});
apps/server/src/desktopUpdate/DesktopUpdateMarker.ts
new
+54
@@ -0,0 +1,54 @@
1
+import { DESKTOP_UPDATE_IN_PROGRESS_TTL_MS } from "@t3tools/contracts";
2
+import * as Clock from "effect/Clock";
3
+import * as Context from "effect/Context";
4
+import * as Effect from "effect/Effect";
5
+import * as FileSystem from "effect/FileSystem";
6
+import * as Layer from "effect/Layer";
7
+import * as Option from "effect/Option";
8
+import * as Schema from "effect/Schema";
9
+
10
+const UpdateMarker = Schema.fromJsonString(
11
+ Schema.Struct({ startedAt: Schema.Number, expiresAt: Schema.Number }),
12
+);
13
+
14
+export class DesktopUpdateMarker extends Context.Service<
15
+ DesktopUpdateMarker,
16
+ {
17
+ /**
18
+ * Remaining SSH launch wait in ms, capped at this build's TTL.
19
+ * Read-only: a newer update may have just replaced the marker.
20
+ */
21
+ readonly remainingWait: (markerFile: string) => Effect.Effect<Option.Option<number>>;
22
+ }
23
+>()("t3/desktopUpdate/DesktopUpdateMarker") {}
24
+
25
+const make = Effect.gen(function* () {
26
+ const fileSystem = yield* FileSystem.FileSystem;
27
+
28
+ const remainingWait: DesktopUpdateMarker["Service"]["remainingWait"] = Effect.fn(
29
+ "DesktopUpdateMarker.remainingWait",
30
+ )(function* (markerFile) {
31
+ const marker = yield* fileSystem
32
+ .readFileString(markerFile)
33
+ .pipe(Effect.flatMap(Schema.decodeUnknownEffect(UpdateMarker)), Effect.option);
34
+ // Sampled after the read so a marker published mid-read is not seen as future-dated.
35
+ const now = yield* Clock.currentTimeMillis;
36
+ if (Option.isSome(marker)) {
37
+ const { startedAt, expiresAt } = marker.value;
38
+ if (
39
+ Number.isFinite(startedAt) &&
40
+ Number.isFinite(expiresAt) &&
41
+ startedAt <= now &&
42
+ expiresAt > now &&
43
+ expiresAt > startedAt
44
+ ) {
45
+ return Option.some(Math.min(expiresAt - now, DESKTOP_UPDATE_IN_PROGRESS_TTL_MS));
46
+ }
47
+ }
48
+ return Option.none();
49
+ });
50
+
51
+ return DesktopUpdateMarker.of({ remainingWait });
52
+});
53
+
54
+export const layer = Layer.effect(DesktopUpdateMarker, make);
packages/contracts/src/desktopBootstrap.ts
+3
@@ -37,3 +37,6 @@ export type DesktopBackendBootstrap = typeof DesktopBackendBootstrap.Type;
37
38
/** Written to `<t3Home>/runtime` before update shutdown so the backend retains its managed tunnel. */
39
export const DESKTOP_UPDATE_RESTART_MARKER_FILE = "desktop-update-restart";
40
+
41
+export const DESKTOP_UPDATE_IN_PROGRESS_MARKER_FILE = "desktop-update-in-progress";
42
+export const DESKTOP_UPDATE_IN_PROGRESS_TTL_MS = 60_000;
packages/ssh/src/launcherTestHarness.ts
new
+233
@@ -0,0 +1,233 @@
1
+// @effect-diagnostics nodeBuiltinImport:off - Executes the generated remote launcher in an isolated shell with fake commands and clock.
2
+import * as NodeFS from "node:fs";
3
+import * as NodePath from "node:path";
4
+import * as NodeURL from "node:url";
5
+import * as NodeChildProcess from "node:child_process";
6
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
7
+import * as NodeServices from "@effect/platform-node/NodeServices";
8
+import * as Effect from "effect/Effect";
9
+import * as Layer from "effect/Layer";
10
+import * as Sink from "effect/Sink";
11
+import * as Stream from "effect/Stream";
12
+import { ChildProcessSpawner } from "effect/process";
13
+import { launchOrReuseRemoteServer, type RemoteT3RunnerOptions } from "./tunnel.ts";
14
+
15
+// Capture exactly the script sent over SSH, then run it with fake remote commands.
16
+export const captureLauncherFor = Effect.fn("test.captureLauncher")(function* (
17
+ runner: RemoteT3RunnerOptions,
18
+) {
19
+ let script = "";
20
+ const spawner = ChildProcessSpawner.make((command) =>
21
+ Effect.gen(function* () {
22
+ if (command._tag === "StandardCommand") {
23
+ const stdin = command.options.stdin;
24
+ if (typeof stdin === "object" && "stream" in stdin && Stream.isStream(stdin.stream)) {
25
+ script = yield* stdin.stream.pipe(Stream.decodeText(), Stream.mkString);
26
+ }
27
+ }
28
+ return ChildProcessSpawner.makeHandle({
29
+ pid: ChildProcessSpawner.ProcessId(123),
30
+ stdout: Stream.make(new TextEncoder().encode('{"remotePort":3773}\n')),
31
+ stderr: Stream.empty,
32
+ all: Stream.empty,
33
+ exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
34
+ isRunning: Effect.succeed(false),
35
+ kill: () => Effect.void,
36
+ stdin: Sink.drain,
37
+ getInputFd: () => Sink.drain,
38
+ getOutputFd: () => Stream.empty,
39
+ unref: Effect.succeed(Effect.void),
40
+ });
41
+ }),
42
+ );
43
+ yield* launchOrReuseRemoteServer(
44
+ { alias: "test", hostname: "test.invalid", username: null, port: null },
45
+ undefined,
46
+ runner,
47
+ ).pipe(
48
+ Effect.provide(
49
+ Layer.mergeAll(
50
+ NodeServices.layer,
51
+ NodeCrypto.layer,
52
+ Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner),
53
+ ),
54
+ ),
55
+ );
56
+ return script;
57
+});
58
+
59
+export const captureLauncher = captureLauncherFor({ nodeScriptPath: "/fake/server.ts" });
60
+
61
+export function runLauncher(
62
+ script: string,
63
+ options: {
64
+ readonly marker?: unknown;
65
+ readonly archive?: boolean;
66
+ readonly clearMarkerOnReady?: boolean;
67
+ readonly recordedKind?: "managed" | "external";
68
+ readonly clockJump?: number;
69
+ readonly readyAt?: number;
70
+ readonly initialPort?: number;
71
+ // The desktop publishes runtime and removes the marker right after the first runtime read.
72
+ readonly publishAfterFirstRuntimeRead?: boolean;
73
+ },
74
+) {
75
+ const root = NodeURL.fileURLToPath(new URL("../../../", import.meta.url));
76
+ const home = NodeFS.mkdtempSync(NodePath.join(root, "packages/ssh/.ssh-launcher-test-"));
77
+ try {
78
+ const bin = NodePath.join(home, "bin");
79
+ const runtime = NodePath.join(home, ".t3/runtime");
80
+ NodeFS.mkdirSync(bin);
81
+ NodeFS.mkdirSync(runtime, { recursive: true });
82
+ const markerPath = NodePath.join(runtime, "desktop-update-in-progress");
83
+ if (options.marker)
84
+ NodeFS.writeFileSync(
85
+ markerPath,
86
+ typeof options.marker === "string" ? options.marker : JSON.stringify(options.marker),
87
+ );
88
+ NodeFS.writeFileSync(NodePath.join(home, "clock"), "0");
89
+ NodeFS.writeFileSync(NodePath.join(home, "events"), "");
90
+ const executable = (name: string, body: string) =>
91
+ NodeFS.writeFileSync(NodePath.join(bin, name), `#!/bin/sh\nset -eu\n${body}\n`, {
92
+ mode: 0o755,
93
+ });
94
+ NodeFS.writeFileSync(
95
+ NodePath.join(home, "clock.cjs"),
96
+ `
97
+const fs = require('node:fs');
98
+Date.now = () => Number(fs.readFileSync(process.env.HOME + '/clock', 'utf8'));
99
+`,
100
+ );
101
+ executable(
102
+ options.archive ? "test-node" : "node",
103
+ `
104
+case "\${2:-}" in
105
+ */server-runtime.json)
106
+ # A started server publishes its runtime record, which the launch waits for.
107
+ if [ -e "$HOME/started-server" ]; then
108
+ printf 'record %s\\n' "$(cat "$HOME/clock")" >> "$HOME/events"
109
+ printf '%s 5999' "$(cat "$HOME/started-server")"
110
+ exit 0
111
+ fi
112
+ NOW="$(cat "$HOME/clock")"
113
+ printf 'runtime %s\\n' "$NOW" >> "$HOME/events"
114
+ if [ "$NOW" -ge "$TEST_READY_AT" ] || [ -e "$2" ]; then printf '%s %s' "$TEST_SERVER_PID" 4888
115
+ elif [ "$TEST_PUBLISH_AFTER_FIRST_READ" = 1 ]; then
116
+ mkdir -p "\${2%/*}"
117
+ printf '{}' > "$2"
118
+ rm -f "$HOME/.t3/runtime/desktop-update-in-progress"
119
+ exit 1
120
+ elif [ -n "$TEST_INITIAL_PORT" ]; then printf '%s %s' "$TEST_SERVER_PID" "$TEST_INITIAL_PORT"
121
+ else exit 1; fi ;;
122
+ */port)
123
+ printf 'start %s\\n' "$(cat "$HOME/clock")" >> "$HOME/events"
124
+ printf 5999 ;;
125
+ [0-9]*)
126
+ NOW="$(cat "$HOME/clock")"
127
+ printf 'probe %s %s\\n' "$2" "$NOW" >> "$HOME/events"
128
+ [ "$2" = 5999 ] || { [ "$2" = 4888 ] && { [ "$NOW" -ge "$TEST_READY_AT" ] || [ -e "$HOME/.t3/userdata/server-runtime.json" ]; }; } ;;
129
+ */desktop-update-in-progress)
130
+ printf 'marker %s\\n' "$(cat "$HOME/clock")" >> "$HOME/events"
131
+ exec "$TEST_REAL_NODE" --require "$HOME/clock.cjs" "$@" ;;
132
+ *) exec "$TEST_REAL_NODE" --require "$HOME/clock.cjs" "$@" ;;
133
+esac`,
134
+ );
135
+ executable(
136
+ "sleep",
137
+ `awk -v seconds="$1" '{ printf "%.0f", $1 + seconds * 1000 }' "$HOME/clock" > "$HOME/clock.next"
138
+mv "$HOME/clock.next" "$HOME/clock"
139
+if [ "$TEST_CLEAR_MARKER" = 1 ] && [ "$(cat "$HOME/clock")" -ge "$TEST_READY_AT" ]; then
140
+ rm -f "$HOME/.t3/runtime/desktop-update-in-progress"
141
+fi
142
+if [ -n "$TEST_CLOCK_JUMP" ] && [ ! -e "$HOME/jumped" ]; then
143
+ printf '%s' "$TEST_CLOCK_JUMP" > "$HOME/clock"
144
+ touch "$HOME/jumped"
145
+fi`,
146
+ );
147
+ executable("nohup", 'printf "%s" "$$" > "$HOME/started-server"');
148
+ // The test process stands in for a recorded server; report the serve command it would run.
149
+ executable(
150
+ "ps",
151
+ `if [ "$*" = "-ww -o args= -p $TEST_SERVER_PID" ]; then
152
+ printf '/bin/sh %s/.t3/ssh-launch/test-target/run-t3.sh serve --host 127.0.0.1 --port 5999\\n' "$HOME"
153
+ exit 0
154
+fi
155
+PATH=/usr/bin:/bin exec ps "$@"`,
156
+ );
157
+ if (options.recordedKind) {
158
+ const state = NodePath.join(home, ".t3/ssh-launch/test-target");
159
+ NodeFS.mkdirSync(state, { recursive: true });
160
+ NodeFS.writeFileSync(NodePath.join(state, "pid"), String(process.pid));
161
+ NodeFS.writeFileSync(NodePath.join(state, "port"), "5999");
162
+ NodeFS.writeFileSync(NodePath.join(state, "managed"), options.recordedKind);
163
+ const runner = script.split("cat >\"$RUNNER_NEXT\" <<'SH'\n")[1]?.split("\nSH\n")[0];
164
+ if (!runner) throw new Error("runner missing");
165
+ NodeFS.writeFileSync(NodePath.join(state, "run-t3.sh"), runner + "\n");
166
+ }
167
+ if (options.archive) {
168
+ executable("node", 'printf "unexpected host node invocation\\n" >&2; exit 1');
169
+ const version = NodePath.join(home, ".t3/runtime/versions/1.2.3");
170
+ NodeFS.mkdirSync(version, { recursive: true });
171
+ NodeFS.writeFileSync(NodePath.join(version, ".install-complete"), "1.2.3");
172
+ NodeFS.writeFileSync(
173
+ NodePath.join(home, "helper.ts"),
174
+ `
175
+import * as Effect from "effect/Effect";
176
+import * as NodeServices from "@effect/platform-node/NodeServices";
177
+import { Command } from "effect/cli";
178
+import { sshHelperCommand } from ${JSON.stringify(NodePath.join(root, "apps/server/src/cli/sshHelper.ts"))};
179
+await Effect.runPromise(Command.runWith(sshHelperCommand, { version: "1.2.3" })(process.argv.slice(2)).pipe(Effect.provide(NodeServices.layer)));
180
+`,
181
+ );
182
+ NodeFS.writeFileSync(
183
+ NodePath.join(version, "t3"),
184
+ `#!/bin/sh
185
+set -eu
186
+if [ "$1" = --version ]; then printf 1.2.3; exit; fi
187
+[ "$1" = __ssh-helper ]
188
+case "$2" in
189
+ update-remaining) printf 'marker %s\\n' "$(cat "$HOME/clock")" >> "$HOME/events"; exec "$TEST_REAL_NODE" --require "$HOME/clock.cjs" "$HOME/helper.ts" "$2" "$3" ;;
190
+ runtime-port | pick-port | wait-ready) exec "$HOME/bin/test-node" - "$3" ;;
191
+ *) exit 1 ;;
192
+esac
193
+`,
194
+ { mode: 0o755 },
195
+ );
196
+ }
197
+ const result = NodeChildProcess.spawnSync("/bin/sh", ["-s", "--", "test-target"], {
198
+ input: `kill() {
199
+ if [ "$1" = -0 ]; then command kill "$@"; else
200
+ printf 'kill %s\\n' "$*" >> "$HOME/events"
201
+ return 1
202
+ fi
203
+}
204
+${script}`,
205
+ encoding: "utf8",
206
+ timeout: 30_000,
207
+ env: {
208
+ ...process.env,
209
+ HOME: home,
210
+ PATH: `${bin}:/usr/bin:/bin`,
211
+ TEST_REAL_NODE: process.execPath,
212
+ TEST_CLEAR_MARKER: options.clearMarkerOnReady ? "1" : "0",
213
+ TEST_CLOCK_JUMP: options.clockJump === undefined ? "" : String(options.clockJump),
214
+ TEST_SERVER_PID: String(process.pid),
215
+ TEST_READY_AT: String(options.readyAt ?? 1_000_000),
216
+ TEST_INITIAL_PORT: options.initialPort === undefined ? "" : String(options.initialPort),
217
+ TEST_PUBLISH_AFTER_FIRST_READ: options.publishAfterFirstRuntimeRead ? "1" : "0",
218
+ },
219
+ });
220
+ if (result.error || result.status !== 0)
221
+ throw new Error(
222
+ `launcher failed: ${result.error ?? result.status}\n${result.stderr}\n${result.stdout}\n${NodeFS.readFileSync(NodePath.join(home, "events"), "utf8")}`,
223
+ );
224
+ return {
225
+ output: JSON.parse(result.stdout.trim()),
226
+ events: NodeFS.readFileSync(NodePath.join(home, "events"), "utf8").trim().split("\n"),
227
+ now: Number(NodeFS.readFileSync(NodePath.join(home, "clock"), "utf8")),
228
+ markerExists: NodeFS.existsSync(markerPath),
229
+ };
230
+ } finally {
231
+ NodeFS.rmSync(home, { recursive: true, force: true });
232
+ }
233
+}
packages/ssh/src/tunnel.test.ts
+133
@@ -27,6 +27,7 @@ import { TestClock } from "effect/testing";
27
import { HttpClient, HttpClientError, HttpClientResponse } from "effect/http";
28
import { ChildProcess, ChildProcessSpawner } from "effect/process";
29
30
+import { captureLauncher, captureLauncherFor, runLauncher } from "./launcherTestHarness.ts";
31
import * as SshAuth from "./auth.ts";
32
import { remoteStateKey } from "./command.ts";
33
import { SshCommandError, SshPasswordPromptError, SshReadinessError } from "./errors.ts";
@@ -1242,3 +1243,135 @@ server.listen(Number(flag("--port") ?? 0), "127.0.0.1", () => {
1243
// desktop app with network access on) listens on *:<port>. Linux refuses that
1244
// bind unless both sockets set SO_REUSEPORT, so on Linux the preload adds it to
1245
// the picker's probe and the holder sets it too.
1246
+
1247
+describe("SSH launch during desktop update", () => {
1248
+ it.effect("archive launcher reuses the replacement without host Node", () =>
1249
+ Effect.gen(function* () {
1250
+ const script = yield* captureLauncherFor({ archiveVersion: "1.2.3" });
1251
+ const result = runLauncher(script, {
1252
+ archive: true,
1253
+ marker: { startedAt: 0, expiresAt: 60_000 },
1254
+ readyAt: 2_000,
1255
+ });
1256
+ assert.deepEqual(result.output, { remotePort: 4888, serverKind: "external" });
1257
+ assert.equal(result.now, 2_000);
1258
+ assert.isFalse(result.events.some((event) => event.startsWith("start ")));
1259
+ }),
1260
+ );
1261
+
1262
+ it.effect.each(["managed", "external"] as const)(
1263
+ "reuses recorded %s server without runtime metadata or an update wait",
1264
+ (recordedKind) =>
1265
+ Effect.gen(function* () {
1266
+ const result = runLauncher(yield* captureLauncher, {
1267
+ marker: { startedAt: 0, expiresAt: 60_000 },
1268
+ recordedKind,
1269
+ });
1270
+ assert.deepEqual(result.output, { remotePort: 5999, serverKind: recordedKind });
1271
+ assert.equal(result.now, 0);
1272
+ assert.isFalse(result.events.some((event) => event.startsWith("kill ")));
1273
+ assert.isFalse(result.events.some((event) => event.startsWith("start ")));
1274
+ }),
1275
+ );
1276
+
1277
+ it.effect.each([
1278
+ ["malformed", "broken"],
1279
+ ["future", { startedAt: 1_000, expiresAt: 61_000 }],
1280
+ ["expired", { startedAt: -60_000, expiresAt: 0 }],
1281
+ ] as const)("preserves %s markers without waiting", ([, marker]) =>
1282
+ Effect.gen(function* () {
1283
+ const result = runLauncher(yield* captureLauncher, { marker });
1284
+ assert.equal(result.now, 0);
1285
+ assert.isTrue(result.markerExists);
1286
+ assert.deepEqual(result.output, { remotePort: 5999, serverKind: "managed" });
1287
+ }),
1288
+ );
1289
+
1290
+ it.effect("bounds the wait when the host clock jumps back", () =>
1291
+ Effect.gen(function* () {
1292
+ const result = runLauncher(yield* captureLauncher, {
1293
+ marker: { startedAt: 0, expiresAt: 60_000 },
1294
+ clockJump: -30_000,
1295
+ });
1296
+ assert.deepEqual(result.output, { remotePort: 5999, serverKind: "managed" });
1297
+ assert.isBelow(result.events.filter((event) => event.startsWith("runtime ")).length, 62);
1298
+ }),
1299
+ );
1300
+
1301
+ it.effect("refreshes runtime after readiness removes the marker between polls", () =>
1302
+ Effect.gen(function* () {
1303
+ const result = runLauncher(yield* captureLauncher, {
1304
+ marker: { startedAt: 0, expiresAt: 60_000 },
1305
+ readyAt: 8_000,
1306
+ clearMarkerOnReady: true,
1307
+ });
1308
+ assert.deepEqual(result.output, { remotePort: 4888, serverKind: "external" });
1309
+ assert.equal(result.now, 8_000);
1310
+ assert.isFalse(result.markerExists);
1311
+ assert.isFalse(result.events.some((event) => event.startsWith("start ")));
1312
+ assert.isFalse(result.events.some((event) => event.startsWith("kill ")));
1313
+ }),
1314
+ );
1315
+
1316
+ it.effect("reuses a runtime published before the first marker read", () =>
1317
+ Effect.gen(function* () {
1318
+ const result = runLauncher(yield* captureLauncher, {
1319
+ marker: { startedAt: 0, expiresAt: 60_000 },
1320
+ publishAfterFirstRuntimeRead: true,
1321
+ });
1322
+ assert.deepEqual(result.output, { remotePort: 4888, serverKind: "external" });
1323
+ assert.equal(result.now, 0);
1324
+ assert.isFalse(result.events.some((event) => event.startsWith("start ")));
1325
+ }),
1326
+ );
1327
+
1328
+ it.effect("waits across the eight-second installer gap and reuses the replacement server", () =>
1329
+ Effect.gen(function* () {
1330
+ const result = runLauncher(yield* captureLauncher, {
1331
+ marker: { startedAt: 0, expiresAt: 60_000 },
1332
+ readyAt: 8_000,
1333
+ });
1334
+ assert.deepEqual(result.output, { remotePort: 4888, serverKind: "external" });
1335
+ assert.equal(result.now, 8_000);
1336
+ assert.isFalse(result.events.some((event) => event.startsWith("start ")));
1337
+ assert.isAtLeast(result.events.filter((event) => event.startsWith("runtime ")).length, 2);
1338
+ }),
1339
+ );
1340
+
1341
+ it.effect("keeps waiting while a stale runtime record points at a dead port", () =>
1342
+ Effect.gen(function* () {
1343
+ const result = runLauncher(yield* captureLauncher, {
1344
+ marker: { startedAt: 0, expiresAt: 60_000 },
1345
+ initialPort: 3773,
1346
+ readyAt: 3_000,
1347
+ });
1348
+ assert.deepEqual(result.output, { remotePort: 4888, serverKind: "external" });
1349
+ assert.equal(result.now, 3_000);
1350
+ assert.isFalse(result.events.some((event) => event.startsWith("start ")));
1351
+ }),
1352
+ );
1353
+
1354
+ it.effect("starts a server when the marker expires without a replacement becoming ready", () =>
1355
+ Effect.gen(function* () {
1356
+ const result = runLauncher(yield* captureLauncher, {
1357
+ marker: { startedAt: 0, expiresAt: 60_000 },
1358
+ });
1359
+ assert.deepEqual(result.output, { remotePort: 5999, serverKind: "managed" });
1360
+ assert.isAtLeast(result.now, 60_000);
1361
+ assert.isAtMost(result.now, 61_000);
1362
+ assert.isTrue(result.markerExists, "an expired marker is ignored, not deleted");
1363
+ assert.equal(result.events.filter((event) => event.startsWith("start ")).length, 1);
1364
+ }),
1365
+ );
1366
+
1367
+ it.effect("starts immediately without a marker", () =>
1368
+ Effect.gen(function* () {
1369
+ const result = runLauncher(yield* captureLauncher, {});
1370
+ assert.deepEqual(result.output, { remotePort: 5999, serverKind: "managed" });
1371
+ assert.equal(result.now, 0);
1372
+ assert.equal(result.events.filter((event) => event.startsWith("start ")).length, 1);
1373
+ assert.equal(result.events.filter((event) => event.startsWith("marker ")).length, 1);
1374
+ assert.equal(result.events.filter((event) => event.startsWith("runtime ")).length, 1);
1375
+ }),
1376
+ );
1377
+});
packages/ssh/src/tunnel.ts
+67
-4
@@ -1,3 +1,7 @@
1
+import {
2
+ DESKTOP_UPDATE_IN_PROGRESS_MARKER_FILE,
3
+ DESKTOP_UPDATE_IN_PROGRESS_TTL_MS,
4
+} from "@t3tools/contracts";
5
import type {
6
DesktopSshEnvironmentBootstrap,
7
DesktopSshEnvironmentTarget,
@@ -72,19 +76,26 @@ const REMOTE_PID_EXIT_WAIT_MS = 2_000;
76
// The server answers HTTP before it writes server-runtime.json, which is how
77
// a launch for another alias finds it.
78
const REMOTE_RUNTIME_RECORD_WAIT_SECONDS = 10;
79
+// The desktop update wait runs under the home lock. Its last poll and the
80
+// adoption after it each add a reuse probe, and the poll adds one sleep.
81
+const REMOTE_UPDATE_WAIT_MS =
82
+ DESKTOP_UPDATE_IN_PROGRESS_TTL_MS +
83
+ 2 * (REMOTE_REUSE_READY_TIMEOUT_MS + SSH_READY_PROBE_TIMEOUT_MS) +
84
+ 1_000;
85
// A launch holds the home lock through up to two reuse probes, readiness, two
76
-// server exit waits, and the runtime record wait; each probe may overrun its
77
-// deadline by one request.
86
+// server exit waits, the runtime record wait, and the update wait; each probe
87
+// may overrun its deadline by one request.
88
const REMOTE_LAUNCH_LOCK_WAIT_SECONDS = Math.ceil(
89
(REMOTE_READY_TIMEOUT_MS +
90
2 * REMOTE_REUSE_READY_TIMEOUT_MS +
91
2 * REMOTE_PID_EXIT_WAIT_MS +
92
REMOTE_RUNTIME_RECORD_WAIT_SECONDS * 1000 +
83
- 4 * SSH_READY_PROBE_TIMEOUT_MS) /
93
+ 4 * SSH_READY_PROBE_TIMEOUT_MS +
94
+ REMOTE_UPDATE_WAIT_MS) /
95
1000,
96
);
97
const REMOTE_LAUNCH_TIMEOUT_MS =
87
- REMOTE_LAUNCH_LOCK_WAIT_SECONDS * 1000 + REMOTE_LAUNCH_BASE_TIMEOUT_MS;
98
+ REMOTE_LAUNCH_LOCK_WAIT_SECONDS * 1000 + REMOTE_UPDATE_WAIT_MS + REMOTE_LAUNCH_BASE_TIMEOUT_MS;
99
100
export interface RemoteT3RunnerOptions {
101
readonly nodeScriptPath?: string | null;
@@ -717,9 +728,29 @@ try {
728
}
729
NODE
730
}
731
+# This script ships with the SSH client; older clients do not honor this marker.
732
+update_remaining() {
733
+ if [ "$T3_ARCHIVE_MODE" = "1" ]; then
734
+ "$RUNNER_FILE" __ssh-helper update-remaining "$DEFAULT_SERVER_HOME/runtime/@@T3_UPDATE_MARKER_FILE@@"
735
+ return
736
+ fi
737
+ node - "$DEFAULT_SERVER_HOME/runtime/@@T3_UPDATE_MARKER_FILE@@" <<'NODE'
738
+const fs = require("node:fs");
739
+const path = process.argv[2];
740
+try {
741
+ const { startedAt, expiresAt } = JSON.parse(fs.readFileSync(path, "utf8"));
742
+ const now = Date.now();
743
+ if (Number.isFinite(startedAt) && Number.isFinite(expiresAt) &&
744
+ startedAt <= now && expiresAt > now && expiresAt > startedAt) {
745
+ process.stdout.write(String(Math.min(expiresAt - now, @@T3_UPDATE_TTL_MS@@)));
746
+ }
747
+} catch {}
748
+NODE
749
+}
750
REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
751
REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
752
REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
753
+adopt_default_server() {
754
DEFAULT_RUNTIME_INFO="$(resolve_default_runtime_port 2>/dev/null || true)"
755
DEFAULT_RUNTIME_PID=""
756
DEFAULT_REMOTE_PORT=""
@@ -734,6 +765,7 @@ fi
765
if [ -n "$DEFAULT_REMOTE_PORT" ] && [ "$REMOTE_MANAGED" = "managed" ] && [ "$DEFAULT_RUNTIME_PID" = "$REMOTE_PID" ]; then
766
REMOTE_PORT="$DEFAULT_REMOTE_PORT"
767
printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
768
+ return 0
769
elif [ -n "$DEFAULT_REMOTE_PORT" ]; then
770
REMOTE_PORT="$DEFAULT_REMOTE_PORT"
771
if wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
@@ -755,12 +787,16 @@ elif [ -n "$DEFAULT_REMOTE_PORT" ]; then
787
REMOTE_PID=""
788
REMOTE_MANAGED="external"
789
fi
790
+ return 0
791
else
792
REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
793
REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
794
REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
795
fi
796
fi
797
+return 1
798
+}
799
+adopt_default_server || true
800
if [ "$REMOTE_MANAGED" = "external" ]; then
801
# A server adopted above has just answered. While it is still alive, probing
802
# it again could catch a momentary stall and launch a second server beside it.
@@ -808,6 +844,30 @@ if [ -z "$REMOTE_PORT" ] && [ -z "$DEFAULT_RUNTIME_INFO" ]; then
844
break
845
done
846
fi
847
+if [ -z "$REMOTE_PORT" ]; then
848
+ # The sleep count bounds a host clock that stops advancing.
849
+ UPDATE_WAITED=0
850
+ UPDATE_SAW_MARKER=0
851
+ while [ "$UPDATE_WAITED" -le @@T3_UPDATE_TTL_SECONDS@@ ]; do
852
+ UPDATE_REMAINING="$(update_remaining 2>/dev/null || true)"
853
+ [ -n "$UPDATE_REMAINING" ] || break
854
+ UPDATE_SAW_MARKER=1
855
+ [ "$UPDATE_WAITED" -lt @@T3_UPDATE_TTL_SECONDS@@ ] || break
856
+ if adopt_default_server; then break; fi
857
+ REMOTE_PID=""
858
+ REMOTE_PORT=""
859
+ REMOTE_MANAGED=""
860
+ sleep 1
861
+ UPDATE_WAITED=$((UPDATE_WAITED + 1))
862
+ done
863
+ # The desktop clears the marker after publishing runtime, possibly before the first marker read,
864
+ # so refresh once more before falling back. A cleanly stopped server leaves no runtime file.
865
+ if { [ "$UPDATE_SAW_MARKER" -eq 1 ] || [ -f "$DEFAULT_RUNTIME_FILE" ]; } && [ -z "$REMOTE_PORT" ] && ! adopt_default_server; then
866
+ REMOTE_PID=""
867
+ REMOTE_PORT=""
868
+ REMOTE_MANAGED=""
869
+ fi
870
+fi
871
if [ -z "$REMOTE_PORT" ]; then
872
REMOTE_PORT="$(pick_port)" || true
873
if [ -z "$REMOTE_PORT" ]; then
@@ -953,6 +1013,9 @@ export function buildRemoteNodeEnvScript(input?: RemoteT3RunnerOptions): string
1013
1014
function buildRemoteLaunchScript(input?: RemoteT3RunnerOptions): string {
1015
return applyScriptPlaceholders(REMOTE_LAUNCH_SCRIPT, {
1016
+ T3_UPDATE_MARKER_FILE: DESKTOP_UPDATE_IN_PROGRESS_MARKER_FILE,
1017
+ T3_UPDATE_TTL_MS: String(DESKTOP_UPDATE_IN_PROGRESS_TTL_MS),
1018
+ T3_UPDATE_TTL_SECONDS: String(DESKTOP_UPDATE_IN_PROGRESS_TTL_MS / 1000),
1019
T3_ARCHIVE_MODE: isNodeScriptRunner(input) ? "0" : "1",
1020
T3_NODE_ENV_SCRIPT: buildRemoteNodeEnvScript(input),
1021
T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),