alchemy 2.0.0-beta.84 → 2.0.0-beta.85

package/src/Local/RpcProviderProxy.ts

@@ -1,6 +1,7 @@
 import { newWebSocketRpcSession, type RpcStub } from "capnweb";
 import * as Config from "effect/Config";
 import * as Context from "effect/Context";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as HttpBody from "effect/http/HttpBody";
 import * as HttpClient from "effect/http/HttpClient";
@@ -14,6 +15,20 @@ import type { RpcProxyApi, SessionProviderCounts } from "./RpcServer.ts";
 import { encodeSessionEnvironment, SESSION_ENV_PARAM } from "./RpcServerEnvironment.ts";
 import type { RpcSpawnPayload } from "./RpcSpawner.ts";
 
+export class RpcProviderProxyOperationFailed extends Data.TaggedError(
+  "RpcProviderProxyOperationFailed",
+)<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class RpcProviderProxyUnexpectedResponse extends Data.TaggedError(
+  "RpcProviderProxyUnexpectedResponse",
+)<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
 /** A test file's leases on the sessions it actually uses. */
 export interface SessionOwner {
   closed: boolean;
@@ -100,28 +115,20 @@ const make = Effect.fn(function* (spawnerUrl: string) {
       });
       const body = yield* response.text;
       if (response.status !== 200) {
-        return yield* Effect.fail(
-          new Error(
-            `RPC spawner POST ${spawnerUrl} returned ${response.status}: ${body.slice(0, 300)}`,
-          ),
-        );
+        return yield* new RpcProviderProxyOperationFailed({
+          message: `RPC spawner POST ${spawnerUrl} returned ${response.status}: ${body.slice(0, 300)}`,
+        });
       }
-      let websocketUrl: URL;
-      try {
-        websocketUrl = new URL(body);
-      } catch {
-        return yield* Effect.fail(
-          new Error(
-            `RPC spawner POST ${spawnerUrl} did not return a websocket URL (got ${JSON.stringify(body.slice(0, 200))})`,
-          ),
-        );
+      if (!URL.canParse(body)) {
+        return yield* new RpcProviderProxyUnexpectedResponse({
+          message: `RPC spawner POST ${spawnerUrl} did not return a websocket URL (got ${JSON.stringify(body.slice(0, 200))})`,
+        });
       }
+      const websocketUrl = new URL(body);
       if (websocketUrl.protocol !== "ws:" && websocketUrl.protocol !== "wss:") {
-        return yield* Effect.fail(
-          new Error(
-            `RPC spawner POST ${spawnerUrl} returned a non-websocket URL: ${websocketUrl.toString()}`,
-          ),
-        );
+        return yield* new RpcProviderProxyUnexpectedResponse({
+          message: `RPC spawner POST ${spawnerUrl} returned a non-websocket URL: ${websocketUrl.toString()}`,
+        });
       }
       websocketUrl.searchParams.set(SESSION_ENV_PARAM, sessionEnv);
       const socket = new WebSocket(websocketUrl.toString());
@@ -185,7 +192,7 @@ const make = Effect.fn(function* (spawnerUrl: string) {
         (entry) => entry.connection !== undefined,
       )?.connection;
       return connection === undefined
-        ? Effect.succeed(undefined)
+        ? Effect.undefined
         : Effect.tryPromise(async () => (await connection.pending).rpc.getDiagnostics()).pipe(
             Effect.map(
               ({ sessions, testSessions, contexts, building, artifactBags, artifacts }) => ({
@@ -239,8 +246,9 @@ const make = Effect.fn(function* (spawnerUrl: string) {
         let connection = current.connection;
         if (connection === undefined) {
           const open = getSession(environment);
+          const context = yield* Effect.context();
           connection = {
-            pending: Effect.runPromise(
+            pending: Effect.runPromiseWith(context)(
               current.testOwned ? open.pipe(Effect.timeout("30 seconds")) : open,
             ),
           };

package/src/Local/RpcSerialization.ts

@@ -12,13 +12,21 @@ import * as Stream from "effect/Stream";
 import * as Output from "../Output.ts";
 import { isRedactedMarker, type RedactedMarker } from "../RuntimeContext.ts";
 import { decodeDuration, DURATION_MARKER, encodeState } from "../State/StateEncoding.ts";
+import {
+  currentTraceParent,
+  type TraceParent,
+  withStreamTraceParent,
+  withTraceParent,
+} from "../Util/TraceParent.ts";
 
 type RpcEffectHandler<Args extends Array<any>, Success, Error> = (
   ...args: Args
 ) => Effect.Effect<Success, Error>;
 
+// `parent`: the caller's span, so the sidecar's work joins its trace.
 type RpcWrappedEffectHandler<Args extends Array<any>, Success, Error> = (
   args: Args,
+  parent?: TraceParent,
 ) => Promise<RpcSerializedExit<Success, Error>>;
 
 type RpcStreamHandler<Args extends Array<any>, Success, Error> = (
@@ -27,6 +35,7 @@ type RpcStreamHandler<Args extends Array<any>, Success, Error> = (
 
 type RpcWrappedStreamHandler<Args extends Array<any>, Success, Error> = (
   args: Args,
+  parent?: TraceParent,
 ) => RpcSerializedStream<Success, Error>;
 
 type RpcSerializedStream<Success, _Error> = ReadableStream<Success>;
@@ -186,11 +195,12 @@ const wrapRpcEffectHandler = <Args extends Array<any>, Success, Error>(
   registerCall?: Effect.Effect<void, never, Scope.Scope>,
 ): RpcWrappedEffectHandler<Args, Success, Error> =>
   flow(
-    (args) => deserializeRpcArgs(args) as Args,
-    (args) =>
-      registerCall === undefined
-        ? handler(...args)
-        : Effect.scoped(registerCall.pipe(Effect.andThen(Effect.suspend(() => handler(...args))))),
+    (args, parent) => {
+      const call = Effect.suspend(() => handler(...(deserializeRpcArgs(args) as Args)));
+      return (
+        registerCall === undefined ? call : Effect.scoped(registerCall.pipe(Effect.andThen(call)))
+      ).pipe(withTraceParent(parent));
+    },
     Effect.exit,
     Effect.flatMap((exit): Effect.Effect<RpcSerializedExit<Success, Error>> => {
       if (exit._tag === "Success") {
@@ -229,11 +239,12 @@ const wrapRpcStreamHandler = <Args extends Array<any>, Success, Error>(
   registerCall?: Effect.Effect<void, never, Scope.Scope>,
 ): RpcWrappedStreamHandler<Args, Success, Error> =>
   flow(
-    (args) => deserializeRpcArgs(args) as Args,
-    (args) =>
-      registerCall === undefined
-        ? handler(...args)
-        : Stream.unwrap(registerCall.pipe(Effect.map(() => handler(...args)))),
+    (args, parent) => {
+      const call = Effect.sync(() => handler(...(deserializeRpcArgs(args) as Args)));
+      return Stream.unwrap(
+        registerCall === undefined ? call : registerCall.pipe(Effect.andThen(call)),
+      ).pipe(withStreamTraceParent(parent));
+    },
     (stream) => Stream.toReadableStream(stream),
   );
 
@@ -242,7 +253,8 @@ const unwrapRpcEffectHandler = <Args extends Array<any>, Success, Error>(
 ): RpcEffectHandler<Args, Success, Error> =>
   flow(
     (...args) => serializeRpcArgs(args) as Args,
-    (args) => Effect.promise(() => handler(args)),
+    (args) =>
+      Effect.flatMap(currentTraceParent, (parent) => Effect.promise(() => handler(args, parent))),
     Effect.flatMap((exit): Exit.Exit<Success, Error> => {
       if (exit._tag === "Success") {
         // Mirror of the wrap side: rebuild `Redacted` wrappers from their
@@ -272,12 +284,15 @@ const unwrapRpcStreamHandler = <Args extends Array<any>, Success, Error>(
 ): RpcStreamHandler<Args, Success, Error> =>
   flow(
     (...args) => serializeRpcArgs(args) as Args,
-    (args) => handler(args),
-    (stream) =>
-      Stream.fromReadableStream({
-        evaluate: () => stream,
-        onError: (error) => error as Error,
-      }),
+    (args) =>
+      Stream.unwrap(
+        Effect.map(currentTraceParent, (parent) =>
+          Stream.fromReadableStream({
+            evaluate: () => handler(args, parent),
+            onError: (error) => error as Error,
+          }),
+        ),
+      ),
   );
 
 const serializeRpcArgs = (value: unknown): unknown => {

package/src/Local/RpcServer.ts

@@ -7,13 +7,14 @@ import * as Fiber from "effect/Fiber";
 import * as FetchHttpClient from "effect/http/FetchHttpClient";
 import type { HttpClient } from "effect/http/HttpClient";
 import * as Layer from "effect/Layer";
-import * as Logger from "effect/Logger";
 import * as Scope from "effect/Scope";
 import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
 import type { ProviderService } from "../Provider.ts";
 import type { ResourceLike } from "../Resource.ts";
-import { makePlainConsoleSink } from "../Util/ConsoleSink.ts";
+import { childJsonLogLayer, LOG_FORMAT_ENV, LogProcess } from "../Util/LogRecord.ts";
 import { platformLayer, PlatformServices, runMain } from "../Util/PlatformServices.ts";
+import { logShutdown } from "../Util/Shutdown.ts";
+import { processTrace, withTraceParent } from "../Util/TraceParent.ts";
 import * as RpcSerialization from "./RpcSerialization.ts";
 import * as RpcServerEnvironment from "./RpcServerEnvironment.ts";
 import type { SessionEnvironment } from "./RpcServerEnvironment.ts";
@@ -156,7 +157,7 @@ const sessionProviders = (resolve: ProviderGroupLoader) =>
           };
           sessions.set(key, session);
           const current = session;
-          Effect.runSync(
+          Effect.runSyncWith(ambient)(
             Scope.addFinalizer(
               current.scope,
               // Calls drain before provider finalizers and artifact disposal.
@@ -195,7 +196,7 @@ const sessionProviders = (resolve: ProviderGroupLoader) =>
           );
         }
         const groupScope = Scope.forkUnsafe(current.resources);
-        const pending = Effect.runPromise(
+        const pending = Effect.runPromiseWith(ambient)(
           resolve(group).pipe(
             Effect.flatMap((providers) =>
               Layer.buildWithMemoMap(
@@ -265,7 +266,7 @@ const sessionProviders = (resolve: ProviderGroupLoader) =>
           lease.closing =
             session === undefined
               ? Promise.resolve()
-              : Effect.runPromise(Scope.close(session.scope, Exit.void));
+              : Effect.runPromiseWith(ambient)(Scope.close(session.scope, Exit.void));
           return lease.closing;
         },
         get: async (sessionEnv, type, group, lease) => {
@@ -332,14 +333,15 @@ export const launch = (providers: ProviderLayer | ProviderGroupLoader) =>
       sessionProviders(Layer.isLayer(providers) ? () => Effect.succeed(providers) : providers),
     ),
     Layer.provide(Layer.mergeAll(PlatformServices, FetchHttpClient.layer)),
-    // Sidecar stdio is piped, so effect's default pretty logger disables
-    // colors (it only checks `isTTY`, never FORCE_COLOR). The spawner sets
-    // FORCE_COLOR exactly when the destination terminal supports color —
-    // honor it here so sidecar log lines match the rest of the dev output.
-    Layer.provide(
-      process.env.FORCE_COLOR ? Logger.layer([makePlainConsoleSink(true)]) : Layer.empty,
-    ),
     Layer.launch,
+    logShutdown("sidecar"),
+    // Spans outside RPC calls join the `alchemy dev` trace, like its records.
+    withTraceParent(processTrace),
+    // The spawner asks for JSON records: the process that owns the
+    // terminal decodes and renders them, so structure (level, resource,
+    // text as written) survives the pipe.
+    Effect.provide(process.env[LOG_FORMAT_ENV] === "json" ? childJsonLogLayer : Layer.empty),
+    Effect.provideService(LogProcess, "sidecar"),
     Effect.scoped,
     runMain,
   );
@@ -363,15 +365,17 @@ export const layerServer = (
     /** Called when the parent connection, indicated by the `/parent` path, is established. */
     parentConnected: () => void;
     /** Called when the parent disconnects. The server will shut down when this is called. */
-    parentDisconnected: () => void;
+    /** The parent link closed; `detail` says how, when the server knows. */
+    parentDisconnected: (detail?: string) => void;
   }) => Effect.Effect<{ readonly url: string }, never, Scope.Scope>,
 ) =>
   Layer.effect(
     RpcServer,
     Effect.gen(function* () {
       const providers = yield* SessionProviders;
+      const context = yield* Effect.context();
       const connected = yield* Deferred.make<void>();
-      const disconnected = yield* Deferred.make<void>();
+      const disconnected = yield* Deferred.make<string | undefined>();
       const { url } = yield* serve({
         createRpcSession: (ws, sessionEnv) => {
           const lease: SessionLease = { closed: false, calls: new Set() };
@@ -395,18 +399,22 @@ export const layerServer = (
             // deliberately retain their contexts across hot reloads.
             if (testOwned) {
               void providers.release(lease).catch((error) => {
-                Effect.runFork(Effect.logError(error));
+                Effect.runForkWith(context)(Effect.logError(error));
               });
             }
           };
           return session;
         },
         parentConnected: () => Deferred.doneUnsafe(connected, Effect.void),
-        parentDisconnected: () => Deferred.doneUnsafe(disconnected, Effect.void),
+        parentDisconnected: (detail) => Deferred.doneUnsafe(disconnected, Effect.succeed(detail)),
       });
       yield* Console.log(`<ALCHEMY_RPC_ADDRESS>${url}</ALCHEMY_RPC_ADDRESS>`);
       yield* Deferred.await(connected).pipe(Effect.timeout("10 seconds")); // TODO(john): should the timeout be shorter?
-      yield* Deferred.await(disconnected);
+      // The sidecar exits with its parent; record why the link closed.
+      const detail = yield* Deferred.await(disconnected);
+      yield* Effect.logInfo(
+        `parent connection closed${detail === undefined ? "" : ` (${detail})`}; shutting down`,
+      );
       return yield* Effect.interrupt;
     }),
   );

package/src/Local/RpcServerBun.ts

@@ -12,6 +12,9 @@ export const RpcServerBun = RpcServer.layerServer(
         | { type: "parent" }
       >({
         port: 0,
+        // Loopback only, as in RpcServerNode: with no hostname Bun listens on
+        // every interface.
+        hostname: "127.0.0.1",
         fetch: (request, server) => {
           const url = new URL(request.url);
           if (
@@ -56,17 +59,18 @@ export const RpcServerBun = RpcServer.layerServer(
             if (ws.data.type === "session") {
               ws.data.session.dispatch.close(code, reason);
             } else if (ws.data.type === "parent") {
-              // The sidecar exits with its parent; record why the link closed.
-              console.error(
-                `[alchemy sidecar] parent connection closed (code ${code}${reason ? `, ${reason}` : ""}); shutting down`,
-              );
-              parentDisconnected();
+              parentDisconnected(`code ${code}${reason ? `, ${reason}` : ""}`);
             }
           },
         },
       }),
     );
-    yield* Effect.addFinalizer(() => Effect.sync(() => server.stop(true)));
+    // Fire and forget: awaiting `stop(true)` can outlive the process's own shutdown.
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        void server.stop(true);
+      }),
+    );
     return {
       url: `ws://${server.hostname}:${server.port}`,
     };

package/src/Local/RpcServerEnvironment.ts

@@ -4,9 +4,9 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import { AlchemyContext } from "../AlchemyContext.ts";
-import { AuthProviders } from "../Auth/AuthProvider.ts";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
 import { ProfileStoreLive } from "../Auth/Profile.ts";
+import { AuthProvidersLive } from "../Auth/Registry.ts";
 import { withProfileOverride } from "../Auth/Resolve.ts";
 import { Stack } from "../Stack.ts";
 import { Stage } from "../Stage.ts";
@@ -58,7 +58,7 @@ export const layer = (
   Layer.mergeAll(
     ProfileStoreLive,
     CredentialsStoreLive,
-    Layer.succeed(AuthProviders, {}),
+    AuthProvidersLive,
     loadConfigProvider(Option.fromNullishOr(environment.envFile)).pipe(
       Effect.map((base) => withProfileOverride(base, environment.profile)),
       ConfigProvider.layer,

package/src/Local/RpcServerNode.ts

@@ -20,7 +20,14 @@ export const RpcServerNode = RpcServer.layerServer(
           undefined;
         const session = createRpcSession(ws, sessionEnv);
         ws.on("message", (data) => {
-          session.dispatch.message(data.toString());
+          session.dispatch.message(
+            (Array.isArray(data)
+              ? Buffer.concat(data)
+              : Buffer.isBuffer(data)
+                ? data
+                : Buffer.from(data)
+            ).toString(),
+          );
         });
         ws.on("close", (code, reason) => {
           session.dispatch.close(code, reason.toString());

package/src/Local/RpcServerSession.ts

@@ -4,7 +4,7 @@ import { RpcSession, type RpcCompatible, type RpcTransport } from "capnweb";
  * A platform-agnostic interface for a server-side WebSocket.
  */
 export interface ServerWebSocketLike {
-  send: (message: string) => any | Promise<any>;
+  send: (message: string) => any;
   close: (code?: number, reason?: string) => void;
 }
 
@@ -32,7 +32,7 @@ function makeWebSocketRpcTransport(ws: ServerWebSocketLike) {
   let receiveQueue: Array<string> = [];
   let receiveResolver: ((value: string) => void) | undefined;
   let receiveRejecter: ((reason: unknown) => void) | undefined;
-  let error: unknown | undefined;
+  let error: unknown;
   return {
     transport: {
       send: async (message: string) => await ws.send(message),

package/src/Local/RpcSpawner.ts

@@ -2,11 +2,12 @@ import { fileURLToPath } from "node:url";
 import * as Cache from "effect/Cache";
 import type * as Cause from "effect/Cause";
 import * as Config from "effect/Config";
-import * as Console from "effect/Console";
 import * as Context from "effect/Context";
+import * as Data from "effect/Data";
 import * as Deferred from "effect/Deferred";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as HttpClient from "effect/http/HttpClient";
 import * as HttpServer from "effect/http/HttpServer";
 import { HttpServerRequest } from "effect/http/HttpServerRequest";
@@ -21,9 +22,12 @@ import * as Schedule from "effect/Schedule";
 import * as Schema from "effect/Schema";
 import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
+import { LOG_FORMAT_ENV, logChildLine } from "../Util/LogRecord.ts";
 import { nodeLoaderArgs } from "../Util/Node.ts";
 import { httpServer } from "../Util/PlatformServices.ts";
+import { timedShutdownStep } from "../Util/Shutdown.ts";
 import { pipedColorEnv } from "../Util/Terminal.ts";
+import { traceParentEnv } from "../Util/TraceParent.ts";
 import { SPAWNER_URL_ENV_KEY } from "./RpcProviderProxy.ts";
 import { RPC_SERVER_ENVIRONMENT_KEY, type RpcServerEnvironment } from "./RpcServerEnvironment.ts";
 
@@ -34,6 +38,10 @@ export class RpcSpawner extends Context.Service<
   }
 >()("alchemy/Local/RpcSpawner") {}
 
+class InvalidServerEntryUrl extends Data.TaggedError("InvalidServerEntryUrl")<{
+  cause: unknown;
+}> {}
+
 /**
  * The spawner forks one child per distinct `serverEntryUrl`. Stack-specific
  * context (stack name/stage, AlchemyContext) is NOT part of the spawn key —
@@ -103,10 +111,9 @@ export const make = Effect.fn(function* ({ profile, envFile, omitEnv = [] }: Rpc
         for (const notify of subscribers) notify(line);
         return Effect.void;
       }
-      // Fallback path (no exec child subscribed): sidecar lines already carry
-      // the sidecar's logger prefix, so print verbatim rather than stamping
-      // this process's logger prefix on top.
-      return line.channel === "stderr" ? Console.error(line.line) : Console.log(line.line);
+      // Fallback path (no exec child subscribed): render the sidecar's
+      // records through this process's loggers.
+      return logChildLine(line.line, { stream: line.channel, process: "sidecar" });
     });
 
   const spawn = Effect.fn(function* (serverEntryUrl: string) {
@@ -157,6 +164,13 @@ export const make = Effect.fn(function* ({ profile, envFile, omitEnv = [] }: Rpc
         env: {
           ...(omitEnv.length > 0 ? yield* inheritedEnv(omitEnv) : {}),
           [RPC_SERVER_ENVIRONMENT_KEY]: JSON.stringify(environment),
+          // Its startup joins the trace of the call that spawned it; each
+          // provider call then carries its caller's span (RpcSerialization).
+          ...(yield* traceParentEnv),
+          // Log records, not rendered text: see `forwardSidecarLogs`.
+          [LOG_FORMAT_ENV]: "json",
+          // Tools further down (vite, workerd) still style their own output;
+          // records keep that text as written.
           ...pipedColorEnv(),
         },
         // With variables to withhold, the full environment is built above.
@@ -164,20 +178,36 @@ export const make = Effect.fn(function* ({ profile, envFile, omitEnv = [] }: Rpc
       },
     );
     const handle = yield* spawner.spawn(command);
-    yield* handle.stderr.pipe(
+    const stderrReader = yield* handle.stderr.pipe(
       Stream.decodeText,
       Stream.splitLines,
       Stream.runForEach((line) => publish({ channel: "stderr", line })),
       Effect.ignore,
       Effect.forkScoped,
     );
+    const stdout = yield* readRpcOutput(handle.stdout, (line) =>
+      publish({ channel: "stdout", line }),
+    );
     // This scope is the child handle's sole owner. Graceful shutdown runs this
     // finalizer; abrupt parent loss closes the RPC parent connection and the
     // child self-terminates (both paths are covered by RpcSpawnerCleanup).
     // Command cleanup allows 1s for TERM and 1s for KILL; reserve 1s for sidecar teardown.
     const kill = handle.kill({ forceKillAfter: "3 seconds" });
-    yield* Effect.addFinalizer(() => kill.pipe(Effect.ignore));
-    const url = yield* getRpcAddress(handle.stdout, (line) => publish({ channel: "stdout", line }));
+    // Registered after the readers, so it runs before they are interrupted:
+    // the sidecar's own shutdown records drain until its pipes close.
+    yield* Effect.addFinalizer(() =>
+      kill.pipe(
+        Effect.ignore,
+        Effect.andThen(
+          Fiber.joinAll([stderrReader, stdout.reader]).pipe(
+            Effect.timeout("1 second"),
+            Effect.ignore,
+          ),
+        ),
+        timedShutdownStep(`stopped sidecar pid ${handle.pid}`),
+      ),
+    );
+    const url = yield* Deferred.await(stdout.address);
     const ws = yield* Effect.acquireRelease(
       Effect.sync(() => {
         const ws = new WebSocket(new URL("/parent", url));
@@ -219,8 +249,8 @@ export const make = Effect.fn(function* ({ profile, envFile, omitEnv = [] }: Rpc
         new Error(`Failed to spawn RPC server for "${serverEntryUrl}" after ${attempt} attempts.`),
       );
     }
-    yield* Console.error(
-      `[alchemy] RPC sidecar for ${serverEntryUrl} is no longer running; respawning (attempt ${attempt + 1})`,
+    yield* Effect.logWarning(
+      `RPC sidecar for ${serverEntryUrl} is no longer running; respawning (attempt ${attempt + 1})`,
     );
     // The sidecar is usually already gone, and killing an exited process fails.
     yield* child.kill.pipe(Effect.ignore);
@@ -282,7 +312,7 @@ export const make = Effect.fn(function* ({ profile, envFile, omitEnv = [] }: Rpc
       const entry = yield* Effect.result(
         Effect.try({
           try: () => new URL(decoded.success.serverEntryUrl),
-          catch: (cause) => cause,
+          catch: (cause) => new InvalidServerEntryUrl({ cause }),
         }),
       );
       if (entry._tag === "Failure" || entry.success.protocol !== "file:") {
@@ -320,28 +350,29 @@ export const layerServer = (environment: RpcSpawnerOptions) =>
 
 const RPC_ADDRESS_REGEX = /(<ALCHEMY_RPC_ADDRESS>)(.+)(<\/ALCHEMY_RPC_ADDRESS>)/;
 
-const getRpcAddress = (
+/**
+ * Read the sidecar's stdout: its log lines and the RPC address line. The
+ * reader runs until the pipe closes, so a caller can drain it on shutdown.
+ */
+const readRpcOutput = (
   stdout: Stream.Stream<Uint8Array, PlatformError>,
   publish: (line: string) => Effect.Effect<void>,
 ) =>
   Effect.gen(function* () {
     const address = yield* Deferred.make<string>();
-    // Set once the address line is seen; lines before it are handshake noise.
-    let addressSeen = false;
-    yield* stdout.pipe(
+    // Every line but the address is published, including what the sidecar
+    // logs while starting: a layer that fails to build says why there.
+    const reader = yield* stdout.pipe(
       Stream.decodeText,
       Stream.splitLines,
       Stream.runForEach((line) => {
         const match = line.match(RPC_ADDRESS_REGEX);
-        if (match) {
-          addressSeen = true;
-          return Deferred.succeed(address, match[2]);
-        }
-        return addressSeen ? publish(line) : Effect.void;
+        return match ? Deferred.succeed(address, match[2]) : publish(line);
       }),
+      Effect.ignore,
       Effect.forkScoped,
     );
-    return yield* Deferred.await(address);
+    return { address, reader };
   });
 
 export const parseSidecarLogLine = (raw: string): SidecarLogLine | undefined => {
@@ -355,19 +386,16 @@ export const parseSidecarLogLine = (raw: string): SidecarLogLine | undefined =>
 };
 
 /**
- * Pull sidecar output from the spawner (the outer `alchemy dev` process)
- * into THIS process's Console. The exec child owns the terminal renderer —
- * Sigil patches its `console`, so lines printed here are inserted cleanly
- * above the repainting progress region instead of racing it on the shared
- * tty. Forks in the ambient scope and never fails: when no spawner is
+ * Pull the sidecars' log records from the spawner (the outer `alchemy dev`
+ * process) into THIS process's loggers. The exec child owns the terminal
+ * renderer, so the records render above the repainting progress region
+ * instead of racing it on the shared tty; it forwards them on to the
+ * supervisor, which writes the run log. Forks in the ambient scope and never fails: when no spawner is
  * configured (`ALCHEMY_RPC_SPAWNER_URL` absent — plain deploy/destroy) it is
  * a no-op, and if the connection drops the spawner's own fallback printing
  * takes over.
  */
-export const forwardSidecarLogs = (
-  /** Mirrors every forwarded line (e.g. into a dev log file). */
-  tee?: (line: SidecarLogLine) => void,
-): Effect.Effect<void, never, HttpClient.HttpClient | Scope.Scope> =>
+export const forwardSidecarLogs: Effect.Effect<void, never, HttpClient.HttpClient | Scope.Scope> =
   Config.String(SPAWNER_URL_ENV_KEY).pipe(
     Effect.flatMap((spawnerUrl) => {
       const streamOnce = Effect.gen(function* () {
@@ -380,13 +408,9 @@ export const forwardSidecarLogs = (
             Effect.suspend(() => {
               const parsed = parseSidecarLogLine(raw);
               if (parsed === undefined) return Effect.void;
-              tee?.(parsed);
-              // Sidecar lines already carry the sidecar's own logger prefix
-              // (timestamp/level/fiber) — print them verbatim; routing through
-              // this process's logger would stamp a second prefix on top.
-              return parsed.channel === "stderr"
-                ? Console.error(parsed.line)
-                : Console.log(parsed.line);
+              // Sidecar lines are log records: replay them through this
+              // process's loggers, which render them (or pass them on as JSON).
+              return logChildLine(parsed.line, { stream: parsed.channel, process: "sidecar" });
             }),
           ),
         );

package/src/Local/Sidecar.ts

@@ -13,10 +13,17 @@
  * (`RpcSpawner`) forks this entry once per run; `RpcProviderProxy` points
  * every provider at it.
  */
+
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as RpcServer from "./RpcServer.ts";
 
+export class SidecarInvalidProps extends Data.TaggedError("SidecarInvalidProps")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
 RpcServer.launch((group) =>
   Effect.promise(() => import(group)).pipe(
     Effect.flatMap((module: { default?: unknown }) =>
@@ -24,7 +31,9 @@ RpcServer.launch((group) =>
         ? // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- dynamically imported provider group module
           Effect.succeed(module.default as RpcServer.ProviderLayer)
         : Effect.fail(
-            new Error(`Provider group module ${group} must default-export its provider Layer`),
+            new SidecarInvalidProps({
+              message: `Provider group module ${group} must default-export its provider Layer`,
+            }),
           ),
     ),
   ),