effect 4.0.2 → 4.0.3

package/src/Stdio.ts

@@ -79,6 +79,12 @@ export interface Stdio {
    * @since 4.0.0
    */
   readonly stdoutIsTerminal: Effect.Effect<boolean>
+  /**
+   * Whether standard error is attached to a terminal.
+   *
+   * @since 4.0.0
+   */
+  readonly stderrIsTerminal: Effect.Effect<boolean>
   stdout(options?: {
     readonly endOnDone?: boolean | undefined
   }): Sink.Sink<void, string | Uint8Array, never, PlatformError>
@@ -127,12 +133,13 @@ export const Stdio: Context.Service<Stdio, Stdio> = Context.Service<Stdio>(TypeI
  */
 export const make = (
   options:
-    & Omit<Stdio, TypeId | "stdinIsTerminal" | "stdoutIsTerminal">
-    & Partial<Pick<Stdio, "stdinIsTerminal" | "stdoutIsTerminal">>
+    & Omit<Stdio, TypeId | "stdinIsTerminal" | "stdoutIsTerminal" | "stderrIsTerminal">
+    & Partial<Pick<Stdio, "stdinIsTerminal" | "stdoutIsTerminal" | "stderrIsTerminal">>
 ): Stdio => ({
   [TypeId]: TypeId,
   stdinIsTerminal: Effect.succeed(false),
   stdoutIsTerminal: Effect.succeed(false),
+  stderrIsTerminal: Effect.succeed(false),
   ...options
 })
 

package/src/Stream.ts

@@ -20774,7 +20774,7 @@ export const mkUint8Array = <E, R>(self: Stream<Uint8Array, E, R>): Effect.Effec
  *
  * const stream = Stream.make(1, 2, 3, 4, 5)
  * const readableStream = Stream.toReadableStreamWith(stream, Context.empty())
- * const values = await Array.fromAsync(readableStream)
+ * const values = await globalThis.Array.fromAsync(readableStream)
  * values // => [ 1, 2, 3, 4, 5 ]
  * ```
  *
@@ -20802,7 +20802,7 @@ export const toReadableStreamWith: {
    *
    * const stream = Stream.make(1, 2, 3, 4, 5)
    * const readableStream = Stream.toReadableStreamWith(stream, Context.empty())
-   * const values = await Array.fromAsync(readableStream)
+   * const values = await globalThis.Array.fromAsync(readableStream)
    * values // => [ 1, 2, 3, 4, 5 ]
    * ```
    *
@@ -20833,7 +20833,7 @@ export const toReadableStreamWith: {
    *
    * const stream = Stream.make(1, 2, 3, 4, 5)
    * const readableStream = Stream.toReadableStreamWith(stream, Context.empty())
-   * const values = await Array.fromAsync(readableStream)
+   * const values = await globalThis.Array.fromAsync(readableStream)
    * values // => [ 1, 2, 3, 4, 5 ]
    * ```
    *
@@ -20906,7 +20906,7 @@ export const toReadableStreamWith: {
  * import { Stream } from "effect"
  *
  * const readableStream = Stream.toReadableStream(Stream.make(1, 2, 3))
- * const values = await Array.fromAsync(readableStream)
+ * const values = await globalThis.Array.fromAsync(readableStream)
  * values // => [ 1, 2, 3 ]
  * ```
  *
@@ -20928,7 +20928,7 @@ export const toReadableStream: {
    * import { Stream } from "effect"
    *
    * const readableStream = Stream.toReadableStream(Stream.make(1, 2, 3))
-   * const values = await Array.fromAsync(readableStream)
+   * const values = await globalThis.Array.fromAsync(readableStream)
    * values // => [ 1, 2, 3 ]
    * ```
    *
@@ -20952,7 +20952,7 @@ export const toReadableStream: {
    * import { Stream } from "effect"
    *
    * const readableStream = Stream.toReadableStream(Stream.make(1, 2, 3))
-   * const values = await Array.fromAsync(readableStream)
+   * const values = await globalThis.Array.fromAsync(readableStream)
    * values // => [ 1, 2, 3 ]
    * ```
    *
@@ -21132,7 +21132,7 @@ export const toReadableStreamEffect: {
  * const stream = Stream.make(1, 2, 3)
  * const iterable = Stream.toAsyncIterableWith(stream, Context.empty())
  *
- * await Array.fromAsync(iterable) // => [1, 2, 3]
+ * await globalThis.Array.fromAsync(iterable) // => [1, 2, 3]
  * ```
  *
  * @stability stable
@@ -21156,7 +21156,7 @@ export const toAsyncIterableWith: {
    * const stream = Stream.make(1, 2, 3)
    * const iterable = Stream.toAsyncIterableWith(stream, Context.empty())
    *
-   * await Array.fromAsync(iterable) // => [1, 2, 3]
+   * await globalThis.Array.fromAsync(iterable) // => [1, 2, 3]
    * ```
    *
    * @stability stable
@@ -21180,7 +21180,7 @@ export const toAsyncIterableWith: {
    * const stream = Stream.make(1, 2, 3)
    * const iterable = Stream.toAsyncIterableWith(stream, Context.empty())
    *
-   * await Array.fromAsync(iterable) // => [1, 2, 3]
+   * await globalThis.Array.fromAsync(iterable) // => [1, 2, 3]
    * ```
    *
    * @stability stable
@@ -21282,7 +21282,7 @@ export const toAsyncIterableWith: {
  *
  * const program = Effect.gen(function*() {
  *   const iterable = yield* Stream.toAsyncIterableEffect(stream)
- *   return yield* Effect.promise(() => Array.fromAsync(iterable))
+ *   return yield* Effect.promise(() => globalThis.Array.fromAsync(iterable))
  * })
  *
  * await Effect.runPromise(program) // => [1, 2, 3]
@@ -21308,7 +21308,7 @@ export const toAsyncIterableEffect = <A, E, R>(self: Stream<A, E, R>): Effect.Ef
  *
  * const stream = Stream.make(1, 2, 3)
  *
- * await Array.fromAsync(Stream.toAsyncIterable(stream)) // => [1, 2, 3]
+ * await globalThis.Array.fromAsync(Stream.toAsyncIterable(stream)) // => [1, 2, 3]
  * ```
  *
  * @stability stable

package/src/ai/McpServer.ts

@@ -94,6 +94,7 @@ type CompletionContext = typeof Complete.payloadSchema.Type["context"]
 
 interface QueuedServerNotification {
   readonly notification: McpCore.ServerNotification
+  listChangeRevision?: number | undefined
   readonly targetClientId?: number | undefined
   readonly delivered: Deferred.Deferred<void>
   readonly requestContext?: McpRequestContext["Service"] | undefined
@@ -103,7 +104,7 @@ interface QueuedServerNotification {
 const internalState = new WeakMap<object, {
   readonly core: McpCore.McpCore
   readonly notifications: Queue.Dequeue<QueuedServerNotification>
-  readonly notificationDelivery: { consumers: number }
+  readonly notificationDelivery: { consumers: number; listChangeRevision: number }
 }>()
 type ServerExtensions = NonNullable<ServerCapabilities["extensions"]>
 type ServerNotificationRequest<
@@ -321,8 +322,8 @@ export class McpServer extends Context.Service<McpServer, {
       readonly annotations: Context.Context<never>
     }> = []
     const notificationsQueue = yield* Queue.make<QueuedServerNotification>()
-    const notificationDelivery = { consumers: 0 }
-    const pendingListChanges = new Set<string>()
+    const notificationDelivery = { consumers: 0, listChangeRevision: 0 }
+    const pendingListChanges = new Map<string, QueuedServerNotification>()
     const dispatcher = (yield* Scheduler).makeDispatcher()
     const notifications = yield* RpcClient.makeNoSerialization(BroadcastServerNotificationRpcs, {
       spanPrefix: "McpServer/Notifications",
@@ -337,7 +338,7 @@ export class McpServer extends Context.Service<McpServer, {
             if (notification === undefined) {
               return Effect.void
             }
-            const queued = {
+            const queued: QueuedServerNotification = {
               notification,
               delivered,
               requestContext: Context.getOrUndefined(fiber.context, McpRequestContext),
@@ -345,14 +346,19 @@ export class McpServer extends Context.Service<McpServer, {
             }
             let enqueued = false
             if (message.tag.includes("list_changed")) {
-              if (!pendingListChanges.has(message.tag)) {
+              const revision = ++notificationDelivery.listChangeRevision
+              const pending = pendingListChanges.get(message.tag)
+              if (pending !== undefined) {
+                // A coalesced change may be newer than an intervening subscription.
+                pending.listChangeRevision = revision
+              } else {
+                queued.listChangeRevision = revision
                 enqueued = true
-                const tag = message.tag
+                pendingListChanges.set(message.tag, queued)
                 dispatcher.scheduleTask(() => {
-                  Queue.offerUnsafe(notificationsQueue, queued)
                   pendingListChanges.delete(message.tag)
+                  Queue.offerUnsafe(notificationsQueue, queued)
                 }, 0)
-                pendingListChanges.add(tag)
               }
             } else {
               enqueued = true
@@ -651,12 +657,14 @@ const MCP_SESSION_ID_HEADER = "mcp-session-id"
 const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version"
 const MCP_INVALID_BATCH_METHOD = "invalid/json-rpc-batch"
 const cancelledResponses = new WeakMap<object, string | number>()
+const httpPostResponses = new WeakMap<HttpServerRequest.HttpServerRequest, { expected: number }>()
 const requestKey = (requestId: string | number): string => `${typeof requestId}:${requestId}`
 
 interface ActiveRequest {
   readonly requestId: RpcMessage.RequestId
   readonly prepared: McpRuntime.PreparedRequest
   readonly cancelled: boolean
+  readonly httpPost: { expected: number } | undefined
 }
 
 class McpClientKey extends Data.Class<{
@@ -716,6 +724,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
     readonly websiteUrl?: string | undefined
     readonly icons?: ReadonlyArray<McpSchema.Icon> | undefined
     readonly extensions?: ServerExtensions | undefined
+    readonly allowSubscriptions?: boolean | undefined
   },
   runtime: McpRuntime.ServerRuntimeShape,
   transport: "custom" | "http" | "stdio"
@@ -807,10 +816,12 @@ const runWithRuntime = Effect.fnUntraced(function*(
         })
     })
   let writeFromClient!: (clientId: number, message: RpcMessage.FromClientEncoded) => Effect.Effect<void>
+  const { core, notificationDelivery, notifications } = internalState.get(server)!
   const handlers = yield* runtime.installHandlers({
-    core: internalState.get(server)!.core,
+    core,
     subscribeServerNotifications: PubSub.subscribe(serverNotifications),
-    ...(!protocol.supportsNotifications ? {} : {
+    getListChangeRevision: () => notificationDelivery.listChangeRevision,
+    ...(!protocol.supportsNotifications || options.allowSubscriptions === false ? {} : {
       sendNotification,
       markSubscriptionCancelled: (clientId: number, requestId: RpcMessage.RequestId) =>
         Effect.sync(() => {
@@ -848,10 +859,13 @@ const runWithRuntime = Effect.fnUntraced(function*(
             if (request._tag === "Interrupt") {
               // A cancelled reverse request may never receive a reply.
               removeReverseRequestClient(requestKey(request.requestId), key)
+              return sendNotification(key.profile.protocolVersion, key.clientId, {
+                tag: "notifications/cancelled",
+                payload: { requestId: request.requestId }
+              })
             }
-            // Ack & co are not part of FromServerEncoded, but the JSON-RPC
-            // serializer encodes them symmetrically for reverse control flow
-            return protocol.send(key.clientId, request as any)
+            // Effect RPC control messages are not part of the MCP protocol.
+            return Effect.void
           },
           supportsAck: true,
           supportsTransferables: false,
@@ -950,12 +964,13 @@ const runWithRuntime = Effect.fnUntraced(function*(
       if (response._tag === "Exit") {
         const requests = activeRequests.get(clientId)
         const key = requestKey(response.requestId)
-        const cancelled = requests?.get(key)?.cancelled
+        const active = requests?.get(key)
         if (requests !== undefined && requests.delete(key) && requests.size === 0) {
           activeRequests.delete(clientId)
         }
-        if (cancelled === true) {
+        if (active?.cancelled === true) {
           if (transport === "custom") return Effect.void
+          if (active.httpPost !== undefined) active.httpPost.expected--
           cancelledResponses.set(response, response.requestId)
           return protocol.send(clientId, response)
         }
@@ -1003,6 +1018,11 @@ const runWithRuntime = Effect.fnUntraced(function*(
         }
         switch (request._tag) {
           case "Request": {
+            if (httpRequest !== undefined && request.isNotification !== true) {
+              const httpPost = httpPostResponses.get(httpRequest) ?? { expected: 0 }
+              httpPost.expected++
+              httpPostResponses.set(httpRequest, httpPost)
+            }
             const headers = isHttp
               ? Context.getUnsafe(
                 Fiber.getCurrent()!.context,
@@ -1138,7 +1158,8 @@ const runWithRuntime = Effect.fnUntraced(function*(
                 requests.set(requestKey(request.id), {
                   requestId: RpcMessage.RequestId(request.id),
                   prepared,
-                  cancelled: false
+                  cancelled: false,
+                  httpPost: httpRequest === undefined ? undefined : httpPostResponses.get(httpRequest)
                 })
                 activeRequests.set(clientId, requests)
               }
@@ -1231,7 +1252,6 @@ const runWithRuntime = Effect.fnUntraced(function*(
     })
   }
 
-  const { notificationDelivery, notifications } = internalState.get(server)!
   yield* Effect.acquireRelease(
     Effect.sync(() => {
       notificationDelivery.consumers++
@@ -1244,9 +1264,9 @@ const runWithRuntime = Effect.fnUntraced(function*(
   const notificationTails = new Map<number, Deferred.Deferred<void>>()
   yield* Queue.take(notifications).pipe(
     Effect.flatMap(Effect.fnUntraced(function*(queued) {
-      const { delivered, notification, targetClientId, requestContext, requestHeaders } = queued
+      const { delivered, listChangeRevision, notification, targetClientId, requestContext, requestHeaders } = queued
       if (McpProtocolInternal.isSubscriptionServerNotification(notification)) {
-        yield* PubSub.publish(serverNotifications, { notification, targetClientId })
+        yield* PubSub.publish(serverNotifications, { notification, targetClientId, listChangeRevision })
       }
       const clientIds = yield* patchedProtocol.clientIds
       for (const clientId of clientStates.keys()) {
@@ -1422,6 +1442,7 @@ const layerWithRuntime = (options: {
   readonly websiteUrl?: string | undefined
   readonly icons?: ReadonlyArray<McpSchema.Icon> | undefined
   readonly extensions?: ServerExtensions | undefined
+  readonly allowSubscriptions?: boolean | undefined
 }, transport: "custom" | "http" | "stdio"): Layer.Layer<
   McpServer | McpServerClient,
   never,
@@ -1568,6 +1589,11 @@ const mcpStdioSerialization = (
  * holding a session id can end that session, so authenticate requests in the
  * surrounding router.
  *
+ * Set `allowSubscriptions: false` to disable `v2026_07_28` subscriptions.
+ * Discovery advertises `listChanged: false`, and `subscriptions/listen` returns
+ * Method not found. Request-scoped progress and logs, legacy protocols, and
+ * default subscription behavior are unchanged.
+ *
  * `layerHttp` always implements the single-endpoint Streamable HTTP topology.
  * Using `v2024_11_05` here is a custom compatibility transport for that
  * revision's schema. It does not implement the historical two-endpoint
@@ -1592,6 +1618,7 @@ export const layerHttp = (options: {
   readonly extensions?: ServerExtensions | undefined
   readonly allowedOrigins?: ReadonlyArray<string> | undefined
   readonly allowSessionTermination?: boolean | undefined
+  readonly allowSubscriptions?: boolean | undefined
 }): Layer.Layer<McpServer | McpServerClient, Cause.IllegalArgumentError, HttpRouter.HttpRouter> => {
   const runtime = McpRuntime.layer(options.protocols)
   return layerWithRuntime(options, "http").pipe(
@@ -1658,17 +1685,30 @@ const layerMcpProtocolHttp = (options: {
         if (admission._tag === "Rejected") {
           return admission.response
         }
-        const response = Effect.map(httpEffect, (response) => {
+        const toResponse = (response: HttpServerResponse.HttpServerResponse) => {
           // Completed responses may already contain notifications followed by the result.
           const hasMultipleMessages = response.body._tag === "Uint8Array" &&
             response.body.body.subarray(0, -1).includes(10)
           return admission.isSubscription || response.body._tag === "Stream" || hasMultipleMessages
             ? toServerSentEvents(response, admission.isSubscription)
             : response
+        }
+        if (admission.acknowledge) {
+          return yield* Effect.catchCause(
+            Effect.map(httpEffect, toResponse),
+            () => Effect.succeed(HttpServerResponse.empty({ status: 202 }))
+          )
+        }
+        return yield* Effect.flatMap(httpEffect, (response) => {
+          if (response.body._tag !== "Uint8Array" || response.body.body.length > 0) {
+            return Effect.succeed(toResponse(response))
+          }
+          // Only fully cancelled request POSTs may return an empty SSE response.
+          // https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server
+          return httpPostResponses.get(request)?.expected === 0
+            ? Effect.succeed(HttpServerResponse.stream(Stream.empty, { contentType: "text/event-stream" }))
+            : Effect.die(new Error("MCP request ended without writing its response"))
         })
-        return yield* admission.acknowledge
-          ? Effect.catchCause(response, () => Effect.succeed(HttpServerResponse.empty({ status: 202 })))
-          : response
       })
     })
     return protocol

package/src/ai/internal/mcpProtocol/v2026_07_28.ts

@@ -386,6 +386,8 @@ export const makeHandlers = (
       }
       const presence = yield* context.registrationPresence
       const eventsScope = yield* Scope.fork(yield* Effect.scope)
+      // Ignore changes emitted before this subscription, even if delivery was deferred.
+      const listChangeRevision = context.getListChangeRevision?.() ?? 0
       const events = yield* Scope.provide(context.subscribeServerNotifications, eventsScope)
       const honored = {
         ...(presence.tools && request.notifications.toolsListChanged === true
@@ -410,6 +412,9 @@ export const makeHandlers = (
       yield* Effect.gen(function*() {
         while (true) {
           const event = yield* PubSub.take(events)
+          if (event.listChangeRevision !== undefined && event.listChangeRevision <= listChangeRevision) {
+            continue
+          }
           if (event.targetClientId !== undefined && event.targetClientId !== client.id) {
             continue
           }

package/src/ai/internal/mcpProtocol.ts

@@ -382,6 +382,8 @@ export interface HandlerInstallationContext {
     never,
     Scope.Scope
   >
+  /** Current list-change revision; subscriptions ignore changes emitted at or before it. */
+  readonly getListChangeRevision?: (() => number) | undefined
   readonly sendNotification?: (
     protocolVersion: string,
     clientId: number,
@@ -419,6 +421,7 @@ export interface HandlerInstallationContext {
  */
 export interface CanonicalServerNotification {
   readonly notification: SubscriptionServerNotification
+  readonly listChangeRevision?: number | undefined
   readonly targetClientId?: number | undefined
 }
 

package/src/ai/internal/mcpRuntime.ts

@@ -123,6 +123,7 @@ export type HttpAdmission =
  */
 export interface HandlerInstallationOptions {
   readonly core: McpCore.McpCore
+  readonly getListChangeRevision?: () => number
   readonly subscribeServerNotifications: McpProtocol.HandlerInstallationContext["subscribeServerNotifications"]
   readonly sendNotification?: NonNullable<McpProtocol.HandlerInstallationContext["sendNotification"]>
   readonly markSubscriptionCancelled?: NonNullable<
@@ -512,6 +513,7 @@ export const make = Effect.fnUntraced(function*(
       const contextMap = new Map<string, unknown>()
       const installationContext: McpProtocol.HandlerInstallationContext = {
         subscribeServerNotifications: options.subscribeServerNotifications,
+        getListChangeRevision: options.getListChangeRevision,
         ...(options.sendNotification === undefined ? {} : { sendNotification: options.sendNotification }),
         ...(options.markSubscriptionCancelled === undefined
           ? {}

package/src/cli/CliOutput.ts

@@ -16,6 +16,7 @@ import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
 import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
+import * as Ansi from "./internal/ansi.ts"
 
 /**
  * Defines the service interface for formatting CLI output including help, errors, and version info.
@@ -306,17 +307,7 @@ const escapeControlCharacters = (text: string): string =>
  * @since 4.0.0
  */
 export const defaultFormatter = (options?: { colors?: boolean }): Formatter => {
-  const globalProcess = (globalThis as any).process
-  const hasProcess = typeof globalProcess === "object" && globalProcess !== null
-
-  const useColor = options?.colors !== undefined
-    ? options.colors
-    // Auto-detect based on environment
-    : (hasProcess &&
-      typeof globalProcess.stdout === "object" &&
-      globalProcess.stdout !== null &&
-      globalProcess.stdout.isTTY === true &&
-      !globalProcess.env?.NO_COLOR)
+  const useColor = options?.colors ?? Ansi.detectColors()
 
   // Color palette using ANSI escape codes
   const colors = useColor
@@ -390,7 +381,7 @@ const stripAnsi = (text: string): string => {
 }
 
 /**
- * Gets the terminal display width of a string (excluding ANSI codes).
+ * Segments text into grapheme clusters.
  * @internal
  */
 const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" })
@@ -424,7 +415,33 @@ const graphemeWidth = (grapheme: string): number => {
   return isFullWidthCodePoint(visible.codePointAt(0)!) ? 2 : 1
 }
 
-const visualLength = (text: string): number => {
+/**
+ * Measures the number of terminal cells a string occupies.
+ *
+ * **Details**
+ *
+ * Uses the same measurement as built-in help and table rendering. ANSI styling
+ * is stripped before measuring graphemes: zero-width graphemes count as `0`,
+ * emoji presentation sequences and fullwidth characters as `2`, and other
+ * graphemes as `1`.
+ *
+ * **Example** (Measuring terminal-cell widths)
+ *
+ * ```ts import.meta.vitest
+ * import { CliOutput } from "effect/cli"
+ *
+ * CliOutput.displayWidth("file") // => 4
+ * CliOutput.displayWidth("ファイル") // => 8
+ * CliOutput.displayWidth("é") // => 1
+ * CliOutput.displayWidth("1️⃣") // => 2
+ * CliOutput.displayWidth("\u001B[1mbold\u001B[0m") // => 4
+ * ```
+ *
+ * @stability unstable
+ * @category measuring
+ * @since 4.0.3
+ */
+export const displayWidth = (text: string): number => {
   let length = 0
   for (const { segment } of graphemeSegmenter.segment(stripAnsi(text))) {
     length += graphemeWidth(segment)
@@ -437,7 +454,7 @@ const visualLength = (text: string): number => {
  * @internal
  */
 const pad = (s: string, width: number) => {
-  const actualLength = visualLength(s)
+  const actualLength = displayWidth(s)
   const padding = Math.max(0, width - actualLength)
   return s + " ".repeat(padding)
 }
@@ -456,9 +473,9 @@ interface Row {
  * @internal
  */
 const renderTable = (rows: ReadonlyArray<Row>, widthCap?: number) => {
-  const maxColumn = Math.max(...rows.map((r) => visualLength(r.left))) + 4
+  const maxColumn = Math.max(...rows.map((r) => displayWidth(r.left))) + 4
   const col = widthCap === undefined ? maxColumn : Math.min(maxColumn, widthCap)
-  return rows.map(({ left, right }) => `  ${pad(left, Math.max(col, visualLength(left) + 1))}${right}`).join("\n")
+  return rows.map(({ left, right }) => `  ${pad(left, Math.max(col, displayWidth(left) + 1))}${right}`).join("\n")
 }
 
 const formatSubcommandName = (name: string, alias: string | undefined): string => alias ? `${name}, ${alias}` : name

package/src/cli/Command.ts

@@ -3104,14 +3104,15 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
         if (!hasEntry) continue
         const [, value] = yield* flag.flag.parse(emptyArgs)
         if (flag === GlobalFlag.Wizard) {
+          const { colors } = yield* Prompt.Theme
           return yield* Effect.gen(function*() {
-            yield* Console.log(Wizard.renderIntroduction(command.name, config.version, command.description))
+            yield* Console.log(Wizard.renderIntroduction(command.name, config.version, command.description, colors))
             const prefix = [
               command.name,
               ...args.filter((arg) => arg !== "--wizard" && !arg.startsWith("--wizard="))
             ]
             const wizardResult = yield* Wizard.run(command, { commandPath, prefix })
-            yield* Console.log(Wizard.renderCompletion(wizardResult.displayArgs))
+            yield* Console.log(Wizard.renderCompletion(wizardResult.displayArgs, colors))
             const shouldRun = yield* Prompt.run(Prompt.Toggle({
               message: "Run this command?",
               initial: true,
@@ -3123,7 +3124,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
               yield* runWith(command, { ...config, renderErrors: false })(wizardResult.args.slice(1))
             }
           }).pipe(
-            Effect.catchTag("QuitError", () => Console.log(Wizard.renderQuit()))
+            Effect.catchTag("QuitError", () => Console.log(Wizard.renderQuit(colors)))
           )
         }
         yield* flag.run(value, handlerCtx)

package/src/cli/Completions.ts

@@ -1,14 +1,15 @@
 /**
  * The `Completions` module turns a plain description of an Effect CLI command
- * tree into shell completion scripts for Bash, Zsh, and Fish. It is the
- * low-level script generation surface used by the unstable CLI package and by
- * the built-in completions global flag.
+ * tree into shell completion scripts for Bash, Zsh, Fish, and PowerShell. It
+ * is the low-level script generation surface used by the unstable CLI package
+ * and by the built-in completions global flag.
  *
  * @stability unstable
  * @since 4.0.0
  */
 import * as Bash from "./internal/completions/bash.ts"
 import * as Fish from "./internal/completions/fish.ts"
+import * as PowerShell from "./internal/completions/powershell.ts"
 import * as Zsh from "./internal/completions/zsh.ts"
 
 /**
@@ -18,7 +19,7 @@ import * as Zsh from "./internal/completions/zsh.ts"
  * @category models
  * @since 4.0.0
  */
-export type Shell = "bash" | "zsh" | "fish"
+export type Shell = "bash" | "zsh" | "fish" | "powershell"
 
 /**
  * Describes a command for completion script generation.
@@ -105,8 +106,8 @@ export type ArgumentType =
  *
  * **Details**
  *
- * Dispatches by `shell` to Bash, Zsh, or Fish generation and returns a static
- * script string for `executableName`.
+ * Dispatches by `shell` to Bash, Zsh, Fish, or PowerShell generation and
+ * returns a static script string for `executableName`.
  *
  * @see {@link Shell} for supported shell names
  * @see {@link CommandDescriptor} for the command shape used by completion generation
@@ -127,5 +128,7 @@ export const generate = (
       return Zsh.generate(executableName, descriptor)
     case "fish":
       return Fish.generate(executableName, descriptor)
+    case "powershell":
+      return PowerShell.generate(executableName, descriptor)
   }
 }

package/src/cli/GlobalFlag.ts

@@ -224,21 +224,29 @@ export const Wizard: Action<boolean> = Action({
  *
  * **Details**
  *
- * Accepted values are `bash`, `zsh`, `fish`, and `sh`; `sh` is normalized to
- * `bash`.
+ * Accepted values are `bash`, `zsh`, `fish`, `powershell`, `sh`, and `pwsh`;
+ * `sh` is normalized to `bash` and `pwsh` to `powershell`.
  *
  * @stability unstable
  * @category references
  * @since 4.0.0
  */
-export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = Action({
-  flag: Flag.Literals("completions", ["bash", "zsh", "fish", "sh"] as const)
-    .pipe(
-      Flag.optional,
-      Flag.map((v) => Option.map(v, (s) => s === "sh" ? "bash" : s)),
-      Flag.withMetavar("<bash|zsh|fish|sh>"),
-      Flag.withDescription("Print shell completion script")
-    ),
+export const Completions: Action<Option.Option<Completions_.Shell>> = Action({
+  flag: Flag.ChoiceWithValue(
+    "completions",
+    [
+      ["bash", "bash"],
+      ["zsh", "zsh"],
+      ["fish", "fish"],
+      ["powershell", "powershell"],
+      ["sh", "bash"],
+      ["pwsh", "powershell"]
+    ] as const
+  ).pipe(
+    Flag.optional,
+    Flag.withMetavar("<bash|zsh|fish|powershell|sh|pwsh>"),
+    Flag.withDescription("Print shell completion script")
+  ),
   run: Effect.fnUntraced(function*(shell, { command }) {
     if (Option.isNone(shell)) return
     const descriptor = CommandDescriptor.fromCommand(command)
@@ -317,7 +325,7 @@ export const BuiltIns: readonly [
   Action<boolean>,
   Action<boolean>,
   Action<boolean>,
-  Action<Option.Option<"bash" | "zsh" | "fish">>,
+  Action<Option.Option<Completions_.Shell>>,
   Setting<"log-level", Option.Option<LogLevelType>>
 ] = [Help, Version, Wizard, Completions, LogLevel]