@miaws/miaw 1.18.3 → 1.18.5

package/src/effect/app-runtime.ts

@@ -0,0 +1,132 @@
+import { Layer, ManagedRuntime } from "effect"
+import { attach } from "./run-service"
+import * as Observability from "@miaw/core/observability"
+
+import { FSUtil } from "@miaw/core/fs-util"
+import { Database } from "@miaw/core/database/database"
+import { Auth } from "@/auth"
+import { Account } from "@/account/account"
+import { Config } from "@/config/config"
+import { Git } from "@/git"
+import { Ripgrep } from "@miaw/core/ripgrep"
+import { Storage } from "@/storage/storage"
+import { Snapshot } from "@/snapshot"
+import { Plugin } from "@/plugin"
+import { ModelsDev } from "@miaw/core/models-dev"
+import { Provider } from "@/provider/provider"
+import { ProviderAuth } from "@/provider/auth"
+import { Agent } from "@/agent/agent"
+import { Skill } from "@/skill"
+import { Discovery } from "@/skill/discovery"
+import { Question } from "@/question"
+import { Permission } from "@/permission"
+import { Todo } from "@/session/todo"
+import { Session } from "@/session/session"
+import { SessionStatus } from "@/session/status"
+import { SessionRunState } from "@/session/run-state"
+import { SessionProcessor } from "@/session/processor"
+import { SessionCompaction } from "@/session/compaction"
+import { SessionRevert } from "@/session/revert"
+import { SessionSummary } from "@/session/summary"
+import { SessionPrompt } from "@/session/prompt"
+import { Instruction } from "@/session/instruction"
+import { LLM } from "@/session/llm"
+import { LSP } from "@/lsp/lsp"
+import { MCP } from "@/mcp"
+import { McpAuth } from "@/mcp/auth"
+import { Command } from "@/command"
+import { Truncate } from "@/tool/truncate"
+import { ToolRegistry } from "@/tool/registry"
+import { Format } from "@/format"
+import { InstanceLayer } from "@/project/instance-layer"
+import { Project } from "@/project/project"
+import { Vcs } from "@/project/vcs"
+import { Workspace } from "@/control-plane/workspace"
+import { Worktree } from "@/worktree"
+import { Installation } from "@/installation"
+import { ShareNext } from "@/share/share-next"
+import { SessionShare } from "@/share/session"
+import { Npm } from "@miaw/core/npm"
+import { memoMap } from "@miaw/core/effect/memo-map"
+import { BackgroundJob } from "@/background/job"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+import { EventV2Bridge } from "@/event-v2-bridge"
+
+export const AppLayer = Layer.mergeAll(
+  Npm.defaultLayer,
+  FSUtil.defaultLayer,
+  Database.defaultLayer,
+  Auth.defaultLayer,
+  Account.defaultLayer,
+  Config.defaultLayer,
+  Git.defaultLayer,
+  Storage.defaultLayer,
+  Snapshot.defaultLayer,
+  Plugin.defaultLayer,
+  ModelsDev.defaultLayer,
+  Provider.defaultLayer,
+  ProviderAuth.defaultLayer,
+  Agent.defaultLayer,
+  Skill.defaultLayer,
+  Discovery.defaultLayer,
+  Question.defaultLayer,
+  Permission.defaultLayer,
+  Todo.defaultLayer,
+  Session.defaultLayer,
+  SessionStatus.defaultLayer,
+  BackgroundJob.defaultLayer,
+  RuntimeFlags.defaultLayer,
+  EventV2Bridge.defaultLayer,
+  SessionRunState.defaultLayer,
+  SessionProcessor.defaultLayer,
+  SessionCompaction.defaultLayer,
+  SessionRevert.defaultLayer,
+  SessionSummary.defaultLayer,
+  SessionPrompt.defaultLayer,
+  Instruction.defaultLayer,
+  LLM.defaultLayer,
+  LSP.defaultLayer,
+  MCP.defaultLayer,
+  McpAuth.defaultLayer,
+  Command.defaultLayer,
+  Truncate.defaultLayer,
+  ToolRegistry.defaultLayer,
+  Format.defaultLayer,
+  Project.defaultLayer,
+  Vcs.defaultLayer,
+  Workspace.defaultLayer,
+  Worktree.appLayer,
+  Installation.defaultLayer,
+  ShareNext.defaultLayer,
+  SessionShare.defaultLayer,
+).pipe(
+  Layer.provideMerge(Ripgrep.defaultLayer),
+  Layer.provideMerge(InstanceLayer.layer),
+  Layer.provideMerge(Observability.layer),
+)
+
+const rt = ManagedRuntime.make(AppLayer, { memoMap })
+type Runtime = Pick<typeof rt, "runSync" | "runPromise" | "runPromiseExit" | "runFork" | "runCallback" | "dispose">
+
+/** Services provided by AppRuntime — i.e. what an Effect run via AppRuntime.runPromise can yield. */
+export type AppServices = ManagedRuntime.ManagedRuntime.Services<typeof rt>
+const wrap = (effect: Parameters<typeof rt.runSync>[0]) => attach(effect as never) as never
+
+export const AppRuntime: Runtime = {
+  runSync(effect) {
+    return rt.runSync(wrap(effect))
+  },
+  runPromise(effect, options) {
+    return rt.runPromise(wrap(effect), options)
+  },
+  runPromiseExit(effect, options) {
+    return rt.runPromiseExit(wrap(effect), options)
+  },
+  runFork(effect) {
+    return rt.runFork(wrap(effect))
+  },
+  runCallback(effect) {
+    return rt.runCallback(wrap(effect))
+  },
+  dispose: () => rt.dispose(),
+}

package/src/effect/bootstrap-runtime.ts

@@ -0,0 +1,23 @@
+import { Layer, ManagedRuntime } from "effect"
+
+import { Plugin } from "@/plugin"
+import { LSP } from "@/lsp/lsp"
+import { Format } from "@/format"
+import { ShareNext } from "@/share/share-next"
+import { Vcs } from "@/project/vcs"
+import { Snapshot } from "@/snapshot"
+import { Config } from "@/config/config"
+import * as Observability from "@miaw/core/observability"
+import { memoMap } from "@miaw/core/effect/memo-map"
+
+export const BootstrapLayer = Layer.mergeAll(
+  Config.defaultLayer,
+  Plugin.defaultLayer,
+  ShareNext.defaultLayer,
+  Format.defaultLayer,
+  LSP.defaultLayer,
+  Vcs.defaultLayer,
+  Snapshot.defaultLayer,
+).pipe(Layer.provide(Observability.layer))
+
+export const BootstrapRuntime = ManagedRuntime.make(BootstrapLayer, { memoMap })

package/src/effect/bridge.ts

@@ -0,0 +1,84 @@
+import { Context, Effect, Exit, Fiber } from "effect"
+import { WorkspaceContext } from "@/control-plane/workspace-context"
+import type { WorkspaceV2 } from "@miaw/core/workspace"
+import { InstanceRef, WorkspaceRef } from "./instance-ref"
+import { attachWith } from "./run-service"
+
+export interface Shape {
+  readonly promise: <A, E, R>(effect: Effect.Effect<A, E, R>) => Promise<A>
+  readonly fork: <A, E, R>(effect: Effect.Effect<A, E, R>) => Fiber.Fiber<A, E>
+  readonly run: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E>
+  readonly bind: <Args extends readonly unknown[], Result>(fn: (...args: Args) => Result) => (...args: Args) => Result
+}
+
+function restoreWorkspace<R>(workspace: WorkspaceV2.ID | undefined, fn: () => R): R {
+  if (workspace !== undefined) return WorkspaceContext.restore(workspace, fn)
+  return fn()
+}
+
+function captureSync() {
+  const fiber = Fiber.getCurrent()
+  const instance = fiber ? Context.getReferenceUnsafe(fiber.context, InstanceRef) : undefined
+  const workspace =
+    (fiber ? Context.getReferenceUnsafe(fiber.context, WorkspaceRef) : undefined) ?? WorkspaceContext.workspaceID
+  return { instance, workspace }
+}
+
+export const bind = <Args extends readonly unknown[], Result>(fn: (...args: Args) => Result) => {
+  const captured = captureSync()
+  return (...args: Args) =>
+    restoreWorkspace(captured.workspace, () =>
+      Effect.runSync(
+        attachWith(
+          Effect.sync(() => fn(...args)),
+          captured,
+        ),
+      ),
+    )
+}
+
+/**
+ * Bridge from Effect into a Promise-returning JS callback while preserving
+ * `WorkspaceContext` AsyncLocalStorage for callback code that still reads it.
+ * `InstanceRef` is captured for effects run through the returned bridge APIs;
+ * plain JS callbacks that need it should receive the ref explicitly.
+ *
+ * Mirrors `Effect.promise` but restores workspace ALS first.
+ */
+export const fromPromise = <T>(fn: () => Promise<T> | T): Effect.Effect<T> =>
+  Effect.gen(function* () {
+    const workspace = yield* WorkspaceRef
+    return yield* Effect.promise(() => Promise.resolve(restoreWorkspace(workspace, () => fn())))
+  })
+
+export function make(): Effect.Effect<Shape> {
+  return Effect.gen(function* () {
+    const ctx = yield* Effect.context()
+    const captured = captureSync()
+    const instance = (yield* InstanceRef) ?? captured.instance
+    const workspace = (yield* WorkspaceRef) ?? captured.workspace
+    const wrap = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+      attachWith(effect.pipe(Effect.provide(ctx)) as Effect.Effect<A, E, never>, { instance, workspace })
+
+    return {
+      promise: <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        restoreWorkspace(workspace, () => Effect.runPromise(wrap(effect))),
+      fork: <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        restoreWorkspace(workspace, () => Effect.runFork(wrap(effect))),
+      run: <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        Effect.callback<A, E>((resume) => {
+          restoreWorkspace(workspace, () =>
+            Effect.runPromiseExit(wrap(effect)).then((exit) =>
+              resume(Exit.isSuccess(exit) ? Effect.succeed(exit.value) : Effect.failCause(exit.cause)),
+            ),
+          )
+        }),
+      bind:
+        <Args extends readonly unknown[], Result>(fn: (...args: Args) => Result) =>
+        (...args: Args) =>
+          restoreWorkspace(workspace, () => Effect.runSync(wrap(Effect.sync(() => fn(...args))))),
+    } satisfies Shape
+  })
+}
+
+export * as EffectBridge from "./bridge"

package/src/effect/config-service.ts

@@ -0,0 +1,67 @@
+import { Config, Context, Effect, Layer } from "effect"
+
+type ConfigMap = Record<string, Config.Config<unknown>>
+
+/**
+ * The service shape inferred from an object of Effect `Config` definitions.
+ */
+export type Shape<Fields extends ConfigMap> = {
+  readonly [Key in keyof Fields]: Config.Success<Fields[Key]>
+}
+
+/**
+ * A Context service class with generated layers for config-backed services.
+ */
+export type ServiceClass<Self, Id extends string, Service> = Context.ServiceClass<Self, Id, Service> & {
+  /** Provide already-parsed config, useful in tests. */
+  readonly layer: (input: Service) => Layer.Layer<Self>
+  /** Parse config once from the active Effect ConfigProvider and provide the service. */
+  readonly defaultLayer: Layer.Layer<Self, Config.ConfigError>
+}
+
+/**
+ * Create a Context service whose implementation is derived from Effect `Config`.
+ *
+ * This keeps Effect `Config` as the source of truth for env names, defaults, and
+ * validation while generating a typed service plus convenient production/test
+ * layers.
+ *
+ * ```ts
+ * class ServerAuthConfig extends ConfigService.Service<ServerAuthConfig>()(
+ *   "@miaw/ServerAuthConfig",
+ *   {
+ *     password: Config.string("MIAW_SERVER_PASSWORD").pipe(Config.option),
+ *     username: Config.string("MIAW_SERVER_USERNAME").pipe(Config.withDefault("miaw")),
+ *   },
+ * ) {}
+ *
+ * const live = ServerAuthConfig.defaultLayer
+ * const test = ServerAuthConfig.layer({ password: Option.some("secret"), username: "kit" })
+ * ```
+ */
+export const Service =
+  <Self>() =>
+  <const Id extends string, const Fields extends ConfigMap>(id: Id, fields: Fields) => {
+    class ConfigTag extends Context.Service<Self, Shape<Fields>>()(id) {
+      static layer(input: Shape<Fields>) {
+        return Layer.succeed(this, this.of(input))
+      }
+
+      static get defaultLayer() {
+        const tag = this
+        return Layer.effect(
+          tag,
+          Effect.gen(function* () {
+            const config = yield* Config.all(fields)
+            // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- Config.all preserves the field shape, but its conditional return type also supports iterable inputs.
+            return tag.of(config as Shape<Fields>)
+          }),
+        )
+      }
+    }
+
+    // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- The generated class carries typed static helpers.
+    return ConfigTag as ServiceClass<Self, Id, Shape<Fields>>
+  }
+
+export * as ConfigService from "./config-service"

package/src/effect/instance-ref.ts

@@ -0,0 +1,11 @@
+import { Context } from "effect"
+import type { InstanceContext } from "@/project/instance-context"
+import type { WorkspaceV2 } from "@miaw/core/workspace"
+
+export const InstanceRef = Context.Reference<InstanceContext | undefined>("~miaw/InstanceRef", {
+  defaultValue: () => undefined,
+})
+
+export const WorkspaceRef = Context.Reference<WorkspaceV2.ID | undefined>("~miaw/WorkspaceRef", {
+  defaultValue: () => undefined,
+})

package/src/effect/instance-registry.ts

@@ -0,0 +1,12 @@
+const disposers = new Set<(directory: string) => Promise<void>>()
+
+export function registerDisposer(disposer: (directory: string) => Promise<void>) {
+  disposers.add(disposer)
+  return () => {
+    disposers.delete(disposer)
+  }
+}
+
+export async function disposeInstance(directory: string) {
+  await Promise.allSettled([...disposers].map((disposer) => disposer(directory)))
+}

package/src/effect/instance-state.ts

@@ -0,0 +1,69 @@
+import { Effect, ScopedCache, Scope } from "effect"
+import type { InstanceContext } from "@/project/instance-context"
+import { InstanceRef, WorkspaceRef } from "./instance-ref"
+import { registerDisposer } from "./instance-registry"
+import { WorkspaceContext } from "@/control-plane/workspace-context"
+
+const TypeId = "~miaw/InstanceState"
+
+export interface InstanceState<A, E = never, R = never> {
+  readonly [TypeId]: typeof TypeId
+  readonly cache: ScopedCache.ScopedCache<string, A, E, R>
+}
+
+export const context = Effect.gen(function* () {
+  const ctx = yield* InstanceRef
+  if (!ctx) return yield* Effect.die(new Error("InstanceRef not provided"))
+  return ctx
+})
+
+export const workspaceID = Effect.gen(function* () {
+  return (yield* WorkspaceRef) ?? WorkspaceContext.workspaceID
+})
+
+export const directory = Effect.map(context, (ctx) => ctx.directory)
+
+export const make = <A, E = never, R = never>(
+  init: (ctx: InstanceContext) => Effect.Effect<A, E, R | Scope.Scope>,
+): Effect.Effect<InstanceState<A, E, Exclude<R, Scope.Scope>>, never, R | Scope.Scope> =>
+  Effect.gen(function* () {
+    const cache = yield* ScopedCache.make<string, A, E, R>({
+      capacity: Number.POSITIVE_INFINITY,
+      lookup: () =>
+        Effect.gen(function* () {
+          return yield* init(yield* context)
+        }),
+    })
+
+    const off = registerDisposer((directory) => Effect.runPromise(ScopedCache.invalidate(cache, directory)))
+    yield* Effect.addFinalizer(() => Effect.sync(off))
+
+    return {
+      [TypeId]: TypeId,
+      cache,
+    }
+  })
+
+export const get = <A, E, R>(self: InstanceState<A, E, R>) =>
+  Effect.gen(function* () {
+    return yield* ScopedCache.get(self.cache, yield* directory)
+  })
+
+export const use = <A, E, R, B>(self: InstanceState<A, E, R>, select: (value: A) => B) => Effect.map(get(self), select)
+
+export const useEffect = <A, E, R, B, E2, R2>(
+  self: InstanceState<A, E, R>,
+  select: (value: A) => Effect.Effect<B, E2, R2>,
+) => Effect.flatMap(get(self), select)
+
+export const has = <A, E, R>(self: InstanceState<A, E, R>) =>
+  Effect.gen(function* () {
+    return yield* ScopedCache.has(self.cache, yield* directory)
+  })
+
+export const invalidate = <A, E, R>(self: InstanceState<A, E, R>) =>
+  Effect.gen(function* () {
+    return yield* ScopedCache.invalidate(self.cache, yield* directory)
+  })
+
+export * as InstanceState from "./instance-state"

package/src/effect/promise.ts

@@ -0,0 +1,17 @@
+import { Cause, Effect } from "effect"
+
+export function refineRejection<A, E>(
+  evaluate: (signal: AbortSignal) => PromiseLike<A>,
+  refine: (cause: unknown) => E | undefined,
+) {
+  return Effect.tryPromise(evaluate).pipe(
+    Effect.catch((error) => {
+      const cause = Cause.isUnknownError(error) ? error.cause : error
+      const refined = refine(cause)
+      if (refined !== undefined) return Effect.fail(refined)
+      return Effect.die(cause)
+    }),
+  )
+}
+
+export * as EffectPromise from "./promise"

package/src/effect/run-service.ts

@@ -0,0 +1,47 @@
+import { Effect, Fiber, Layer, ManagedRuntime } from "effect"
+import * as Context from "effect/Context"
+import { InstanceRef, WorkspaceRef } from "./instance-ref"
+import * as Observability from "@miaw/core/observability"
+import { WorkspaceContext } from "@/control-plane/workspace-context"
+import type { InstanceContext } from "@/project/instance-context"
+import { memoMap } from "@miaw/core/effect/memo-map"
+
+type Refs = {
+  instance?: InstanceContext
+  workspace?: string
+}
+
+export function attachWith<A, E, R>(effect: Effect.Effect<A, E, R>, refs: Refs): Effect.Effect<A, E, R> {
+  if (!refs.instance && !refs.workspace) return effect
+  if (!refs.instance) return effect.pipe(Effect.provideService(WorkspaceRef, refs.workspace))
+  if (!refs.workspace) return effect.pipe(Effect.provideService(InstanceRef, refs.instance))
+  return effect.pipe(
+    Effect.provideService(InstanceRef, refs.instance),
+    Effect.provideService(WorkspaceRef, refs.workspace),
+  )
+}
+
+export function attach<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> {
+  const workspace = WorkspaceContext.workspaceID
+  const fiber = Fiber.getCurrent()
+  return attachWith(effect, {
+    instance: fiber ? Context.getReferenceUnsafe(fiber.context, InstanceRef) : undefined,
+    workspace: workspace ?? (fiber ? Context.getReferenceUnsafe(fiber.context, WorkspaceRef) : undefined),
+  })
+}
+
+export function makeRuntime<I, S, E>(service: Context.Service<I, S>, layer: Layer.Layer<I, E>) {
+  let rt: ManagedRuntime.ManagedRuntime<I, E> | undefined
+  const getRuntime = () => (rt ??= ManagedRuntime.make(Layer.provideMerge(layer, Observability.layer), { memoMap }))
+
+  return {
+    runSync: <A, Err>(fn: (svc: S) => Effect.Effect<A, Err, I>) => getRuntime().runSync(attach(service.use(fn))),
+    runPromiseExit: <A, Err>(fn: (svc: S) => Effect.Effect<A, Err, I>, options?: Effect.RunOptions) =>
+      getRuntime().runPromiseExit(attach(service.use(fn)), options),
+    runPromise: <A, Err>(fn: (svc: S) => Effect.Effect<A, Err, I>, options?: Effect.RunOptions) =>
+      getRuntime().runPromise(attach(service.use(fn)), options),
+    runFork: <A, Err>(fn: (svc: S) => Effect.Effect<A, Err, I>) => getRuntime().runFork(attach(service.use(fn))),
+    runCallback: <A, Err>(fn: (svc: S) => Effect.Effect<A, Err, I>) =>
+      getRuntime().runCallback(attach(service.use(fn))),
+  }
+}

package/src/effect/runner.ts

@@ -0,0 +1,217 @@
+import { Cause, Deferred, Effect, Exit, Fiber, Latch, Schema, Scope, SynchronizedRef } from "effect"
+
+export interface Runner<A, E = never> {
+  readonly state: State<A, E>
+  readonly busy: boolean
+  readonly ensureRunning: (work: Effect.Effect<A, E>) => Effect.Effect<A, E>
+  readonly startShell: (work: Effect.Effect<A, E>, ready?: Latch.Latch) => Effect.Effect<A, E | Busy>
+  readonly cancel: Effect.Effect<void>
+}
+
+export class Cancelled extends Schema.TaggedErrorClass<Cancelled>()("RunnerCancelled", {}) {}
+export class Busy extends Schema.TaggedErrorClass<Busy>()("RunnerBusy", {}) {}
+
+interface RunHandle<A, E> {
+  id: number
+  done: Deferred.Deferred<A, E | Cancelled>
+  fiber: Fiber.Fiber<A, E>
+}
+
+interface ShellHandle<A, E> {
+  id: number
+  cancelled: Deferred.Deferred<void>
+  ready?: Latch.Latch
+  fiber: Fiber.Fiber<A, E>
+}
+
+interface PendingHandle<A, E> {
+  id: number
+  done: Deferred.Deferred<A, E | Cancelled>
+  work: Effect.Effect<A, E>
+}
+
+export type State<A, E> =
+  | { readonly _tag: "Idle" }
+  | { readonly _tag: "Running"; readonly run: RunHandle<A, E> }
+  | { readonly _tag: "Shell"; readonly shell: ShellHandle<A, E> }
+  | { readonly _tag: "ShellThenRun"; readonly shell: ShellHandle<A, E>; readonly run: PendingHandle<A, E> }
+
+export const make = <A, E = never>(
+  scope: Scope.Scope,
+  opts?: {
+    onIdle?: Effect.Effect<void>
+    onBusy?: Effect.Effect<void>
+    onInterrupt?: Effect.Effect<A, E>
+  },
+): Runner<A, E> => {
+  const ref = SynchronizedRef.makeUnsafe<State<A, E>>({ _tag: "Idle" })
+  const idle = opts?.onIdle ?? Effect.void
+  const onBusy = opts?.onBusy ?? Effect.void
+  const onInterrupt = opts?.onInterrupt
+  let ids = 0
+
+  const state = () => SynchronizedRef.getUnsafe(ref)
+  const next = () => {
+    ids += 1
+    return ids
+  }
+
+  const complete = (done: Deferred.Deferred<A, E | Cancelled>, exit: Exit.Exit<A, E>) =>
+    Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)
+      ? Deferred.fail(done, new Cancelled()).pipe(Effect.asVoid)
+      : Deferred.done(done, exit).pipe(Effect.asVoid)
+
+  const awaitDone = (done: Deferred.Deferred<A, E | Cancelled>) =>
+    Deferred.await(done).pipe(Effect.catchTag("RunnerCancelled", (e) => onInterrupt ?? Effect.die(e)))
+
+  const idleIfCurrent = () =>
+    SynchronizedRef.modify(ref, (st) => [st._tag === "Idle" ? idle : Effect.void, st] as const).pipe(Effect.flatten)
+
+  const finishRun = (id: number, done: Deferred.Deferred<A, E | Cancelled>, exit: Exit.Exit<A, E>) =>
+    SynchronizedRef.modify(
+      ref,
+      (st) =>
+        [
+          Effect.gen(function* () {
+            if (st._tag === "Running" && st.run.id === id) yield* idle
+            yield* complete(done, exit)
+          }),
+          st._tag === "Running" && st.run.id === id ? ({ _tag: "Idle" } as const) : st,
+        ] as const,
+    ).pipe(Effect.flatten)
+
+  const startRun = (work: Effect.Effect<A, E>, done: Deferred.Deferred<A, E | Cancelled>) =>
+    Effect.gen(function* () {
+      const id = next()
+      const fiber = yield* work.pipe(
+        Effect.onExit((exit) => finishRun(id, done, exit)),
+        Effect.forkIn(scope),
+      )
+      return { id, done, fiber } satisfies RunHandle<A, E>
+    })
+
+  const finishShell = (id: number) =>
+    SynchronizedRef.modifyEffect(
+      ref,
+      Effect.fnUntraced(function* (st) {
+        if (st._tag === "Shell" && st.shell.id === id) {
+          return [idle, { _tag: "Idle" }] as const
+        }
+        if (st._tag === "ShellThenRun" && st.shell.id === id) {
+          const run = yield* startRun(st.run.work, st.run.done)
+          return [Effect.void, { _tag: "Running", run }] as const
+        }
+        return [Effect.void, st] as const
+      }),
+    ).pipe(Effect.flatten)
+
+  const stopShell = (shell: ShellHandle<A, E>) =>
+    Effect.gen(function* () {
+      if (shell.ready) yield* shell.ready.await.pipe(Effect.exit, Effect.asVoid)
+      yield* Deferred.succeed(shell.cancelled, undefined).pipe(Effect.asVoid)
+      yield* Fiber.interrupt(shell.fiber)
+    })
+
+  const ensureRunning = (work: Effect.Effect<A, E>) =>
+    SynchronizedRef.modifyEffect(
+      ref,
+      Effect.fnUntraced(function* (st) {
+        switch (st._tag) {
+          case "Running":
+          case "ShellThenRun":
+            return [awaitDone(st.run.done), st] as const
+          case "Shell": {
+            const run = {
+              id: next(),
+              done: yield* Deferred.make<A, E | Cancelled>(),
+              work,
+            } satisfies PendingHandle<A, E>
+            return [awaitDone(run.done), { _tag: "ShellThenRun", shell: st.shell, run }] as const
+          }
+          case "Idle": {
+            const done = yield* Deferred.make<A, E | Cancelled>()
+            const run = yield* startRun(work, done)
+            return [awaitDone(done), { _tag: "Running", run }] as const
+          }
+        }
+      }),
+    ).pipe(Effect.flatten)
+
+  const startShell = (work: Effect.Effect<A, E>, ready?: Latch.Latch): Effect.Effect<A, E | Busy> =>
+    SynchronizedRef.modifyEffect(
+      ref,
+      Effect.fnUntraced(function* (st) {
+        if (st._tag !== "Idle") {
+          const reject: Effect.Effect<A, E | Busy> = Effect.fail(new Busy())
+          return [reject, st] as const
+        }
+        yield* onBusy
+        const id = next()
+        const cancelled = yield* Deferred.make<void>()
+        const fiber = yield* work.pipe(Effect.ensuring(finishShell(id)), Effect.forkChild)
+        const shell = { id, cancelled, ready, fiber } satisfies ShellHandle<A, E>
+        return [
+          Effect.gen(function* () {
+            const exit = yield* Fiber.await(fiber)
+            if (Exit.isSuccess(exit)) return exit.value
+            if (
+              Cause.hasInterruptsOnly(exit.cause) ||
+              ((yield* Deferred.isDone(cancelled)) && Cause.hasInterrupts(exit.cause) && !Cause.hasDies(exit.cause))
+            ) {
+              if (onInterrupt) return yield* onInterrupt
+              return yield* Effect.die(new Cancelled())
+            }
+            return yield* Effect.failCause(exit.cause)
+          }),
+          { _tag: "Shell", shell },
+        ] as const
+      }),
+    ).pipe(Effect.flatten)
+
+  const cancel = SynchronizedRef.modify(ref, (st) => {
+    switch (st._tag) {
+      case "Idle":
+        return [Effect.void, st] as const
+      case "Running":
+        return [
+          Effect.gen(function* () {
+            yield* Fiber.interrupt(st.run.fiber)
+            yield* Deferred.fail(st.run.done, new Cancelled()).pipe(Effect.asVoid)
+            yield* idleIfCurrent()
+          }),
+          { _tag: "Idle" } as const,
+        ] as const
+      case "Shell":
+        return [
+          Effect.gen(function* () {
+            yield* stopShell(st.shell)
+            yield* idleIfCurrent()
+          }),
+          { _tag: "Idle" } as const,
+        ] as const
+      case "ShellThenRun":
+        return [
+          Effect.gen(function* () {
+            yield* stopShell(st.shell)
+            yield* Deferred.fail(st.run.done, new Cancelled()).pipe(Effect.asVoid)
+            yield* idleIfCurrent()
+          }),
+          { _tag: "Idle" } as const,
+        ] as const
+    }
+  }).pipe(Effect.flatten)
+
+  return {
+    get state() {
+      return state()
+    },
+    get busy() {
+      return state()._tag !== "Idle"
+    },
+    ensureRunning,
+    startShell,
+    cancel,
+  }
+}
+
+export * as Runner from "./runner"