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

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

fix(desktop): a policy that stops startup no longer points at another release (#30319)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Julius Marminge committed Nov 3, 2026 at 11:46 UTC dd24b375f0c94cdeb76d1774ab5022aff2e1406e
6 files changed +107 -56
apps/desktop/src/app/DesktopStartupRecovery.test.ts
+14
@@ -74,6 +74,19 @@ describe("resolveStartupRecoveryOffer", () => {
74 ).toEqual({ _tag: "Reinstall", version: "0.1.2" });
75 });
76
77 + it("blames the managed policy unless a newer version can read it", () => {
78 + expect(
79 + resolveStartupRecoveryOffer(
80 + updateState({ status: "available", availableVersion: "0.1.4" }),
81 + "0.1.2",
82 + true,
83 + ),
84 + ).toEqual({ _tag: "Update", version: "0.1.4" });
85 + expect(
86 + resolveStartupRecoveryOffer(updateState({ status: "up-to-date" }), "0.1.2", true),
87 + ).toEqual({ _tag: "ManagedPolicy" });
88 + });
89 +
90 it("falls back to the releases page when this version never started", () => {
91 expect(resolveStartupRecoveryOffer(updateState({ status: "disabled" }), "0.1.3")).toEqual({
92 _tag: "Releases",
@@ -168,6 +181,7 @@ it.effect.each([
181 yield* SubscriptionRef.set(state.primaryBackendStartup, {
182 _tag: "Failing",
183 reason: "Server failed before readiness",
184 + managedPolicy: false,
185 output: "Failure details",
186 });
187 yield* Deferred.await(checked);
apps/desktop/src/app/DesktopStartupRecovery.ts
+20 -4
@@ -32,7 +32,8 @@ export type StartupRecoveryOffer =
32 | { readonly _tag: "Update"; readonly version: string }
33 | { readonly _tag: "Downloading"; readonly version: string; readonly percent: number | null }
34 | { readonly _tag: "Reinstall"; readonly version: string }
35 - | { readonly _tag: "Releases" };
35 + | { readonly _tag: "Releases" }
36 + | { readonly _tag: "ManagedPolicy" };
37
38 const STARTUP_RECOVERY_ACTIONS = ["update", "reinstall", "releases", "copy", "quit"] as const;
39 type StartupRecoveryAction = (typeof STARTUP_RECOVERY_ACTIONS)[number];
@@ -41,6 +42,7 @@ type StartupRecoveryAction = (typeof STARTUP_RECOVERY_ACTIONS)[number];
42 export function resolveStartupRecoveryOffer(
43 update: DesktopUpdateState,
44 lastStartedVersion: string | null,
45 + managedPolicy = false,
46 ): StartupRecoveryOffer {
47 if (update.status === "downloading" && update.availableVersion !== null) {
48 return {
@@ -55,6 +57,8 @@ export function resolveStartupRecoveryOffer(
57 if (updateVersion !== null && updateVersion !== update.notAppliedVersion) {
58 return { _tag: "Update", version: updateVersion };
59 }
60 + // A newer release can know a key this one refuses; an older one or the releases page cannot help.
61 + if (managedPolicy) return { _tag: "ManagedPolicy" };
62 if (update.enabled && (update.status === "idle" || update.status === "checking")) {
63 return { _tag: "Checking" };
64 }
@@ -98,6 +102,11 @@ function describeOffer(offer: StartupRecoveryOffer): { text: string; action: str
102 text: "Get a different version from the releases page.",
103 action: actionLink("releases", "Open releases", true),
104 };
105 + case "ManagedPolicy":
106 + return {
107 + text: "Your organization's managed policy stopped T3 Code from starting. Send the details below to your IT administrator.",
108 + action: "",
109 + };
110 }
111 }
112
@@ -171,8 +180,14 @@ export const listen: Effect.Effect<
180 const { latest, changes: updateChanges } = yield* updates.subscribe;
181 const updateStateRef = yield* Ref.make(latest);
182
174 - const offer = Ref.get(updateStateRef).pipe(
175 - Effect.map((state) => resolveStartupRecoveryOffer(state, lastStartedVersion)),
183 + const offer = Effect.all([Ref.get(updateStateRef), Ref.get(failureRef)]).pipe(
184 + Effect.map(([state, failure]) =>
185 + resolveStartupRecoveryOffer(
186 + state,
187 + lastStartedVersion,
188 + Option.exists(failure, ({ managedPolicy }) => managedPolicy),
189 + ),
190 + ),
191 );
192
193 const render = Effect.gen(function* () {
@@ -332,7 +347,8 @@ export const listen: Effect.Effect<
347 }
348 if (startup._tag !== "Failing") return;
349 if (Option.isSome(yield* Ref.get(failureRef))) return;
335 - yield* Ref.set(failureRef, Option.some({ reason: startup.reason, output: startup.output }));
350 + const { _tag, ...failure } = startup;
351 + yield* Ref.set(failureRef, Option.some(failure));
352 // The backend manager already logs each failure's reason.
353 yield* logWarning("primary backend failing to start");
354 yield* show();
apps/desktop/src/backend/DesktopBackendManager.test.ts
+54 -46
@@ -1,4 +1,5 @@
1 import {
2 + SERVER_EXIT_CODE_MANAGED_POLICY,
3 SERVER_EXIT_CODE_STATE_DIR_OWNED,
4 DesktopBackendBootstrap,
5 type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
@@ -623,56 +624,63 @@ describe("DesktopBackendManager", () => {
624 ),
625 );
626
626 - it.effect("reports a crash loop with the server output on the third restart", () =>
627 - Effect.scoped(
628 - Effect.gen(function* () {
629 - const message = "Error: Cannot find module 'zod/v4' in /Users/René";
630 - let exitCount = 0;
631 - const firstExit = yield* Deferred.make<void>();
632 - const reports = yield* Queue.unbounded<{
633 - readonly exitCount: number;
634 - readonly failure: DesktopBackendManager.BackendStartupFailure;
635 - }>();
636 - const instance = yield* makeTestInstance({
637 - spawnerLayer: Layer.succeed(
638 - ChildProcessSpawner.ChildProcessSpawner,
639 - ChildProcessSpawner.make(() =>
640 - Effect.succeed(
641 - makeProcess({
642 - // "é" split across chunks must not decode as U+FFFD, and the 4,000-char cut
643 - // lands inside the emoji's surrogate pair.
644 - stderr: Stream.make(
645 - new TextEncoder().encode(
646 - `😀${"x".repeat(3_999 - message.length)}${message.slice(0, -1)}`,
627 + // A policy refusal is reported on the first exit, since retrying cannot fix it.
628 + it.effect.each([
629 + { code: 1, exits: 3, managedPolicy: false },
630 + { code: SERVER_EXIT_CODE_MANAGED_POLICY, exits: 1, managedPolicy: true },
631 + ])(
632 + "reports exit $code with the server output after $exits exits",
633 + ({ code, exits, managedPolicy }) =>
634 + Effect.scoped(
635 + Effect.gen(function* () {
636 + const message = "Error: Cannot find module 'zod/v4' in /Users/René";
637 + let exitCount = 0;
638 + const firstExit = yield* Deferred.make<void>();
639 + const reports = yield* Queue.unbounded<{
640 + readonly exitCount: number;
641 + readonly failure: DesktopBackendManager.BackendStartupFailure;
642 + }>();
643 + const instance = yield* makeTestInstance({
644 + spawnerLayer: Layer.succeed(
645 + ChildProcessSpawner.ChildProcessSpawner,
646 + ChildProcessSpawner.make(() =>
647 + Effect.succeed(
648 + makeProcess({
649 + // "é" split across chunks must not decode as U+FFFD, and the 4,000-char cut
650 + // lands inside the emoji's surrogate pair.
651 + stderr: Stream.make(
652 + new TextEncoder().encode(
653 + `😀${"x".repeat(3_999 - message.length)}${message.slice(0, -1)}`,
654 + ),
655 + new Uint8Array([0xc3]),
656 + new Uint8Array([0xa9]),
657 ),
648 - new Uint8Array([0xc3]),
649 - new Uint8Array([0xa9]),
650 - ),
651 - exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(1)),
652 - }),
658 + exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(code)),
659 + }),
660 + ),
661 ),
662 ),
655 - ),
656 - httpClientLayer: layerHttpClient(() => Effect.never),
657 - backendOutputLog: {
658 - persistFailure: () => {
659 - exitCount += 1;
660 - return Deferred.succeed(firstExit, undefined).pipe(Effect.asVoid);
663 + httpClientLayer: layerHttpClient(() => Effect.never),
664 + backendOutputLog: {
665 + persistFailure: () => {
666 + exitCount += 1;
667 + return Deferred.succeed(firstExit, undefined).pipe(Effect.asVoid);
668 + },
669 },
662 - },
663 - onStartupFailure: (failure) =>
664 - Queue.offer(reports, { exitCount, failure }).pipe(Effect.asVoid),
665 - });
666 - yield* instance.start;
667 - yield* Deferred.await(firstExit);
668 - yield* TestClock.adjust(Duration.minutes(1));
669 - const { exitCount: exitsWhenReported, failure } = yield* Queue.take(reports);
670 - assert.equal(exitsWhenReported, 3);
671 - assert.equal(failure.reason, "The server could not start (code=1).");
672 - assert.isTrue(failure.output.endsWith(message));
673 - assert.isTrue(failure.output.isWellFormed());
674 - }).pipe(Effect.provide(TestClock.layer())),
675 - ),
670 + onStartupFailure: (failure) =>
671 + Queue.offer(reports, { exitCount, failure }).pipe(Effect.asVoid),
672 + });
673 + yield* instance.start;
674 + yield* Deferred.await(firstExit);
675 + yield* TestClock.adjust(Duration.minutes(1));
676 + const { exitCount: exitsWhenReported, failure } = yield* Queue.take(reports);
677 + assert.equal(exitsWhenReported, exits);
678 + assert.equal(failure.reason, `The server could not start (code=${code}).`);
679 + assert.equal(failure.managedPolicy, managedPolicy);
680 + assert.isTrue(failure.output.endsWith(message));
681 + assert.isTrue(failure.output.isWellFormed());
682 + }).pipe(Effect.provide(TestClock.layer())),
683 + ),
684 );
685
686 it.effect("waits out a slow startup and reports one that never becomes ready", () =>
apps/desktop/src/backend/DesktopBackendManager.ts
+13 -5
@@ -17,6 +17,7 @@ import { HttpClient } from "effect/http";
17 import { ChildProcess, ChildProcessSpawner } from "effect/process";
18
19 import {
20 + SERVER_EXIT_CODE_MANAGED_POLICY,
21 SERVER_EXIT_CODE_STATE_DIR_OWNED,
22 DesktopBackendBootstrap,
23 type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
@@ -223,6 +224,8 @@ export const PRIMARY_INSTANCE_ID: BackendInstanceId = BackendInstanceId(
224
225 export interface BackendStartupFailure {
226 readonly reason: string;
227 + /** The server refused to start under this machine's managed policy. */
228 + readonly managedPolicy: boolean;
229 /** Tail of the last run's stdout and stderr. */
230 readonly output: string;
231 }
@@ -635,9 +638,11 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
638 // One streaming decoder per stream keeps UTF-8 characters split across chunks intact.
639 const makeOutputDecoders = () => ({ stdout: new TextDecoder(), stderr: new TextDecoder() });
640 let outputDecoders = makeOutputDecoders();
638 - const reportStartupFailure = (reason: string) =>
641 + const reportStartupFailure = (reason: string, managedPolicy = false) =>
642 Ref.get(outputTail).pipe(
640 - Effect.flatMap((output) => spec.onStartupFailure?.({ reason, output }) ?? Effect.void),
643 + Effect.flatMap(
644 + (output) => spec.onStartupFailure?.({ reason, managedPolicy, output }) ?? Effect.void,
645 + ),
646 );
647
648 const { logWarning: logInstanceWarning, logError: logInstanceError } =
@@ -880,7 +885,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
885 yield* (spec.onStateDirOwned?.() ?? Effect.void).pipe(Effect.ignore);
886 return;
887 }
883 - yield* scheduleRestart(reason);
888 + yield* scheduleRestart(reason, exitCode);
889 }
890 }),
891 );
@@ -980,6 +985,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
985
986 const scheduleRestart = Effect.fn("desktop.backendInstance.scheduleRestart")(function* (
987 reason: string,
988 + exitCode?: number,
989 ) {
990 const scheduled = yield* SubscriptionRef.modify(state, (latest) => {
991 if (!latest.desiredRunning || Option.isSome(latest.restartFiber)) {
@@ -1003,8 +1009,10 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
1009 reason,
1010 delayMs: Duration.toMillis(delay),
1011 });
1006 - if (attempt >= STARTUP_FAILURE_RESTART_ATTEMPTS) {
1007 - yield* reportStartupFailure(`The server could not start (${reason}).`);
1012 + // Retrying cannot fix a policy refusal, so say so at once; retries still pick up a fix.
1013 + const managedPolicy = exitCode === SERVER_EXIT_CODE_MANAGED_POLICY;
1014 + if (managedPolicy || attempt >= STARTUP_FAILURE_RESTART_ATTEMPTS) {
1015 + yield* reportStartupFailure(`The server could not start (${reason}).`, managedPolicy);
1016 }
1017 const restartFiber = yield* Effect.forkIn(
1018 Effect.sleep(delay).pipe(
packages/contracts/src/desktopBootstrap.ts
+2
@@ -4,6 +4,8 @@ import { PortSchema, PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts
4
5 // A supervisor must not restart a server refused by the state-directory owner.
6 export const SERVER_EXIT_CODE_STATE_DIR_OWNED = 78;
7 +// A server the managed policy refused, so the desktop app blames the policy rather than the release.
8 +export const SERVER_EXIT_CODE_MANAGED_POLICY = 77;
9
10 export const DesktopBackendBootstrap = Schema.Struct({
11 mode: Schema.Literal("desktop"),
packages/shared/src/managedPolicyFile.ts
+4 -1
@@ -1,4 +1,4 @@
1 -import { ManagedPolicyDocument } from "@t3tools/contracts";
1 +import { ManagedPolicyDocument, SERVER_EXIT_CODE_MANAGED_POLICY } from "@t3tools/contracts";
2 import * as Cause from "effect/Cause";
3 import * as Context from "effect/Context";
4 import * as Duration from "effect/Duration";
@@ -6,6 +6,7 @@ import * as Effect from "effect/Effect";
6 import * as Exit from "effect/Exit";
7 import * as FileSystem from "effect/FileSystem";
8 import * as Layer from "effect/Layer";
9 +import * as Runtime from "effect/Runtime";
10 import * as Schema from "effect/Schema";
11 import * as Stream from "effect/Stream";
12 import { ChildProcess, ChildProcessSpawner } from "effect/process";
@@ -20,6 +21,8 @@ export class ManagedPolicyFileError extends Schema.TaggedError<ManagedPolicyFile
21 cause: Schema.optional(Schema.Defect()),
22 },
23 ) {
24 + override readonly [Runtime.errorExitCode] = SERVER_EXIT_CODE_MANAGED_POLICY;
25 +
26 override get message(): string {
27 return `T3 Code cannot use the managed policy at ${this.path}: ${this.reason}. It will not start until an administrator fixes this.`;
28 }