fix: use codebase import conventions and shared memoMap for bash tool

- Fix imports to use barrel imports from "effect" and "effect/unstable/process"
- Use shared memoMap from run-service for layer deduplication
- Use ChildProcessSpawner.ChildProcessSpawner (barrel export pattern)

packages/app/e2e/actions.ts

@@ -312,10 +312,11 @@ export async function openSettings(page: Page) {
   return dialog
 }
 
-export async function seedProjects(page: Page, input: { directory: string; extra?: string[] }) {
+export async function seedProjects(page: Page, input: { directory: string; extra?: string[]; serverUrl?: string }) {
   await page.addInitScript(
     (args: { directory: string; serverUrl: string; extra: string[] }) => {
       const key = "opencode.global.dat:server"
+      const defaultKey = "opencode.settings.dat:defaultServerUrl"
       const raw = localStorage.getItem(key)
       const parsed = (() => {
         if (!raw) return undefined
@@ -331,6 +332,7 @@ export async function seedProjects(page: Page, input: { directory: string; extra
       const lastProject = store.lastProject && typeof store.lastProject === "object" ? store.lastProject : {}
       const projects = store.projects && typeof store.projects === "object" ? store.projects : {}
       const nextProjects = { ...(projects as Record<string, unknown>) }
+      const nextList = list.includes(args.serverUrl) ? list : [args.serverUrl, ...list]
 
       const add = (origin: string, directory: string) => {
         const current = nextProjects[origin]
@@ -356,17 +358,18 @@ export async function seedProjects(page: Page, input: { directory: string; extra
       localStorage.setItem(
         key,
         JSON.stringify({
-          list,
+          list: nextList,
           projects: nextProjects,
           lastProject,
         }),
       )
+      localStorage.setItem(defaultKey, args.serverUrl)
     },
-    { directory: input.directory, serverUrl, extra: input.extra ?? [] },
+    { directory: input.directory, serverUrl: input.serverUrl ?? serverUrl, extra: input.extra ?? [] },
   )
 }
 
-export async function createTestProject() {
+export async function createTestProject(input?: { serverUrl?: string }) {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-e2e-project-"))
   const id = `e2e-${path.basename(root)}`
 
@@ -381,7 +384,7 @@ export async function createTestProject() {
     stdio: "ignore",
   })
 
-  return resolveDirectory(root)
+  return resolveDirectory(root, input?.serverUrl)
 }
 
 export async function cleanupTestProject(directory: string) {
@@ -430,22 +433,22 @@ export async function waitSlug(page: Page, skip: string[] = []) {
   return next
 }
 
-export async function resolveSlug(slug: string) {
+export async function resolveSlug(slug: string, input?: { serverUrl?: string }) {
   const directory = base64Decode(slug)
   if (!directory) throw new Error(`Failed to decode workspace slug: ${slug}`)
-  const resolved = await resolveDirectory(directory)
+  const resolved = await resolveDirectory(directory, input?.serverUrl)
   return { directory: resolved, slug: base64Encode(resolved), raw: slug }
 }
 
-export async function waitDir(page: Page, directory: string) {
-  const target = await resolveDirectory(directory)
+export async function waitDir(page: Page, directory: string, input?: { serverUrl?: string }) {
+  const target = await resolveDirectory(directory, input?.serverUrl)
   await expect
     .poll(
       async () => {
         await assertHealthy(page, "waitDir")
         const slug = slugFromUrl(page.url())
         if (!slug) return ""
-        return resolveSlug(slug)
+        return resolveSlug(slug, input)
           .then((item) => item.directory)
           .catch(() => "")
       },
@@ -455,15 +458,15 @@ export async function waitDir(page: Page, directory: string) {
   return { directory: target, slug: base64Encode(target) }
 }
 
-export async function waitSession(page: Page, input: { directory: string; sessionID?: string }) {
-  const target = await resolveDirectory(input.directory)
+export async function waitSession(page: Page, input: { directory: string; sessionID?: string; serverUrl?: string }) {
+  const target = await resolveDirectory(input.directory, input.serverUrl)
   await expect
     .poll(
       async () => {
         await assertHealthy(page, "waitSession")
         const slug = slugFromUrl(page.url())
         if (!slug) return false
-        const resolved = await resolveSlug(slug).catch(() => undefined)
+        const resolved = await resolveSlug(slug, { serverUrl: input.serverUrl }).catch(() => undefined)
         if (!resolved || resolved.directory !== target) return false
         const current = sessionIDFromUrl(page.url())
         if (input.sessionID && current !== input.sessionID) return false
@@ -473,7 +476,7 @@ export async function waitSession(page: Page, input: { directory: string; sessio
         if (input.sessionID && (!state || state.sessionID !== input.sessionID)) return false
         if (!input.sessionID && state?.sessionID) return false
         if (state?.dir) {
-          const dir = await resolveDirectory(state.dir).catch(() => state.dir ?? "")
+          const dir = await resolveDirectory(state.dir, input.serverUrl).catch(() => state.dir ?? "")
           if (dir !== target) return false
         }
 
@@ -489,9 +492,9 @@ export async function waitSession(page: Page, input: { directory: string; sessio
   return { directory: target, slug: base64Encode(target) }
 }
 
-export async function waitSessionSaved(directory: string, sessionID: string, timeout = 30_000) {
-  const sdk = createSdk(directory)
-  const target = await resolveDirectory(directory)
+export async function waitSessionSaved(directory: string, sessionID: string, timeout = 30_000, serverUrl?: string) {
+  const sdk = createSdk(directory, serverUrl)
+  const target = await resolveDirectory(directory, serverUrl)
 
   await expect
     .poll(
@@ -501,7 +504,7 @@ export async function waitSessionSaved(directory: string, sessionID: string, tim
           .then((x) => x.data)
           .catch(() => undefined)
         if (!data?.directory) return ""
-        return resolveDirectory(data.directory).catch(() => data.directory)
+        return resolveDirectory(data.directory, serverUrl).catch(() => data.directory)
       },
       { timeout },
     )
@@ -666,8 +669,9 @@ export async function cleanupSession(input: {
   sessionID: string
   directory?: string
   sdk?: ReturnType<typeof createSdk>
+  serverUrl?: string
 }) {
-  const sdk = input.sdk ?? (input.directory ? createSdk(input.directory) : undefined)
+  const sdk = input.sdk ?? (input.directory ? createSdk(input.directory, input.serverUrl) : undefined)
   if (!sdk) throw new Error("cleanupSession requires sdk or directory")
   await waitSessionIdle(sdk, input.sessionID, 5_000).catch(() => undefined)
   const current = await status(sdk, input.sessionID).catch(() => undefined)
@@ -1019,3 +1023,13 @@ export async function openWorkspaceMenu(page: Page, workspaceSlug: string) {
   await expect(menu).toBeVisible()
   return menu
 }
+
+export async function assistantText(sdk: ReturnType<typeof createSdk>, sessionID: string) {
+  const messages = await sdk.session.messages({ sessionID, limit: 50 }).then((r) => r.data ?? [])
+  return messages
+    .filter((m) => m.info.role === "assistant")
+    .flatMap((m) => m.parts)
+    .filter((p) => p.type === "text")
+    .map((p) => p.text)
+    .join("\n")
+}

packages/app/e2e/backend.ts

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process"
+import fs from "node:fs/promises"
+import net from "node:net"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+type Handle = {
+  url: string
+  stop: () => Promise<void>
+}
+
+function freePort() {
+  return new Promise<number>((resolve, reject) => {
+    const server = net.createServer()
+    server.once("error", reject)
+    server.listen(0, () => {
+      const address = server.address()
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to acquire a free port")))
+        return
+      }
+      server.close((err) => {
+        if (err) reject(err)
+        else resolve(address.port)
+      })
+    })
+  })
+}
+
+async function waitForHealth(url: string, probe = "/global/health") {
+  const end = Date.now() + 120_000
+  let last = ""
+  while (Date.now() < end) {
+    try {
+      const res = await fetch(`${url}${probe}`)
+      if (res.ok) return
+      last = `status ${res.status}`
+    } catch (err) {
+      last = err instanceof Error ? err.message : String(err)
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+  throw new Error(`Timed out waiting for backend health at ${url}${probe}${last ? ` (${last})` : ""}`)
+}
+
+const LOG_CAP = 100
+
+function cap(input: string[]) {
+  if (input.length > LOG_CAP) input.splice(0, input.length - LOG_CAP)
+}
+
+function tail(input: string[]) {
+  return input.slice(-40).join("")
+}
+
+export async function startBackend(label: string): Promise<Handle> {
+  const port = await freePort()
+  const sandbox = await fs.mkdtemp(path.join(os.tmpdir(), `opencode-e2e-${label}-`))
+  const appDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+  const repoDir = path.resolve(appDir, "../..")
+  const opencodeDir = path.join(repoDir, "packages", "opencode")
+  const env = {
+    ...process.env,
+    OPENCODE_DISABLE_SHARE: process.env.OPENCODE_DISABLE_SHARE ?? "true",
+    OPENCODE_DISABLE_LSP_DOWNLOAD: "true",
+    OPENCODE_DISABLE_DEFAULT_PLUGINS: "true",
+    OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER: "true",
+    OPENCODE_TEST_HOME: path.join(sandbox, "home"),
+    XDG_DATA_HOME: path.join(sandbox, "share"),
+    XDG_CACHE_HOME: path.join(sandbox, "cache"),
+    XDG_CONFIG_HOME: path.join(sandbox, "config"),
+    XDG_STATE_HOME: path.join(sandbox, "state"),
+    OPENCODE_CLIENT: "app",
+    OPENCODE_STRICT_CONFIG_DEPS: "true",
+  } satisfies Record<string, string | undefined>
+  const out: string[] = []
+  const err: string[] = []
+  const proc = spawn(
+    "bun",
+    ["run", "--conditions=browser", "./src/index.ts", "serve", "--port", String(port), "--hostname", "127.0.0.1"],
+    {
+      cwd: opencodeDir,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    },
+  )
+  proc.stdout?.on("data", (chunk) => {
+    out.push(String(chunk))
+    cap(out)
+  })
+  proc.stderr?.on("data", (chunk) => {
+    err.push(String(chunk))
+    cap(err)
+  })
+
+  const url = `http://127.0.0.1:${port}`
+  try {
+    await waitForHealth(url)
+  } catch (error) {
+    proc.kill("SIGTERM")
+    await fs.rm(sandbox, { recursive: true, force: true }).catch(() => undefined)
+    throw new Error(
+      [
+        `Failed to start isolated e2e backend for ${label}`,
+        error instanceof Error ? error.message : String(error),
+        tail(out),
+        tail(err),
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    )
+  }
+
+  return {
+    url,
+    async stop() {
+      if (proc.exitCode === null) {
+        proc.kill("SIGTERM")
+        await new Promise((resolve) => proc.once("exit", () => resolve(undefined))).catch(() => undefined)
+      }
+      await fs.rm(sandbox, { recursive: true, force: true }).catch(() => undefined)
+    },
+  }
+}

packages/app/e2e/fixtures.ts

@@ -3,6 +3,7 @@ import { ManagedRuntime } from "effect"
 import type { E2EWindow } from "../src/testing/terminal"
 import type { Item, Reply, Usage } from "../../opencode/test/lib/llm-server"
 import { TestLLMServer } from "../../opencode/test/lib/llm-server"
+import { startBackend } from "./backend"
 import {
   healthPhase,
   cleanupSession,
@@ -19,6 +20,20 @@ import { createSdk, dirSlug, getWorktree, sessionPath } from "./utils"
 type LLMFixture = {
   url: string
   push: (...input: (Item | Reply)[]) => Promise<void>
+  pushMatch: (
+    match: (hit: { url: URL; body: Record<string, unknown> }) => boolean,
+    ...input: (Item | Reply)[]
+  ) => Promise<void>
+  textMatch: (
+    match: (hit: { url: URL; body: Record<string, unknown> }) => boolean,
+    value: string,
+    opts?: { usage?: Usage },
+  ) => Promise<void>
+  toolMatch: (
+    match: (hit: { url: URL; body: Record<string, unknown> }) => boolean,
+    name: string,
+    input: unknown,
+  ) => Promise<void>
   text: (value: string, opts?: { usage?: Usage }) => Promise<void>
   tool: (name: string, input: unknown) => Promise<void>
   toolHang: (name: string, input: unknown) => Promise<void>
@@ -46,32 +61,54 @@ const seedModel = (() => {
   }
 })()
 
+type ProjectHandle = {
+  directory: string
+  slug: string
+  gotoSession: (sessionID?: string) => Promise<void>
+  trackSession: (sessionID: string, directory?: string) => void
+  trackDirectory: (directory: string) => void
+  sdk: ReturnType<typeof createSdk>
+}
+
+type ProjectOptions = {
+  extra?: string[]
+  model?: { providerID: string; modelID: string }
+  setup?: (directory: string) => Promise<void>
+  beforeGoto?: (project: { directory: string; sdk: ReturnType<typeof createSdk> }) => Promise<void>
+}
+
 type TestFixtures = {
   llm: LLMFixture
   sdk: ReturnType<typeof createSdk>
   gotoSession: (sessionID?: string) => Promise<void>
-  withProject: <T>(
-    callback: (project: {
-      directory: string
-      slug: string
-      gotoSession: (sessionID?: string) => Promise<void>
-      trackSession: (sessionID: string, directory?: string) => void
-      trackDirectory: (directory: string) => void
-    }) => Promise<T>,
-    options?: {
-      extra?: string[]
-      model?: { providerID: string; modelID: string }
-      setup?: (directory: string) => Promise<void>
-    },
-  ) => Promise<T>
+  withProject: <T>(callback: (project: ProjectHandle) => Promise<T>, options?: ProjectOptions) => Promise<T>
+  withBackendProject: <T>(callback: (project: ProjectHandle) => Promise<T>, options?: ProjectOptions) => Promise<T>
 }
 
 type WorkerFixtures = {
+  backend: {
+    url: string
+    sdk: (directory?: string) => ReturnType<typeof createSdk>
+  }
   directory: string
   slug: string
 }
 
 export const test = base.extend<TestFixtures, WorkerFixtures>({
+  backend: [
+    async ({}, use, workerInfo) => {
+      const handle = await startBackend(`w${workerInfo.workerIndex}`)
+      try {
+        await use({
+          url: handle.url,
+          sdk: (directory?: string) => createSdk(directory, handle.url),
+        })
+      } finally {
+        await handle.stop()
+      }
+    },
+    { scope: "worker" },
+  ],
   llm: async ({}, use) => {
     const rt = ManagedRuntime.make(TestLLMServer.layer)
     try {
@@ -79,6 +116,9 @@ export const test = base.extend<TestFixtures, WorkerFixtures>({
       await use({
         url: svc.url,
         push: (...input) => rt.runPromise(svc.push(...input)),
+        pushMatch: (match, ...input) => rt.runPromise(svc.pushMatch(match, ...input)),
+        textMatch: (match, value, opts) => rt.runPromise(svc.textMatch(match, value, opts)),
+        toolMatch: (match, name, input) => rt.runPromise(svc.toolMatch(match, name, input)),
         text: (value, opts) => rt.runPromise(svc.text(value, opts)),
         tool: (name, input) => rt.runPromise(svc.tool(name, input)),
         toolHang: (name, input) => rt.runPromise(svc.toolHang(name, input)),
@@ -146,51 +186,74 @@ export const test = base.extend<TestFixtures, WorkerFixtures>({
     await use(gotoSession)
   },
   withProject: async ({ page }, use) => {
-    await use(async (callback, options) => {
-      const root = await createTestProject()
-      const sessions = new Map<string, string>()
-      const dirs = new Set<string>()
-      await options?.setup?.(root)
-      await seedStorage(page, { directory: root, extra: options?.extra, model: options?.model })
-
-      const gotoSession = async (sessionID?: string) => {
-        await page.goto(sessionPath(root, sessionID))
-        await waitSession(page, { directory: root, sessionID })
-        const current = sessionIDFromUrl(page.url())
-        if (current) trackSession(current)
-      }
-
-      const trackSession = (sessionID: string, directory?: string) => {
-        sessions.set(sessionID, directory ?? root)
-      }
-
-      const trackDirectory = (directory: string) => {
-        if (directory !== root) dirs.add(directory)
-      }
-
-      try {
-        await gotoSession()
-        const slug = await waitSlug(page)
-        return await callback({ directory: root, slug, gotoSession, trackSession, trackDirectory })
-      } finally {
-        setHealthPhase(page, "cleanup")
-        await Promise.allSettled(
-          Array.from(sessions, ([sessionID, directory]) => cleanupSession({ sessionID, directory })),
-        )
-        await Promise.allSettled(Array.from(dirs, (directory) => cleanupTestProject(directory)))
-        await cleanupTestProject(root)
-        setHealthPhase(page, "test")
-      }
-    })
+    await use((callback, options) => runProject(page, callback, options))
+  },
+  withBackendProject: async ({ page, backend }, use) => {
+    await use((callback, options) =>
+      runProject(page, callback, { ...options, serverUrl: backend.url, sdk: backend.sdk }),
+    )
   },
 })
 
+async function runProject<T>(
+  page: Page,
+  callback: (project: ProjectHandle) => Promise<T>,
+  options?: ProjectOptions & {
+    serverUrl?: string
+    sdk?: (directory?: string) => ReturnType<typeof createSdk>
+  },
+) {
+  const url = options?.serverUrl
+  const root = await createTestProject(url ? { serverUrl: url } : undefined)
+  const sdk = options?.sdk?.(root) ?? createSdk(root, url)
+  const sessions = new Map<string, string>()
+  const dirs = new Set<string>()
+  await options?.setup?.(root)
+  await seedStorage(page, {
+    directory: root,
+    extra: options?.extra,
+    model: options?.model,
+    serverUrl: url,
+  })
+
+  const gotoSession = async (sessionID?: string) => {
+    await page.goto(sessionPath(root, sessionID))
+    await waitSession(page, { directory: root, sessionID, serverUrl: url })
+    const current = sessionIDFromUrl(page.url())
+    if (current) trackSession(current)
+  }
+
+  const trackSession = (sessionID: string, directory?: string) => {
+    sessions.set(sessionID, directory ?? root)
+  }
+
+  const trackDirectory = (directory: string) => {
+    if (directory !== root) dirs.add(directory)
+  }
+
+  try {
+    await options?.beforeGoto?.({ directory: root, sdk })
+    await gotoSession()
+    const slug = await waitSlug(page)
+    return await callback({ directory: root, slug, gotoSession, trackSession, trackDirectory, sdk })
+  } finally {
+    setHealthPhase(page, "cleanup")
+    await Promise.allSettled(
+      Array.from(sessions, ([sessionID, directory]) => cleanupSession({ sessionID, directory, serverUrl: url })),
+    )
+    await Promise.allSettled(Array.from(dirs, (directory) => cleanupTestProject(directory)))
+    await cleanupTestProject(root)
+    setHealthPhase(page, "test")
+  }
+}
+
 async function seedStorage(
   page: Page,
   input: {
     directory: string
     extra?: string[]
     model?: { providerID: string; modelID: string }
+    serverUrl?: string
   },
 ) {
   await seedProjects(page, input)

packages/app/e2e/prompt/mock.ts

@@ -0,0 +1,46 @@
+import { createSdk } from "../utils"
+
+export const openaiModel = { providerID: "openai", modelID: "gpt-5.3-chat-latest" }
+
+type Hit = { body: Record<string, unknown> }
+
+export function bodyText(hit: Hit) {
+  return JSON.stringify(hit.body)
+}
+
+export function titleMatch(hit: Hit) {
+  return bodyText(hit).includes("Generate a title for this conversation")
+}
+
+export function promptMatch(token: string) {
+  return (hit: Hit) => bodyText(hit).includes(token)
+}
+
+export async function withMockOpenAI<T>(input: { serverUrl: string; llmUrl: string; fn: () => Promise<T> }) {
+  const sdk = createSdk(undefined, input.serverUrl)
+  const prev = await sdk.global.config.get().then((res) => res.data ?? {})
+
+  try {
+    await sdk.global.config.update({
+      config: {
+        ...prev,
+        model: `${openaiModel.providerID}/${openaiModel.modelID}`,
+        enabled_providers: ["openai"],
+        provider: {
+          ...prev.provider,
+          openai: {
+            ...prev.provider?.openai,
+            options: {
+              ...prev.provider?.openai?.options,
+              apiKey: "test-key",
+              baseURL: input.llmUrl,
+            },
+          },
+        },
+      },
+    })
+    return await input.fn()
+  } finally {
+    await sdk.global.config.update({ config: prev })
+  }
+}

packages/app/e2e/prompt/prompt-async.spec.ts

@@ -1,47 +1,51 @@
 import { test, expect } from "../fixtures"
 import { promptSelector } from "../selectors"
-import { cleanupSession, sessionIDFromUrl, withSession } from "../actions"
+import { assistantText, sessionIDFromUrl, withSession } from "../actions"
+import { openaiModel, promptMatch, withMockOpenAI } from "./mock"
 
 const text = (value: string | null) => (value ?? "").replace(/\u200B/g, "").trim()
 
 // Regression test for Issue #12453: the synchronous POST /message endpoint holds
 // the connection open while the agent works, causing "Failed to fetch" over
 // VPN/Tailscale. The fix switches to POST /prompt_async which returns immediately.
-test("prompt succeeds when sync message endpoint is unreachable", async ({ page, sdk, gotoSession }) => {
+test("prompt succeeds when sync message endpoint is unreachable", async ({
+  page,
+  llm,
+  backend,
+  withBackendProject,
+}) => {
   test.setTimeout(120_000)
 
   // Simulate Tailscale/VPN killing the long-lived sync connection
   await page.route("**/session/*/message", (route) => route.abort("connectionfailed"))
 
-  await gotoSession()
+  await withMockOpenAI({
+    serverUrl: backend.url,
+    llmUrl: llm.url,
+    fn: async () => {
+      const token = `E2E_ASYNC_${Date.now()}`
+      await llm.textMatch(promptMatch(token), token)
 
-  const token = `E2E_ASYNC_${Date.now()}`
-  await page.locator(promptSelector).click()
-  await page.keyboard.type(`Reply with exactly: ${token}`)
-  await page.keyboard.press("Enter")
+      await withBackendProject(
+        async (project) => {
+          await page.locator(promptSelector).click()
+          await page.keyboard.type(`Reply with exactly: ${token}`)
+          await page.keyboard.press("Enter")
 
-  await expect(page).toHaveURL(/\/session\/[^/?#]+/, { timeout: 30_000 })
-  const sessionID = sessionIDFromUrl(page.url())!
+          await expect(page).toHaveURL(/\/session\/[^/?#]+/, { timeout: 30_000 })
+          const sessionID = sessionIDFromUrl(page.url())!
+          project.trackSession(sessionID)
 
-  try {
-    // Agent response arrives via SSE despite sync endpoint being dead
-    await expect
-      .poll(
-        async () => {
-          const messages = await sdk.session.messages({ sessionID, limit: 50 }).then((r) => r.data ?? [])
-          return messages
-            .filter((m) => m.info.role === "assistant")
-            .flatMap((m) => m.parts)
-            .filter((p) => p.type === "text")
-            .map((p) => p.text)
-            .join("\n")
+          await expect.poll(() => llm.calls()).toBeGreaterThanOrEqual(1)
+
+          await expect.poll(() => assistantText(project.sdk, sessionID), { timeout: 90_000 }).toContain(token)
+        },
+        {
+          model: openaiModel,
         },
-        { timeout: 90_000 },
       )
-      .toContain(token)
-  } finally {
-    await cleanupSession({ sdk, sessionID })
-  }
+    },
+  })
 })
 
 test("failed prompt send restores the composer input", async ({ page, sdk, gotoSession }) => {

packages/app/e2e/prompt/prompt-shell.spec.ts

@@ -2,7 +2,6 @@ import type { ToolPart } from "@opencode-ai/sdk/v2/client"
 import { test, expect } from "../fixtures"
 import { sessionIDFromUrl } from "../actions"
 import { promptSelector } from "../selectors"
-import { createSdk } from "../utils"
 
 const isBash = (part: unknown): part is ToolPart => {
   if (!part || typeof part !== "object") return false
@@ -14,10 +13,9 @@ const isBash = (part: unknown): part is ToolPart => {
 test("shell mode runs a command in the project directory", async ({ page, withProject }) => {
   test.setTimeout(120_000)
 
-  await withProject(async ({ directory, gotoSession, trackSession }) => {
-    const sdk = createSdk(directory)
+  await withProject(async ({ directory, gotoSession, trackSession, sdk }) => {
     const prompt = page.locator(promptSelector)
-    const cmd = process.platform === "win32" ? "dir" : "ls"
+    const cmd = process.platform === "win32" ? "dir" : "command ls"
 
     await gotoSession()
     await prompt.click()

packages/app/e2e/prompt/prompt.spec.ts

@@ -1,44 +1,9 @@
-import fs from "node:fs/promises"
-import path from "node:path"
 import { test, expect } from "../fixtures"
 import { promptSelector } from "../selectors"
-import { sessionIDFromUrl } from "../actions"
-import { createSdk } from "../utils"
+import { assistantText, sessionIDFromUrl } from "../actions"
+import { openaiModel, promptMatch, titleMatch, withMockOpenAI } from "./mock"
 
-async function config(dir: string, url: string) {
-  await fs.writeFile(
-    path.join(dir, "opencode.json"),
-    JSON.stringify({
-      $schema: "https://opencode.ai/config.json",
-      enabled_providers: ["e2e-llm"],
-      provider: {
-        "e2e-llm": {
-          name: "E2E LLM",
-          npm: "@ai-sdk/openai-compatible",
-          env: [],
-          models: {
-            "test-model": {
-              name: "Test Model",
-              tool_call: true,
-              limit: { context: 128000, output: 32000 },
-            },
-          },
-          options: {
-            apiKey: "test-key",
-            baseURL: url,
-          },
-        },
-      },
-      agent: {
-        build: {
-          model: "e2e-llm/test-model",
-        },
-      },
-    }),
-  )
-}
-
-test("can send a prompt and receive a reply", async ({ page, llm, withProject }) => {
+test("can send a prompt and receive a reply", async ({ page, llm, backend, withBackendProject }) => {
   test.setTimeout(120_000)
 
   const pageErrors: string[] = []
@@ -48,48 +13,41 @@ test("can send a prompt and receive a reply", async ({ page, llm, withProject })
   page.on("pageerror", onPageError)
 
   try {
-    await withProject(
-      async (project) => {
-        const sdk = createSdk(project.directory)
+    await withMockOpenAI({
+      serverUrl: backend.url,
+      llmUrl: llm.url,
+      fn: async () => {
         const token = `E2E_OK_${Date.now()}`
 
-        await llm.text(token)
-        await project.gotoSession()
+        await llm.textMatch(titleMatch, "E2E Title")
+        await llm.textMatch(promptMatch(token), token)
 
-        const prompt = page.locator(promptSelector)
-        await prompt.click()
-        await page.keyboard.type(`Reply with exactly: ${token}`)
-        await page.keyboard.press("Enter")
+        await withBackendProject(
+          async (project) => {
+            const prompt = page.locator(promptSelector)
+            await prompt.click()
+            await page.keyboard.type(`Reply with exactly: ${token}`)
+            await page.keyboard.press("Enter")
 
-        await expect(page).toHaveURL(/\/session\/[^/?#]+/, { timeout: 30_000 })
+            await expect(page).toHaveURL(/\/session\/[^/?#]+/, { timeout: 30_000 })
 
-        const sessionID = (() => {
-          const id = sessionIDFromUrl(page.url())
-          if (!id) throw new Error(`Failed to parse session id from url: ${page.url()}`)
-          return id
-        })()
-        project.trackSession(sessionID)
+            const sessionID = (() => {
+              const id = sessionIDFromUrl(page.url())
+              if (!id) throw new Error(`Failed to parse session id from url: ${page.url()}`)
+              return id
+            })()
+            project.trackSession(sessionID)
 
-        await expect
-          .poll(
-            async () => {
-              const messages = await sdk.session.messages({ sessionID, limit: 50 }).then((r) => r.data ?? [])
-              return messages
-                .filter((m) => m.info.role === "assistant")
-                .flatMap((m) => m.parts)
-                .filter((p) => p.type === "text")
-                .map((p) => p.text)
-                .join("\n")
-            },
-            { timeout: 30_000 },
-          )
-          .toContain(token)
+            await expect.poll(() => llm.calls()).toBeGreaterThanOrEqual(1)
+
+            await expect.poll(() => assistantText(project.sdk, sessionID), { timeout: 30_000 }).toContain(token)
+          },
+          {
+            model: openaiModel,
+          },
+        )
       },
-      {
-        model: { providerID: "e2e-llm", modelID: "test-model" },
-        setup: (dir) => config(dir, llm.url),
-      },
-    )
+    })
   } finally {
     page.off("pageerror", onPageError)
   }

packages/app/e2e/utils.ts

@@ -26,21 +26,21 @@ export const serverNamePattern = new RegExp(`(?:${serverNames.map(escape).join("
 export const modKey = process.platform === "darwin" ? "Meta" : "Control"
 export const terminalToggleKey = "Control+Backquote"
 
-export function createSdk(directory?: string) {
-  return createOpencodeClient({ baseUrl: serverUrl, directory, throwOnError: true })
+export function createSdk(directory?: string, baseUrl = serverUrl) {
+  return createOpencodeClient({ baseUrl, directory, throwOnError: true })
 }
 
-export async function resolveDirectory(directory: string) {
-  return createSdk(directory)
+export async function resolveDirectory(directory: string, baseUrl = serverUrl) {
+  return createSdk(directory, baseUrl)
     .path.get()
     .then((x) => x.data?.directory ?? directory)
 }
 
-export async function getWorktree() {
-  const sdk = createSdk()
+export async function getWorktree(baseUrl = serverUrl) {
+  const sdk = createSdk(undefined, baseUrl)
   const result = await sdk.path.get()
   const data = result.data
-  if (!data?.worktree) throw new Error(`Failed to resolve a worktree from ${serverUrl}/path`)
+  if (!data?.worktree) throw new Error(`Failed to resolve a worktree from ${baseUrl}/path`)
   return data.worktree
 }
 

packages/opencode/src/bus/index.ts

@@ -46,7 +46,7 @@ export namespace Bus {
   export const layer = Layer.effect(
     Service,
     Effect.gen(function* () {
-      const cache = yield* InstanceState.make<State>(
+      const state = yield* InstanceState.make<State>(
         Effect.fn("Bus.state")(function* (ctx) {
           const wildcard = yield* PubSub.unbounded<Payload>()
           const typed = new Map<string, PubSub.PubSub<Payload>>()
@@ -82,13 +82,13 @@ export namespace Bus {
 
       function publish<D extends BusEvent.Definition>(def: D, properties: z.output<D["properties"]>) {
         return Effect.gen(function* () {
-          const state = yield* InstanceState.get(cache)
+          const s = yield* InstanceState.get(state)
           const payload: Payload = { type: def.type, properties }
           log.info("publishing", { type: def.type })
 
-          const ps = state.typed.get(def.type)
+          const ps = s.typed.get(def.type)
           if (ps) yield* PubSub.publish(ps, payload)
-          yield* PubSub.publish(state.wildcard, payload)
+          yield* PubSub.publish(s.wildcard, payload)
 
           const dir = yield* InstanceState.directory
           GlobalBus.emit("event", {
@@ -102,8 +102,8 @@ export namespace Bus {
         log.info("subscribing", { type: def.type })
         return Stream.unwrap(
           Effect.gen(function* () {
-            const state = yield* InstanceState.get(cache)
-            const ps = yield* getOrCreate(state, def)
+            const s = yield* InstanceState.get(state)
+            const ps = yield* getOrCreate(s, def)
             return Stream.fromPubSub(ps)
           }),
         ).pipe(Stream.ensuring(Effect.sync(() => log.info("unsubscribing", { type: def.type }))))
@@ -113,8 +113,8 @@ export namespace Bus {
         log.info("subscribing", { type: "*" })
         return Stream.unwrap(
           Effect.gen(function* () {
-            const state = yield* InstanceState.get(cache)
-            return Stream.fromPubSub(state.wildcard)
+            const s = yield* InstanceState.get(state)
+            return Stream.fromPubSub(s.wildcard)
           }),
         ).pipe(Stream.ensuring(Effect.sync(() => log.info("unsubscribing", { type: "*" }))))
       }
@@ -150,14 +150,14 @@ export namespace Bus {
         def: D,
         callback: (event: Payload<D>) => unknown,
       ) {
-        const state = yield* InstanceState.get(cache)
-        const ps = yield* getOrCreate(state, def)
+        const s = yield* InstanceState.get(state)
+        const ps = yield* getOrCreate(s, def)
         return yield* on(ps, def.type, callback)
       })
 
       const subscribeAllCallback = Effect.fn("Bus.subscribeAllCallback")(function* (callback: (event: any) => unknown) {
-        const state = yield* InstanceState.get(cache)
-        return yield* on(state.wildcard, "*", callback)
+        const s = yield* InstanceState.get(state)
+        return yield* on(s.wildcard, "*", callback)
       })
 
       return Service.of({ publish, subscribe, subscribeAll, subscribeCallback, subscribeAllCallback })

packages/opencode/src/cli/cmd/tui/context/local.tsx

@@ -57,7 +57,7 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
           return agents()
         },
         current() {
-          return agents().find((x) => x.name === agentStore.current)!
+          return agents().find((x) => x.name === agentStore.current) ?? agents()[0]
         },
         set(name: string) {
           if (!agents().some((x) => x.name === name))

packages/opencode/src/command/index.ts

@@ -85,7 +85,7 @@ export namespace Command {
 
         commands[Default.INIT] = {
           name: Default.INIT,
-          description: "create/update AGENTS.md",
+          description: "guided AGENTS.md setup",
           source: "command",
           get template() {
             return PROMPT_INITIALIZE.replace("${path}", ctx.worktree)
@@ -161,16 +161,16 @@ export namespace Command {
         }
       })
 
-      const cache = yield* InstanceState.make<State>((ctx) => init(ctx))
+      const state = yield* InstanceState.make<State>((ctx) => init(ctx))
 
       const get = Effect.fn("Command.get")(function* (name: string) {
-        const state = yield* InstanceState.get(cache)
-        return state.commands[name]
+        const s = yield* InstanceState.get(state)
+        return s.commands[name]
       })
 
       const list = Effect.fn("Command.list")(function* () {
-        const state = yield* InstanceState.get(cache)
-        return Object.values(state.commands)
+        const s = yield* InstanceState.get(state)
+        return Object.values(s.commands)
       })
 
       return Service.of({ get, list })

packages/opencode/src/command/template/initialize.txt

@@ -1,10 +1,66 @@
-Please analyze this codebase and create an AGENTS.md file containing:
-1. Build/lint/test commands - especially for running a single test
-2. Code style guidelines including imports, formatting, types, naming conventions, error handling, etc.
+Create or update `AGENTS.md` for this repository.
 
-The file you create will be given to agentic coding agents (such as yourself) that operate in this repository. Make it about 150 lines long.
-If there are Cursor rules (in .cursor/rules/ or .cursorrules) or Copilot rules (in .github/copilot-instructions.md), make sure to include them.
-
-If there's already an AGENTS.md, improve it if it's located in ${path}
+The goal is a compact instruction file that helps future OpenCode sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.
 
+User-provided focus or constraints (honor these):
 $ARGUMENTS
+
+## How to investigate
+
+Read the highest-value sources first:
+- `README*`, root manifests, workspace config, lockfiles
+- build, test, lint, formatter, typecheck, and codegen config
+- CI workflows and pre-commit / task runner config
+- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
+- repo-local OpenCode config such as `opencode.json`
+
+If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
+
+Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.
+
+## What to extract
+
+Look for the highest-signal facts for an agent working in this repo:
+- exact developer commands, especially non-obvious ones
+- how to run a single test, a single package, or a focused verification step
+- required command order when it matters, such as `lint -> typecheck -> test`
+- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
+- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
+- repo-specific style or workflow conventions that differ from defaults
+- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
+- important constraints from existing instruction files worth preserving
+
+Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.
+
+## Questions
+
+Only ask the user questions if the repo cannot answer something important. Use the `question` tool for one short batch at most.
+
+Good questions:
+- undocumented team conventions
+- branch / PR / release expectations
+- missing setup or test prerequisites that are known but not written down
+
+Do not ask about anything the repo already makes clear.
+
+## Writing rules
+
+Include only high-signal, repo-specific guidance such as:
+- exact commands and shortcuts the agent would otherwise guess wrong
+- architecture notes that are not obvious from filenames
+- conventions that differ from language or framework defaults
+- setup requirements, environment quirks, and operational gotchas
+- references to existing instruction sources that matter
+
+Exclude:
+- generic software advice
+- long tutorials or exhaustive file trees
+- obvious language conventions
+- speculative claims or anything you could not verify
+- content better stored in another file referenced via `opencode.json` `instructions`
+
+When in doubt, omit.
+
+Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.
+
+If `AGENTS.md` already exists at `${path}`, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.

packages/opencode/src/effect/cross-spawn-spawner.ts

@@ -386,9 +386,17 @@ export const make = Effect.gen(function* () {
                 if (code !== 0 && Predicate.isNotNull(code)) return yield* Effect.ignore(kill(killGroup))
                 return yield* Effect.void
               }
-              return yield* kill((command, proc, signal) =>
-                Effect.catch(killGroup(command, proc, signal), () => killOne(command, proc, signal)),
-              ).pipe(Effect.andThen(Deferred.await(signal)), Effect.ignore)
+              const send = (s: NodeJS.Signals) =>
+                Effect.catch(killGroup(command, proc, s), () => killOne(command, proc, s))
+              const sig = command.options.killSignal ?? "SIGTERM"
+              const attempt = send(sig).pipe(Effect.andThen(Deferred.await(signal)), Effect.asVoid)
+              const escalated = command.options.forceKillAfter
+                ? Effect.timeoutOrElse(attempt, {
+                    duration: command.options.forceKillAfter,
+                    orElse: () => send("SIGKILL").pipe(Effect.andThen(Deferred.await(signal)), Effect.asVoid),
+                  })
+                : attempt
+              return yield* Effect.ignore(escalated)
             }),
           )
 
@@ -413,14 +421,17 @@ export const make = Effect.gen(function* () {
                 ),
               )
             }),
-            kill: (opts?: ChildProcess.KillOptions) =>
-              timeout(
-                proc,
-                command,
-                opts,
-              )((command, proc, signal) =>
-                Effect.catch(killGroup(command, proc, signal), () => killOne(command, proc, signal)),
-              ).pipe(Effect.andThen(Deferred.await(signal)), Effect.asVoid),
+            kill: (opts?: ChildProcess.KillOptions) => {
+              const sig = opts?.killSignal ?? "SIGTERM"
+              const send = (s: NodeJS.Signals) =>
+                Effect.catch(killGroup(command, proc, s), () => killOne(command, proc, s))
+              const attempt = send(sig).pipe(Effect.andThen(Deferred.await(signal)), Effect.asVoid)
+              if (!opts?.forceKillAfter) return attempt
+              return Effect.timeoutOrElse(attempt, {
+                duration: opts.forceKillAfter,
+                orElse: () => send("SIGKILL").pipe(Effect.andThen(Deferred.await(signal)), Effect.asVoid),
+              })
+            },
           })
         }
         case "PipedCommand": {
@@ -477,3 +488,14 @@ export const layer: Layer.Layer<ChildProcessSpawner, never, FileSystem.FileSyste
 )
 
 export const defaultLayer = layer.pipe(Layer.provide(NodeFileSystem.layer), Layer.provide(NodePath.layer))
+
+import { lazy } from "@/util/lazy"
+
+const rt = lazy(() => {
+  // Dynamic import to avoid circular dep: cross-spawn-spawner → run-service → Instance → project → cross-spawn-spawner
+  const { makeRuntime } = require("@/effect/run-service") as typeof import("@/effect/run-service")
+  return makeRuntime(ChildProcessSpawner, defaultLayer)
+})
+
+export const runPromiseExit: ReturnType<typeof rt>["runPromiseExit"] = (...args) => rt().runPromiseExit(...(args as [any]))
+export const runPromise: ReturnType<typeof rt>["runPromise"] = (...args) => rt().runPromise(...(args as [any]))

packages/opencode/src/mcp/index.ts

@@ -477,7 +477,7 @@ export namespace MCP {
         })
       }
 
-      const cache = yield* InstanceState.make<State>(
+      const state = yield* InstanceState.make<State>(
         Effect.fn("MCP.state")(function* () {
           const cfg = yield* cfgSvc.get()
           const config = cfg.mcp ?? {}
@@ -549,7 +549,7 @@ export namespace MCP {
       }
 
       const status = Effect.fn("MCP.status")(function* () {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
 
         const cfg = yield* cfgSvc.get()
         const config = cfg.mcp ?? {}
@@ -564,12 +564,12 @@ export namespace MCP {
       })
 
       const clients = Effect.fn("MCP.clients")(function* () {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         return s.clients
       })
 
       const createAndStore = Effect.fn("MCP.createAndStore")(function* (name: string, mcp: Config.Mcp) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const result = yield* create(name, mcp)
 
         s.status[name] = result.status
@@ -588,7 +588,7 @@ export namespace MCP {
 
       const add = Effect.fn("MCP.add")(function* (name: string, mcp: Config.Mcp) {
         yield* createAndStore(name, mcp)
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         return { status: s.status }
       })
 
@@ -602,7 +602,7 @@ export namespace MCP {
       })
 
       const disconnect = Effect.fn("MCP.disconnect")(function* (name: string) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         yield* closeClient(s, name)
         delete s.clients[name]
         s.status[name] = { status: "disabled" }
@@ -610,7 +610,7 @@ export namespace MCP {
 
       const tools = Effect.fn("MCP.tools")(function* () {
         const result: Record<string, Tool> = {}
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
 
         const cfg = yield* cfgSvc.get()
         const config = cfg.mcp ?? {}
@@ -657,12 +657,12 @@ export namespace MCP {
       }
 
       const prompts = Effect.fn("MCP.prompts")(function* () {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         return yield* collectFromConnected(s, (c) => c.listPrompts().then((r) => r.prompts), "prompts")
       })
 
       const resources = Effect.fn("MCP.resources")(function* () {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         return yield* collectFromConnected(s, (c) => c.listResources().then((r) => r.resources), "resources")
       })
 
@@ -672,7 +672,7 @@ export namespace MCP {
         label: string,
         meta?: Record<string, unknown>,
       ) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const client = s.clients[clientName]
         if (!client) {
           log.warn(`client not found for ${label}`, { clientName })

packages/opencode/src/plugin/index.ts

@@ -103,7 +103,7 @@ export namespace Plugin {
       const bus = yield* Bus.Service
       const config = yield* Config.Service
 
-      const cache = yield* InstanceState.make<State>(
+      const state = yield* InstanceState.make<State>(
         Effect.fn("Plugin.state")(function* (ctx) {
           const hooks: Hooks[] = []
 
@@ -279,8 +279,8 @@ export namespace Plugin {
         Output = Parameters<Required<Hooks>[Name]>[1],
       >(name: Name, input: Input, output: Output) {
         if (!name) return output
-        const state = yield* InstanceState.get(cache)
-        for (const hook of state.hooks) {
+        const s = yield* InstanceState.get(state)
+        for (const hook of s.hooks) {
           const fn = hook[name] as any
           if (!fn) continue
           yield* Effect.promise(async () => fn(input, output))
@@ -289,12 +289,12 @@ export namespace Plugin {
       })
 
       const list = Effect.fn("Plugin.list")(function* () {
-        const state = yield* InstanceState.get(cache)
-        return state.hooks
+        const s = yield* InstanceState.get(state)
+        return s.hooks
       })
 
       const init = Effect.fn("Plugin.init")(function* () {
-        yield* InstanceState.get(cache)
+        yield* InstanceState.get(state)
       })
 
       return Service.of({ trigger, list, init })

packages/opencode/src/provider/provider.ts

@@ -967,7 +967,7 @@ export namespace Provider {
       const config = yield* Config.Service
       const auth = yield* Auth.Service
 
-      const cache = yield* InstanceState.make<State>(() =>
+      const state = yield* InstanceState.make<State>(() =>
         Effect.gen(function* () {
           using _ = log.time("state")
           const cfg = yield* config.get()
@@ -1247,7 +1247,7 @@ export namespace Provider {
         }),
       )
 
-      const list = Effect.fn("Provider.list")(() => InstanceState.use(cache, (s) => s.providers))
+      const list = Effect.fn("Provider.list")(() => InstanceState.use(state, (s) => s.providers))
 
       async function resolveSDK(model: Model, s: State) {
         try {
@@ -1385,11 +1385,11 @@ export namespace Provider {
       }
 
       const getProvider = Effect.fn("Provider.getProvider")((providerID: ProviderID) =>
-        InstanceState.use(cache, (s) => s.providers[providerID]),
+        InstanceState.use(state, (s) => s.providers[providerID]),
       )
 
       const getModel = Effect.fn("Provider.getModel")(function* (providerID: ProviderID, modelID: ModelID) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const provider = s.providers[providerID]
         if (!provider) {
           const available = Object.keys(s.providers)
@@ -1407,7 +1407,7 @@ export namespace Provider {
       })
 
       const getLanguage = Effect.fn("Provider.getLanguage")(function* (model: Model) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const key = `${model.providerID}/${model.id}`
         if (s.models.has(key)) return s.models.get(key)!
 
@@ -1439,7 +1439,7 @@ export namespace Provider {
       })
 
       const closest = Effect.fn("Provider.closest")(function* (providerID: ProviderID, query: string[]) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const provider = s.providers[providerID]
         if (!provider) return undefined
         for (const item of query) {
@@ -1458,7 +1458,7 @@ export namespace Provider {
           return yield* getModel(parsed.providerID, parsed.modelID)
         }
 
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const provider = s.providers[providerID]
         if (!provider) return undefined
 
@@ -1510,7 +1510,7 @@ export namespace Provider {
         const cfg = yield* config.get()
         if (cfg.model) return parseModel(cfg.model)
 
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const recent = yield* Effect.promise(() =>
           Filesystem.readJson<{
             recent?: { providerID: ProviderID; modelID: ModelID }[]

packages/opencode/src/pty/index.ts

@@ -130,7 +130,7 @@ export namespace Pty {
         session.subscribers.clear()
       }
 
-      const cache = yield* InstanceState.make<State>(
+      const state = yield* InstanceState.make<State>(
         Effect.fn("Pty.state")(function* (ctx) {
           const state = {
             dir: ctx.directory,
@@ -151,27 +151,27 @@ export namespace Pty {
       )
 
       const remove = Effect.fn("Pty.remove")(function* (id: PtyID) {
-        const state = yield* InstanceState.get(cache)
-        const session = state.sessions.get(id)
+        const s = yield* InstanceState.get(state)
+        const session = s.sessions.get(id)
         if (!session) return
-        state.sessions.delete(id)
+        s.sessions.delete(id)
         log.info("removing session", { id })
         teardown(session)
         void Bus.publish(Event.Deleted, { id: session.info.id })
       })
 
       const list = Effect.fn("Pty.list")(function* () {
-        const state = yield* InstanceState.get(cache)
-        return Array.from(state.sessions.values()).map((session) => session.info)
+        const s = yield* InstanceState.get(state)
+        return Array.from(s.sessions.values()).map((session) => session.info)
       })
 
       const get = Effect.fn("Pty.get")(function* (id: PtyID) {
-        const state = yield* InstanceState.get(cache)
-        return state.sessions.get(id)?.info
+        const s = yield* InstanceState.get(state)
+        return s.sessions.get(id)?.info
       })
 
       const create = Effect.fn("Pty.create")(function* (input: CreateInput) {
-        const state = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         return yield* Effect.promise(async () => {
           const id = PtyID.ascending()
           const command = input.command || Shell.preferred()
@@ -180,7 +180,7 @@ export namespace Pty {
             args.push("-l")
           }
 
-          const cwd = input.cwd || state.dir
+          const cwd = input.cwd || s.dir
           const shellEnv = await Plugin.trigger("shell.env", { cwd }, { env: {} })
           const env = {
             ...process.env,
@@ -221,7 +221,7 @@ export namespace Pty {
             cursor: 0,
             subscribers: new Map(),
           }
-          state.sessions.set(id, session)
+          s.sessions.set(id, session)
           proc.onData(
             Instance.bind((chunk) => {
               session.cursor += chunk.length
@@ -264,8 +264,8 @@ export namespace Pty {
       })
 
       const update = Effect.fn("Pty.update")(function* (id: PtyID, input: UpdateInput) {
-        const state = yield* InstanceState.get(cache)
-        const session = state.sessions.get(id)
+        const s = yield* InstanceState.get(state)
+        const session = s.sessions.get(id)
         if (!session) return
         if (input.title) {
           session.info.title = input.title
@@ -278,24 +278,24 @@ export namespace Pty {
       })
 
       const resize = Effect.fn("Pty.resize")(function* (id: PtyID, cols: number, rows: number) {
-        const state = yield* InstanceState.get(cache)
-        const session = state.sessions.get(id)
+        const s = yield* InstanceState.get(state)
+        const session = s.sessions.get(id)
         if (session && session.info.status === "running") {
           session.process.resize(cols, rows)
         }
       })
 
       const write = Effect.fn("Pty.write")(function* (id: PtyID, data: string) {
-        const state = yield* InstanceState.get(cache)
-        const session = state.sessions.get(id)
+        const s = yield* InstanceState.get(state)
+        const session = s.sessions.get(id)
         if (session && session.info.status === "running") {
           session.process.write(data)
         }
       })
 
       const connect = Effect.fn("Pty.connect")(function* (id: PtyID, ws: Socket, cursor?: number) {
-        const state = yield* InstanceState.get(cache)
-        const session = state.sessions.get(id)
+        const s = yield* InstanceState.get(state)
+        const session = s.sessions.get(id)
         if (!session) {
           ws.close()
           return

packages/opencode/src/session/prompt.ts

@@ -28,7 +28,9 @@ import { ReadTool } from "../tool/read"
 import { FileTime } from "../file/time"
 import { Flag } from "../flag/flag"
 import { ulid } from "ulid"
-import { spawn } from "child_process"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+import * as CrossSpawnSpawner from "@/effect/cross-spawn-spawner"
+import * as Stream from "effect/Stream"
 import { Command } from "../command"
 import { pathToFileURL, fileURLToPath } from "url"
 import { ConfigMarkdown } from "../config/markdown"
@@ -96,9 +98,10 @@ export namespace SessionPrompt {
       const filetime = yield* FileTime.Service
       const registry = yield* ToolRegistry.Service
       const truncate = yield* Truncate.Service
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
       const scope = yield* Scope.Scope
 
-      const cache = yield* InstanceState.make(
+      const state = yield* InstanceState.make(
         Effect.fn("SessionPrompt.state")(function* () {
           const runners = new Map<string, Runner<MessageV2.WithParts>>()
           yield* Effect.addFinalizer(
@@ -132,14 +135,14 @@ export namespace SessionPrompt {
       const assertNotBusy: (sessionID: SessionID) => Effect.Effect<void, Session.BusyError> = Effect.fn(
         "SessionPrompt.assertNotBusy",
       )(function* (sessionID: SessionID) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const runner = s.runners.get(sessionID)
         if (runner?.busy) throw new Session.BusyError(sessionID)
       })
 
       const cancel = Effect.fn("SessionPrompt.cancel")(function* (sessionID: SessionID) {
         log.info("cancel", { sessionID })
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const runner = s.runners.get(sessionID)
         if (!runner || !runner.busy) {
           yield* status.set(sessionID, { type: "idle" })
@@ -809,22 +812,26 @@ NOTE: At any point in time through this workflow you should feel free to ask the
           fish: { args: ["-c", input.command] },
           zsh: {
             args: [
-              "-c",
               "-l",
+              "-c",
               `
+                __oc_cwd=$PWD
                 [[ -f ~/.zshenv ]] && source ~/.zshenv >/dev/null 2>&1 || true
                 [[ -f "\${ZDOTDIR:-$HOME}/.zshrc" ]] && source "\${ZDOTDIR:-$HOME}/.zshrc" >/dev/null 2>&1 || true
+                cd "$__oc_cwd"
                 eval ${JSON.stringify(input.command)}
               `,
             ],
           },
           bash: {
             args: [
-              "-c",
               "-l",
+              "-c",
               `
+                __oc_cwd=$PWD
                 shopt -s expand_aliases
                 [[ -f ~/.bashrc ]] && source ~/.bashrc >/dev/null 2>&1 || true
+                cd "$__oc_cwd"
                 eval ${JSON.stringify(input.command)}
               `,
             ],
@@ -832,7 +839,7 @@ NOTE: At any point in time through this workflow you should feel free to ask the
           cmd: { args: ["/c", input.command] },
           powershell: { args: ["-NoProfile", "-Command", input.command] },
           pwsh: { args: ["-NoProfile", "-Command", input.command] },
-          "": { args: ["-c", `${input.command}`] },
+          "": { args: ["-c", input.command] },
         }
 
         const args = (invocations[shellName] ?? invocations[""]).args
@@ -842,51 +849,20 @@ NOTE: At any point in time through this workflow you should feel free to ask the
           { cwd, sessionID: input.sessionID, callID: part.callID },
           { env: {} },
         )
-        const proc = yield* Effect.sync(() =>
-          spawn(sh, args, {
-            cwd,
-            detached: process.platform !== "win32",
-            windowsHide: process.platform === "win32",
-            stdio: ["ignore", "pipe", "pipe"],
-            env: {
-              ...process.env,
-              ...shellEnv.env,
-              TERM: "dumb",
-            },
-          }),
-        )
+
+        const cmd = ChildProcess.make(sh, args, {
+          cwd,
+          extendEnv: true,
+          env: { ...shellEnv.env, TERM: "dumb" },
+          stdin: "ignore",
+          forceKillAfter: "3 seconds",
+        })
 
         let output = ""
-        const write = () => {
-          if (part.state.status !== "running") return
-          part.state.metadata = { output, description: "" }
-          void Effect.runFork(sessions.updatePart(part))
-        }
-
-        proc.stdout?.on("data", (chunk) => {
-          output += chunk.toString()
-          write()
-        })
-        proc.stderr?.on("data", (chunk) => {
-          output += chunk.toString()
-          write()
-        })
-
         let aborted = false
-        let exited = false
-        let finished = false
-        const kill = Effect.promise(() => Shell.killTree(proc, { exited: () => exited }))
-
-        const abortHandler = () => {
-          if (aborted) return
-          aborted = true
-          void Effect.runFork(kill)
-        }
 
         const finish = Effect.uninterruptible(
           Effect.gen(function* () {
-            if (finished) return
-            finished = true
             if (aborted) {
               output += "\n\n" + ["<metadata>", "User aborted the command", "</metadata>"].join("\n")
             }
@@ -908,20 +884,26 @@ NOTE: At any point in time through this workflow you should feel free to ask the
           }),
         )
 
-        const exit = yield* Effect.promise(() => {
-          signal.addEventListener("abort", abortHandler, { once: true })
-          if (signal.aborted) abortHandler()
-          return new Promise<void>((resolve) => {
-            const close = () => {
-              exited = true
-              proc.off("close", close)
-              resolve()
-            }
-            proc.once("close", close)
-          })
+        const exit = yield* Effect.gen(function* () {
+          const handle = yield* spawner.spawn(cmd)
+          yield* Stream.runForEach(Stream.decodeText(handle.all), (chunk) =>
+            Effect.sync(() => {
+              output += chunk
+              if (part.state.status === "running") {
+                part.state.metadata = { output, description: "" }
+                void Effect.runFork(sessions.updatePart(part))
+              }
+            }),
+          )
+          yield* handle.exitCode
         }).pipe(
-          Effect.onInterrupt(() => Effect.sync(abortHandler)),
-          Effect.ensuring(Effect.sync(() => signal.removeEventListener("abort", abortHandler))),
+          Effect.scoped,
+          Effect.onInterrupt(() =>
+            Effect.sync(() => {
+              aborted = true
+            }),
+          ),
+          Effect.orDie,
           Effect.ensuring(finish),
           Effect.exit,
         )
@@ -1575,14 +1557,14 @@ NOTE: At any point in time through this workflow you should feel free to ask the
       const loop: (input: z.infer<typeof LoopInput>) => Effect.Effect<MessageV2.WithParts> = Effect.fn(
         "SessionPrompt.loop",
       )(function* (input: z.infer<typeof LoopInput>) {
-        const s = yield* InstanceState.get(cache)
+        const s = yield* InstanceState.get(state)
         const runner = getRunner(s.runners, input.sessionID)
         return yield* runner.ensureRunning(runLoop(input.sessionID))
       })
 
       const shell: (input: ShellInput) => Effect.Effect<MessageV2.WithParts> = Effect.fn("SessionPrompt.shell")(
         function* (input: ShellInput) {
-          const s = yield* InstanceState.get(cache)
+          const s = yield* InstanceState.get(state)
           const runner = getRunner(s.runners, input.sessionID)
           return yield* runner.startShell((signal) => shellImpl(input, signal))
         },
@@ -1735,6 +1717,7 @@ NOTE: At any point in time through this workflow you should feel free to ask the
         Layer.provide(Session.defaultLayer),
         Layer.provide(Agent.defaultLayer),
         Layer.provide(Bus.layer),
+        Layer.provide(CrossSpawnSpawner.defaultLayer),
       ),
     ),
   )

packages/opencode/src/tool/bash.ts

@@ -1,6 +1,5 @@
 import z from "zod"
 import os from "os"
-import { spawn } from "child_process"
 import { Tool } from "./tool"
 import path from "path"
 import DESCRIPTION from "./bash.txt"
@@ -18,6 +17,9 @@ import { Shell } from "@/shell/shell"
 import { BashArity } from "@/permission/arity"
 import { Truncate } from "./truncate"
 import { Plugin } from "@/plugin"
+import { Cause, Effect, Exit, Stream } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+import * as CrossSpawnSpawner from "@/effect/cross-spawn-spawner"
 
 const MAX_METADATA_LENGTH = 30_000
 const DEFAULT_TIMEOUT = Flag.OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS || 2 * 60 * 1000
@@ -293,27 +295,26 @@ async function shellEnv(ctx: Tool.Context, cwd: string) {
   }
 }
 
-function launch(shell: string, name: string, command: string, cwd: string, env: NodeJS.ProcessEnv) {
+function cmd(shell: string, name: string, command: string, cwd: string, env: NodeJS.ProcessEnv) {
   if (process.platform === "win32" && PS.has(name)) {
-    return spawn(shell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", command], {
+    return ChildProcess.make(shell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", command], {
       cwd,
       env,
-      stdio: ["ignore", "pipe", "pipe"],
+      stdin: "ignore",
       detached: false,
-      windowsHide: true,
     })
   }
 
-  return spawn(command, {
+  return ChildProcess.make(command, [], {
     shell,
     cwd,
     env,
-    stdio: ["ignore", "pipe", "pipe"],
+    stdin: "ignore",
     detached: process.platform !== "win32",
-    windowsHide: process.platform === "win32",
   })
 }
 
+
 async function run(
   input: {
     shell: string
@@ -326,8 +327,9 @@ async function run(
   },
   ctx: Tool.Context,
 ) {
-  const proc = launch(input.shell, input.name, input.command, input.cwd, input.env)
   let output = ""
+  let expired = false
+  let aborted = false
 
   ctx.metadata({
     metadata: {
@@ -336,76 +338,78 @@ async function run(
     },
   })
 
-  const append = (chunk: Buffer) => {
-    output += chunk.toString()
-    ctx.metadata({
-      metadata: {
-        output: preview(output),
-        description: input.description,
-      },
-    })
+  const exit = await CrossSpawnSpawner.runPromiseExit((spawner) =>
+    Effect.gen(function* () {
+      const handle = yield* spawner.spawn(
+        cmd(input.shell, input.name, input.command, input.cwd, input.env),
+      )
+
+      yield* Effect.forkScoped(
+        Stream.runForEach(
+          Stream.decodeText(handle.all),
+          (chunk) =>
+            Effect.sync(() => {
+              output += chunk
+              ctx.metadata({
+                metadata: {
+                  output: preview(output),
+                  description: input.description,
+                },
+              })
+            }),
+        ),
+      )
+
+      const abort = Effect.callback<void>((resume) => {
+        if (ctx.abort.aborted) return resume(Effect.void)
+        const handler = () => resume(Effect.void)
+        ctx.abort.addEventListener("abort", handler, { once: true })
+        return Effect.sync(() => ctx.abort.removeEventListener("abort", handler))
+      })
+
+      const timeout = Effect.sleep(`${input.timeout + 100} millis`)
+
+      const exit = yield* Effect.raceAll([
+        handle.exitCode.pipe(Effect.map((code) => ({ kind: "exit" as const, code }))),
+        abort.pipe(Effect.map(() => ({ kind: "abort" as const, code: null }))),
+        timeout.pipe(Effect.map(() => ({ kind: "timeout" as const, code: null }))),
+      ])
+
+      if (exit.kind === "abort") {
+        aborted = true
+        yield* handle.kill({ forceKillAfter: "3 seconds" }).pipe(Effect.orDie)
+      }
+      if (exit.kind === "timeout") {
+        expired = true
+        yield* handle.kill({ forceKillAfter: "3 seconds" }).pipe(Effect.orDie)
+      }
+
+      return exit.kind === "exit" ? exit.code : null
+    }).pipe(
+      Effect.scoped,
+      Effect.orDie,
+    ),
+  )
+
+  let code: number | null = null
+  if (Exit.isSuccess(exit)) {
+    code = exit.value
+  } else if (!Cause.hasInterruptsOnly(exit.cause)) {
+    throw Cause.squash(exit.cause)
   }
 
-  proc.stdout?.on("data", append)
-  proc.stderr?.on("data", append)
-
-  let expired = false
-  let aborted = false
-  let exited = false
-
-  const kill = () => Shell.killTree(proc, { exited: () => exited })
-
-  if (ctx.abort.aborted) {
-    aborted = true
-    await kill()
-  }
-
-  const abort = () => {
-    aborted = true
-    void kill()
-  }
-
-  ctx.abort.addEventListener("abort", abort, { once: true })
-  const timer = setTimeout(() => {
-    expired = true
-    void kill()
-  }, input.timeout + 100)
-
-  await new Promise<void>((resolve, reject) => {
-    const cleanup = () => {
-      clearTimeout(timer)
-      ctx.abort.removeEventListener("abort", abort)
-    }
-
-    proc.once("exit", () => {
-      exited = true
-    })
-
-    proc.once("close", () => {
-      exited = true
-      cleanup()
-      resolve()
-    })
-
-    proc.once("error", (error) => {
-      exited = true
-      cleanup()
-      reject(error)
-    })
-  })
-
-  const metadata: string[] = []
-  if (expired) metadata.push(`bash tool terminated command after exceeding timeout ${input.timeout} ms`)
-  if (aborted) metadata.push("User aborted the command")
-  if (metadata.length > 0) {
-    output += "\n\n<bash_metadata>\n" + metadata.join("\n") + "\n</bash_metadata>"
+  const meta: string[] = []
+  if (expired) meta.push(`bash tool terminated command after exceeding timeout ${input.timeout} ms`)
+  if (aborted) meta.push("User aborted the command")
+  if (meta.length > 0) {
+    output += "\n\n<bash_metadata>\n" + meta.join("\n") + "\n</bash_metadata>"
   }
 
   return {
     title: input.description,
     metadata: {
       output: preview(output),
-      exit: proc.exitCode,
+      exit: code,
       description: input.description,
     },
     output,

packages/opencode/src/tool/registry.ts

@@ -57,7 +57,7 @@ export namespace ToolRegistry {
       const config = yield* Config.Service
       const plugin = yield* Plugin.Service
 
-      const cache = yield* InstanceState.make<State>(
+      const state = yield* InstanceState.make<State>(
         Effect.fn("ToolRegistry.state")(function* (ctx) {
           const custom: Tool.Info[] = []
 
@@ -139,18 +139,18 @@ export namespace ToolRegistry {
       })
 
       const register = Effect.fn("ToolRegistry.register")(function* (tool: Tool.Info) {
-        const state = yield* InstanceState.get(cache)
-        const idx = state.custom.findIndex((t) => t.id === tool.id)
+        const s = yield* InstanceState.get(state)
+        const idx = s.custom.findIndex((t) => t.id === tool.id)
         if (idx >= 0) {
-          state.custom.splice(idx, 1, tool)
+          s.custom.splice(idx, 1, tool)
           return
         }
-        state.custom.push(tool)
+        s.custom.push(tool)
       })
 
       const ids = Effect.fn("ToolRegistry.ids")(function* () {
-        const state = yield* InstanceState.get(cache)
-        const tools = yield* all(state.custom)
+        const s = yield* InstanceState.get(state)
+        const tools = yield* all(s.custom)
         return tools.map((t) => t.id)
       })
 
@@ -158,8 +158,8 @@ export namespace ToolRegistry {
         model: { providerID: ProviderID; modelID: ModelID },
         agent?: Agent.Info,
       ) {
-        const state = yield* InstanceState.get(cache)
-        const allTools = yield* all(state.custom)
+        const s = yield* InstanceState.get(state)
+        const allTools = yield* all(s.custom)
         const filtered = allTools.filter((tool) => {
           if (tool.id === "codesearch" || tool.id === "websearch") {
             return model.providerID === ProviderID.opencode || Flag.OPENCODE_ENABLE_EXA

packages/opencode/test/lib/llm-server.ts

@@ -20,6 +20,13 @@ type Hit = {
   body: Record<string, unknown>
 }
 
+type Match = (hit: Hit) => boolean
+
+type Queue = {
+  item: Item
+  match?: Match
+}
+
 type Wait = {
   count: number
   ready: Deferred.Deferred<void>
@@ -420,7 +427,7 @@ const reset = Effect.fn("TestLLMServer.reset")(function* (item: Sse) {
     for (const part of item.tail) res.write(line(part))
     res.destroy(new Error("connection reset"))
   })
-  yield* Effect.never
+  return yield* Effect.never
 })
 
 function fail(item: HttpError) {
@@ -581,6 +588,9 @@ namespace TestLLMServer {
   export interface Service {
     readonly url: string
     readonly push: (...input: (Item | Reply)[]) => Effect.Effect<void>
+    readonly pushMatch: (match: Match, ...input: (Item | Reply)[]) => Effect.Effect<void>
+    readonly textMatch: (match: Match, value: string, opts?: { usage?: Usage }) => Effect.Effect<void>
+    readonly toolMatch: (match: Match, name: string, input: unknown) => Effect.Effect<void>
     readonly text: (value: string, opts?: { usage?: Usage }) => Effect.Effect<void>
     readonly tool: (name: string, input: unknown) => Effect.Effect<void>
     readonly toolHang: (name: string, input: unknown) => Effect.Effect<void>
@@ -605,11 +615,15 @@ export class TestLLMServer extends ServiceMap.Service<TestLLMServer, TestLLMServ
       const router = yield* HttpRouter.HttpRouter
 
       let hits: Hit[] = []
-      let list: Item[] = []
+      let list: Queue[] = []
       let waits: Wait[] = []
 
       const queue = (...input: (Item | Reply)[]) => {
-        list = [...list, ...input.map(item)]
+        list = [...list, ...input.map((value) => ({ item: item(value) }))]
+      }
+
+      const queueMatch = (match: Match, ...input: (Item | Reply)[]) => {
+        list = [...list, ...input.map((value) => ({ item: item(value), match }))]
       }
 
       const notify = Effect.fnUntraced(function* () {
@@ -619,19 +633,21 @@ export class TestLLMServer extends ServiceMap.Service<TestLLMServer, TestLLMServ
         yield* Effect.forEach(ready, (item) => Deferred.succeed(item.ready, void 0))
       })
 
-      const pull = () => {
-        const first = list[0]
-        if (!first) return
-        list = list.slice(1)
-        return first
+      const pull = (hit: Hit) => {
+        const index = list.findIndex((entry) => !entry.match || entry.match(hit))
+        if (index === -1) return
+        const first = list[index]
+        list = [...list.slice(0, index), ...list.slice(index + 1)]
+        return first.item
       }
 
       const handle = Effect.fn("TestLLMServer.handle")(function* (mode: "chat" | "responses") {
         const req = yield* HttpServerRequest.HttpServerRequest
-        const next = pull()
-        if (!next) return HttpServerResponse.text("unexpected request", { status: 500 })
         const body = yield* req.json.pipe(Effect.orElseSucceed(() => ({})))
-        hits = [...hits, hit(req.originalUrl, body)]
+        const current = hit(req.originalUrl, body)
+        const next = pull(current)
+        if (!next) return HttpServerResponse.text("unexpected request", { status: 500 })
+        hits = [...hits, current]
         yield* notify()
         if (next.type !== "sse") return fail(next)
         if (mode === "responses") return send(responses(next, modelFrom(body)))
@@ -655,6 +671,21 @@ export class TestLLMServer extends ServiceMap.Service<TestLLMServer, TestLLMServ
         push: Effect.fn("TestLLMServer.push")(function* (...input: (Item | Reply)[]) {
           queue(...input)
         }),
+        pushMatch: Effect.fn("TestLLMServer.pushMatch")(function* (match: Match, ...input: (Item | Reply)[]) {
+          queueMatch(match, ...input)
+        }),
+        textMatch: Effect.fn("TestLLMServer.textMatch")(function* (
+          match: Match,
+          value: string,
+          opts?: { usage?: Usage },
+        ) {
+          const out = reply().text(value)
+          if (opts?.usage) out.usage(opts.usage)
+          queueMatch(match, out.stop().item())
+        }),
+        toolMatch: Effect.fn("TestLLMServer.toolMatch")(function* (match: Match, name: string, input: unknown) {
+          queueMatch(match, reply().tool(name, input).item())
+        }),
         text: Effect.fn("TestLLMServer.text")(function* (value: string, opts?: { usage?: Usage }) {
           const out = reply().text(value)
           if (opts?.usage) out.usage(opts.usage)

packages/opencode/test/session/prompt-effect.test.ts

@@ -1,6 +1,7 @@
 import { NodeFileSystem } from "@effect/platform-node"
 import { expect, spyOn } from "bun:test"
 import { Cause, Effect, Exit, Fiber, Layer } from "effect"
+import path from "path"
 import z from "zod"
 import type { Agent } from "../../src/agent/agent"
 import { Agent as AgentSvc } from "../../src/agent/agent"
@@ -887,6 +888,79 @@ unix("shell captures stdout and stderr in completed tool output", () =>
   ),
 )
 
+unix("shell completes a fast command on the preferred shell", () =>
+  provideTmpdirInstance(
+    (dir) =>
+      Effect.gen(function* () {
+        const { prompt, chat } = yield* boot()
+        const result = yield* prompt.shell({
+          sessionID: chat.id,
+          agent: "build",
+          command: "pwd",
+        })
+
+        expect(result.info.role).toBe("assistant")
+        const tool = completedTool(result.parts)
+        if (!tool) return
+
+        expect(tool.state.input.command).toBe("pwd")
+        expect(tool.state.output).toContain(dir)
+        expect(tool.state.metadata.output).toContain(dir)
+        yield* prompt.assertNotBusy(chat.id)
+      }),
+    { git: true, config: cfg },
+  ),
+)
+
+unix("shell lists files from the project directory", () =>
+  provideTmpdirInstance(
+    (dir) =>
+      Effect.gen(function* () {
+        const { prompt, chat } = yield* boot()
+        yield* Effect.promise(() => Bun.write(path.join(dir, "README.md"), "# e2e\n"))
+
+        const result = yield* prompt.shell({
+          sessionID: chat.id,
+          agent: "build",
+          command: "command ls",
+        })
+
+        expect(result.info.role).toBe("assistant")
+        const tool = completedTool(result.parts)
+        if (!tool) return
+
+        expect(tool.state.input.command).toBe("command ls")
+        expect(tool.state.output).toContain("README.md")
+        expect(tool.state.metadata.output).toContain("README.md")
+        yield* prompt.assertNotBusy(chat.id)
+      }),
+    { git: true, config: cfg },
+  ),
+)
+
+unix("shell captures stderr from a failing command", () =>
+  provideTmpdirInstance(
+    (dir) =>
+      Effect.gen(function* () {
+        const { prompt, chat } = yield* boot()
+        const result = yield* prompt.shell({
+          sessionID: chat.id,
+          agent: "build",
+          command: "command -v __nonexistent_cmd_e2e__ || echo 'not found' >&2; exit 1",
+        })
+
+        expect(result.info.role).toBe("assistant")
+        const tool = completedTool(result.parts)
+        if (!tool) return
+
+        expect(tool.state.output).toContain("not found")
+        expect(tool.state.metadata.output).toContain("not found")
+        yield* prompt.assertNotBusy(chat.id)
+      }),
+    { git: true, config: cfg },
+  ),
+)
+
 unix(
   "shell updates running metadata before process exit",
   () =>

packages/opencode/test/tool/bash.test.ts

@@ -896,6 +896,121 @@ describe("tool.bash permissions", () => {
   })
 })
 
+describe("tool.bash abort", () => {
+  test("preserves output when aborted", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        const controller = new AbortController()
+        const collected: string[] = []
+        const result = bash.execute(
+          {
+            command: `echo before && sleep 30`,
+            description: "Long running command",
+          },
+          {
+            ...ctx,
+            abort: controller.signal,
+            metadata: (input) => {
+              const output = (input.metadata as { output?: string })?.output
+              if (output && output.includes("before") && !controller.signal.aborted) {
+                collected.push(output)
+                controller.abort()
+              }
+            },
+          },
+        )
+        const res = await result
+        expect(res.output).toContain("before")
+        expect(res.output).toContain("User aborted the command")
+        expect(collected.length).toBeGreaterThan(0)
+      },
+    })
+  }, 15_000)
+
+  test("terminates command on timeout", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        const result = await bash.execute(
+          {
+            command: `echo started && sleep 60`,
+            description: "Timeout test",
+            timeout: 500,
+          },
+          ctx,
+        )
+        expect(result.output).toContain("started")
+        expect(result.output).toContain("bash tool terminated command after exceeding timeout")
+      },
+    })
+  }, 15_000)
+
+  test.skipIf(process.platform === "win32")("captures stderr in output", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        const result = await bash.execute(
+          {
+            command: `echo stdout_msg && echo stderr_msg >&2`,
+            description: "Stderr test",
+          },
+          ctx,
+        )
+        expect(result.output).toContain("stdout_msg")
+        expect(result.output).toContain("stderr_msg")
+        expect(result.metadata.exit).toBe(0)
+      },
+    })
+  })
+
+  test("returns non-zero exit code", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        const result = await bash.execute(
+          {
+            command: `exit 42`,
+            description: "Non-zero exit",
+          },
+          ctx,
+        )
+        expect(result.metadata.exit).toBe(42)
+      },
+    })
+  })
+
+  test("streams metadata updates progressively", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        const updates: string[] = []
+        const result = await bash.execute(
+          {
+            command: `echo first && sleep 0.1 && echo second`,
+            description: "Streaming test",
+          },
+          {
+            ...ctx,
+            metadata: (input) => {
+              const output = (input.metadata as { output?: string })?.output
+              if (output) updates.push(output)
+            },
+          },
+        )
+        expect(result.output).toContain("first")
+        expect(result.output).toContain("second")
+        expect(updates.length).toBeGreaterThan(1)
+      },
+    })
+  })
+})
+
 describe("tool.bash truncation", () => {
   test("truncates output exceeding line limit", async () => {
     await Instance.provide({

packages/web/src/content/docs/rules.mdx

@@ -15,9 +15,17 @@ To create a new `AGENTS.md` file, you can run the `/init` command in opencode.
 You should commit your project's `AGENTS.md` file to Git.
 :::
 
-This will scan your project and all its contents to understand what the project is about and generate an `AGENTS.md` file with it. This helps opencode to navigate the project better.
+`/init` scans the important files in your repo, may ask a couple of targeted questions when the codebase cannot answer them, and then creates or updates `AGENTS.md` with concise project-specific guidance.
 
-If you have an existing `AGENTS.md` file, this will try to add to it.
+It focuses on the things future agent sessions are most likely to need:
+
+- build, lint, and test commands
+- command order and focused verification steps when they matter
+- architecture and repo structure that are not obvious from filenames alone
+- project-specific conventions, setup quirks, and operational gotchas
+- references to existing instruction sources like Cursor or Copilot rules
+
+If you already have an `AGENTS.md`, `/init` will improve it in place instead of blindly replacing it.
 
 ---
 

packages/web/src/content/docs/tui.mdx

@@ -153,7 +153,7 @@ Show the help dialog.
 
 ### init
 
-Create or update `AGENTS.md` file. [Learn more](/docs/rules).
+Guided setup for creating or updating `AGENTS.md`. [Learn more](/docs/rules).
 
 ```bash frame="none"
 /init