port desktop app to Effect

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}

[juliusmarminge]

Summary

• Reworked desktop backend readiness probing around Effect-based services and effects, with temporary promise shims preserved for existing call sites.
• Added Effect/Vitest coverage for readiness polling, request timeouts, abort handling, and backend startup race behavior.
• Updated the desktop main process to use typed URL handling for backend endpoints and the new readiness error type.

Testing

• bun fmt
• bun lint
• bun typecheck
• bun run test for apps/desktop/src/backendReadiness.test.ts and apps/desktop/src/backendStartupReadiness.test.ts

---

Note

High Risk
Large refactor of the Electron desktop main process, backend spawning/readiness, and lifecycle handling; mistakes could prevent the app from starting or shut down cleanly. Also changes runtime configuration/paths and protocol handling, which can impact packaging and local file access.

Overview
Ports the desktop Electron main process to an Effect-based architecture, introducing layered services for app identity/environment/config, lifecycle/shutdown coordination, observability/tracing, and Electron wrappers (app/dialog/menu/protocol).

Reworks desktop backend startup into Effect-managed spawning with fd-based bootstrap payloads, HTTP readiness polling, structured child-process output logging, and automatic restart scheduling/cancellation logic.

Cleans up legacy promise/imperative utilities and tests (e.g., backendPort, readiness helpers, settings/persistence/dialog helpers) in favor of new Effect/Vitest test coverage, and updates build hygiene (.gitignore consolidation) plus bumps electron to 41.5.0.

^{Reviewed by Cursor Bugbot for commit 35835a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Port desktop app to Effect by replacing imperative Electron code with layered Effect-TS services

• Rewrites main.ts from imperative Electron startup code to a declarative Effect-TS layer composition, using NodeRuntime.runMain to execute a DesktopApp.program with all services provided via layers.
• Introduces a large set of new Effect-based Electron service wrappers: ElectronApp, ElectronDialog, ElectronMenu, ElectronProtocol, ElectronSafeStorage, ElectronShell, ElectronTheme, ElectronUpdater, and ElectronWindow, each with typed errors and scoped resource management.
• Adds desktop domain services (DesktopEnvironment, DesktopAppSettings, DesktopClientSettings, DesktopSavedEnvironments, DesktopBackendManager, DesktopBackendConfiguration, DesktopServerExposure, DesktopSshEnvironment, DesktopUpdates, DesktopWindow, etc.) as injectable Effect layers.
• Moves shared observability utilities (trace sink, NDJSON tracer, compactTraceAttributes) from the server app to @t3tools/shared/observability, and moves DesktopBackendBootstrap schema to @t3tools/contracts.
• Adds a comprehensive set of typed IPC handlers via DesktopIpc and installDesktopIpcHandlers, covering settings, SSH, server exposure, updates, and window operations; the preload bridge now sends structured object payloads instead of positional arguments.
• Converts all Effect imports across packages/contracts, packages/ssh, packages/shared, packages/tailscale, and related scripts to namespaced form, enforced by @effect/language-service plugin added to multiple tsconfig.json files.
• Risk: main.ts is a wholesale rewrite; any existing behavior not covered by the new layers (imperative window creation, old IPC handler signatures, title bar overlay config) is removed or changed.

^{Macroscope summarized 35835a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 43ea1a9d-4a21-4540-b157-0dd7ba97ae0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/a1238be3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Timeout silently succeeds instead of failing with error
  • Added Option.match after Effect.timeoutOption to convert Option.None (timeout) into a BackendTimeoutError failure instead of silently succeeding, matching the established pattern used in all other timeoutOption call sites in the codebase.

Or push these changes by commenting:

@cursor push 27f2b65c9b

Preview (27f2b65c9b)

diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts--- a/apps/desktop/src/backendReadiness.ts+++ b/apps/desktop/src/backendReadiness.ts@@ -3,6 +3,7 @@
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { HttpClient } from "effect/unstable/http";
@@ -60,9 +61,13 @@
yield* client.get(requestUrl).pipe(
Effect.asVoid,
Effect.timeoutOption(timeout),
+ Effect.flatMap(+ Option.match({+ onNone: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),+ onSome: () => Effect.void,+ }),+ ),
Effect.catchTags({
- TimeoutError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),- // Maybe map this to different error kind?
HttpClientError: () => Effect.fail(new BackendTimeoutError({ url: baseUrl })),
}),
);

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

@cursor push 27f2b65

Dismissing prior approval to re-evaluate d8f0d72

Dismissing prior approval to re-evaluate b5c8ea4

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Port fields lose range validation in bootstrap schema
  • Replaced Schema.Number with a shared PortSchema (Schema.Int with isBetween 1-65535) for both port and tailscaleServePort fields in DesktopBackendBootstrap, restoring the validation that was present in the old BootstrapEnvelopeSchema.
• ✅ Fixed: Readiness timeout fires but no window ever created
  • Added fallback window creation in the onReadinessFailure handler so users get a window (showing reconnection state) instead of being stuck with no UI when the readiness probe times out.

Or push these changes by commenting:

@cursor push 1291f41e07

Preview (1291f41e07)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -1496,6 +1496,12 @@
`bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
);
console.warn("[desktop] backend readiness check failed during bootstrap", error);
++ if (isDevelopment) return;+ const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existingWindow !== null) return;+ mainWindow = createWindow();+ writeDesktopLogHeader("bootstrap main window created (readiness timeout fallback)");
}),
onOutput: (streamName, chunk) =>
Effect.sync(() => {
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts--- a/apps/server/src/cli.ts+++ b/apps/server/src/cli.ts@@ -5,6 +5,7 @@
CommandId,
DesktopBackendBootstrap,
OrchestrationReadModel,
+ PortSchema,
ProjectId,
type ClientOrchestrationCommand,
} from "@t3tools/contracts";
@@ -67,8 +68,6 @@
import { WorkspacePaths } from "./workspace/Services/WorkspacePaths.ts";
import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));-
const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
Flag.optional,
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -5,6 +5,7 @@
export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
export const IsoDateTime = Schema.String;
export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts--- a/packages/contracts/src/desktopBootstrap.ts+++ b/packages/contracts/src/desktopBootstrap.ts@@ -1,14 +1,16 @@
import { Schema } from "effect";
+import { PortSchema } from "./baseSchemas.ts";+
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
noBrowser: Schema.Boolean,
- port: Schema.Number,+ port: PortSchema,
t3Home: Schema.String,
host: Schema.String,
desktopBootstrapToken: Schema.String,
tailscaleServeEnabled: Schema.Boolean,
- tailscaleServePort: Schema.Number,+ tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
});

_{You can send follow-ups to the cloud agent here.}

[cursor]

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Start leaks restart fiber without interrupting it
  • Added a call to the existing cancelRestart helper before the state update in start(), which properly interrupts the restart fiber before clearing its reference, preventing the orphaned fiber leak.

Or push these changes by commenting:

@cursor push fbac652b11

Preview (fbac652b11)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -232,11 +232,11 @@
.exists(config.entryPath)
.pipe(Effect.orElseSucceed(() => false));
+ yield* cancelRestart;
yield* Ref.update(state, (latest) => ({
...latest,
desiredRunning: true,
ready: false,
- restartFiber: Option.none(),
}));
if (!entryExists) {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Restart backoff resets on spawn, not readiness
  • Moved the restartAttempt: 0 reset from the onStarted callback to the onReady callback so exponential backoff is maintained for backends that crash during initialization.

Or push these changes by commenting:

@cursor push 269ea9ef0e

Preview (269ea9ef0e)

diff --git a/apps/desktop/src/desktopBackendManager.ts b/apps/desktop/src/desktopBackendManager.ts--- a/apps/desktop/src/desktopBackendManager.ts+++ b/apps/desktop/src/desktopBackendManager.ts@@ -324,16 +324,13 @@
...run,
pid: Option.some(pid),
}));
- yield* Ref.update(state, (latest) => ({- ...latest,- restartAttempt: 0,- }));
yield* events.onStarted({ pid, config });
}),
onReady: () =>
Effect.gen(function* () {
yield* Ref.update(state, (latest) => ({
...latest,
+ restartAttempt: 0,
ready: Option.match(latest.active, {
onNone: () => latest.ready,
onSome: (run) => (run.id === runId ? true : latest.ready),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Misleading log emitted when backend start is skipped
  • Moved the log statement inside the conditional block and added a distinct "skipped" log for the quitting case, so logs now accurately reflect whether the backend was started or skipped.

Or push these changes by commenting:

@cursor push 5f643f6923

Preview (5f643f6923)

diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts--- a/apps/desktop/src/app/DesktopApp.ts+++ b/apps/desktop/src/app/DesktopApp.ts@@ -178,8 +178,10 @@
if (!(yield* Ref.get(state.quitting))) {
yield* backendManager.start;
+ yield* Effect.logInfo("bootstrap backend start requested");+ } else {+ yield* Effect.logInfo("bootstrap backend start skipped (quitting)");
}
- yield* Effect.logInfo("bootstrap backend start requested");
if (environment.isDevelopment) {
yield* desktopWindow.ensureMain;

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: desktopState.backendReady is never set to true
  • Added Ref.set(desktopState.backendReady, true) in the onReady callback and removed the manual workaround in the test that externally set it to true.

Or push these changes by commenting:

@cursor push e5394e09b4

Preview (e5394e09b4)

diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts@@ -328,7 +328,6 @@
yield* manager.start;
assert.equal(yield* Queue.take(startedPids), 123);
yield* Deferred.await(ready);
- yield* Ref.set(backendReady, true);
assert.isTrue(yield* Ref.get(backendReady));
assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts--- a/apps/desktop/src/backend/DesktopBackendManager.ts+++ b/apps/desktop/src/backend/DesktopBackendManager.ts@@ -443,6 +443,7 @@
onSome: (run) => (run.id === runId ? true : latest.ready),
}),
}));
+ yield* Ref.set(desktopState.backendReady, true);
yield* desktopWindow.handleBackendReady.pipe(
Effect.catch((error) =>
Effect.logError("failed to open main window after backend readiness").pipe(

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 413d2f9. Configure here.}