refactor(core): narrow shell spawn handling

packages/core/src/session.ts

@@ -645,7 +645,9 @@ const layer = Layer.effect(
             yield* execution.awaitIdle(input.sessionID)
             const started = yield* Effect.gen(function* () {
               const shell = yield* Shell.Service
-              return yield* shell.create({ command: input.command, cwd: session.location.directory, timeout: 0 })
+              return yield* shell
+                .create({ command: input.command, cwd: session.location.directory, timeout: 0 })
+                .pipe(Effect.orDie)
             }).pipe(Effect.provide(locations.get(session.location)))
             yield* bus.publish(
               SessionEvent.Shell.Started,

packages/core/src/shell.ts

@@ -5,6 +5,7 @@ import { Context, Deferred, Duration, Effect, Fiber, Layer, Schema, Stream } fro
 import { ChildProcess } from "effect/unstable/process"
 import { produce } from "immer"
 import { Shell } from "@opencode-ai/schema/shell"
+import { AppProcess } from "@opencode-ai/util/process"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
 import { Config } from "./config"
 import { Bus } from "./bus"
@@ -50,7 +51,7 @@ export interface Interface {
   readonly create: <E = never, R = never>(
     input: Shell.CreateInput,
     before?: (input: ShellCreateBefore) => Effect.Effect<void, E, R>,
-  ) => Effect.Effect<Shell.Info, E, R>
+  ) => Effect.Effect<Shell.Info, E | AppProcess.AppProcessError, R>
   // Currently running commands only; exited shells are retained for get/output but excluded here.
   readonly list: () => Effect.Effect<Shell.Info[]>
   readonly get: (id: Shell.ID) => Effect.Effect<Shell.Info, NotFoundError>
@@ -213,19 +214,23 @@ export const layer = (options?: ShellSelect.Options) =>
         // Spawn through the Environment and stream combined output to the file. The handle is scope-bound, so
         // the managing fiber keeps its scope open until the command terminates (it awaits `done` at the
         // end). `create` returns once `ready` resolves with the registered session.
-        const ready = Deferred.makeUnsafe<Active>()
+        const ready = Deferred.makeUnsafe<Active, AppProcess.AppProcessError>()
         runFork(
           Effect.scoped(
             Effect.gen(function* () {
-              const handle = yield* environment.spawner.spawn(
-                ChildProcess.make(invocation.shell, args, {
-                  cwd: invocation.cwd,
-                  env: invocation.env,
-                  stdin: "ignore",
-                  detached: process.platform !== "win32",
-                  forceKillAfter: Duration.seconds(3),
-                }),
-              )
+              const handle = yield* environment.spawner
+                .spawn(
+                  ChildProcess.make(invocation.shell, args, {
+                    cwd: invocation.cwd,
+                    env: invocation.env,
+                    stdin: "ignore",
+                    detached: process.platform !== "win32",
+                    forceKillAfter: Duration.seconds(3),
+                  }),
+                )
+                .pipe(
+                  Effect.mapError((cause) => new AppProcess.AppProcessError({ command: invocation.command, cause })),
+                )
               const session: Active = {
                 info: produce(info, (draft) => {
                   draft.pid = handle.pid
@@ -327,7 +332,7 @@ export const layer = (options?: ShellSelect.Options) =>
               // release (kill) the process before its exit is observed.
               yield* Deferred.await(session.done).pipe(Effect.catch(() => Effect.void))
             }),
-          ).pipe(Effect.catch(() => Effect.void)),
+          ).pipe(Effect.catchTag("AppProcessError", (error) => Deferred.fail(ready, error))),
         )
 
         const session = yield* Deferred.await(ready)

packages/core/test/tool-shell.test.ts

@@ -286,6 +286,31 @@ describe("ShellTool", () => {
     ),
   )
 
+  it.live(
+    "reports a command that fails to spawn",
+    () =>
+      Effect.acquireUseRelease(
+        Effect.promise(() => tmpdir()),
+        (tmp) => {
+          reset()
+          const command = "printf before\0after"
+          return withSession(tmp.path, (registry) =>
+            executeTool(registry, call({ command })).pipe(
+              Effect.andThen((settled) =>
+                Effect.sync(() => {
+                  expect(settled.status).toBe("error")
+                  if (settled.status !== "error") return
+                  expect(settled.error?.message).toContain("Command failed")
+                }),
+              ),
+            ),
+          )
+        },
+        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]().then(() => undefined)),
+      ),
+    { timeout: 2_000 },
+  )
+
   it.live("permissions compound commands separately", () =>
     Effect.acquireUseRelease(
       Effect.promise(() => tmpdir()),

packages/server/src/handlers/shell.ts

@@ -21,7 +21,9 @@ export const ShellHandler = HttpApiBuilder.group(Api, "server.shell", (handlers)
         Effect.fn(function* (ctx) {
           const shell = yield* Shell.Service
           const location = yield* Location.Service
-          return yield* response(shell.create({ ...ctx.payload, cwd: ctx.payload.cwd || location.directory }))
+          return yield* response(
+            shell.create({ ...ctx.payload, cwd: ctx.payload.cwd || location.directory }).pipe(Effect.orDie),
+          )
         }),
       )
       .handle(

packages/util/src/cross-spawn-spawner.ts

@@ -258,7 +258,13 @@ const makeCrossSpawnSpawner = Effect.gen(function* () {
   const spawn = (command: ChildProcess.StandardCommand, opts: NodeChildProcess.SpawnOptions) =>
     Effect.callback<readonly [NodeChildProcess.ChildProcess, ExitSignal], PlatformError.PlatformError>((resume) => {
       const signal = Deferred.makeUnsafe<readonly [code: number | null, signal: NodeJS.Signals | null]>()
-      const proc = launch(command.command, command.args, opts)
+      let proc: NodeChildProcess.ChildProcess
+      try {
+        proc = launch(command.command, command.args, opts)
+      } catch (err) {
+        resume(Effect.fail(toPlatformError("spawn", toError(err), command)))
+        return Effect.void
+      }
       let end = false
       let exit: readonly [code: number | null, signal: NodeJS.Signals | null] | undefined
       proc.on("error", (err) => {