Skip to content

fix(server): close remote update race windows

MacroscopeApp / Macroscope - Effect Service Conventions failed Aug 1, 2026 in 3m 57s

Effect Service Conventions: 3 issues found

Three convention issues remain in the new Effect service code. Prior findings (module-global shutdown channel, free-form launcher error, duplicated launcher-context read in the SQLite layer, duplicated ServiceLauncherClient layer) are resolved.

  • apps/server/src/cloud/selfUpdate.ts (line 66): failWith no longer accepts a cause, so both wrapping sites drop the structured PinnedRuntimeInstallError / ServiceLauncherClientError and build reason from error.message. ServerSelfUpdateError declares an optional cause; the immediate error should be preserved and the wrapper text derived from structural attributes.
  • apps/server/src/cloud/pinnedRuntime.ts (lines 114-125): newly added Effect.catchTag("PinnedRuntimeInstallError", ...) should be Effect.catchTags({ ... }).
  • apps/server/src/cloud/selfUpdate.ts (line 27): the local service module serviceLauncherClient.ts is consumed at a service boundary but imported with named imports instead of a namespace import.

All three were posted as inline review comments with suggested fixes.

Details

Note

Your check run agent prompt is: .macroscope/check-run-agents/effect-service-conventions.md
More information about how Check Run Agents work can be found in our Help Center.

Scope reviewed: new and changed service modules under apps/server/src (cloud/serviceLauncherClient.ts, cloud/serviceProtocol.ts, cloud/servicePreflight.ts, cloud/selfUpdate.ts, cloud/bootService.ts, cloud/pinnedRuntime.ts, serverShutdown.ts, serverActivation.ts, serverRuntimeStartup.ts, server.ts, cli/server.ts, cli/servicePreflight.ts, persistence/Layers/Sqlite.ts, persistence/Migrations.ts, reactor service/layer shape changes) plus packages/contracts and packages/client-runtime contract/state updates.

Verified as acceptable:

  • ServerShutdown is now a proper Context.Service with make and layer, replacing the previously flagged module-global set; the CLI supplies it via Layer.succeed at the CLI boundary.
  • ServiceLauncherClient is constructed once in makeServerLayer and shared as a single instance to both the routes layer and runtime services, so the stateful client is no longer built twice.
  • ServiceLauncherTrial is now a Context.Reference populated from the single client instance, so the SQLite layer no longer re-decodes launcher context from process.env.
  • ServiceLauncherClientError now uses a multi-value operation discriminator with a message derived from structural attributes, matching the guidance for one service-level error covering related IPC failures.
  • PinnedRuntimePreflightBlockedError correctly separates the caller-visible blocked-preflight case from the diagnostic PinnedRuntimeInstallError.step field.
  • ensurePinnedRuntimeInstalled's explicit fs / path / runner parameters are pre-existing and out of scope; the new validate parameter is a deliberate callback strategy, not service injection.
  • forkParked activation gates passed to reactor start(...) are synchronization values, not service instances.

🔍 Agent activity — 1 tool call

💭 Looking at the diff between the current commit and the prior run, I can see that several issues have been resolved: the serverShutdown module-global Set has been refactored into a proper Context.Service with make and layer functions, the error message about PinnedRuntimeInstallError has been cleaned up into PinnedRuntimePreflightBlockedError, and the serviceLauncherClient now properly uses ServiceLauncherHostProcess from Context instead of defaulting to global process and environment variables. The Reference and HostProcessEnvironment still touch the global process at the default level, but that's acceptable since it's a Context.Reference default. The ServiceLauncherClientError has been updated to use an operation literal discriminator with a message switch, which aligns with the convention allowing a single error with a multi-value operation discriminator when failures share the same semantics. The Sqlite.ts isServiceLauncherTrial check now properly uses the ServiceLauncherTrial Context.Reference from launcherClient.trial, and the duplicate ServiceLauncherClient.layer provision has been eliminated by constructing launcherClient once in makeServerLayer and sharing it throughout. Now reviewing the current diff for any new violations. The serviceLauncherClient.ts file exports make, layer, and the ServiceLauncherClient service with a reasonable structure—imports, error class, interfaces, References, helpers, tag, and layer definition. The layer uses Layer.effect with make(), while server.ts calls make() directly with Layer.succeed at the application boundary, which is acceptable. The ServiceLauncherHostProcess Reference's defaultValue reading global process follows the host-process reference pattern and is acceptable. serverShutdown.ts follows the standard Context.Service, make, and layer structure. In cli/server.ts, ServerShutdown.make is yielded and then Layer.succeed wraps it—that's fine. The comment notes the CLI supplies configuration and the controlled-shutdown service, and while server.test.ts also provides ServerShutdown.layer, there's no conflict. serverRuntimeStartup.ts now has make as a function accepting optional parameters that returns an Effect, with layerWithOptions and a default layer—that's acceptable. Sqlite.ts has a setup function taking trial, which is fine. In Migrations.ts, MigrationManifestMismatchError has structured attributes like expectedCount and actualCount, but the message is a constant generic string rather than derived from those attributes. It's not ideal by convention, but the attributes are there and the message is clear enough—not worth flagging as a real issue. servicePreflight.ts contains pure synchronous functions using node:sqlite directly, used in CLI commands and child processes, so it's not an Effect service. runServicePreflight appears to be a synchronous function doing file operations. The runServicePreflight function catches all errors and returns a blocked state, so no exceptions escape—it's eager IO that runs when the handler is invoked at execution time, which is acceptable. In bootService.ts, I'm using node:fs/promises directly with Effect.tryPromise for durable writes since the Effect FileSystem service doesn't expose fsync, which justifies bypassing the abstraction. However, there's a path parsing issue where writeDurably manually slices the file path instead of using the Path service already available, and it references the process.pid global—these are quality concerns but not core convention violations, and since bootService is Linux-only, the Windows path bug isn't in scope. I'm also noticing that readState implements hand-rolled JSON validation instead of using the preferSchemaOverJson diagnostic that's enforced elsewhere in the repo. Looking at whether hand-rolled decoders in serviceProtocol.ts, bootService.ts, and serviceLauncherClient.ts violate the Effect Service Conventions — they're not explicitly called out in the check's sections on imports, service definition, dependency acquisition, errors, predicates, file layout, or change discipline. The convention does mention exporting schema predicates like isFoo, but that's not applicable here. isExactServiceVersion is just a plain regex predicate which seems fine, so I'm checking for other potential violations. Now I'm going through the imports systematically — the touched code uses namespace imports from "effect" consistently, and the subpath import from effect/unstable/cli matches existing repo conventions. The named import from the contracts package is allowed, but I'm noticing selfUpdate.ts imports from the local service module serviceLauncherClient.ts using named imports rather than a namespace, which might conflict with the service boundary convention. In serverRuntimeStartup.ts and server.ts, they're using namespace imports for ServiceLauncherClient, but selfUpdate.ts uses named imports instead—that's an inconsistency worth flagging. The pinnedRuntime.ts imports are fine as named imports since it's just helpers and errors, not a service module. Looking at other files, ServerShutdown follows the namespace pattern correctly, bootService.ts uses named imports for pure constants and types which is appropriate, and Sqlite.ts imports just the ServiceLauncherTrial reference from the service module—that's a borderline case since it's only the reference, not the full service. Test files are less strict about these conventions anyway. The question is whether flagging the named import of ServiceLauncherClient in selfUpdate.ts is worth the effort, given that it's a generated type. The convention says to import service modules as namespaces, and while the named import doesn't erase clarity entirely, it does erase the module namespace context. Since the check defaults to failure and I want to avoid noise, I should look for stronger findings instead. Let me examine the service definition structure itself — the tag, inline interface, exported make and layer, and how the error class and ServiceLauncherProcess interface are ordered. Now I'm checking the dependency acquisition pattern. The key rule is that production service construction must acquire Effect service dependencies from the environment using the namespace pattern, and the make/layer types must expose those requirements. Looking at how server.ts constructs the launcher client and merges layers... The application composes the resource once in an application-owned layer and provides its context to integration runtimes, which aligns with the instructions. makeServerLayer uses Layer.unwrap with Effect.gen, so ServiceLauncherClient.make() can fail with ServiceLauncherClientError — that's acceptable. The serverRuntimeStartup.make function takes awaitAuxiliaryParked as an Effect value rather than a service instance, which is a deliberate callback strategy, though passing an Effect as a parameter is a bit unconventional. I'm noticing that isServiceLauncherManaged in selfUpdate.ts is re-reading and re-decoding the launcher context from the environment, which duplicates what ServiceLauncherClient.managed already does — and with different strictness levels too, since one returns false for invalid context while the other fails. I should trace where resolveServerSelfUpdateCapability is actually being used to see if this duplication matters. The ServerUpdateTerminalError message construction looks fine, but PinnedRuntimePreflightBlockedError has a similar pattern where it stores a user-facing sentence as reason and returns it directly as the message. This mirrors the earlier issue I flagged — the reason comes from the remote preflight service, so I should check whether this violates the convention of deriving messages from structured attributes rather than storing unstructured text. Actually, since the target version generates this message and there's no way to reconstruct it structurally on the client side, this is defensible. The previous version had the main complaint fixed already, so I won't re-flag it. Looking at the error mapping in selfUpdate.ts, I'm checking how errors are transformed when they're caught and re-thrown. Continuing with error handling... I need to check the ServerSelfUpdateError definition to see if it supports a cause field. Looking at the contracts, it seems the previous version accepted both reason and cause parameters, but this PR's implementation drops the cause entirely and derives the reason string directly from error.message. That's a regression — the cause is lost and the message violates the principle of not interpolating cause.message into wrapper messages. The same issue appears in the launcher.requestUpdate call, which also drops the cause when mapping the error. Let me verify the ServerSelfUpdateError schema and trace where resolveServerSelfUpdateCapability is actually used. I'm noticing that ServerEnvironment.make and ServiceLauncherClient.managed are both trying to determine the same launcher management status, but they're doing it differently — one re-decodes the launcher context from environment variables while the other already has it exposed, and they handle errors differently too, with one failing strictly and the other silently returning false. This is the same kind of duplicate state acquisition I flagged before in Sqlite.ts that they fixed. Since ServerEnvironment is constructed within the runtime layers where ServiceLauncherClient is already provided through the dependency injection setup, using the client directly instead of re-decoding should be feasible. Let me check the full selfUpdate.ts file to see what's happening with the failWith and cause handling. I'm noticing a pattern in how errors are being handled across these two sites—both ensurePinnedRuntimeInstalled and requestUpdate are dropping the underlying error details when they map to their wrapper errors, relying instead on extracting the message from the caught error. The ServerSelfUpdateError type supports an optional cause field, but the current implementation isn't using it, which breaks the convention for error chaining. There's also a regression here: the old code passed the cause explicitly and used static reason strings, whereas now the reason string is being interpolated from error.message. Additionally, line 170 uses inline tag discrimination to pick caller-visible text based on the error type, which works but could be cleaner with Effect.catchTags instead of doing the tag check inside mapError. I'm also noticing that resolveServerSelfUpdateCapability and isSer are duplicating launcher-context decoding outside of ServiceLauncherClient, which should be consolidated. There's also an inconsistency in how ServiceLauncherClient is imported across files — selfUpdate.ts uses a named import while other files like server.ts use namespace imports, which breaks the pattern. Let me verify the other new files aren't introducing similar violations. Looking at pinnedRuntime.ts, the ensurePinnedRuntimeInstalled function already had those explicit parameters before this PR, though it now accepts a validate callback which is a deliberate design choice. I need to check whether this violates the rule about factories accepting service implementations as dependencies. I notice the ensurePinnedRuntimeInstalled function already accepted those parameters before this PR, so that's not a new issue. But there's a problem at line 114 where Effect.catchTag is being used for a single error tag — the style guide says to use Effect.catchTags with an object instead, and this appears to be a new addition in this PR that violates that convention. Let me search through the diff for other catchTag usages and check the full files for additional issues like hand-rolled state reading in bootService.ts and serviceLauncherClient.ts. The rule explicitly forbids using catchTag, and this is a newly-added line, so I should flag it even though it's used elsewhere in the repo. I'll include a brief inline comment with a fix suggestion since it's a trivial change. Now looking at the actual findings: the main issue is in selfUpdate.ts where failWith is dropping the cause field and building the reason only from error.message. The ServerSelfUpdateError has an optional cause that should be preserved. I need to flag this violation of the "preserve the immediate underlying error as cause" principle and suggest restoring the cause parameter to failWith, passing the structured error object directly so the reason comes from the error's attributes rather than its message string. I'll place a single comment at line 66 on the failWith function definition to explain that it drops the cause at both call sites and derives the reason from the error message. That's the most focused location to document the issue and the fix. Now I'm moving on to the second finding in selfUpdate.ts around lines 37-42 and ServerEnvironment. ts at line 128, where there's duplicate launcher-context acquisition happening. The resolveServerSelfUpdateCapability function is re-decoding the launcher context through isServiceLauncherManaged() instead of reading directly from ServiceLauncherClient.managed, and they have different strictness levels — one silently returns false while the other throws a typed error. I need to check whether ServiceLauncherClient is actually available in ServerEnvironment's layer context before I can safely suggest a fix. Looking at how ServerEnvironment is constructed, it goes through ServerEnvironment.make in RuntimeCoreDependenciesLive, and the launcher layer gets provided via Layer.provide(launcherLayer) on runtimeServicesLive. So it should be available there. But ServerEnvironment might be used in other contexts like the CLI, so I should phrase this carefully as acquiring from ServiceLauncherClient rather than making a hard assertion. Let me trace through where ServerEnvironment.layer is actually used to understand the scope of this change. I also spotted a couple other issues: Effect.catchTag should be Effect.catchTags in pinnedRuntime.ts, and there's a named import versus namespace import inconsistency in selfUpdate.ts that's low priority—I can fold that into the comment for the main finding instead of calling it out separately. I'm realizing that ServerEnvironment.layer is also used in the connect CLI code, which complicates things since ServiceLauncherClient might not be available there. Adding ServiceLauncherClient.layer would be the right approach, though it means the connect CLI wouldn't be launcher-managed, so make() would still succeed with managed=false since there's no context environment. Looking at this more carefully, the convention violation isn't as clear-cut as I initially thought. The code does properly acquire dependencies from the Effect environment through ServiceLauncherHostProcess and HostProcessEnvironment, so it's not hiding dependencies. The real issue is duplicated decoding logic — more of a DRY and consistency concern than a stated convention violation. Since the conventions don't explicitly forbid duplicate derivation, and I'm supposed to report only concrete violations, I should probably drop or downgrade this finding to keep the signal strong. The behavioral inconsistency between ServiceLauncherClient.make() failing hard on invalid context while isServiceLauncherManaged silently reports unmanaged is interesting, but it's moot in practice since make() runs first and would kill startup anyway. That's low value. The named import at line 27 is worth flagging though — the convention explicitly requires importing service modules as namespaces at service boundaries, and selfUpdate.ts line 56 uses ServiceLauncherClient at a service boundary. The file already does this correctly for ServerShutdown, ProcessRunner, and ServerConfig, so this is a trivial fix and worth calling out. I should include it as a minor comment. Checking the other imports: Sqlite.ts uses ServiceLauncherTrial as a Context.Reference which is allowed, server.ts and serverRuntimeStartup.ts already namespace-import correctly, and CheckpointReactor.ts imports from a pure helper module which is fine. The Layer.succeed calls look good — server.ts composes once at the app boundary and cli/server.ts does it at the CLI boundary. Now I need to verify whether ServiceLauncherClient.layer is being provided twice in the layer composition around line 436. Looking at the diff, makeRoutesLayer.pipe(Layer.provide(launcherLayer)) and runtimeServicesLive both provide the same instance through Layer.succeed, so that's resolved. serverRuntimeStartup.ts exports a layer that requires ServiceLauncherClient and ServerShutdown, which is correct, and ServerShutdown is properly acquired from the environment in selfUpdate.ts. One more thing to check: servicePreflight.ts has a synchronous IO function being called inside servicePreflightCommand with Console.log(JSON.stringify(runServicePreflight(...))). The sync IO happens at handler invocation time during CLI execution, before the Effect actually runs, so there's no interruption or tracing involved — it's just a CLI adapter boundary, so I'll skip that. In bootService.ts, writeDurably uses process.pid and Node's filesystem directly even though FileSystem and Path services are available in the service's make function, but since writeDurably is a module-level helper outside the service, it can't access those services. The string slicing for dirname instead of using the path service is fragile, but it's out of scope since the file already has the nodeBuiltinImport:off diagnostic suppression and imports the necessary Node builtins. Moving on to the actual findings. I've identified three issues to comment on: the failWith call in selfUpdate.ts that drops the cause, the Effect.catchTag that should be Effect.catchTags in pinnedRuntime.ts, and the namespace import for a local service module in selfUpdate.ts. Let me verify these line numbers exist in the diff and then draft the comments. For the first issue at selfUpdate.ts:66, failWith no longer accepts a cause parameter, so both error-wrapping sites discard the structured error details and instead extract error.message for the reason. Since ServerSelfUpdateError already has a cause field defined as optional, the convention should be to preserve the original error as the cause and derive the wrapper's reason from stable attributes rather than relying on cause.message. At the call sites, I need to update how errors are passed: for the blocked runtime case, pass the error as cause; for the launcher rejection, the detail is actually a structural attribute on the reply, so using error.message loses information—I should pass the error as cause and let the reason be derived from that message, or better yet, extract the meaningful detail from the launcher's response directly. For the inline suggestion, I'll focus on the failWith definition at line 66 and describe the call-site changes in prose rather than showing all the code. Now looking at the second comment in pinnedRuntime.ts around line 114, where there's a catchTag handler for PinnedRuntimeInstallError... Converting this to catchTags requires modifying multiple lines (114-125), so a single-line suggestion won't work. I need to use a multi-line suggestion or unified diff that covers the entire block, showing how to restructure from catchTag to catchTags with the handler as an object property. For the third comment about the namespace import in selfUpdate.ts, changing to a namespace import would require updating all the usages throughout the file, which creates a multi-hunk diff. That's too complex for a suggestion, so I'll just mention it in prose instead. Given that there are actual findings here and the check defaults to failure when convention violations are present, I should mark this as a failure and post the review.

1. modify_pr — Reviewed the Effect service changes in this PR (launcher client, shutdown service, self-update, pinned runtime, startup/activation wiring). The prior findings on the module-global shutdown channel, the free-form launcher error, duplicated launcher-context reads in the SQLite layer, and the double ServiceLauncherClient layer are all resolved. Three smaller convention issues remain in the new code.


Agent Credits: 217 credits