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

package/src/Interaction.ts

@@ -1,14 +1,16 @@
 /**
- * The engine's capability contract for talking to a human.
+ * The capability to talk to the human driving this process.
  *
- * `Interaction` is the narrow, presentation-free slice of terminal
- * interaction that non-CLI code (auth flows, the state store, engine
- * surfaces) may use: plain-string messages, a handful of prompt shapes,
- * and `task`. Nothing in its vocabulary knows a renderer exists — the CLI
- * provides an implementation backed by its terminal UI kit (see
- * `Cli/CliKit/interaction.ts`), while every other process gets
- * {@link layerNonInteractive}: messages render as plain status lines and
- * every prompt fails with the typed {@link NonInteractiveTerminal}.
+ * One contract, two renderers:
+ *
+ * - {@link layerSigil} — the interactive Sigil renderer: live rows,
+ *   prompts as real screens, full-screen sessions.
+ * - {@link layerNonInteractive} — append-only plain output for CI, piped
+ *   output, the Alchemist API and tests. Views print once, every prompt,
+ *   screen and session fails with the typed {@link NonInteractiveTerminal}.
+ *
+ * {@link layer} picks between them from the terminal's capabilities, so
+ * callers never branch on the renderer themselves.
  *
  * Child processes (the RPC sidecar, spawned dev children) deliberately do
  * NOT provide this service at all — interaction capability is structural,
@@ -23,9 +25,11 @@ import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import { ChildProcess } from "effect/process";
+import type { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
+import type * as Scope from "effect/Scope";
+import type { ReactNode } from "react";
 import { UserFacingError } from "./UserFacingError.ts";
-import { ANSI_DIM, ANSI_RESET, ansiFg, colorsEnabled } from "./Util/Terminal.ts";
-import { unicodeEnabled } from "./Util/Terminal.ts";
+import { ANSI_DIM, ANSI_RESET, ansiFg, colorsEnabled, unicodeEnabled } from "./Util/Terminal.ts";
 import { glyphsFor, statusColor, type StatusVariant } from "./Util/Theme.ts";
 
 /** The user dismissed the active terminal interaction. */
@@ -107,20 +111,24 @@ export interface MultiSelectOptions<Value> extends Omit<SelectOptions<Value>, "i
   readonly required?: boolean;
 }
 
-export interface AwaitExternalOptions {
-  readonly message: string;
-  readonly waitingLabel: string;
-  readonly url?: string;
-  /** Short code the user must enter on the authorization page. */
+export interface BrowserLoginOptions<A, E, R, E2 = never, R2 = never> {
+  /** Display name, e.g. `"Railway"`; titles the login. */
+  readonly provider: string;
+  /** The page the user logs in on. Opened in their browser for them. */
+  readonly url: string;
+  /** Short code the user confirms on the login page (device flows). */
   readonly code?: string;
-  readonly openFailed?: boolean;
-  /** Open the authorization URL again from the waiting screen. */
-  readonly onOpen?: () => Promise<void>;
-  /** Allow Enter to switch to manual code entry. @default true */
-  readonly allowManualInput?: boolean;
-  readonly inputLabel?: string;
-  readonly placeholder?: string;
-  readonly validate?: (value: string) => string | Error | undefined;
+  /** @default "waiting for browser authorization (up to 5 minutes)…" */
+  readonly waitingLabel?: string;
+  /** Completes the login: a token poll, a CLI process, an OAuth callback. */
+  readonly waitFor: Effect.Effect<A, E, R>;
+  /** Let the user paste a code instead, exchanged for the same result. */
+  readonly manualCode?: {
+    readonly label?: string;
+    readonly placeholder?: string;
+    readonly validate?: (value: string) => string | Error | undefined;
+    readonly exchange: (code: string) => Effect.Effect<A, E2, R2>;
+  };
 }
 
 export interface ProgressOptions {
@@ -132,15 +140,90 @@ export interface ProgressOptions {
   readonly spinning?: boolean;
 }
 
+/** A composable layout. Views are inert; only a renderer draws them. */
+export type View = ReactNode;
+
+/** What the terminal behind this process can do. */
+export interface TerminalCapabilities {
+  /** Whether this process has usable terminal input for prompts and sessions. */
+  readonly input: boolean;
+  readonly columns: number;
+  readonly rows: number;
+  readonly colors: boolean;
+  readonly unicode: boolean;
+  /** Whether full-screen sessions may use the terminal's alternate buffer. */
+  readonly alternateScreen: boolean;
+}
+
+export interface ScreenController<Value> {
+  readonly submit: (value: Value, summary?: View) => void;
+  readonly cancel: () => void;
+}
+
+/**
+ * An interactive scene. The scene owns its local component state while the
+ * renderer owns input streams, serialization, rendering and teardown. Every
+ * prompt is a screen; {@link Interaction} `prompt.screen` runs any other.
+ */
+export interface Screen<Value> {
+  readonly name: string;
+  readonly render: (controller: ScreenController<Value>) => View;
+}
+
+export const Screen = {
+  make: <Value>(
+    name: string,
+    render: (controller: ScreenController<Value>) => View,
+  ): Screen<Value> => ({ name, render }),
+};
+
+/**
+ * Handle for a progress row. Acquired within a `Scope`: the enclosing
+ * scope's close is a release backstop, so an interrupted fiber can never leave
+ * an orphaned row pinning the renderer. Settling early via `succeed`/`fail`/
+ * `close` is the normal path; every settle operation is idempotent.
+ */
+export interface ProgressHandle {
+  readonly update: (options: ProgressOptions) => Effect.Effect<void>;
+  readonly succeed: (message?: string) => Effect.Effect<void>;
+  readonly fail: (message?: string) => Effect.Effect<void>;
+  readonly close: Effect.Effect<void>;
+}
+
+/**
+ * A mounted live view. The view itself is immutable — dynamic content flows
+ * through a caller-owned store that its component subscribes to — so the
+ * handle only controls the block's lifetime. Scope-bound the same way as
+ * {@link ProgressHandle}; `close` settles early and is idempotent.
+ */
+export interface LiveViewHandle {
+  readonly close: Effect.Effect<void>;
+}
+
+export interface LiveViewOptions {
+  /** Place a session shell/header before completed prompt output. */
+  readonly placement?: "beforeTranscript" | "afterTranscript";
+  /** Commit the final view to the static transcript when it closes. */
+  readonly persistOnClose?: boolean;
+}
+
+export interface SessionOptions {
+  /** Take over the terminal's alternate screen buffer when supported. */
+  readonly alternate?: boolean;
+}
+
 /**
  * The capability to ask or tell the human driving this process. Provided
- * by the CLI (terminal-backed) or {@link layerNonInteractive} (plain
- * output, typed prompt failures); never provided in child processes.
+ * by {@link layer}; never provided in child processes.
  */
 export class Interaction extends Context.Service<
   Interaction,
   {
+    readonly terminal: TerminalCapabilities;
+
     readonly output: {
+      /** Append a completed layout to terminal scrollback/output. */
+      readonly print: (view: View) => Effect.Effect<void>;
       readonly info: (message: string | MessageOptions) => Effect.Effect<void>;
       readonly success: (message: string | MessageOptions) => Effect.Effect<void>;
       readonly warning: (message: string | MessageOptions) => Effect.Effect<void>;
@@ -157,46 +240,103 @@ export class Interaction extends Context.Service<
       readonly multiSelect: <Value>(
         options: MultiSelectOptions<Value>,
       ) => Effect.Effect<ReadonlyArray<Value>, InteractionError>;
-      readonly awaitExternal: (
-        options: AwaitExternalOptions,
-      ) => Effect.Effect<string, InteractionError>;
+      /** Run an arbitrary interactive screen. */
+      readonly screen: <Value>(screen: Screen<Value>) => Effect.Effect<Value, InteractionError>;
     };
 
+    /**
+     * Log the user in through their browser: open `url`, show it (and the
+     * device code), and wait for `waitFor`. Fails with `TerminalCancelled`
+     * when the user dismisses the login.
+     */
+    readonly browserLogin: <A, E, R, E2 = never, R2 = never>(
+      options: BrowserLoginOptions<A, E, R, E2, R2>,
+    ) => Effect.Effect<A, E | E2 | InteractionError, R | R2 | ChildProcessSpawner>;
+
+    /**
+     * Mount a live layout while the scope is open. Without an interactive
+     * renderer the view prints once.
+     */
+    readonly live: (
+      view: View,
+      options?: LiveViewOptions,
+    ) => Effect.Effect<LiveViewHandle, never, Scope.Scope>;
+
+    /** Add a mutable progress row, settled through its handle. */
+    readonly progress: (
+      options: ProgressOptions,
+    ) => Effect.Effect<ProgressHandle, never, Scope.Scope>;
+
     /** Run work behind a progress row and collapse it to a final status line. */
     readonly task: <A, E, R>(
       options: ProgressOptions,
       effect: Effect.Effect<A, E, R>,
     ) => Effect.Effect<A, E, R>;
+
+    /**
+     * Keep one renderer alive while an Effect drives screens and prompts. A
+     * nested session reuses the outer renderer and clears the prompts it
+     * showed when it settles.
+     */
+    readonly session: <A, E, R>(
+      effect: Effect.Effect<A, E, R>,
+      options?: SessionOptions,
+    ) => Effect.Effect<A, E | NonInteractiveTerminal, R>;
   }
 >()("Alchemy::Interaction") {}
 
-/** Effectful service accessors for code that must defer acquisition to use time. */
-export const accessors = {
-  output: {
-    info: (message: string | MessageOptions) =>
-      Effect.flatMap(Interaction, (service) => service.output.info(message)),
-    success: (message: string | MessageOptions) =>
-      Effect.flatMap(Interaction, (service) => service.output.success(message)),
-    warning: (message: string | MessageOptions) =>
-      Effect.flatMap(Interaction, (service) => service.output.warning(message)),
-    error: (message: string | MessageOptions) =>
-      Effect.flatMap(Interaction, (service) => service.output.error(message)),
-  },
-  prompt: {
-    text: (options: TextInputOptions) =>
-      Effect.flatMap(Interaction, (service) => service.prompt.text(options)),
-    password: (options: PasswordInputOptions) =>
-      Effect.flatMap(Interaction, (service) => service.prompt.password(options)),
-    confirm: (options: ConfirmOptions) =>
-      Effect.flatMap(Interaction, (service) => service.prompt.confirm(options)),
-    select: <Value>(options: SelectOptions<Value>) =>
-      Effect.flatMap(Interaction, (service) => service.prompt.select(options)),
-    multiSelect: <Value>(options: MultiSelectOptions<Value>) =>
-      Effect.flatMap(Interaction, (service) => service.prompt.multiSelect(options)),
-    awaitExternal: (options: AwaitExternalOptions) =>
-      Effect.flatMap(Interaction, (service) => service.prompt.awaitExternal(options)),
-  },
-};
+// Top-level forms of the service's messages and prompts. Each acquires
+// `Interaction` when it runs, not when it's built, so a provider can hold
+// one in a value without capturing whichever service was ambient then.
+
+export const print = (view: View) => Effect.flatMap(Interaction, (i) => i.output.print(view));
+export const info = (message: string | MessageOptions) =>
+  Effect.flatMap(Interaction, (i) => i.output.info(message));
+export const success = (message: string | MessageOptions) =>
+  Effect.flatMap(Interaction, (i) => i.output.success(message));
+export const warning = (message: string | MessageOptions) =>
+  Effect.flatMap(Interaction, (i) => i.output.warning(message));
+export const error = (message: string | MessageOptions) =>
+  Effect.flatMap(Interaction, (i) => i.output.error(message));
+
+export const text = (options: TextInputOptions) =>
+  Effect.flatMap(Interaction, (i) => i.prompt.text(options));
+export const password = (options: PasswordInputOptions) =>
+  Effect.flatMap(Interaction, (i) => i.prompt.password(options));
+export const confirm = (options: ConfirmOptions) =>
+  Effect.flatMap(Interaction, (i) => i.prompt.confirm(options));
+export const select = <Value>(options: SelectOptions<Value>) =>
+  Effect.flatMap(Interaction, (i) => i.prompt.select(options));
+export const multiSelect = <Value>(options: MultiSelectOptions<Value>) =>
+  Effect.flatMap(Interaction, (i) => i.prompt.multiSelect(options));
+export const browserLogin = <A, E, R, E2 = never, R2 = never>(
+  options: BrowserLoginOptions<A, E, R, E2, R2>,
+) => Effect.flatMap(Interaction, (i) => i.browserLogin(options));
+export const screen = <Value>(scene: Screen<Value>) =>
+  Effect.flatMap(Interaction, (i) => i.prompt.screen(scene));
+
+/**
+ * `task` for any renderer: a scoped progress row settled by the effect's
+ * exit. Interruption (Ctrl+C) is not a failure — the row is dropped instead
+ * of painted as an error.
+ */
+export const taskFromProgress =
+  (progress: Interaction["Service"]["progress"]): Interaction["Service"]["task"] =>
+  (options, effect) =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const handle = yield* progress(options);
+        return yield* effect.pipe(
+          Effect.onExit((exit) =>
+            Exit.isSuccess(exit)
+              ? handle.succeed()
+              : Cause.hasInterruptsOnly(exit.cause)
+                ? handle.close
+                : handle.fail(),
+          ),
+        );
+      }),
+    );
 
 /**
  * Open a URL in the platform's default browser without invoking a shell.
@@ -223,16 +363,50 @@ export const openUrl = (url: string) =>
     }
   }).pipe(Effect.scoped);
 
-export interface NonInteractiveOptions {
+// Bun can hand concurrent dynamic imports of one module a half-evaluated
+// namespace (a TDZ ReferenceError on its exports), so every lazy renderer
+// module is imported through one shared promise.
+const importOnce = <M>(load: () => Promise<M>) => {
+  let module: Promise<M> | undefined;
+  return () => (module ??= load());
+};
+const loadFormat = importOnce(() => import("./Cli/components/view/Format.tsx"));
+const loadSigilRuntime = importOnce(() => import("./Cli/components/view/Runtime.tsx"));
+const loadCapabilities = importOnce(() => import("./Cli/components/capabilities.ts"));
+
+export interface TerminalOptions {
+  readonly stdin?: NodeJS.ReadStream;
   readonly stdout?: NodeJS.WriteStream;
+  readonly stderr?: NodeJS.WriteStream;
+  /** Override automatic TTY input detection. Primarily useful for tests. */
+  readonly input?: boolean;
   readonly colors?: boolean;
   readonly unicode?: boolean;
+  /** Capture console output while the interactive renderer owns the tty. */
+  readonly captureConsole?: boolean;
 }
 
-const makeNonInteractive = (options: NonInteractiveOptions): Interaction["Service"] => {
+export type NonInteractiveOptions = Pick<TerminalOptions, "stdout" | "colors" | "unicode">;
+
+const nonInteractiveFailure = (operation: string) =>
+  new NonInteractiveTerminal({
+    operation,
+    message: `Cannot run ${operation} without an interactive terminal. Provide the equivalent command flags instead.`,
+  });
+
+export const makeNonInteractive = (options: NonInteractiveOptions = {}): Interaction["Service"] => {
   const stdout = options.stdout ?? process.stdout;
   const colors = options.colors ?? colorsEnabled(stdout);
-  const glyphs = glyphsFor(options.unicode ?? unicodeEnabled());
+  const unicode = options.unicode ?? unicodeEnabled();
+  const glyphs = glyphsFor(unicode);
+  const terminal: TerminalCapabilities = {
+    input: false,
+    columns: stdout.columns ?? 80,
+    rows: stdout.rows ?? 24,
+    colors,
+    unicode,
+    alternateScreen: false,
+  };
 
   const colorize = (hex: string, value: string) =>
     colors ? `${ansiFg(hex)}${value}${ANSI_RESET}` : value;
@@ -252,16 +426,52 @@ const makeNonInteractive = (options: NonInteractiveOptions): Interaction["Servic
       stdout.write(`${statusText(variant, text, detail)}\n`);
     });
 
-  const unavailable = (operation: string) =>
-    Effect.fail(
-      new NonInteractiveTerminal({
-        operation,
-        message: `Cannot run ${operation} without an interactive terminal. Provide the equivalent command flags instead.`,
-      }),
+  // Views are React layouts: load the static formatter only when one is
+  // actually printed, so headless processes never pull in the renderer.
+  const print = (view: View) =>
+    Effect.promise(loadFormat).pipe(
+      Effect.map(({ formatView }) =>
+        formatView(view, { ...terminal, columns: stdout.columns ?? terminal.columns }),
+      ),
+      Effect.flatMap((text) =>
+        text === "" ? Effect.void : Effect.sync(() => void stdout.write(`${text}\n`)),
+      ),
+    );
+
+  const unavailable = (operation: string) => Effect.fail(nonInteractiveFailure(operation));
+
+  const progress: Interaction["Service"]["progress"] = (initial) =>
+    Effect.acquireRelease(
+      log("info")({ message: initial.label, detail: initial.detail }).pipe(
+        Effect.map((): ProgressHandle => {
+          let current = initial;
+          let settled = false;
+          const settle = (variant: "success" | "error", message?: string) =>
+            Effect.suspend(() => {
+              if (settled) return Effect.void;
+              settled = true;
+              return log(variant)(message ?? current.label);
+            });
+          return {
+            update: (next) =>
+              Effect.sync(() => {
+                if (!settled) current = next;
+              }),
+            succeed: (message) => settle("success", message),
+            fail: (message) => settle("error", message),
+            close: Effect.sync(() => {
+              settled = true;
+            }),
+          };
+        }),
+      ),
+      (handle) => handle.close,
     );
 
   return {
+    terminal,
     output: {
+      print,
       info: log("info"),
       success: log("success"),
       warning: log("warning"),
@@ -273,47 +483,72 @@ const makeNonInteractive = (options: NonInteractiveOptions): Interaction["Servic
       confirm: () => unavailable("confirmation"),
       select: () => unavailable("selection"),
       multiSelect: () => unavailable("multiple selection"),
-      awaitExternal: () => unavailable("external authorization"),
+      screen: (screen) => unavailable(screen.name),
     },
-    task: (taskOptions, effect) =>
-      Effect.suspend(() => {
-        let settled = false;
-        const settle = (variant: "success" | "error", message?: string) =>
-          Effect.suspend(() => {
-            if (settled) return Effect.void;
-            settled = true;
-            return log(variant)(message ?? taskOptions.label);
-          });
-        return log("info")({
-          message: taskOptions.label,
-          detail: taskOptions.detail,
-        }).pipe(
-          Effect.andThen(
-            effect.pipe(
-              Effect.onExit((exit) =>
-                Exit.isSuccess(exit)
-                  ? settle("success")
-                  : // Interruption (Ctrl+C) is not a failure — leave the row
-                    // unsettled instead of painting a red error status.
-                    Cause.hasInterruptsOnly(exit.cause)
-                    ? Effect.void
-                    : settle("error"),
-              ),
-            ),
-          ),
-        );
+    // Without a screen there's nothing to paste a code into: print the URL
+    // and wait, so device and poll logins still work headless.
+    browserLogin: (login) =>
+      Effect.gen(function* () {
+        const openFailed = yield* Effect.isFailure(openUrl(login.url));
+        yield* log("info")({
+          message: `${login.provider} authorization: ${openFailed ? "open" : "opened"} ${login.url}`,
+          detail: login.code === undefined ? undefined : `code ${login.code}`,
+        });
+        return yield* login.waitFor;
       }),
+    live: (view) => print(view).pipe(Effect.as({ close: Effect.void })),
+    progress,
+    task: taskFromProgress(progress),
+    session: () => unavailable("application"),
   };
 };
 
 /**
- * The default Interaction for processes without a terminal renderer: the
- * programmatic engine API, tests, and any headless embedding. Messages
- * print as plain status lines; every prompt fails immediately with the
- * typed {@link NonInteractiveTerminal}.
+ * The append-only renderer: CI, redirected output, the programmatic engine
+ * API, tests, and any headless embedding. Messages print as plain status
+ * lines; every prompt fails immediately with the typed
+ * {@link NonInteractiveTerminal}.
  */
 export const layerNonInteractive = (options: NonInteractiveOptions = {}) =>
   Layer.effect(
     Interaction,
     Effect.sync(() => makeNonInteractive(options)),
   );
+
+/**
+ * The interactive Sigil renderer, regardless of what the terminal reports.
+ * Prefer {@link layer}, which falls back to plain output without a TTY.
+ */
+export const layerSigil = (options: TerminalOptions = {}) =>
+  Layer.effect(
+    Interaction,
+    Effect.gen(function* () {
+      const { resolveCapabilities } = yield* Effect.promise(loadCapabilities);
+      const { makeRuntime } = yield* Effect.promise(loadSigilRuntime);
+      const { service } = yield* Effect.acquireRelease(
+        Effect.sync(() => makeRuntime(options, { ...resolveCapabilities(options), input: true })),
+        ({ dispose }) => Effect.promise(dispose),
+      );
+      return service;
+    }),
+  );
+
+/**
+ * The renderer this process's terminal supports: the interactive one when
+ * stdin and stdout are a TTY and nothing opted out (`--no-input`, CI, coding
+ * agents), plain output otherwise.
+ */
+export const layer = (options: TerminalOptions = {}) =>
+  Layer.unwrap(
+    Effect.gen(function* () {
+      const { resolveCapabilities } = yield* Effect.promise(loadCapabilities);
+      const capabilities = resolveCapabilities(options);
+      return capabilities.input
+        ? layerSigil(options)
+        : layerNonInteractive({
+            stdout: options.stdout,
+            colors: capabilities.colors,
+            unicode: capabilities.unicode,
+          });
+    }),
+  );

package/src/Local/LocalProvider.ts

@@ -1,5 +1,6 @@
 /** @effect-diagnostics anyUnknownInErrorContext:off */
 
+import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
@@ -11,6 +12,7 @@ import type { Platform } from "../Platform.ts";
 import type { ProviderService } from "../Provider.ts";
 import type { ScopedPlanStatusSession } from "../Report.ts";
 import type { ResourceBinding, ResourceClassLike, ResourceLike } from "../Resource.ts";
+import { LogAnnotation } from "../Util/LogAnnotation.ts";
 import { sha256 } from "../Util/sha256.ts";
 import * as RpcProvider from "./RpcProvider.ts";
 
@@ -283,7 +285,27 @@ export const make = <
       // shutdown, interrupting every registered instance and running its
       // finalizers (killing the processes).
       // Close independent instances concurrently at provider shutdown.
-      const rootScope = yield* Scope.fork(yield* Effect.scope, "parallel");
+      const providerScope = yield* Effect.scope;
+      // Registered before the fork, so it runs after every instance closed.
+      let closingAt: number | undefined;
+      yield* Scope.addFinalizer(
+        providerScope,
+        Effect.flatMap(Clock.currentTimeMillis, (now) =>
+          closingAt === undefined
+            ? Effect.void
+            : Effect.logDebug(`shutdown: stopped ${cls.Type} instances in ${now - closingAt}ms`),
+        ),
+      );
+      const rootScope = yield* Scope.fork(providerScope, "parallel");
+      // Registered after the fork, so it runs first: the shutdown start.
+      yield* Scope.addFinalizer(
+        providerScope,
+        Effect.flatMap(Clock.currentTimeMillis, (now) => {
+          if (instances.size === 0) return Effect.void;
+          closingAt = now;
+          return Effect.logDebug(`shutdown: stopping ${instances.size} ${cls.Type} instance(s)`);
+        }),
+      );
 
       // Keyed by FQN (namespace path + logical id): a restart replaces the
       // entry, a replacement's new generation overwrites it (and the old
@@ -313,9 +335,14 @@ export const make = <
         return { config, configHash };
       });
 
-      const teardown = Effect.fn(function* (instance: Instance<R["Attributes"]>) {
+      const teardown = Effect.fn(function* (fqn: string, instance: Instance<R["Attributes"]>) {
+        const start = yield* Clock.currentTimeMillis;
         yield* Fiber.interrupt(instance.fiber);
         yield* Scope.close(instance.scope, Exit.void);
+        const end = yield* Clock.currentTimeMillis;
+        yield* Effect.logDebug(`stopped ${fqn} in ${end - start}ms`).pipe(
+          Effect.annotateLogs(LogAnnotation.fqn, fqn),
+        );
       });
 
       const startInstance = Effect.fn(function* (
@@ -349,8 +376,12 @@ export const make = <
           Effect.onExit((exit) =>
             exit._tag === "Failure"
               ? // A failed start must not linger as "running" — the next
-                // plan should report `update` and try again.
-                invalidate
+                // plan should report `update` and try again — nor keep what
+                // it acquired: the instance scope would otherwise hold a
+                // process that outlived its start (one still waiting for
+                // its URL when the deploy was interrupted, say) until the
+                // provider shut down.
+                invalidate.pipe(Effect.andThen(Scope.close(scope, exit)))
               : Effect.void,
           ),
         );
@@ -431,18 +462,18 @@ export const make = <
               const existing = instances.get(fqn);
               if (existing) {
                 if (existing.configHash === configHash) {
-                  yield* Effect.log(`[${fqn}] No changes, using existing instance`);
+                  yield* Effect.log(`No changes, using existing instance`);
                   // Adopt the newest instanceId so a later replacement's
                   // old-generation delete cannot tear this instance down.
                   existing.instanceId = instanceId;
                   return yield* Fiber.join(existing.fiber);
                 }
-                yield* Effect.log(`[${fqn}] Changes detected, restarting instance`);
-                yield* teardown(existing);
+                yield* Effect.log(`Changes detected, restarting instance`);
+                yield* teardown(fqn, existing);
                 instances.delete(fqn);
               }
               return yield* startInstance(input, session, config, configHash);
-            }),
+            }).pipe(Effect.annotateLogs(LogAnnotation.fqn, fqn)),
           );
         }),
         delete: Effect.fn(function* ({
@@ -465,7 +496,7 @@ export const make = <
                 return;
               }
               if (existing) {
-                yield* teardown(existing);
+                yield* teardown(fqn, existing);
                 instances.delete(fqn);
               }
               // Runs even when nothing is registered: cross-restart state

package/src/Local/RpcProvider.ts

@@ -1,5 +1,6 @@
 import type * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import { identity } from "effect/Function";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
@@ -13,6 +14,7 @@ import type { ResourceClassLike, ResourceLike } from "../Resource.ts";
 import { ResourceContext } from "../ResourceContext.ts";
 import { Stack } from "../Stack.ts";
 import { Stage } from "../Stage.ts";
+import { LogAnnotation } from "../Util/LogAnnotation.ts";
 import { RpcProviderProxy } from "./RpcProviderProxy.ts";
 
 /**
@@ -221,8 +223,16 @@ export const effect = <
                     )
                   : Layer.empty,
               );
+              if (Stream.isStream(result)) return result.pipe(Stream.provide(services));
+              // In a sidecar the engine's per-resource annotation doesn't
+              // cross the RPC boundary: tag the call's logs here.
+              const fqn =
+                Predicate.hasProperty(args[0], "fqn") && Predicate.isString(args[0].fqn)
+                  ? args[0].fqn
+                  : undefined;
               return result.pipe(
-                Stream.isStream(result) ? Stream.provide(services) : Effect.provide(services),
+                Effect.provide(services),
+                fqn === undefined ? identity : Effect.annotateLogs(LogAnnotation.fqn, fqn),
               );
             };
           },