Convert question lifecycle tests to Effect

packages/opencode/script/httpapi-exercise.ts

@@ -0,0 +1,1632 @@
+/**
+ * End-to-end exerciser for the legacy Hono instance routes and the Effect HttpApi routes.
+ *
+ * The goal is not to be a normal unit test file. This is a route-coverage and parity
+ * harness we can run while deleting Hono: every public route should eventually have a
+ * small scenario that proves the Effect route decodes requests, uses the right instance
+ * context, mutates storage when expected, and returns a compatible response shape.
+ *
+ * The script intentionally isolates `OPENCODE_DB` before importing modules that touch
+ * storage. Scenarios may create/delete sessions and reset the database after each run,
+ * so this must never point at a developer's real session database.
+ *
+ * DSL shape:
+ * - `http.get/post/...` starts a scenario for one OpenAPI route key.
+ * - `.seeded(...)` creates typed per-scenario state using Effect helpers on `ctx`.
+ * - `.at(...)` builds the request from that typed state.
+ * - `.json(...)` / `.jsonEffect(...)` assert response shape and optional side effects.
+ * - `.mutating()` tells parity mode to run Effect and Hono in separate isolated contexts
+ *   so destructive routes compare equivalent fresh setups instead of sharing one DB.
+ */
+import { Cause, ConfigProvider, Effect, Layer } from "effect"
+import { HttpRouter } from "effect/unstable/http"
+import { OpenApi } from "effect/unstable/httpapi"
+import { Flag } from "@opencode-ai/core/flag/flag"
+import { TestLLMServer } from "../test/lib/llm-server"
+import type { Config } from "../src/config/config"
+import { MessageID, PartID, type SessionID } from "../src/session/schema"
+import { ModelID, ProviderID } from "../src/provider/schema"
+import type { MessageV2 } from "../src/session/message-v2"
+import type { Worktree } from "../src/worktree"
+import type { Project } from "../src/project/project"
+import path from "path"
+
+const exerciseGlobalRoot = process.env.OPENCODE_HTTPAPI_EXERCISE_GLOBAL ?? path.join(process.env.TMPDIR ?? "/tmp", `opencode-httpapi-global-${process.pid}`)
+process.env.XDG_DATA_HOME = path.join(exerciseGlobalRoot, "data")
+process.env.XDG_CONFIG_HOME = path.join(exerciseGlobalRoot, "config")
+process.env.XDG_STATE_HOME = path.join(exerciseGlobalRoot, "state")
+process.env.XDG_CACHE_HOME = path.join(exerciseGlobalRoot, "cache")
+process.env.OPENCODE_DISABLE_SHARE = "true"
+const exerciseConfigDirectory = path.join(exerciseGlobalRoot, "config", "opencode")
+const exerciseDataDirectory = path.join(exerciseGlobalRoot, "data", "opencode")
+
+const exerciseDatabasePath = process.env.OPENCODE_HTTPAPI_EXERCISE_DB ?? path.join(process.env.TMPDIR ?? "/tmp", `opencode-httpapi-exercise-${process.pid}.db`)
+process.env.OPENCODE_DB = exerciseDatabasePath
+Flag.OPENCODE_DB = exerciseDatabasePath
+
+void (await import("@opencode-ai/core/util/log")).init({ print: false })
+
+const OpenApiMethods = ["get", "post", "put", "delete", "patch"] as const
+const Methods = ["GET", "POST", "PUT", "DELETE", "PATCH"] as const
+const color = {
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  reset: "\x1b[0m",
+}
+
+type Method = (typeof Methods)[number]
+type OpenApiMethod = (typeof OpenApiMethods)[number]
+type Mode = "effect" | "parity" | "coverage"
+type Comparison = "none" | "status" | "json"
+type CaptureMode = "full" | "stream"
+type ProjectOptions = { git?: boolean; config?: Partial<Config.Info>; llm?: boolean }
+type OpenApiSpec = { paths?: Record<string, Partial<Record<OpenApiMethod, unknown>>> }
+type JsonObject = Record<string, unknown>
+
+type Options = {
+  mode: Mode
+  include: string | undefined
+  failOnMissing: boolean
+  failOnSkip: boolean
+}
+
+type RequestSpec = {
+  path: string
+  headers?: Record<string, string>
+  body?: unknown
+}
+
+type CallResult = {
+  status: number
+  contentType: string
+  body: unknown
+  text: string
+}
+
+/** Effect-native helpers available while setting up and asserting a scenario. */
+type ScenarioContext = {
+  directory: string | undefined
+  headers: (extra?: Record<string, string>) => Record<string, string>
+  file: (name: string, content: string) => Effect.Effect<void>
+  session: (input?: { title?: string; parentID?: SessionID }) => Effect.Effect<SessionInfo>
+  sessionGet: (sessionID: SessionID) => Effect.Effect<SessionInfo | undefined>
+  project: () => Effect.Effect<Project.Info>
+  message: (sessionID: SessionID, input?: { text?: string }) => Effect.Effect<MessageSeed>
+  messages: (sessionID: SessionID) => Effect.Effect<MessageV2.WithParts[]>
+  todos: (sessionID: SessionID, todos: TodoInfo[]) => Effect.Effect<void>
+  worktree: (input?: { name?: string }) => Effect.Effect<Worktree.Info>
+  worktreeRemove: (directory: string) => Effect.Effect<void>
+  llmText: (value: string) => Effect.Effect<void>
+  llmWait: (count: number) => Effect.Effect<void>
+  tuiRequest: (request: { path: string; body: unknown }) => Effect.Effect<void>
+}
+
+/** Scenario context after `.seeded(...)`; `state` preserves the seed return type in the DSL. */
+type SeededContext<S> = ScenarioContext & {
+  state: S
+}
+
+type Scenario = ActiveScenario | TodoScenario
+type ActiveScenario = {
+  kind: "active"
+  method: Method
+  path: string
+  name: string
+  project: ProjectOptions | undefined
+  seed: (ctx: ScenarioContext) => Effect.Effect<unknown>
+  request: (ctx: ScenarioContext, state: unknown) => RequestSpec
+  expect: (ctx: ScenarioContext, state: unknown, result: CallResult) => Effect.Effect<void>
+  compare: Comparison
+  capture: CaptureMode
+  mutates: boolean
+  reset: boolean
+}
+
+/** Internal builder state stays generic until `.json(...)` erases it into `ActiveScenario`. */
+type BuilderState<S> = {
+  method: Method
+  path: string
+  name: string
+  project: ProjectOptions | undefined
+  seed: (ctx: ScenarioContext) => Effect.Effect<S>
+  request: (ctx: SeededContext<S>) => RequestSpec
+  capture: CaptureMode
+  mutates: boolean
+  reset: boolean
+}
+type TodoScenario = {
+  kind: "todo"
+  method: Method
+  path: string
+  name: string
+  reason: string
+}
+type Result =
+  | { status: "pass"; scenario: ActiveScenario }
+  | { status: "fail"; scenario: ActiveScenario; message: string }
+  | { status: "skip"; scenario: TodoScenario }
+
+type SessionInfo = { id: SessionID; title: string; parentID?: SessionID }
+type TodoInfo = { content: string; status: string; priority: string }
+type MessageSeed = { info: MessageV2.User; part: MessageV2.TextPart }
+
+const original = {
+  OPENCODE_EXPERIMENTAL_HTTPAPI: Flag.OPENCODE_EXPERIMENTAL_HTTPAPI,
+  OPENCODE_SERVER_PASSWORD: Flag.OPENCODE_SERVER_PASSWORD,
+  OPENCODE_SERVER_USERNAME: Flag.OPENCODE_SERVER_USERNAME,
+}
+
+type Runtime = {
+  PublicApi: typeof import("../src/server/routes/instance/httpapi/public")["PublicApi"]
+  ExperimentalHttpApiServer: typeof import("../src/server/routes/instance/httpapi/server")["ExperimentalHttpApiServer"]
+  Server: typeof import("../src/server/server")["Server"]
+  AppLayer: typeof import("../src/effect/app-runtime")["AppLayer"]
+  InstanceRef: typeof import("../src/effect/instance-ref")["InstanceRef"]
+  Instance: typeof import("../src/project/instance")["Instance"]
+  InstanceStore: typeof import("../src/project/instance-store")["InstanceStore"]
+  Session: typeof import("../src/session/session")["Session"]
+  Todo: typeof import("../src/session/todo")["Todo"]
+  Worktree: typeof import("../src/worktree")["Worktree"]
+  Project: typeof import("../src/project/project")["Project"]
+  Tui: typeof import("../src/server/routes/instance/tui")
+  disposeAllInstances: typeof import("../test/fixture/fixture")["disposeAllInstances"]
+  tmpdir: typeof import("../test/fixture/fixture")["tmpdir"]
+  resetDatabase: typeof import("../test/fixture/db")["resetDatabase"]
+}
+
+let runtimePromise: Promise<Runtime> | undefined
+
+function runtime() {
+  return (runtimePromise ??= (async () => {
+    const publicApi = await import("../src/server/routes/instance/httpapi/public")
+    const httpApiServer = await import("../src/server/routes/instance/httpapi/server")
+    const server = await import("../src/server/server")
+    const appRuntime = await import("../src/effect/app-runtime")
+    const instanceRef = await import("../src/effect/instance-ref")
+    const instance = await import("../src/project/instance")
+    const instanceStore = await import("../src/project/instance-store")
+    const session = await import("../src/session/session")
+    const todo = await import("../src/session/todo")
+    const worktree = await import("../src/worktree")
+    const project = await import("../src/project/project")
+    const tui = await import("../src/server/routes/instance/tui")
+    const fixture = await import("../test/fixture/fixture")
+    const db = await import("../test/fixture/db")
+    return {
+      PublicApi: publicApi.PublicApi,
+      ExperimentalHttpApiServer: httpApiServer.ExperimentalHttpApiServer,
+      Server: server.Server,
+      AppLayer: appRuntime.AppLayer,
+      InstanceRef: instanceRef.InstanceRef,
+      Instance: instance.Instance,
+      InstanceStore: instanceStore.InstanceStore,
+      Session: session.Session,
+      Todo: todo.Todo,
+      Worktree: worktree.Worktree,
+      Project: project.Project,
+      Tui: tui,
+      disposeAllInstances: fixture.disposeAllInstances,
+      tmpdir: fixture.tmpdir,
+      resetDatabase: db.resetDatabase,
+    }
+  })())
+}
+
+class ScenarioBuilder<S = undefined> {
+  private readonly state: BuilderState<S>
+
+  constructor(method: Method, path: string, name: string) {
+    this.state = {
+      method,
+      path,
+      name,
+      project: { git: true },
+      seed: () => Effect.succeed(undefined as S),
+      request: (ctx) => ({ path, headers: ctx.headers() }),
+      capture: "full",
+      mutates: false,
+      reset: true,
+    }
+  }
+
+  global() {
+    return this.clone({ project: undefined, request: () => ({ path: this.state.path }) })
+  }
+
+  inProject(project: ProjectOptions = { git: true }) {
+    return this.clone({ project })
+  }
+
+  withLlm() {
+    return this.clone({ project: { ...(this.state.project ?? { git: true }), llm: true } })
+  }
+
+  at(request: BuilderState<S>["request"]) {
+    return this.clone({ request })
+  }
+
+  mutating() {
+    return this.clone({ mutates: true })
+  }
+
+  preserveDatabase() {
+    return this.clone({ reset: false })
+  }
+
+  stream() {
+    return this.clone({ capture: "stream" })
+  }
+
+  /** Assert a non-JSON or shape-only response. */
+  ok(status = 200, compare: Comparison = "status") {
+    return this.done(compare, (_ctx, result) =>
+      Effect.sync(() => {
+        if (result.status !== status) throw new Error(`expected ${status}, got ${result.status}: ${result.text}`)
+      }),
+    )
+  }
+
+  status(status = 200, inspect?: (ctx: SeededContext<S>, result: CallResult) => Effect.Effect<void>, compare: Comparison = "status") {
+    return this.done(compare, (ctx, result) =>
+      Effect.gen(function* () {
+        if (result.status !== status) throw new Error(`expected ${status}, got ${result.status}: ${result.text}`)
+        if (inspect) yield* inspect(ctx, result)
+      }),
+    )
+  }
+
+  /** Assert JSON status/content-type plus an optional synchronous body check. */
+  json(status = 200, inspect?: (body: unknown, ctx: SeededContext<S>) => void, compare: Comparison = "json") {
+    return this.jsonEffect(
+      status,
+      inspect ? (body, ctx) => Effect.sync(() => inspect(body, ctx)) : undefined,
+      compare,
+    )
+  }
+
+  /** Assert JSON status/content-type plus optional Effect assertions, e.g. DB side effects. */
+  jsonEffect(status = 200, inspect?: (body: unknown, ctx: SeededContext<S>) => Effect.Effect<void>, compare: Comparison = "json") {
+    return this.done(compare, (ctx, result) =>
+      Effect.gen(function* () {
+        if (result.status !== status) throw new Error(`expected ${status}, got ${result.status}: ${result.text}`)
+        if (!looksJson(result)) throw new Error(`expected JSON response, got ${result.contentType || "no content-type"}`)
+        if (inspect) yield* inspect(result.body, ctx)
+      }),
+    )
+  }
+
+  private clone(next: Partial<BuilderState<S>>) {
+    const builder = new ScenarioBuilder<S>(this.state.method, this.state.path, this.state.name)
+    Object.assign(builder.state, this.state, next)
+    return builder
+  }
+
+  /**
+   * Seed typed state before the HTTP request. The returned value becomes `ctx.state`
+   * for `.at(...)` and assertions, giving stateful route tests type-safe setup.
+   */
+  seeded<Next>(seed: (ctx: ScenarioContext) => Effect.Effect<Next>) {
+    const builder = new ScenarioBuilder<Next>(this.state.method, this.state.path, this.state.name)
+    Object.assign(builder.state, this.state, { seed })
+    return builder
+  }
+
+  private done(compare: Comparison, expect: (ctx: SeededContext<S>, result: CallResult) => Effect.Effect<void>): ActiveScenario {
+    const state = this.state
+    return {
+      kind: "active",
+      method: state.method,
+      path: state.path,
+      name: state.name,
+      project: state.project,
+      seed: state.seed,
+      request: (ctx, seeded) => state.request({ ...ctx, state: seeded as S }),
+      expect: (ctx, seeded, result) => expect({ ...ctx, state: seeded as S }, result),
+      compare,
+      capture: state.capture,
+      mutates: state.mutates,
+      reset: state.reset,
+    }
+  }
+}
+
+const http = {
+  get: (path: string, name: string) => new ScenarioBuilder("GET", path, name),
+  post: (path: string, name: string) => new ScenarioBuilder("POST", path, name),
+  put: (path: string, name: string) => new ScenarioBuilder("PUT", path, name),
+  patch: (path: string, name: string) => new ScenarioBuilder("PATCH", path, name),
+  delete: (path: string, name: string) => new ScenarioBuilder("DELETE", path, name),
+}
+
+const pending = (method: Method, path: string, name: string, reason: string): TodoScenario => ({
+  kind: "todo",
+  method,
+  path,
+  name,
+  reason,
+})
+
+function route(template: string, params: Record<string, string>) {
+  return Object.entries(params).reduce((next, [key, value]) => next.replaceAll(`{${key}}`, value).replaceAll(`:${key}`, value), template)
+}
+
+const scenarios: Scenario[] = [
+  http.get("/global/health", "global.health").global().json(200, (body) => {
+    object(body)
+    check(body.healthy === true, "server should report healthy")
+  }),
+  http
+    .get("/global/event", "global.event")
+    .global()
+    .stream()
+    .status(200, (_ctx, result) =>
+      Effect.sync(() => {
+        check(result.contentType.includes("text/event-stream"), "global event should be an SSE stream")
+        check(result.text.includes("server.connected"), "global event should emit initial connection event")
+      }),
+    "status"),
+  http.get("/global/config", "global.config.get").global().json(),
+  http
+    .patch("/global/config", "global.config.update")
+    .global()
+    .seeded(() =>
+      Effect.promise(() =>
+        Bun.write(path.join(exerciseConfigDirectory, "opencode.jsonc"), JSON.stringify({ username: "httpapi-global" }, null, 2)),
+      ),
+    )
+    .at(() => ({ path: "/global/config", body: { username: "httpapi-global" } }))
+    .jsonEffect(200, (body) =>
+      Effect.gen(function* () {
+        object(body)
+        check(body.username === "httpapi-global", "global config update should return patched config")
+        const text = yield* Effect.promise(() => Bun.file(path.join(exerciseConfigDirectory, "opencode.jsonc")).text())
+        check(text.includes('"username": "httpapi-global"'), "global config update should write isolated config file")
+      }),
+    "status"),
+  http.post("/global/dispose", "global.dispose").global().mutating().json(200, (body) => {
+    check(body === true, "global dispose should return true")
+  }, "status"),
+  http.get("/path", "path.get").json(200, (body, ctx) => {
+    object(body)
+    check(body.directory === ctx.directory, "directory should resolve from x-opencode-directory")
+    check(body.worktree === ctx.directory, "worktree should resolve from x-opencode-directory")
+  }),
+  http.get("/vcs", "vcs.get").json(),
+  http.get("/vcs/diff", "vcs.diff").at((ctx) => ({ path: "/vcs/diff?mode=git", headers: ctx.headers() })).json(200, array),
+  http.get("/command", "command.list").json(200, array, "status"),
+  http.get("/agent", "app.agents").json(200, array, "status"),
+  http.get("/skill", "app.skills").json(200, array, "status"),
+  http.get("/lsp", "lsp.status").json(200, array),
+  http.get("/formatter", "formatter.status").json(200, array),
+  http.get("/config", "config.get").json(200, undefined, "status"),
+  http
+    .patch("/config", "config.update")
+    .mutating()
+    .at((ctx) => ({ path: "/config", headers: ctx.headers(), body: { username: "httpapi-local" } }))
+    .json(200, (body) => {
+      object(body)
+      check(body.username === "httpapi-local", "local config update should return patched config")
+    }, "status"),
+  http.get("/config/providers", "config.providers").json(),
+  http.get("/project", "project.list").json(200, array, "status"),
+  http.get("/project/current", "project.current").json(200, (body, ctx) => {
+    object(body)
+    check(body.worktree === ctx.directory, "current project should resolve from scenario directory")
+  }, "status"),
+  http
+    .patch("/project/{projectID}", "project.update")
+    .mutating()
+    .seeded((ctx) => ctx.project())
+    .at((ctx) => ({
+      path: route("/project/{projectID}", { projectID: ctx.state.id }),
+      headers: ctx.headers(),
+      body: { name: "HTTP API Project", commands: { start: "bun --version" } },
+    }))
+    .json(200, (body) => {
+      object(body)
+      check(body.name === "HTTP API Project", "project update should return patched name")
+      check(isRecord(body.commands) && body.commands.start === "bun --version", "project update should return patched command")
+    }, "status"),
+  http
+    .post("/project/git/init", "project.initGit")
+    .mutating()
+    .inProject({ git: false })
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.worktree === ctx.directory, "git init should return current project")
+      check(body.vcs === "git", "git init should mark the project as git-backed")
+    }, "status"),
+  http.get("/provider", "provider.list").json(),
+  http.get("/provider/auth", "provider.auth").json(),
+  http
+    .post("/provider/{providerID}/oauth/authorize", "provider.oauth.authorize")
+    .at((ctx) => ({ path: route("/provider/{providerID}/oauth/authorize", { providerID: "httpapi" }), headers: ctx.headers(), body: { method: "bad" } }))
+    .status(400),
+  http
+    .post("/provider/{providerID}/oauth/callback", "provider.oauth.callback")
+    .at((ctx) => ({ path: route("/provider/{providerID}/oauth/callback", { providerID: "httpapi" }), headers: ctx.headers(), body: { method: "bad" } }))
+    .status(400),
+  http.get("/permission", "permission.list").json(200, array),
+  http
+    .post("/permission/{requestID}/reply", "permission.reply")
+    .at((ctx) => ({ path: route("/permission/{requestID}/reply", { requestID: "per_httpapi" }), headers: ctx.headers(), body: { reply: "once" } }))
+    .json(200, (body) => {
+      check(body === true, "permission reply should return true even when request is no longer pending")
+    }, "status"),
+  http.get("/question", "question.list").json(200, array),
+  http
+    .post("/question/{requestID}/reply", "question.reply")
+    .at((ctx) => ({ path: route("/question/{requestID}/reply", { requestID: "que_httpapi_reply" }), headers: ctx.headers(), body: { answers: [["Yes"]] } }))
+    .json(200, (body) => {
+      check(body === true, "question reply should return true even when request is no longer pending")
+    }, "status"),
+  http
+    .post("/question/{requestID}/reject", "question.reject")
+    .at((ctx) => ({ path: route("/question/{requestID}/reject", { requestID: "que_httpapi_reject" }), headers: ctx.headers() }))
+    .json(200, (body) => {
+      check(body === true, "question reject should return true even when request is no longer pending")
+    }, "status"),
+  http
+    .get("/file", "file.list")
+    .seeded((ctx) => ctx.file("hello.txt", "hello\n"))
+    .at((ctx) => ({ path: `/file?${new URLSearchParams({ path: "." })}`, headers: ctx.headers() }))
+    .json(200, array),
+  http
+    .get("/file/content", "file.read")
+    .seeded((ctx) => ctx.file("hello.txt", "hello\n"))
+    .at((ctx) => ({ path: `/file/content?${new URLSearchParams({ path: "hello.txt" })}`, headers: ctx.headers() }))
+    .json(200, (body) => {
+      object(body)
+      check(body.content === "hello", `content should match seeded file: ${JSON.stringify(body)}`)
+    }),
+  http.get("/file/status", "file.status").json(200, array),
+  http
+    .get("/find", "find.text")
+    .seeded((ctx) => ctx.file("hello.txt", "hello\n"))
+    .at((ctx) => ({ path: `/find?${new URLSearchParams({ pattern: "hello" })}`, headers: ctx.headers() }))
+    .json(200, array),
+  http
+    .get("/find/file", "find.files")
+    .seeded((ctx) => ctx.file("hello.txt", "hello\n"))
+    .at((ctx) => ({ path: `/find/file?${new URLSearchParams({ query: "hello", dirs: "false" })}`, headers: ctx.headers() }))
+    .json(200, array),
+  http
+    .get("/find/symbol", "find.symbols")
+    .seeded((ctx) => ctx.file("hello.ts", "export const hello = 1\n"))
+    .at((ctx) => ({ path: `/find/symbol?${new URLSearchParams({ query: "hello" })}`, headers: ctx.headers() }))
+    .json(200, array),
+  http
+    .get("/event", "event.stream")
+    .stream()
+    .status(200, (_ctx, result) =>
+      Effect.sync(() => {
+        check(result.contentType.includes("text/event-stream"), "event should be an SSE stream")
+        check(result.text.includes("server.connected"), "event should emit initial connection event")
+      }),
+    "status"),
+  http.get("/mcp", "mcp.status").json(),
+  http
+    .post("/mcp", "mcp.add")
+    .mutating()
+    .at((ctx) => ({
+      path: "/mcp",
+      headers: ctx.headers(),
+      body: { name: "httpapi-disabled", config: { type: "local", command: ["bun", "--version"], enabled: false } },
+    }))
+    .json(200, (body) => {
+      object(body)
+      object(body["httpapi-disabled"])
+      check(body["httpapi-disabled"].status === "disabled", "disabled MCP server should be added without spawning")
+    }, "status"),
+  http
+    .post("/mcp/{name}/auth", "mcp.auth.start")
+    .at((ctx) => ({ path: route("/mcp/{name}/auth", { name: "httpapi-missing" }), headers: ctx.headers() }))
+    .json(400, (body) => {
+      object(body)
+      check(typeof body.error === "string", "unsupported MCP OAuth response should include error")
+    }, "status"),
+  http
+    .delete("/mcp/{name}/auth", "mcp.auth.remove")
+    .mutating()
+    .at((ctx) => ({ path: route("/mcp/{name}/auth", { name: "httpapi-missing" }), headers: ctx.headers() }))
+    .json(200, (body) => {
+      object(body)
+      check(body.success === true, "MCP auth removal should return success")
+    }, "status"),
+  http
+    .post("/mcp/{name}/auth/authenticate", "mcp.auth.authenticate")
+    .at((ctx) => ({ path: route("/mcp/{name}/auth/authenticate", { name: "httpapi-missing" }), headers: ctx.headers() }))
+    .json(400, (body) => {
+      object(body)
+      check(typeof body.error === "string", "unsupported MCP OAuth authenticate response should include error")
+    }, "status"),
+  http
+    .post("/mcp/{name}/auth/callback", "mcp.auth.callback")
+    .at((ctx) => ({ path: route("/mcp/{name}/auth/callback", { name: "httpapi-missing" }), headers: ctx.headers(), body: { code: 1 } }))
+    .status(400),
+  http
+    .post("/mcp/{name}/connect", "mcp.connect")
+    .mutating()
+    .at((ctx) => ({ path: route("/mcp/{name}/connect", { name: "httpapi-missing" }), headers: ctx.headers() }))
+    .json(200, (body) => {
+      check(body === true, "missing MCP connect should remain a no-op success")
+    }, "status"),
+  http
+    .post("/mcp/{name}/disconnect", "mcp.disconnect")
+    .mutating()
+    .at((ctx) => ({ path: route("/mcp/{name}/disconnect", { name: "httpapi-missing" }), headers: ctx.headers() }))
+    .json(200, (body) => {
+      check(body === true, "missing MCP disconnect should remain a no-op success")
+    }, "status"),
+  http.get("/pty/shells", "pty.shells").json(200, array),
+  http.get("/pty", "pty.list").json(200, array),
+  http
+    .post("/pty", "pty.create")
+    .mutating()
+    .at((ctx) => ({ path: "/pty", headers: ctx.headers(), body: controlledPtyInput("HTTP API PTY") }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.title === "HTTP API PTY", "PTY create should return requested title")
+      check(body.command === "/bin/sh", "PTY create should use controlled shell command")
+      check(body.cwd === ctx.directory, "PTY create should default cwd to scenario directory")
+    }, "status"),
+  http
+    .get("/pty/{ptyID}", "pty.get")
+    .at((ctx) => ({ path: route("/pty/{ptyID}", { ptyID: "pty_httpapi_missing" }), headers: ctx.headers() }))
+    .status(404),
+  http
+    .put("/pty/{ptyID}", "pty.update")
+    .mutating()
+    .at((ctx) => ({
+      path: route("/pty/{ptyID}", { ptyID: "pty_httpapi_missing" }),
+      headers: ctx.headers(),
+      body: { size: { rows: 0, cols: 0 } },
+    }))
+    .status(400),
+  http
+    .delete("/pty/{ptyID}", "pty.remove")
+    .mutating()
+    .at((ctx) => ({ path: route("/pty/{ptyID}", { ptyID: "pty_httpapi_missing" }), headers: ctx.headers() }))
+    .json(200, (body) => {
+      check(body === true, "PTY remove should return true")
+    }, "status"),
+  http
+    .get("/pty/{ptyID}/connect", "pty.connect")
+    .at((ctx) => ({ path: route("/pty/{ptyID}/connect", { ptyID: "invalid" }), headers: ctx.headers() }))
+    .status(404, undefined, "none"),
+  http.get("/experimental/console", "experimental.console.get").json(),
+  http.get("/experimental/console/orgs", "experimental.console.listOrgs").json(),
+  http
+    .post("/experimental/console/switch", "experimental.console.switchOrg")
+    .at((ctx) => ({ path: "/experimental/console/switch", headers: ctx.headers(), body: { accountID: 1, orgID: 1 } }))
+    .status(400),
+  http.get("/experimental/workspace/adapter", "experimental.workspace.adapter.list").json(200, array),
+  http.get("/experimental/workspace", "experimental.workspace.list").json(200, array),
+  http.get("/experimental/workspace/status", "experimental.workspace.status").json(200, array),
+  http
+    .post("/experimental/workspace", "experimental.workspace.create")
+    .at((ctx) => ({ path: "/experimental/workspace", headers: ctx.headers(), body: {} }))
+    .status(400),
+  http
+    .delete("/experimental/workspace/{id}", "experimental.workspace.remove")
+    .mutating()
+    .at((ctx) => ({ path: route("/experimental/workspace/{id}", { id: "wrk_httpapi_missing" }), headers: ctx.headers() }))
+    .status(200),
+  http
+    .post("/experimental/workspace/{id}/session-restore", "experimental.workspace.sessionRestore")
+    .at((ctx) => ({ path: route("/experimental/workspace/{id}/session-restore", { id: "wrk_httpapi_missing" }), headers: ctx.headers(), body: {} }))
+    .status(400),
+  http
+    .get("/experimental/tool", "tool.list")
+    .at((ctx) => ({ path: `/experimental/tool?${new URLSearchParams({ provider: "opencode", model: "test" })}`, headers: ctx.headers() }))
+    .json(200, array, "status"),
+  http.get("/experimental/tool/ids", "tool.ids").json(200, array),
+  http.get("/experimental/worktree", "worktree.list").json(200, array),
+  http
+    .post("/experimental/worktree", "worktree.create")
+    .mutating()
+    .at((ctx) => ({ path: "/experimental/worktree", headers: ctx.headers(), body: { name: "api-dsl" } }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        object(body)
+        check(typeof body.directory === "string", "created worktree should include directory")
+        yield* ctx.worktreeRemove(body.directory)
+      }),
+    "status"),
+  http
+    .delete("/experimental/worktree", "worktree.remove")
+    .mutating()
+    .seeded((ctx) => ctx.worktree({ name: "api-remove" }))
+    .at((ctx) => ({ path: "/experimental/worktree", headers: ctx.headers(), body: { directory: ctx.state.directory } }))
+    .json(200, (body) => {
+      check(body === true, "worktree remove should return true")
+    }, "status"),
+  http
+    .post("/experimental/worktree/reset", "worktree.reset")
+    .mutating()
+    .seeded((ctx) => ctx.worktree({ name: "api-reset" }))
+    .at((ctx) => ({ path: "/experimental/worktree/reset", headers: ctx.headers(), body: { directory: ctx.state.directory } }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        check(body === true, "worktree reset should return true")
+        yield* ctx.worktreeRemove(ctx.state.directory)
+      }),
+    "status"),
+  http.get("/experimental/session", "experimental.session.list").json(200, array),
+  http.get("/experimental/resource", "experimental.resource.list").json(),
+  http.post("/sync/history", "sync.history.list").at((ctx) => ({ path: "/sync/history", headers: ctx.headers(), body: {} })).json(200, array),
+  http
+    .post("/sync/replay", "sync.replay")
+    .at((ctx) => ({ path: "/sync/replay", headers: ctx.headers(), body: { directory: ctx.directory, events: [] } }))
+    .status(400),
+  http.post("/sync/start", "sync.start").mutating().preserveDatabase().json(200, (body) => {
+    check(body === true, "sync start should return true when no workspace sessions exist")
+  }, "status"),
+  http.post("/instance/dispose", "instance.dispose").mutating().json(200, (body) => {
+    check(body === true, "instance dispose should return true")
+  }, "status"),
+  http
+    .post("/log", "app.log")
+    .global()
+    .at(() => ({ path: "/log", body: { service: "httpapi-exercise", level: "info", message: "route coverage" } }))
+    .json(200, (body) => {
+      check(body === true, "log route should return true")
+    }),
+  http
+    .put("/auth/{providerID}", "auth.set")
+    .global()
+    .at(() => ({ path: route("/auth/{providerID}", { providerID: "test" }), body: { type: "api", key: "test-key" } }))
+    .jsonEffect(200, (body) =>
+      Effect.gen(function* () {
+        check(body === true, "auth set should return true")
+        const auth = yield* Effect.promise(() => Bun.file(path.join(exerciseDataDirectory, "auth.json")).json())
+        object(auth)
+        check(isRecord(auth.test) && auth.test.key === "test-key", "auth set should write isolated auth file")
+      }),
+    "status"),
+  http
+    .delete("/auth/{providerID}", "auth.remove")
+    .global()
+    .seeded(() =>
+      Effect.promise(() =>
+        Bun.write(path.join(exerciseDataDirectory, "auth.json"), JSON.stringify({ test: { type: "api", key: "remove-me" } })),
+      ),
+    )
+    .at(() => ({ path: route("/auth/{providerID}", { providerID: "test" }) }))
+    .jsonEffect(200, (body) =>
+      Effect.gen(function* () {
+        check(body === true, "auth remove should return true")
+        const auth = yield* Effect.promise(() => Bun.file(path.join(exerciseDataDirectory, "auth.json")).json())
+        object(auth)
+        check(auth.test === undefined, "auth remove should delete provider from isolated auth file")
+      }),
+    "status"),
+  http
+    .get("/session", "session.list")
+    .seeded((ctx) => ctx.session({ title: "List me" }))
+    .at((ctx) => ({ path: "/session?roots=true", headers: ctx.headers() }))
+    .json(200, (body, ctx) => {
+      array(body)
+      check(body.some((item) => isRecord(item) && item.id === ctx.state.id && item.title === "List me"), "seeded session should be listed")
+    }),
+  http
+    .get("/session/status", "session.status")
+    .seeded((ctx) => ctx.session({ title: "Status session" }))
+    .json(200, object),
+  http
+    .post("/session", "session.create")
+    .mutating()
+    .at((ctx) => ({ path: "/session", headers: ctx.headers(), body: { title: "Created session" } }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.title === "Created session", "created session should use requested title")
+      check(body.directory === ctx.directory, "created session should use scenario directory")
+    }, "status"),
+  http
+    .get("/session/{sessionID}", "session.get")
+    .seeded((ctx) => ctx.session({ title: "Get me" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.id === ctx.state.id, "should return requested session")
+      check(body.title === "Get me", "should preserve seeded title")
+    }),
+  http
+    .patch("/session/{sessionID}", "session.update")
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Before rename" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}", { sessionID: ctx.state.id }), headers: ctx.headers(), body: { title: "After rename" } }))
+    .json(200, (body) => {
+      object(body)
+      check(body.title === "After rename", "updated session should use new title")
+    }, "status"),
+  http
+    .delete("/session/{sessionID}", "session.delete")
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Delete me" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        check(body === true, "delete should return true")
+        check((yield* ctx.sessionGet(ctx.state.id)) === undefined, "deleted session should not remain in storage")
+      }),
+    "status"),
+  http
+    .get("/session/{sessionID}/children", "session.children")
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const parent = yield* ctx.session({ title: "Parent" })
+        const child = yield* ctx.session({ title: "Child", parentID: parent.id })
+        return { parent, child }
+      }),
+    )
+    .at((ctx) => ({ path: route("/session/{sessionID}/children", { sessionID: ctx.state.parent.id }), headers: ctx.headers() }))
+    .json(200, (body, ctx) => {
+      array(body)
+      check(body.some((item) => isRecord(item) && item.id === ctx.state.child.id && item.parentID === ctx.state.parent.id), "children should include seeded child")
+    }),
+  http
+    .get("/session/{sessionID}/todo", "session.todo")
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Todo session" })
+        const todos = [{ content: "cover session todo", status: "pending", priority: "high" }]
+        yield* ctx.todos(session.id, todos)
+        return { session, todos }
+      }),
+    )
+    .at((ctx) => ({ path: route("/session/{sessionID}/todo", { sessionID: ctx.state.session.id }), headers: ctx.headers() }))
+    .json(200, (body, ctx) => {
+      check(stable(body) === stable(ctx.state.todos), "todos should match seeded state")
+    }),
+  http
+    .get("/session/{sessionID}/diff", "session.diff")
+    .seeded((ctx) => ctx.session({ title: "Diff session" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}/diff", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .json(200, array),
+  http
+    .get("/session/{sessionID}/message", "session.messages")
+    .seeded((ctx) => ctx.session({ title: "Messages session" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}/message", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .json(200, (body) => {
+      array(body)
+      check(body.length === 0, "new session should have no messages")
+    }),
+  http
+    .get("/session/{sessionID}/message/{messageID}", "session.message")
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Message get session" })
+        const message = yield* ctx.message(session.id, { text: "read me" })
+        return { session, message }
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/message/{messageID}", {
+        sessionID: ctx.state.session.id,
+        messageID: ctx.state.message.info.id,
+      }),
+      headers: ctx.headers(),
+    }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(isRecord(body.info) && body.info.id === ctx.state.message.info.id, "should return requested message")
+      check(Array.isArray(body.parts) && body.parts.some((part) => isRecord(part) && part.id === ctx.state.message.part.id), "message should include seeded part")
+    }),
+  http
+    .patch("/session/{sessionID}/message/{messageID}/part/{partID}", "part.update")
+    .mutating()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Part update session" })
+        const message = yield* ctx.message(session.id, { text: "before" })
+        return { session, message }
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/message/{messageID}/part/{partID}", {
+        sessionID: ctx.state.session.id,
+        messageID: ctx.state.message.info.id,
+        partID: ctx.state.message.part.id,
+      }),
+      headers: ctx.headers(),
+      body: { ...ctx.state.message.part, text: "after" },
+    }))
+    .json(200, (body) => {
+      object(body)
+      check(body.type === "text" && body.text === "after", "updated part should be returned")
+    }, "status"),
+  http
+    .delete("/session/{sessionID}/message/{messageID}/part/{partID}", "part.delete")
+    .mutating()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Part delete session" })
+        const message = yield* ctx.message(session.id, { text: "delete part" })
+        return { session, message }
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/message/{messageID}/part/{partID}", {
+        sessionID: ctx.state.session.id,
+        messageID: ctx.state.message.info.id,
+        partID: ctx.state.message.part.id,
+      }),
+      headers: ctx.headers(),
+    }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        check(body === true, "delete part should return true")
+        const messages = yield* ctx.messages(ctx.state.session.id)
+        check(messages[0]?.parts.length === 0, "deleted part should not remain on message")
+      }),
+    "status"),
+  http
+    .delete("/session/{sessionID}/message/{messageID}", "session.deleteMessage")
+    .mutating()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Message delete session" })
+        const message = yield* ctx.message(session.id, { text: "delete message" })
+        return { session, message }
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/message/{messageID}", {
+        sessionID: ctx.state.session.id,
+        messageID: ctx.state.message.info.id,
+      }),
+      headers: ctx.headers(),
+    }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        check(body === true, "delete message should return true")
+        check((yield* ctx.messages(ctx.state.session.id)).length === 0, "deleted message should not remain")
+      }),
+    "status"),
+  http
+    .post("/session/{sessionID}/fork", "session.fork")
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Fork source" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}/fork", { sessionID: ctx.state.id }), headers: ctx.headers(), body: {} }))
+    .json(200, (body) => {
+      object(body)
+      check(typeof body.id === "string", "fork should return a session")
+    }, "status"),
+  http
+    .post("/session/{sessionID}/abort", "session.abort")
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Abort session" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}/abort", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .json(200, (body) => {
+      check(body === true, "abort should return true")
+    }, "status"),
+  http
+    .post("/session/{sessionID}/init", "session.init")
+    .preserveDatabase()
+    .withLlm()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Init session" })
+        const message = yield* ctx.message(session.id, { text: "initialize" })
+        yield* ctx.llmText("initialized")
+        yield* ctx.llmText("initialized")
+        return { session, message }
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/init", { sessionID: ctx.state.session.id }),
+      headers: ctx.headers(),
+      body: { providerID: "test", modelID: "test-model", messageID: ctx.state.message.info.id },
+    }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        check(body === true, "init should return true")
+        yield* ctx.llmWait(1)
+      }),
+    "status"),
+  http
+    .post("/session/{sessionID}/message", "session.prompt")
+    .preserveDatabase()
+    .withLlm()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "LLM prompt session" })
+        yield* ctx.llmText("fake assistant")
+        yield* ctx.llmText("fake assistant")
+        return session
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/message", { sessionID: ctx.state.id }),
+      headers: ctx.headers(),
+      body: {
+        agent: "build",
+        model: { providerID: "test", modelID: "test-model" },
+        parts: [{ type: "text", text: "hello llm" }],
+      },
+    }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        object(body)
+        check(isRecord(body.info) && body.info.role === "assistant", "prompt should return assistant message")
+        check(Array.isArray(body.parts) && body.parts.some((part) => isRecord(part) && part.text === "fake assistant"), "assistant message should use fake LLM text")
+        yield* ctx.llmWait(1)
+      }),
+    "status"),
+  http
+    .post("/session/{sessionID}/prompt_async", "session.prompt_async")
+    .preserveDatabase()
+    .withLlm()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Async prompt session" })
+        yield* ctx.llmText("fake async assistant")
+        yield* ctx.llmText("fake async assistant")
+        return session
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/prompt_async", { sessionID: ctx.state.id }),
+      headers: ctx.headers(),
+      body: {
+        agent: "build",
+        model: { providerID: "test", modelID: "test-model" },
+        parts: [{ type: "text", text: "hello async" }],
+      },
+    }))
+    .status(204, (ctx) =>
+      Effect.gen(function* () {
+        yield* ctx.llmWait(1)
+      }),
+    ),
+  http
+    .post("/session/{sessionID}/command", "session.command")
+    .preserveDatabase()
+    .withLlm()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Command session" })
+        yield* ctx.llmText("command done")
+        yield* ctx.llmText("command done")
+        return session
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/command", { sessionID: ctx.state.id }),
+      headers: ctx.headers(),
+      body: { command: "init", arguments: "", model: "test/test-model" },
+    }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        object(body)
+        check(isRecord(body.info) && body.info.role === "assistant", "command should return assistant message")
+        yield* ctx.llmWait(1)
+      }),
+    "status"),
+  http
+    .post("/session/{sessionID}/shell", "session.shell")
+    .preserveDatabase()
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Shell session" }))
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/shell", { sessionID: ctx.state.id }),
+      headers: ctx.headers(),
+      body: { agent: "build", model: { providerID: "test", modelID: "test-model" }, command: "printf shell-ok" },
+    }))
+    .json(200, (body) => {
+      object(body)
+      check(isRecord(body.info) && body.info.role === "assistant", "shell should return assistant message")
+      check(Array.isArray(body.parts) && body.parts.some((part) => isRecord(part) && part.type === "tool"), "shell should return a tool part")
+    }, "status"),
+  http
+    .post("/session/{sessionID}/summarize", "session.summarize")
+    .preserveDatabase()
+    .withLlm()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Summarize session" })
+        yield* ctx.message(session.id, { text: "summarize this work" })
+        const summary = [
+          "## Goal",
+          "- Exercise session summarize.",
+          "",
+          "## Constraints & Preferences",
+          "- Use fake LLM.",
+          "",
+          "## Progress",
+          "### Done",
+          "- Summary generated.",
+          "",
+          "### In Progress",
+          "- (none)",
+          "",
+          "### Blocked",
+          "- (none)",
+          "",
+          "## Key Decisions",
+          "- Keep route local.",
+          "",
+          "## Next Steps",
+          "- (none)",
+          "",
+          "## Critical Context",
+          "- Test fixture.",
+          "",
+          "## Relevant Files",
+          "- script/httpapi-exercise.ts: scenario",
+        ].join("\n")
+        yield* ctx.llmText(summary)
+        yield* ctx.llmText(summary)
+        return session
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/summarize", { sessionID: ctx.state.id }),
+      headers: ctx.headers(),
+      body: { providerID: "test", modelID: "test-model", auto: false },
+    }))
+    .jsonEffect(200, (body, ctx) =>
+      Effect.gen(function* () {
+        check(body === true, "summarize should return true")
+        const messages = yield* ctx.messages(ctx.state.id)
+        check(
+          messages.some((message) => message.info.role === "assistant" && message.info.summary === true),
+          "summarize should create a summary assistant message",
+        )
+        yield* ctx.llmWait(1)
+      }),
+    "status"),
+  http
+    .post("/session/{sessionID}/revert", "session.revert")
+    .mutating()
+    .seeded((ctx) =>
+      Effect.gen(function* () {
+        const session = yield* ctx.session({ title: "Revert session" })
+        const message = yield* ctx.message(session.id, { text: "revert me" })
+        return { session, message }
+      }),
+    )
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/revert", { sessionID: ctx.state.session.id }),
+      headers: ctx.headers(),
+      body: { messageID: ctx.state.message.info.id },
+    }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.id === ctx.state.session.id, "revert should return the session")
+      check(isRecord(body.revert) && body.revert.messageID === ctx.state.message.info.id, "revert should record reverted message")
+    }, "status"),
+  http
+    .post("/session/{sessionID}/unrevert", "session.unrevert")
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Unrevert session" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}/unrevert", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.id === ctx.state.id, "unrevert should return the session")
+    }, "status"),
+  http
+    .post("/session/{sessionID}/permissions/{permissionID}", "permission.respond")
+    .seeded((ctx) => ctx.session({ title: "Deprecated permission session" }))
+    .at((ctx) => ({
+      path: route("/session/{sessionID}/permissions/{permissionID}", { sessionID: ctx.state.id, permissionID: "per_httpapi_deprecated" }),
+      headers: ctx.headers(),
+      body: { response: "once" },
+    }))
+    .json(200, (body) => {
+      check(body === true, "deprecated permission response should return true")
+    }, "status"),
+  http
+    .post("/session/{sessionID}/share", "session.share")
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Share session" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}/share", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.id === ctx.state.id, "share should return the session")
+    }, "status"),
+  http
+    .delete("/session/{sessionID}/share", "session.unshare")
+    .mutating()
+    .seeded((ctx) => ctx.session({ title: "Unshare session" }))
+    .at((ctx) => ({ path: route("/session/{sessionID}/share", { sessionID: ctx.state.id }), headers: ctx.headers() }))
+    .json(200, (body, ctx) => {
+      object(body)
+      check(body.id === ctx.state.id, "unshare should return the session")
+    }, "status"),
+  http
+    .post("/tui/append-prompt", "tui.appendPrompt")
+    .at((ctx) => ({ path: "/tui/append-prompt", headers: ctx.headers(), body: { text: "hello" } }))
+    .json(200, boolean, "status"),
+  http.post("/tui/open-help", "tui.openHelp").json(200, boolean, "status"),
+  http.post("/tui/open-sessions", "tui.openSessions").json(200, boolean, "status"),
+  http.post("/tui/open-themes", "tui.openThemes").json(200, boolean, "status"),
+  http.post("/tui/open-models", "tui.openModels").json(200, boolean, "status"),
+  http.post("/tui/submit-prompt", "tui.submitPrompt").json(200, boolean, "status"),
+  http.post("/tui/clear-prompt", "tui.clearPrompt").json(200, boolean, "status"),
+  http
+    .post("/tui/execute-command", "tui.executeCommand")
+    .at((ctx) => ({ path: "/tui/execute-command", headers: ctx.headers(), body: { command: "agent_cycle" } }))
+    .json(200, boolean, "status"),
+  http
+    .post("/tui/show-toast", "tui.showToast")
+    .at((ctx) => ({
+      path: "/tui/show-toast",
+      headers: ctx.headers(),
+      body: { title: "Exercise", message: "covered", variant: "info", duration: 1000 },
+    }))
+    .json(200, boolean, "status"),
+  http
+    .post("/tui/publish", "tui.publish")
+    .at((ctx) => ({
+      path: "/tui/publish",
+      headers: ctx.headers(),
+      body: { type: "tui.prompt.append", properties: { text: "published" } },
+    }))
+    .json(200, boolean, "status"),
+  http
+    .post("/tui/select-session", "tui.selectSession")
+    .seeded((ctx) => ctx.session({ title: "TUI select" }))
+    .at((ctx) => ({ path: "/tui/select-session", headers: ctx.headers(), body: { sessionID: ctx.state.id } }))
+    .json(200, boolean, "status"),
+  http
+    .post("/tui/control/response", "tui.control.response")
+    .at((ctx) => ({ path: "/tui/control/response", headers: ctx.headers(), body: { ok: true } }))
+    .json(200, boolean, "status"),
+  http
+    .get("/tui/control/next", "tui.control.next")
+    .mutating()
+    .seeded((ctx) => ctx.tuiRequest({ path: "/tui/exercise", body: { text: "queued" } }))
+    .json(200, (body) => {
+      object(body)
+      check(body.path === "/tui/exercise", "control next should return queued path")
+      object(body.body)
+      check(body.body.text === "queued", "control next should return queued body")
+    }, "status"),
+  http.post("/global/upgrade", "global.upgrade").global().at(() => ({ path: "/global/upgrade", body: { target: 1 } })).status(400),
+]
+
+const main = Effect.gen(function* () {
+  const options = parseOptions(Bun.argv.slice(2))
+  const modules = yield* Effect.promise(() => runtime())
+  const effectRoutes = routeKeys(OpenApi.fromApi(modules.PublicApi))
+  const honoRoutes = routeKeys(yield* Effect.promise(() => modules.Server.openapi()))
+  const selected = scenarios.filter((scenario) => matches(options, scenario))
+  const missing = effectRoutes.filter((route) => !scenarios.some((scenario) => route === routeKey(scenario)))
+  const extra = scenarios.filter((scenario) => !effectRoutes.includes(routeKey(scenario)))
+
+  printHeader(options, effectRoutes, honoRoutes, selected, missing, extra)
+
+  const results = options.mode === "coverage" ? selected.map(coverageResult) : yield* Effect.forEach(selected, runScenario(options), { concurrency: 1 })
+  printResults(results, missing, extra)
+
+  if (results.some((result) => result.status === "fail")) return yield* Effect.fail(new Error("one or more scenarios failed"))
+  if (options.failOnSkip && results.some((result) => result.status === "skip")) return yield* Effect.fail(new Error("one or more scenarios are skipped"))
+  if (options.failOnMissing && missing.length > 0) return yield* Effect.fail(new Error("one or more routes have no scenario"))
+})
+
+function runScenario(options: Options) {
+  return (scenario: Scenario) => {
+    if (scenario.kind === "todo") return Effect.succeed({ status: "skip", scenario } as Result)
+    return runActive(options, scenario).pipe(
+      Effect.as({ status: "pass", scenario } as Result),
+      Effect.catchCause((cause) => Effect.succeed({ status: "fail" as const, scenario, message: Cause.pretty(cause) })),
+      Effect.scoped,
+    )
+  }
+}
+
+function runActive(options: Options, scenario: ActiveScenario) {
+  if (options.mode === "parity" && scenario.mutates && scenario.compare !== "none") {
+    return Effect.gen(function* () {
+      const effect = yield* runBackend("effect", scenario)
+      const legacy = yield* runBackend("legacy", scenario)
+      yield* compare(scenario, effect, legacy)
+    })
+  }
+
+  return withContext(scenario, (ctx) =>
+    Effect.gen(function* () {
+      const effect = yield* call("effect", scenario, ctx)
+      yield* scenario.expect(ctx, ctx.state, effect)
+      if (options.mode === "parity" && scenario.compare !== "none") {
+        const legacy = yield* call("legacy", scenario, ctx)
+        yield* scenario.expect(ctx, ctx.state, legacy)
+        yield* compare(scenario, effect, legacy)
+      }
+    }),
+  )
+}
+
+function runBackend(backend: "effect" | "legacy", scenario: ActiveScenario) {
+  return withContext(scenario, (ctx) =>
+    Effect.gen(function* () {
+      const result = yield* call(backend, scenario, ctx)
+      yield* scenario.expect(ctx, ctx.state, result)
+      return result
+    }),
+  )
+}
+
+function withContext<A, E>(scenario: ActiveScenario, use: (ctx: SeededContext<unknown>) => Effect.Effect<A, E>) {
+  return Effect.acquireRelease(
+    Effect.gen(function* () {
+      const llm = scenario.project?.llm ? yield* TestLLMServer : undefined
+      const project = scenario.project
+      const dir = project
+        ? yield* Effect.promise(async () => (await runtime()).tmpdir(projectOptions(project, llm?.url)))
+        : undefined
+      return { dir, llm }
+    }),
+    (ctx) => Effect.promise(async () => void (await ctx.dir?.[Symbol.asyncDispose]())).pipe(Effect.ignore),
+  ).pipe(
+    Effect.flatMap((context) => Effect.gen(function* () {
+      const modules = yield* Effect.promise(() => runtime())
+      const path = context.dir?.path
+      const instance = path
+        ? yield* modules.InstanceStore.Service.use((store) => store.load({ directory: path })).pipe(
+            Effect.provide(modules.AppLayer),
+            Effect.catchCause((cause) =>
+              Effect.sleep("100 millis").pipe(
+                Effect.andThen(
+                  modules.InstanceStore.Service.use((store) => store.load({ directory: path })).pipe(
+                    Effect.provide(modules.AppLayer),
+                  ),
+                ),
+                Effect.catchCause(() => Effect.failCause(cause)),
+              ),
+            ),
+          )
+        : undefined
+      const run = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        effect.pipe(Effect.provideService(modules.InstanceRef, instance), Effect.provide(modules.AppLayer))
+      const directory = () => {
+        if (!context.dir?.path) throw new Error("scenario needs a project directory")
+        return context.dir.path
+      }
+      const llm = () => {
+        if (!context.llm) throw new Error("scenario needs fake LLM")
+        return context.llm
+      }
+      const base: ScenarioContext = {
+        directory: context.dir?.path,
+        headers: (extra) => ({ ...(context.dir?.path ? { "x-opencode-directory": context.dir.path } : {}), ...extra }),
+        file: (name, content) =>
+          Effect.promise(() => {
+            return Bun.write(`${directory()}/${name}`, content)
+          }).pipe(Effect.asVoid),
+        session: (input) =>
+          run(modules.Session.Service.use((svc) => svc.create({ title: input?.title, parentID: input?.parentID }))),
+        sessionGet: (sessionID) =>
+          run(modules.Session.Service.use((svc) => svc.get(sessionID))).pipe(
+            Effect.catchCause(() => Effect.succeed(undefined)),
+          ),
+        project: () =>
+          Effect.sync(() => {
+            if (!instance) throw new Error("scenario needs a project directory")
+            return instance.project
+          }),
+        message: (sessionID, input) =>
+          Effect.gen(function* () {
+            const info: MessageV2.User = {
+              id: MessageID.ascending(),
+              sessionID,
+              role: "user",
+              time: { created: Date.now() },
+              agent: "build",
+              model: {
+                providerID: ProviderID.opencode,
+                modelID: ModelID.make("test"),
+              },
+            }
+            const part: MessageV2.TextPart = {
+              id: PartID.ascending(),
+              sessionID,
+              messageID: info.id,
+              type: "text",
+              text: input?.text ?? "hello",
+            }
+            yield* run(
+              modules.Session.Service.use((svc) =>
+                Effect.gen(function* () {
+                  yield* svc.updateMessage(info)
+                  yield* svc.updatePart(part)
+                }),
+              ),
+            )
+            return { info, part }
+          }),
+        messages: (sessionID) =>
+          run(modules.Session.Service.use((svc) => svc.messages({ sessionID }))),
+        todos: (sessionID, todos) =>
+          run(modules.Todo.Service.use((svc) => svc.update({ sessionID, todos }))),
+        worktree: (input) =>
+          run(modules.Worktree.Service.use((svc) => svc.create(input))),
+        worktreeRemove: (directory) =>
+          run(modules.Worktree.Service.use((svc) => svc.remove({ directory })).pipe(Effect.ignore)),
+        llmText: (value) => Effect.suspend(() => llm().text(value)),
+        llmWait: (count) => Effect.suspend(() => llm().wait(count)),
+        tuiRequest: (request) => Effect.sync(() => modules.Tui.submitTuiRequest(request)),
+      }
+      const state = yield* scenario.seed(base)
+      return yield* use({ ...base, state })
+    }).pipe(Effect.ensuring(context.llm ? context.llm.reset : Effect.void))),
+    Effect.ensuring(scenario.reset ? resetState : Effect.void),
+  )
+}
+
+function projectOptions(project: ProjectOptions, llmUrl: string | undefined): { git?: boolean; config?: Partial<Config.Info> } {
+  if (!project.llm || !llmUrl) return { git: project.git, config: project.config }
+  const fake = fakeLlmConfig(llmUrl)
+  return {
+    git: project.git,
+    config: {
+      ...fake,
+      ...project.config,
+      provider: {
+        ...fake.provider,
+        ...project.config?.provider,
+      },
+    },
+  }
+}
+
+function fakeLlmConfig(url: string): Partial<Config.Info> {
+  return {
+    model: "test/test-model",
+    small_model: "test/test-model",
+    provider: {
+      test: {
+        name: "Test",
+        id: "test",
+        env: [],
+        npm: "@ai-sdk/openai-compatible",
+        models: {
+          "test-model": {
+            id: "test-model",
+            name: "Test Model",
+            attachment: false,
+            reasoning: false,
+            temperature: false,
+            tool_call: true,
+            release_date: "2025-01-01",
+            limit: { context: 100000, output: 10000 },
+            cost: { input: 0, output: 0 },
+            options: {},
+          },
+        },
+        options: {
+          apiKey: "test-key",
+          baseURL: url,
+        },
+      },
+    },
+  }
+}
+
+function controlledPtyInput(title: string | undefined) {
+  return {
+    command: "/bin/sh",
+    args: ["-c", "sleep 30"],
+    ...(title ? { title } : {}),
+  }
+}
+
+function call(backend: "effect" | "legacy", scenario: ActiveScenario, ctx: SeededContext<unknown>) {
+  return Effect.promise(async () => capture(await app(await runtime(), backend).request(toRequest(scenario, ctx)), scenario.capture))
+}
+
+function app(modules: Runtime, backend: "effect" | "legacy") {
+  Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = backend === "effect"
+  Flag.OPENCODE_SERVER_PASSWORD = undefined
+  Flag.OPENCODE_SERVER_USERNAME = undefined
+  if (backend === "legacy") return modules.Server.Legacy().app
+
+  const handler = HttpRouter.toWebHandler(
+    modules.ExperimentalHttpApiServer.routes.pipe(
+      Layer.provide(ConfigProvider.layer(ConfigProvider.fromUnknown({ OPENCODE_SERVER_PASSWORD: undefined, OPENCODE_SERVER_USERNAME: undefined }))),
+    ),
+    { disableLogger: true },
+  ).handler
+  return {
+    fetch: (request: Request) => handler(request, modules.ExperimentalHttpApiServer.context),
+    request(input: string | URL | Request, init?: RequestInit) {
+      return this.fetch(input instanceof Request ? input : new Request(new URL(input, "http://localhost"), init))
+    },
+  }
+}
+
+function toRequest(scenario: ActiveScenario, ctx: SeededContext<unknown>) {
+  const spec = scenario.request(ctx, ctx.state)
+  return new Request(new URL(spec.path, "http://localhost"), {
+    method: scenario.method,
+    headers: spec.body === undefined ? spec.headers : { "content-type": "application/json", ...spec.headers },
+    body: spec.body === undefined ? undefined : JSON.stringify(spec.body),
+  })
+}
+
+async function capture(response: Response, mode: CaptureMode): Promise<CallResult> {
+  const text = mode === "stream" ? await captureStream(response) : await response.text()
+  return {
+    status: response.status,
+    contentType: response.headers.get("content-type") ?? "",
+    text,
+    body: parse(text),
+  }
+}
+
+async function captureStream(response: Response) {
+  if (!response.body) return ""
+  const reader = response.body.getReader()
+  const read = reader.read().then((result) => ({ result }))
+  const winner = await Promise.race([read, Bun.sleep(1_000).then(() => ({ timeout: true }))])
+  if ("timeout" in winner) {
+    await reader.cancel("timed out waiting for stream chunk").catch(() => undefined)
+    throw new Error("timed out waiting for stream chunk")
+  }
+  await reader.cancel().catch(() => undefined)
+  if (winner.result.done) return ""
+  return new TextDecoder().decode(winner.result.value)
+}
+
+function compare(scenario: ActiveScenario, effect: CallResult, legacy: CallResult) {
+  return Effect.sync(() => {
+    if (effect.status !== legacy.status) throw new Error(`legacy returned ${legacy.status}, effect returned ${effect.status}`)
+    if (scenario.compare === "status") return
+    if (stable(effect.body) !== stable(legacy.body)) throw new Error(`JSON parity mismatch\nlegacy: ${stable(legacy.body)}\neffect: ${stable(effect.body)}`)
+  })
+}
+
+const resetState = Effect.promise(async () => {
+  const modules = await runtime()
+  Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = original.OPENCODE_EXPERIMENTAL_HTTPAPI
+  Flag.OPENCODE_SERVER_PASSWORD = original.OPENCODE_SERVER_PASSWORD
+  Flag.OPENCODE_SERVER_USERNAME = original.OPENCODE_SERVER_USERNAME
+  await modules.disposeAllInstances()
+  await modules.resetDatabase()
+  await Bun.sleep(25)
+})
+
+function routeKeys(spec: OpenApiSpec) {
+  return Object.entries(spec.paths ?? {})
+    .flatMap(([path, item]) => OpenApiMethods.filter((method) => item[method]).map((method) => `${method.toUpperCase()} ${path}`))
+    .sort()
+}
+
+function routeKey(scenario: Scenario) {
+  return `${scenario.method} ${scenario.path}`
+}
+
+function coverageResult(scenario: Scenario): Result {
+  if (scenario.kind === "todo") return { status: "skip", scenario }
+  return { status: "pass", scenario }
+}
+
+function parseOptions(args: string[]): Options {
+  const mode = option(args, "--mode") ?? "effect"
+  if (mode !== "effect" && mode !== "parity" && mode !== "coverage") throw new Error(`invalid --mode ${mode}`)
+  return {
+    mode,
+    include: option(args, "--include"),
+    failOnMissing: args.includes("--fail-on-missing"),
+    failOnSkip: args.includes("--fail-on-skip"),
+  }
+}
+
+function option(args: string[], name: string) {
+  const index = args.indexOf(name)
+  if (index === -1) return undefined
+  return args[index + 1]
+}
+
+function matches(options: Options, scenario: Scenario) {
+  if (!options.include) return true
+  return scenario.name.includes(options.include) || scenario.path.includes(options.include) || scenario.method.includes(options.include.toUpperCase())
+}
+
+function printHeader(options: Options, effectRoutes: string[], honoRoutes: string[], selected: Scenario[], missing: string[], extra: Scenario[]) {
+  console.log(`${color.cyan}HttpApi exerciser${color.reset}`)
+  console.log(`${color.dim}db=${exerciseDatabasePath}${color.reset}`)
+  console.log(`${color.dim}global=${exerciseGlobalRoot}${color.reset}`)
+  console.log(
+    `${color.dim}mode=${options.mode} selected=${selected.length} effectRoutes=${effectRoutes.length} missing=${missing.length} extra=${extra.length} onlyEffect=${effectRoutes.filter((route) => !honoRoutes.includes(route)).length} onlyHono=${honoRoutes.filter((route) => !effectRoutes.includes(route)).length}${color.reset}`,
+  )
+  console.log("")
+}
+
+function printResults(results: Result[], missing: string[], extra: Scenario[]) {
+  for (const result of results) {
+    if (result.status === "pass") {
+      console.log(`${color.green}PASS${color.reset} ${pad(result.scenario.method, 6)} ${pad(result.scenario.path, 48)} ${result.scenario.name}`)
+      continue
+    }
+    if (result.status === "skip") {
+      console.log(`${color.yellow}SKIP${color.reset} ${pad(result.scenario.method, 6)} ${pad(result.scenario.path, 48)} ${result.scenario.name} ${color.dim}${result.scenario.reason}${color.reset}`)
+      continue
+    }
+    console.log(`${color.red}FAIL${color.reset} ${pad(result.scenario.method, 6)} ${pad(result.scenario.path, 48)} ${result.scenario.name}`)
+    console.log(`${color.red}${indent(result.message)}${color.reset}`)
+  }
+  if (missing.length > 0) {
+    console.log("\nMissing scenarios")
+    for (const route of missing) console.log(`${color.red}MISS${color.reset} ${route}`)
+  }
+  if (extra.length > 0) {
+    console.log("\nExtra scenarios")
+    for (const scenario of extra) console.log(`${color.yellow}EXTRA${color.reset} ${routeKey(scenario)} ${scenario.name}`)
+  }
+  console.log(
+    `\n${color.dim}summary pass=${results.filter((result) => result.status === "pass").length} fail=${results.filter((result) => result.status === "fail").length} skip=${results.filter((result) => result.status === "skip").length} missing=${missing.length} extra=${extra.length}${color.reset}`,
+  )
+}
+
+function parse(text: string): unknown {
+  if (!text) return undefined
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    return text
+  }
+}
+
+function looksJson(result: CallResult) {
+  return result.contentType.includes("application/json") || result.text.startsWith("{") || result.text.startsWith("[")
+}
+
+function stable(value: unknown): string {
+  return JSON.stringify(sort(value))
+}
+
+function sort(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sort)
+  if (!value || typeof value !== "object") return value
+  return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, sort(item)]))
+}
+
+function array(value: unknown): asserts value is unknown[] {
+  if (!Array.isArray(value)) throw new Error("expected array")
+}
+
+function object(value: unknown): asserts value is JsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected object")
+}
+
+function boolean(value: unknown): asserts value is boolean {
+  if (typeof value !== "boolean") throw new Error("expected boolean")
+}
+
+function isRecord(value: unknown): value is JsonObject {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+}
+
+function check(value: boolean, message: string): asserts value {
+  if (!value) throw new Error(message)
+}
+
+function message(error: unknown) {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
+function pad(value: string, size: number) {
+  return value.length >= size ? value : value + " ".repeat(size - value.length)
+}
+
+function indent(value: string) {
+  return value
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n")
+}
+
+Effect.runPromise(main.pipe(Effect.provide(TestLLMServer.layer), Effect.scoped)).then(
+  () => process.exit(0),
+  (error: unknown) => {
+    console.error(`${color.red}${message(error)}${color.reset}`)
+    process.exit(1)
+  },
+)

packages/opencode/src/server/routes/instance/tui.ts

@@ -26,13 +26,17 @@ export function nextTuiRequest() {
   return request.next()
 }
 
+export function submitTuiRequest(body: TuiRequest) {
+  request.push(body)
+}
+
 export function submitTuiResponse(body: unknown) {
   response.push(body)
 }
 
 export async function callTui(ctx: Context) {
   const body = await ctx.req.json()
-  request.push({
+  submitTuiRequest({
     path: ctx.req.path,
     body,
   })

packages/opencode/src/storage/db.ts

@@ -122,6 +122,7 @@ export const Client = lazy(() => {
 })
 
 export function close() {
+  if (!Client.loaded()) return
   Client().$client.close()
   Client.reset()
 }

packages/opencode/src/util/lazy.ts

@@ -14,5 +14,7 @@ export function lazy<T>(fn: () => T) {
     value = undefined
   }
 
+  result.loaded = () => loaded
+
   return result
 }

packages/opencode/test/AGENTS.md

@@ -89,20 +89,17 @@ Use `testEffect(...)` from `test/lib/effect.ts` for tests that exercise Effect s
 ```typescript
 import { describe, expect } from "bun:test"
 import { Effect, Layer } from "effect"
-import { provideTmpdirInstance } from "../fixture/fixture"
 import { testEffect } from "../lib/effect"
 
 const it = testEffect(Layer.mergeAll(MyService.defaultLayer))
 
 describe("my service", () => {
-  it.live("does the thing", () =>
-    provideTmpdirInstance(() =>
-      Effect.gen(function* () {
-        const svc = yield* MyService.Service
-        const out = yield* svc.run()
-        expect(out).toEqual("ok")
-      }),
-    ),
+  it.instance("does the thing", () =>
+    Effect.gen(function* () {
+      const svc = yield* MyService.Service
+      const out = yield* svc.run()
+      expect(out).toEqual("ok")
+    }),
   )
 })
 ```
@@ -111,6 +108,7 @@ describe("my service", () => {
 
 - Use `it.effect(...)` when the test should run with `TestClock` and `TestConsole`.
 - Use `it.live(...)` when the test depends on real time, filesystem mtimes, child processes, git, locks, or other live OS behavior.
+- Use `it.instance(...)` for live Effect tests that need a scoped temporary directory and instance context.
 - Most integration-style tests in this package use `it.live(...)`.
 
 ### Effect Fixtures
@@ -122,7 +120,20 @@ Prefer the Effect-aware helpers from `fixture/fixture.ts` instead of building a
 - `provideTmpdirInstance((dir) => effect, options?)` is the convenience helper. It creates a temp directory, binds it as the active instance, and disposes the instance on cleanup.
 - `provideTmpdirServer((input) => effect, options?)` does the same, but also provides the test LLM server.
 
-Use `provideTmpdirInstance(...)` by default when a test only needs one temp instance. Use `tmpdirScoped()` plus `provideInstance(...)` when a test needs multiple directories, custom setup before binding, or needs to switch instance context within one test.
+Use `it.instance(...)` by default when a test only needs one temp instance. Yield `TestInstance` from `fixture/fixture.ts` when the test needs the temp directory path:
+
+```typescript
+import { TestInstance } from "../fixture/fixture"
+
+it.instance("uses the temp directory", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    expect(test.directory).toContain("opencode-test-")
+  }),
+)
+```
+
+Use `provideTmpdirInstance(...)` or `tmpdirScoped()` plus `provideInstance(...)` when a test needs multiple directories, custom setup before binding, needs to switch instance context within one test, or explicitly tests instance disposal/reload lifetime.
 
 ### Style
 
@@ -130,4 +141,4 @@ Use `provideTmpdirInstance(...)` by default when a test only needs one temp inst
 - Keep the test body inside `Effect.gen(function* () { ... })`.
 - Yield services directly with `yield* MyService.Service` or `yield* MyTool`.
 - Avoid custom `ManagedRuntime`, `attach(...)`, or ad hoc `run(...)` wrappers when `testEffect(...)` already provides the runtime.
-- When a test needs instance-local state, prefer `provideTmpdirInstance(...)` or `provideInstance(...)` over manual `Instance.provide(...)` inside Promise-style tests.
+- When a test needs instance-local state, prefer `it.instance(...)` over manual `Instance.provide(...)` inside Promise-style tests.

packages/opencode/test/bus/bus-effect.test.ts

@@ -2,9 +2,8 @@ import { describe, expect } from "bun:test"
 import { Deferred, Effect, Layer, Schema, Stream } from "effect"
 import { Bus } from "../../src/bus"
 import { BusEvent } from "../../src/bus/bus-event"
-import { Instance } from "../../src/project/instance"
 import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
-import { disposeAllInstances, provideInstance, provideTmpdirInstance, tmpdirScoped } from "../fixture/fixture"
+import { disposeAllInstances, provideInstance, tmpdirScoped } from "../fixture/fixture"
 import { testEffect } from "../lib/effect"
 
 const TestEvent = {
@@ -19,111 +18,103 @@ const live = Layer.mergeAll(Bus.layer, node)
 const it = testEffect(live)
 
 describe("Bus (Effect-native)", () => {
-  it.live("publish + subscribe stream delivers events", () =>
-    provideTmpdirInstance(() =>
-      Effect.gen(function* () {
-        const bus = yield* Bus.Service
-        const received: number[] = []
-        const done = yield* Deferred.make<void>()
+  it.instance("publish + subscribe stream delivers events", () =>
+    Effect.gen(function* () {
+      const bus = yield* Bus.Service
+      const received: number[] = []
+      const done = yield* Deferred.make<void>()
 
-        yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
-          Effect.sync(() => {
-            received.push(evt.properties.value)
-            if (received.length === 2) Deferred.doneUnsafe(done, Effect.void)
-          }),
-        ).pipe(Effect.forkScoped)
+      yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
+        Effect.sync(() => {
+          received.push(evt.properties.value)
+          if (received.length === 2) Deferred.doneUnsafe(done, Effect.void)
+        }),
+      ).pipe(Effect.forkScoped)
 
-        yield* Effect.sleep("10 millis")
-        yield* bus.publish(TestEvent.Ping, { value: 1 })
-        yield* bus.publish(TestEvent.Ping, { value: 2 })
-        yield* Deferred.await(done)
+      yield* Effect.sleep("10 millis")
+      yield* bus.publish(TestEvent.Ping, { value: 1 })
+      yield* bus.publish(TestEvent.Ping, { value: 2 })
+      yield* Deferred.await(done)
 
-        expect(received).toEqual([1, 2])
-      }),
-    ),
+      expect(received).toEqual([1, 2])
+    }),
   )
 
-  it.live("subscribe filters by event type", () =>
-    provideTmpdirInstance(() =>
-      Effect.gen(function* () {
-        const bus = yield* Bus.Service
-        const pings: number[] = []
-        const done = yield* Deferred.make<void>()
+  it.instance("subscribe filters by event type", () =>
+    Effect.gen(function* () {
+      const bus = yield* Bus.Service
+      const pings: number[] = []
+      const done = yield* Deferred.make<void>()
 
-        yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
-          Effect.sync(() => {
-            pings.push(evt.properties.value)
-            Deferred.doneUnsafe(done, Effect.void)
-          }),
-        ).pipe(Effect.forkScoped)
+      yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
+        Effect.sync(() => {
+          pings.push(evt.properties.value)
+          Deferred.doneUnsafe(done, Effect.void)
+        }),
+      ).pipe(Effect.forkScoped)
 
-        yield* Effect.sleep("10 millis")
-        yield* bus.publish(TestEvent.Pong, { message: "ignored" })
-        yield* bus.publish(TestEvent.Ping, { value: 42 })
-        yield* Deferred.await(done)
+      yield* Effect.sleep("10 millis")
+      yield* bus.publish(TestEvent.Pong, { message: "ignored" })
+      yield* bus.publish(TestEvent.Ping, { value: 42 })
+      yield* Deferred.await(done)
 
-        expect(pings).toEqual([42])
-      }),
-    ),
+      expect(pings).toEqual([42])
+    }),
   )
 
-  it.live("subscribeAll receives all types", () =>
-    provideTmpdirInstance(() =>
-      Effect.gen(function* () {
-        const bus = yield* Bus.Service
-        const types: string[] = []
-        const done = yield* Deferred.make<void>()
+  it.instance("subscribeAll receives all types", () =>
+    Effect.gen(function* () {
+      const bus = yield* Bus.Service
+      const types: string[] = []
+      const done = yield* Deferred.make<void>()
 
-        yield* Stream.runForEach(bus.subscribeAll(), (evt) =>
-          Effect.sync(() => {
-            types.push(evt.type)
-            if (types.length === 2) Deferred.doneUnsafe(done, Effect.void)
-          }),
-        ).pipe(Effect.forkScoped)
+      yield* Stream.runForEach(bus.subscribeAll(), (evt) =>
+        Effect.sync(() => {
+          types.push(evt.type)
+          if (types.length === 2) Deferred.doneUnsafe(done, Effect.void)
+        }),
+      ).pipe(Effect.forkScoped)
 
-        yield* Effect.sleep("10 millis")
-        yield* bus.publish(TestEvent.Ping, { value: 1 })
-        yield* bus.publish(TestEvent.Pong, { message: "hi" })
-        yield* Deferred.await(done)
+      yield* Effect.sleep("10 millis")
+      yield* bus.publish(TestEvent.Ping, { value: 1 })
+      yield* bus.publish(TestEvent.Pong, { message: "hi" })
+      yield* Deferred.await(done)
 
-        expect(types).toContain("test.effect.ping")
-        expect(types).toContain("test.effect.pong")
-      }),
-    ),
+      expect(types).toContain("test.effect.ping")
+      expect(types).toContain("test.effect.pong")
+    }),
   )
 
-  it.live("multiple subscribers each receive the event", () =>
-    provideTmpdirInstance(() =>
-      Effect.gen(function* () {
-        const bus = yield* Bus.Service
-        const a: number[] = []
-        const b: number[] = []
-        const doneA = yield* Deferred.make<void>()
-        const doneB = yield* Deferred.make<void>()
+  it.instance("multiple subscribers each receive the event", () =>
+    Effect.gen(function* () {
+      const bus = yield* Bus.Service
+      const a: number[] = []
+      const b: number[] = []
+      const doneA = yield* Deferred.make<void>()
+      const doneB = yield* Deferred.make<void>()
 
-        yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
-          Effect.sync(() => {
-            a.push(evt.properties.value)
-            Deferred.doneUnsafe(doneA, Effect.void)
-          }),
-        ).pipe(Effect.forkScoped)
+      yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
+        Effect.sync(() => {
+          a.push(evt.properties.value)
+          Deferred.doneUnsafe(doneA, Effect.void)
+        }),
+      ).pipe(Effect.forkScoped)
 
-        yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
-          Effect.sync(() => {
-            b.push(evt.properties.value)
-            Deferred.doneUnsafe(doneB, Effect.void)
-          }),
-        ).pipe(Effect.forkScoped)
+      yield* Stream.runForEach(bus.subscribe(TestEvent.Ping), (evt) =>
+        Effect.sync(() => {
+          b.push(evt.properties.value)
+          Deferred.doneUnsafe(doneB, Effect.void)
+        }),
+      ).pipe(Effect.forkScoped)
 
-        yield* Effect.sleep("10 millis")
-        yield* bus.publish(TestEvent.Ping, { value: 99 })
-        yield* Deferred.await(doneA)
-        yield* Deferred.await(doneB)
+      yield* Effect.sleep("10 millis")
+      yield* bus.publish(TestEvent.Ping, { value: 99 })
+      yield* Deferred.await(doneA)
+      yield* Deferred.await(doneB)
 
-        expect(a).toEqual([99])
-        expect(b).toEqual([99])
-      }),
-    ),
+      expect(a).toEqual([99])
+      expect(b).toEqual([99])
+    }),
   )
 
   it.live("subscribeAll stream sees InstanceDisposed on disposal", () =>

packages/opencode/test/fixture/fixture.ts

@@ -5,10 +5,12 @@ import path from "path"
 import { Effect, Context } from "effect"
 import type * as PlatformError from "effect/PlatformError"
 import type * as Scope from "effect/Scope"
+import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
 import type { Config } from "@/config/config"
 import { InstanceRef } from "../../src/effect/instance-ref"
 import { Instance } from "../../src/project/instance"
+import { InstanceStore } from "../../src/project/instance-store"
 import { TestLLMServer } from "../lib/llm-server"
 
 // Re-export for test ergonomics. The implementation lives next to the runtime
@@ -160,6 +162,18 @@ export function provideTmpdirInstance<A, E, R>(
   })
 }
 
+export class TestInstance extends Context.Service<TestInstance, { readonly directory: string }>()("@test/Instance") {}
+
+export const withTmpdirInstance =
+  (options?: { git?: boolean; config?: Partial<Config.Info> }) =>
+  <A, E, R>(self: Effect.Effect<A, E, R>) =>
+    Effect.gen(function* () {
+      const directory = yield* tmpdirScoped(options)
+      return yield* InstanceStore.Service.use((store) =>
+        store.provide({ directory }, self.pipe(Effect.provideService(TestInstance, { directory }))),
+      )
+    }).pipe(Effect.provide(InstanceStore.defaultLayer), Effect.provide(CrossSpawnSpawner.defaultLayer))
+
 export function provideTmpdirServer<A, E, R>(
   self: (input: { dir: string; llm: TestLLMServer["Service"] }) => Effect.Effect<A, E, R>,
   options?: { git?: boolean; config?: (url: string) => Partial<Config.Info> },

packages/opencode/test/lib/effect.ts

@@ -3,8 +3,11 @@ import { Cause, Effect, Exit, Layer } from "effect"
 import type * as Scope from "effect/Scope"
 import * as TestClock from "effect/testing/TestClock"
 import * as TestConsole from "effect/testing/TestConsole"
+import type { Config } from "@/config/config"
+import { TestInstance, withTmpdirInstance } from "../fixture/fixture"
 
 type Body<A, E, R> = Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>)
+type InstanceOptions = { git?: boolean; config?: Partial<Config.Info> }
 
 const body = <A, E, R>(value: Body<A, E, R>) => Effect.suspend(() => (typeof value === "function" ? value() : value))
 
@@ -38,7 +41,28 @@ const make = <R, E>(testLayer: Layer.Layer<R, E>, liveLayer: Layer.Layer<R, E>)
   live.skip = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
     test.skip(name, () => run(value, liveLayer), opts)
 
-  return { effect, live }
+  const instance = <A, E2>(
+    name: string,
+    value: Body<A, E2, R | TestInstance | Scope.Scope>,
+    instanceOptions?: InstanceOptions,
+    opts?: number | TestOptions,
+  ) => test(name, () => run(body(value).pipe(withTmpdirInstance(instanceOptions)), liveLayer), opts)
+
+  instance.only = <A, E2>(
+    name: string,
+    value: Body<A, E2, R | TestInstance | Scope.Scope>,
+    instanceOptions?: InstanceOptions,
+    opts?: number | TestOptions,
+  ) => test.only(name, () => run(body(value).pipe(withTmpdirInstance(instanceOptions)), liveLayer), opts)
+
+  instance.skip = <A, E2>(
+    name: string,
+    value: Body<A, E2, R | TestInstance | Scope.Scope>,
+    instanceOptions?: InstanceOptions,
+    opts?: number | TestOptions,
+  ) => test.skip(name, () => run(body(value).pipe(withTmpdirInstance(instanceOptions)), liveLayer), opts)
+
+  return { effect, live, instance }
 }
 
 // Test environment with TestClock and TestConsole

packages/opencode/test/question/question.test.ts

@@ -1,64 +1,63 @@
-import { afterEach, test, expect } from "bun:test"
+import { afterEach, expect } from "bun:test"
+import { Cause, Effect, Exit, Fiber, Layer } from "effect"
 import { Question } from "../../src/question"
 import { Instance } from "../../src/project/instance"
 import { QuestionID } from "../../src/question/schema"
-import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import { disposeAllInstances, provideInstance, tmpdirScoped } from "../fixture/fixture"
 import { SessionID } from "../../src/session/schema"
-import { AppRuntime } from "../../src/effect/app-runtime"
+import { testEffect } from "../lib/effect"
+import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
 
-const ask = (input: { sessionID: SessionID; questions: ReadonlyArray<Question.Info>; tool?: Question.Tool }) =>
-  AppRuntime.runPromise(Question.Service.use((svc) => svc.ask(input)))
+const it = testEffect(Layer.mergeAll(Question.defaultLayer, CrossSpawnSpawner.defaultLayer))
 
-const list = () => AppRuntime.runPromise(Question.Service.use((svc) => svc.list()))
+const askEffect = Effect.fn("QuestionTest.ask")(function* (input: {
+  sessionID: SessionID
+  questions: ReadonlyArray<Question.Info>
+  tool?: Question.Tool
+}) {
+  const question = yield* Question.Service
+  return yield* question.ask(input)
+})
 
-const reply = (input: { requestID: QuestionID; answers: ReadonlyArray<Question.Answer> }) =>
-  AppRuntime.runPromise(Question.Service.use((svc) => svc.reply(input)))
+const listEffect = Question.Service.use((svc) => svc.list())
 
-const reject = (id: QuestionID) => AppRuntime.runPromise(Question.Service.use((svc) => svc.reject(id)))
+const replyEffect = Effect.fn("QuestionTest.reply")(function* (input: {
+  requestID: QuestionID
+  answers: ReadonlyArray<Question.Answer>
+}) {
+  const question = yield* Question.Service
+  yield* question.reply(input)
+})
+
+const rejectEffect = Effect.fn("QuestionTest.reject")(function* (id: QuestionID) {
+  const question = yield* Question.Service
+  yield* question.reject(id)
+})
 
 afterEach(async () => {
   await disposeAllInstances()
 })
 
 /** Reject all pending questions so dangling Deferred fibers don't hang the test. */
-async function rejectAll() {
-  const pending = await list()
-  for (const req of pending) {
-    await reject(req.id)
-  }
-}
-
-test("ask - returns pending promise", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const promise = ask({
-        sessionID: SessionID.make("ses_test"),
-        questions: [
-          {
-            question: "What would you like to do?",
-            header: "Action",
-            options: [
-              { label: "Option 1", description: "First option" },
-              { label: "Option 2", description: "Second option" },
-            ],
-          },
-        ],
-      })
-      expect(promise).toBeInstanceOf(Promise)
-      await rejectAll()
-      await promise.catch(() => {})
-    },
-  })
+const rejectAll = Effect.gen(function* () {
+  yield* Effect.forEach(yield* listEffect, (req) => rejectEffect(req.id), { discard: true })
 })
 
-test("ask - adds to pending list", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const questions = [
+const waitForPending = (count: number) =>
+  Effect.gen(function* () {
+    for (let i = 0; i < 100; i++) {
+      const pending = yield* listEffect
+      if (pending.length === count) return pending
+      yield* Effect.sleep("10 millis")
+    }
+    return yield* Effect.fail(new Error(`timed out waiting for ${count} pending question request(s)`))
+  })
+
+it.instance("ask - remains pending until answered", () =>
+  Effect.gen(function* () {
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_test"),
+      questions: [
         {
           question: "What would you like to do?",
           header: "Action",
@@ -67,30 +66,81 @@ test("ask - adds to pending list", async () => {
             { label: "Option 2", description: "Second option" },
           ],
         },
-      ]
+      ],
+    }).pipe(Effect.forkScoped)
 
-      const promise = ask({
-        sessionID: SessionID.make("ses_test"),
-        questions,
-      })
+    expect(yield* waitForPending(1)).toHaveLength(1)
+    yield* rejectAll
+    expect((yield* Fiber.await(fiber))._tag).toBe("Failure")
+  }),
+  { git: true },
+)
 
-      const pending = await list()
-      expect(pending.length).toBe(1)
-      expect(pending[0].questions).toEqual(questions)
-      await rejectAll()
-      await promise.catch(() => {})
-    },
-  })
-})
+it.instance("ask - adds to pending list", () =>
+  Effect.gen(function* () {
+    const questions = [
+      {
+        question: "What would you like to do?",
+        header: "Action",
+        options: [
+          { label: "Option 1", description: "First option" },
+          { label: "Option 2", description: "Second option" },
+        ],
+      },
+    ]
+
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_test"),
+      questions,
+    }).pipe(Effect.forkScoped)
+
+    const pending = yield* waitForPending(1)
+    expect(pending.length).toBe(1)
+    expect(pending[0].questions).toEqual(questions)
+    yield* rejectAll
+    expect((yield* Fiber.await(fiber))._tag).toBe("Failure")
+  }),
+  { git: true },
+)
 
 // reply tests
 
-test("reply - resolves the pending ask with answers", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const questions = [
+it.instance("reply - resolves the pending ask with answers", () =>
+  Effect.gen(function* () {
+    const questions = [
+      {
+        question: "What would you like to do?",
+        header: "Action",
+        options: [
+          { label: "Option 1", description: "First option" },
+          { label: "Option 2", description: "Second option" },
+        ],
+      },
+    ]
+
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_test"),
+      questions,
+    }).pipe(Effect.forkScoped)
+
+    const pending = yield* waitForPending(1)
+    const requestID = pending[0].id
+
+    yield* replyEffect({
+      requestID,
+      answers: [["Option 1"]],
+    })
+
+    expect(yield* Fiber.join(fiber)).toEqual([["Option 1"]])
+  }),
+  { git: true },
+)
+
+it.instance("reply - removes from pending list", () =>
+  Effect.gen(function* () {
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_test"),
+      questions: [
         {
           question: "What would you like to do?",
           header: "Action",
@@ -99,366 +149,258 @@ test("reply - resolves the pending ask with answers", async () => {
             { label: "Option 2", description: "Second option" },
           ],
         },
-      ]
+      ],
+    }).pipe(Effect.forkScoped)
 
-      const promise = ask({
-        sessionID: SessionID.make("ses_test"),
-        questions,
-      })
+    const pending = yield* waitForPending(1)
+    expect(pending.length).toBe(1)
 
-      const pending = await list()
-      const requestID = pending[0].id
+    yield* replyEffect({
+      requestID: pending[0].id,
+      answers: [["Option 1"]],
+    })
+    yield* Fiber.join(fiber)
 
-      await reply({
-        requestID,
-        answers: [["Option 1"]],
-      })
+    const after = yield* listEffect
+    expect(after.length).toBe(0)
+  }),
+  { git: true },
+)
 
-      const answers = await promise
-      expect(answers).toEqual([["Option 1"]])
-    },
-  })
-})
-
-test("reply - removes from pending list", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const promise = ask({
-        sessionID: SessionID.make("ses_test"),
-        questions: [
-          {
-            question: "What would you like to do?",
-            header: "Action",
-            options: [
-              { label: "Option 1", description: "First option" },
-              { label: "Option 2", description: "Second option" },
-            ],
-          },
-        ],
-      })
-
-      const pending = await list()
-      expect(pending.length).toBe(1)
-
-      await reply({
-        requestID: pending[0].id,
-        answers: [["Option 1"]],
-      })
-      await promise
-
-      const after = await list()
-      expect(after.length).toBe(0)
-    },
-  })
-})
-
-test("reply - does nothing for unknown requestID", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      await reply({
-        requestID: QuestionID.make("que_unknown"),
-        answers: [["Option 1"]],
-      })
-      // Should not throw
-    },
-  })
-})
+it.instance("reply - does nothing for unknown requestID", () =>
+  replyEffect({
+    requestID: QuestionID.make("que_unknown"),
+    answers: [["Option 1"]],
+  }),
+  { git: true },
+)
 
 // reject tests
 
-test("reject - throws RejectedError", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const promise = ask({
-        sessionID: SessionID.make("ses_test"),
-        questions: [
-          {
-            question: "What would you like to do?",
-            header: "Action",
-            options: [
-              { label: "Option 1", description: "First option" },
-              { label: "Option 2", description: "Second option" },
-            ],
-          },
-        ],
-      })
-
-      const pending = await list()
-      await reject(pending[0].id)
-
-      await expect(promise).rejects.toBeInstanceOf(Question.RejectedError)
-    },
-  })
-})
-
-test("reject - removes from pending list", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const promise = ask({
-        sessionID: SessionID.make("ses_test"),
-        questions: [
-          {
-            question: "What would you like to do?",
-            header: "Action",
-            options: [
-              { label: "Option 1", description: "First option" },
-              { label: "Option 2", description: "Second option" },
-            ],
-          },
-        ],
-      })
-
-      const pending = await list()
-      expect(pending.length).toBe(1)
-
-      await reject(pending[0].id)
-      promise.catch(() => {}) // Ignore rejection
-
-      const after = await list()
-      expect(after.length).toBe(0)
-    },
-  })
-})
-
-test("reject - does nothing for unknown requestID", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      await reject(QuestionID.make("que_unknown"))
-      // Should not throw
-    },
-  })
-})
-
-// multiple questions tests
-
-test("ask - handles multiple questions", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const questions = [
+it.instance("reject - throws RejectedError", () =>
+  Effect.gen(function* () {
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_test"),
+      questions: [
         {
           question: "What would you like to do?",
           header: "Action",
           options: [
-            { label: "Build", description: "Build the project" },
-            { label: "Test", description: "Run tests" },
+            { label: "Option 1", description: "First option" },
+            { label: "Option 2", description: "Second option" },
           ],
         },
+      ],
+    }).pipe(Effect.forkScoped)
+
+    const pending = yield* waitForPending(1)
+    yield* rejectEffect(pending[0].id)
+
+    const exit = yield* Fiber.await(fiber)
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") expect(exit.cause.toString()).toContain("QuestionRejectedError")
+  }),
+  { git: true },
+)
+
+it.instance("reject - removes from pending list", () =>
+  Effect.gen(function* () {
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_test"),
+      questions: [
         {
-          question: "Which environment?",
-          header: "Env",
+          question: "What would you like to do?",
+          header: "Action",
           options: [
-            { label: "Dev", description: "Development" },
-            { label: "Prod", description: "Production" },
+            { label: "Option 1", description: "First option" },
+            { label: "Option 2", description: "Second option" },
           ],
         },
-      ]
+      ],
+    }).pipe(Effect.forkScoped)
 
-      const promise = ask({
-        sessionID: SessionID.make("ses_test"),
-        questions,
-      })
+    const pending = yield* waitForPending(1)
+    expect(pending.length).toBe(1)
 
-      const pending = await list()
+    yield* rejectEffect(pending[0].id)
+    expect((yield* Fiber.await(fiber))._tag).toBe("Failure")
 
-      await reply({
-        requestID: pending[0].id,
-        answers: [["Build"], ["Dev"]],
-      })
+    const after = yield* listEffect
+    expect(after.length).toBe(0)
+  }),
+  { git: true },
+)
 
-      const answers = await promise
-      expect(answers).toEqual([["Build"], ["Dev"]])
-    },
-  })
-})
+it.instance("reject - does nothing for unknown requestID", () => rejectEffect(QuestionID.make("que_unknown")), { git: true })
+
+// multiple questions tests
+
+it.instance("ask - handles multiple questions", () =>
+  Effect.gen(function* () {
+    const questions = [
+      {
+        question: "What would you like to do?",
+        header: "Action",
+        options: [
+          { label: "Build", description: "Build the project" },
+          { label: "Test", description: "Run tests" },
+        ],
+      },
+      {
+        question: "Which environment?",
+        header: "Env",
+        options: [
+          { label: "Dev", description: "Development" },
+          { label: "Prod", description: "Production" },
+        ],
+      },
+    ]
+
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_test"),
+      questions,
+    }).pipe(Effect.forkScoped)
+
+    const pending = yield* waitForPending(1)
+
+    yield* replyEffect({
+      requestID: pending[0].id,
+      answers: [["Build"], ["Dev"]],
+    })
+
+    expect(yield* Fiber.join(fiber)).toEqual([["Build"], ["Dev"]])
+  }),
+  { git: true },
+)
 
 // list tests
 
-test("list - returns all pending requests", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const p1 = ask({
-        sessionID: SessionID.make("ses_test1"),
-        questions: [
-          {
-            question: "Question 1?",
-            header: "Q1",
-            options: [{ label: "A", description: "A" }],
-          },
-        ],
-      })
+it.instance("list - returns all pending requests", () =>
+  Effect.gen(function* () {
+    const fiber1 = yield* askEffect({
+      sessionID: SessionID.make("ses_test1"),
+      questions: [
+        {
+          question: "Question 1?",
+          header: "Q1",
+          options: [{ label: "A", description: "A" }],
+        },
+      ],
+    }).pipe(Effect.forkScoped)
 
-      const p2 = ask({
-        sessionID: SessionID.make("ses_test2"),
-        questions: [
-          {
-            question: "Question 2?",
-            header: "Q2",
-            options: [{ label: "B", description: "B" }],
-          },
-        ],
-      })
+    const fiber2 = yield* askEffect({
+      sessionID: SessionID.make("ses_test2"),
+      questions: [
+        {
+          question: "Question 2?",
+          header: "Q2",
+          options: [{ label: "B", description: "B" }],
+        },
+      ],
+    }).pipe(Effect.forkScoped)
 
-      const pending = await list()
-      expect(pending.length).toBe(2)
-      await rejectAll()
-      p1.catch(() => {})
-      p2.catch(() => {})
-    },
-  })
-})
+    const pending = yield* waitForPending(2)
+    expect(pending.length).toBe(2)
+    yield* rejectAll
+    expect((yield* Fiber.await(fiber1))._tag).toBe("Failure")
+    expect((yield* Fiber.await(fiber2))._tag).toBe("Failure")
+  }),
+  { git: true },
+)
 
-test("list - returns empty when no pending", async () => {
-  await using tmp = await tmpdir({ git: true })
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const pending = await list()
-      expect(pending.length).toBe(0)
-    },
-  })
-})
+it.instance("list - returns empty when no pending", () =>
+  Effect.gen(function* () {
+    const pending = yield* listEffect
+    expect(pending.length).toBe(0)
+  }),
+  { git: true },
+)
 
-test("questions stay isolated by directory", async () => {
-  await using one = await tmpdir({ git: true })
-  await using two = await tmpdir({ git: true })
+it.live("questions stay isolated by directory", () =>
+  Effect.gen(function* () {
+    const one = yield* tmpdirScoped({ git: true })
+    const two = yield* tmpdirScoped({ git: true })
 
-  const p1 = Instance.provide({
-    directory: one.path,
-    fn: () =>
-      ask({
-        sessionID: SessionID.make("ses_one"),
-        questions: [
-          {
-            question: "Question 1?",
-            header: "Q1",
-            options: [{ label: "A", description: "A" }],
-          },
-        ],
-      }),
-  })
+    const fiber1 = yield* askEffect({
+      sessionID: SessionID.make("ses_one"),
+      questions: [
+        {
+          question: "Question 1?",
+          header: "Q1",
+          options: [{ label: "A", description: "A" }],
+        },
+      ],
+    }).pipe(provideInstance(one), Effect.forkScoped)
 
-  const p2 = Instance.provide({
-    directory: two.path,
-    fn: () =>
-      ask({
-        sessionID: SessionID.make("ses_two"),
-        questions: [
-          {
-            question: "Question 2?",
-            header: "Q2",
-            options: [{ label: "B", description: "B" }],
-          },
-        ],
-      }),
-  })
+    const fiber2 = yield* askEffect({
+      sessionID: SessionID.make("ses_two"),
+      questions: [
+        {
+          question: "Question 2?",
+          header: "Q2",
+          options: [{ label: "B", description: "B" }],
+        },
+      ],
+    }).pipe(provideInstance(two), Effect.forkScoped)
 
-  const onePending = await Instance.provide({
-    directory: one.path,
-    fn: () => list(),
-  })
-  const twoPending = await Instance.provide({
-    directory: two.path,
-    fn: () => list(),
-  })
+    const onePending = yield* waitForPending(1).pipe(provideInstance(one))
+    const twoPending = yield* waitForPending(1).pipe(provideInstance(two))
 
-  expect(onePending.length).toBe(1)
-  expect(twoPending.length).toBe(1)
-  expect(onePending[0].sessionID).toBe(SessionID.make("ses_one"))
-  expect(twoPending[0].sessionID).toBe(SessionID.make("ses_two"))
+    expect(onePending.length).toBe(1)
+    expect(twoPending.length).toBe(1)
+    expect(onePending[0].sessionID).toBe(SessionID.make("ses_one"))
+    expect(twoPending[0].sessionID).toBe(SessionID.make("ses_two"))
 
-  await Instance.provide({
-    directory: one.path,
-    fn: () => reject(onePending[0].id),
-  })
-  await Instance.provide({
-    directory: two.path,
-    fn: () => reject(twoPending[0].id),
-  })
+    yield* rejectEffect(onePending[0].id).pipe(provideInstance(one))
+    yield* rejectEffect(twoPending[0].id).pipe(provideInstance(two))
 
-  await p1.catch(() => {})
-  await p2.catch(() => {})
-})
+    expect((yield* Fiber.await(fiber1))._tag).toBe("Failure")
+    expect((yield* Fiber.await(fiber2))._tag).toBe("Failure")
+  }),
+)
 
-test("pending question rejects on instance dispose", async () => {
-  await using tmp = await tmpdir({ git: true })
+it.live("pending question rejects on instance dispose", () =>
+  Effect.gen(function* () {
+    const dir = yield* tmpdirScoped({ git: true })
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_dispose"),
+      questions: [
+        {
+          question: "Dispose me?",
+          header: "Dispose",
+          options: [{ label: "Yes", description: "Yes" }],
+        },
+      ],
+    }).pipe(provideInstance(dir), Effect.forkScoped)
 
-  const pending = Instance.provide({
-    directory: tmp.path,
-    fn: () => {
-      return ask({
-        sessionID: SessionID.make("ses_dispose"),
-        questions: [
-          {
-            question: "Dispose me?",
-            header: "Dispose",
-            options: [{ label: "Yes", description: "Yes" }],
-          },
-        ],
-      })
-    },
-  })
-  const result = pending.then(
-    () => "resolved" as const,
-    (err) => err,
-  )
+    expect(yield* waitForPending(1).pipe(provideInstance(dir))).toHaveLength(1)
+    yield* Effect.promise(() => Instance.provide({ directory: dir, fn: () => void Instance.dispose() }))
 
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const items = await list()
-      expect(items).toHaveLength(1)
-      await Instance.dispose()
-    },
-  })
+    const exit = yield* Fiber.await(fiber)
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) expect(Cause.squash(exit.cause)).toBeInstanceOf(Question.RejectedError)
+  }),
+)
 
-  expect(await result).toBeInstanceOf(Question.RejectedError)
-})
+it.live("pending question rejects on instance reload", () =>
+  Effect.gen(function* () {
+    const dir = yield* tmpdirScoped({ git: true })
+    const fiber = yield* askEffect({
+      sessionID: SessionID.make("ses_reload"),
+      questions: [
+        {
+          question: "Reload me?",
+          header: "Reload",
+          options: [{ label: "Yes", description: "Yes" }],
+        },
+      ],
+    }).pipe(provideInstance(dir), Effect.forkScoped)
 
-test("pending question rejects on instance reload", async () => {
-  await using tmp = await tmpdir({ git: true })
+    expect(yield* waitForPending(1).pipe(provideInstance(dir))).toHaveLength(1)
+    yield* Effect.promise(() => Instance.reload({ directory: dir }))
 
-  const pending = Instance.provide({
-    directory: tmp.path,
-    fn: () => {
-      return ask({
-        sessionID: SessionID.make("ses_reload"),
-        questions: [
-          {
-            question: "Reload me?",
-            header: "Reload",
-            options: [{ label: "Yes", description: "Yes" }],
-          },
-        ],
-      })
-    },
-  })
-  const result = pending.then(
-    () => "resolved" as const,
-    (err) => err,
-  )
-
-  await Instance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const items = await list()
-      expect(items).toHaveLength(1)
-      await Instance.reload({ directory: tmp.path })
-    },
-  })
-
-  expect(await result).toBeInstanceOf(Question.RejectedError)
-})
+    const exit = yield* Fiber.await(fiber)
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) expect(Cause.squash(exit.cause)).toBeInstanceOf(Question.RejectedError)
+  }),
+)

packages/opencode/test/server/global-bus.ts

@@ -0,0 +1,34 @@
+import { GlobalBus, type GlobalEvent } from "@/bus/global"
+import { Cause, Effect } from "effect"
+
+export function waitGlobalBusEvent(input: {
+  timeout?: number
+  message?: string
+  predicate: (event: GlobalEvent) => boolean
+}) {
+  return Effect.callback<GlobalEvent, unknown>((resume) => {
+    const cleanup = () => GlobalBus.off("event", handler)
+
+    const handler = (event: GlobalEvent) => {
+      try {
+        if (!input.predicate(event)) return
+        cleanup()
+        resume(Effect.succeed(event))
+      } catch (error) {
+        cleanup()
+        resume(Effect.fail(error))
+      }
+    }
+
+    GlobalBus.on("event", handler)
+    return Effect.sync(cleanup)
+  }).pipe(
+    Effect.timeout(input.timeout ?? 10_000),
+    Effect.mapError((error) =>
+      Cause.isTimeoutError(error) ? new Error(input.message ?? "timed out waiting for global bus event") : error,
+    ),
+  )
+}
+
+export const waitGlobalBusEventPromise = (input: Parameters<typeof waitGlobalBusEvent>[0]) =>
+  Effect.runPromise(waitGlobalBusEvent(input))

packages/opencode/test/server/httpapi-config.test.ts

@@ -1,12 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import path from "path"
 import { Flag } from "@opencode-ai/core/flag/flag"
-import { GlobalBus } from "@/bus/global"
-import { Instance } from "../../src/project/instance"
 import { Server } from "../../src/server/server"
 import * as Log from "@opencode-ai/core/util/log"
 import { resetDatabase } from "../fixture/db"
 import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import { waitGlobalBusEventPromise } from "./global-bus"
 
 void Log.init({ print: false })
 
@@ -18,20 +17,9 @@ function app() {
 }
 
 async function waitDisposed(directory: string) {
-  return await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      GlobalBus.off("event", onEvent)
-      reject(new Error("timed out waiting for instance disposal"))
-    }, 10_000)
-
-    function onEvent(event: { directory?: string; payload: { type?: string } }) {
-      if (event.payload.type !== "server.instance.disposed" || event.directory !== directory) return
-      clearTimeout(timer)
-      GlobalBus.off("event", onEvent)
-      resolve()
-    }
-
-    GlobalBus.on("event", onEvent)
+  await waitGlobalBusEventPromise({
+    message: "timed out waiting for instance disposal",
+    predicate: (event) => event.payload.type === "server.instance.disposed" && event.directory === directory,
   })
 }
 

packages/opencode/test/server/httpapi-experimental.test.ts

@@ -1,7 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { Flag } from "@opencode-ai/core/flag/flag"
-import { GlobalBus } from "@/bus/global"
 import { Instance } from "../../src/project/instance"
 import { Server } from "../../src/server/server"
 import { ExperimentalPaths } from "../../src/server/routes/instance/httpapi/groups/experimental"
@@ -11,6 +10,7 @@ import * as Log from "@opencode-ai/core/util/log"
 import { Worktree } from "../../src/worktree"
 import { resetDatabase } from "../fixture/db"
 import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import { waitGlobalBusEventPromise } from "./global-bus"
 
 void Log.init({ print: false })
 
@@ -31,20 +31,9 @@ function createSession(input?: Session.CreateInput) {
 }
 
 async function waitReady(directory: string) {
-  return await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      GlobalBus.off("event", onEvent)
-      reject(new Error("timed out waiting for worktree.ready"))
-    }, 10_000)
-
-    function onEvent(event: { directory?: string; payload: { type?: string } }) {
-      if (event.payload.type !== Worktree.Event.Ready.type || event.directory !== directory) return
-      clearTimeout(timer)
-      GlobalBus.off("event", onEvent)
-      resolve()
-    }
-
-    GlobalBus.on("event", onEvent)
+  await waitGlobalBusEventPromise({
+    message: "timed out waiting for worktree.ready",
+    predicate: (event) => event.payload.type === Worktree.Event.Ready.type && event.directory === directory,
   })
 }
 

packages/opencode/test/server/httpapi-instance-context.test.ts

@@ -1,6 +1,5 @@
 import { NodeHttpServer, NodeServices } from "@effect/platform-node"
 import { Flag } from "@opencode-ai/core/flag/flag"
-import { GlobalBus } from "@/bus/global"
 import { describe, expect } from "bun:test"
 import { Effect, Fiber, Layer } from "effect"
 import { HttpClient, HttpClientRequest, HttpRouter, HttpServerResponse } from "effect/unstable/http"
@@ -20,6 +19,7 @@ import { instanceRouterMiddleware } from "../../src/server/routes/instance/httpa
 import { workspaceRouterMiddleware } from "../../src/server/routes/instance/httpapi/middleware/workspace-routing"
 import { resetDatabase } from "../fixture/db"
 import { disposeAllInstances, tmpdirScoped } from "../fixture/fixture"
+import { waitGlobalBusEvent } from "./global-bus"
 import { testEffect } from "../lib/effect"
 
 const testStateLayer = Layer.effectDiscard(
@@ -97,24 +97,10 @@ const serveProbe = (probePath: HttpRouter.PathInput = "/probe") =>
     Layer.build,
   )
 
-const waitDisposedEvent = Effect.promise(
-  () =>
-    new Promise<{ directory?: string; workspace?: string }>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        GlobalBus.off("event", onEvent)
-        reject(new Error("timed out waiting for instance disposal"))
-      }, 10_000)
-
-      function onEvent(event: { directory?: string; workspace?: string; payload: { type?: string } }) {
-        if (event.payload.type !== "server.instance.disposed") return
-        clearTimeout(timer)
-        GlobalBus.off("event", onEvent)
-        resolve({ directory: event.directory, workspace: event.workspace })
-      }
-
-      GlobalBus.on("event", onEvent)
-    }),
-)
+const waitDisposedEvent = waitGlobalBusEvent({
+  message: "timed out waiting for instance disposal",
+  predicate: (event) => event.payload.type === "server.instance.disposed",
+}).pipe(Effect.map((event) => ({ directory: event.directory, workspace: event.workspace })))
 
 const serveDisposeProbe = () =>
   HttpRouter.serve(

packages/opencode/test/server/httpapi-instance.legacy.test.ts

@@ -1,12 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import { Flag } from "@opencode-ai/core/flag/flag"
-import { GlobalBus } from "@/bus/global"
-import { Instance } from "../../src/project/instance"
 import { Server } from "../../src/server/server"
 import { InstancePaths } from "../../src/server/routes/instance/httpapi/groups/instance"
 import * as Log from "@opencode-ai/core/util/log"
 import { resetDatabase } from "../fixture/db"
 import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import { waitGlobalBusEventPromise } from "./global-bus"
 
 void Log.init({ print: false })
 
@@ -18,20 +17,9 @@ function app() {
 }
 
 async function waitDisposed(directory: string) {
-  return await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      GlobalBus.off("event", onEvent)
-      reject(new Error("timed out waiting for instance disposal"))
-    }, 10_000)
-
-    function onEvent(event: { directory?: string; payload: { type?: string } }) {
-      if (event.payload.type !== "server.instance.disposed" || event.directory !== directory) return
-      clearTimeout(timer)
-      GlobalBus.off("event", onEvent)
-      resolve()
-    }
-
-    GlobalBus.on("event", onEvent)
+  await waitGlobalBusEventPromise({
+    message: "timed out waiting for instance disposal",
+    predicate: (event) => event.payload.type === "server.instance.disposed" && event.directory === directory,
   })
 }
 
@@ -117,13 +105,9 @@ describe("instance HttpApi", () => {
   test("serves instance dispose through Hono bridge", async () => {
     await using tmp = await tmpdir()
 
-    const disposed = new Promise<string | undefined>((resolve) => {
-      const onEvent = (event: { directory?: string; payload: { type?: string } }) => {
-        if (event.payload.type !== "server.instance.disposed") return
-        GlobalBus.off("event", onEvent)
-        resolve(event.directory)
-      }
-      GlobalBus.on("event", onEvent)
+    const disposed = waitGlobalBusEventPromise({
+      message: "timed out waiting for instance disposal",
+      predicate: (event) => event.payload.type === "server.instance.disposed",
     })
 
     const response = await app().request(InstancePaths.dispose, {
@@ -133,6 +117,6 @@ describe("instance HttpApi", () => {
 
     expect(response.status).toBe(200)
     expect(await response.json()).toBe(true)
-    expect(await disposed).toBe(tmp.path)
+    expect((await disposed).directory).toBe(tmp.path)
   })
 })

packages/opencode/test/server/httpapi-tui.test.ts

@@ -1,7 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import type { Context } from "hono"
 import { Flag } from "@opencode-ai/core/flag/flag"
-import { GlobalBus } from "../../src/bus/global"
 import { TuiEvent } from "../../src/cli/cmd/tui/event"
 import { SessionID } from "../../src/session/schema"
 import { Instance } from "../../src/project/instance"
@@ -12,6 +11,7 @@ import * as Log from "@opencode-ai/core/util/log"
 import { OpenApi } from "effect/unstable/httpapi"
 import { resetDatabase } from "../fixture/db"
 import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import { waitGlobalBusEventPromise } from "./global-bus"
 
 void Log.init({ print: false })
 
@@ -23,14 +23,9 @@ function app(experimental = true) {
 }
 
 function nextCommandExecute() {
-  return new Promise<unknown>((resolve) => {
-    const listener = (event: { payload: { type?: string; properties?: { command?: unknown } } }) => {
-      if (event.payload.type !== TuiEvent.CommandExecute.type) return
-      GlobalBus.off("event", listener)
-      resolve(event.payload.properties?.command)
-    }
-    GlobalBus.on("event", listener)
-  })
+  return waitGlobalBusEventPromise({
+    predicate: (event) => event.payload.type === TuiEvent.CommandExecute.type,
+  }).then((event) => event.payload.properties?.command)
 }
 
 async function expectTrue(path: string, headers: Record<string, string>, body?: unknown) {

packages/opencode/test/tool/glob.test.ts

@@ -8,7 +8,7 @@ import { Ripgrep } from "../../src/file/ripgrep"
 import { AppFileSystem } from "@opencode-ai/core/filesystem"
 import { Truncate } from "@/tool/truncate"
 import { Agent } from "../../src/agent/agent"
-import { provideTmpdirInstance } from "../fixture/fixture"
+import { TestInstance } from "../fixture/fixture"
 import { testEffect } from "../lib/effect"
 
 const it = testEffect(
@@ -33,49 +33,47 @@ const ctx = {
 }
 
 describe("tool.glob", () => {
-  it.live("matches files from a directory path", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        yield* Effect.promise(() => Bun.write(path.join(dir, "a.ts"), "export const a = 1\n"))
-        yield* Effect.promise(() => Bun.write(path.join(dir, "b.txt"), "hello\n"))
-        const info = yield* GlobTool
-        const glob = yield* info.init()
-        const result = yield* glob.execute(
+  it.instance("matches files from a directory path", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      yield* Effect.promise(() => Bun.write(path.join(test.directory, "a.ts"), "export const a = 1\n"))
+      yield* Effect.promise(() => Bun.write(path.join(test.directory, "b.txt"), "hello\n"))
+      const info = yield* GlobTool
+      const glob = yield* info.init()
+      const result = yield* glob.execute(
+        {
+          pattern: "*.ts",
+          path: test.directory,
+        },
+        ctx,
+      )
+      expect(result.metadata.count).toBe(1)
+      expect(result.output).toContain(path.join(test.directory, "a.ts"))
+      expect(result.output).not.toContain(path.join(test.directory, "b.txt"))
+    }),
+  )
+
+  it.instance("rejects exact file paths", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const file = path.join(test.directory, "a.ts")
+      yield* Effect.promise(() => Bun.write(file, "export const a = 1\n"))
+      const info = yield* GlobTool
+      const glob = yield* info.init()
+      const exit = yield* glob
+        .execute(
           {
             pattern: "*.ts",
-            path: dir,
+            path: file,
           },
           ctx,
         )
-        expect(result.metadata.count).toBe(1)
-        expect(result.output).toContain(path.join(dir, "a.ts"))
-        expect(result.output).not.toContain(path.join(dir, "b.txt"))
-      }),
-    ),
-  )
-
-  it.live("rejects exact file paths", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        const file = path.join(dir, "a.ts")
-        yield* Effect.promise(() => Bun.write(file, "export const a = 1\n"))
-        const info = yield* GlobTool
-        const glob = yield* info.init()
-        const exit = yield* glob
-          .execute(
-            {
-              pattern: "*.ts",
-              path: file,
-            },
-            ctx,
-          )
-          .pipe(Effect.exit)
-        expect(Exit.isFailure(exit)).toBe(true)
-        if (Exit.isFailure(exit)) {
-          const err = Cause.squash(exit.cause)
-          expect(err instanceof Error ? err.message : String(err)).toContain("glob path must be a directory")
-        }
-      }),
-    ),
+        .pipe(Effect.exit)
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const err = Cause.squash(exit.cause)
+        expect(err instanceof Error ? err.message : String(err)).toContain("glob path must be a directory")
+      }
+    }),
   )
 })

packages/opencode/test/tool/grep.test.ts

@@ -2,7 +2,7 @@ import { describe, expect } from "bun:test"
 import path from "path"
 import { Effect, Layer } from "effect"
 import { GrepTool } from "../../src/tool/grep"
-import { provideInstance, provideTmpdirInstance } from "../fixture/fixture"
+import { provideInstance, TestInstance } from "../fixture/fixture"
 import { SessionID, MessageID } from "../../src/session/schema"
 import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
 import { Truncate } from "@/tool/truncate"
@@ -54,61 +54,58 @@ describe("tool.grep", () => {
     }),
   )
 
-  it.live("no matches returns correct output", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        yield* Effect.promise(() => Bun.write(path.join(dir, "test.txt"), "hello world"))
-        const info = yield* GrepTool
-        const grep = yield* info.init()
-        const result = yield* grep.execute(
-          {
-            pattern: "xyznonexistentpatternxyz123",
-            path: dir,
-          },
-          ctx,
-        )
-        expect(result.metadata.matches).toBe(0)
-        expect(result.output).toBe("No files found")
-      }),
-    ),
+  it.instance("no matches returns correct output", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      yield* Effect.promise(() => Bun.write(path.join(test.directory, "test.txt"), "hello world"))
+      const info = yield* GrepTool
+      const grep = yield* info.init()
+      const result = yield* grep.execute(
+        {
+          pattern: "xyznonexistentpatternxyz123",
+          path: test.directory,
+        },
+        ctx,
+      )
+      expect(result.metadata.matches).toBe(0)
+      expect(result.output).toBe("No files found")
+    }),
   )
 
-  it.live("finds matches in tmp instance", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        yield* Effect.promise(() => Bun.write(path.join(dir, "test.txt"), "line1\nline2\nline3"))
-        const info = yield* GrepTool
-        const grep = yield* info.init()
-        const result = yield* grep.execute(
-          {
-            pattern: "line",
-            path: dir,
-          },
-          ctx,
-        )
-        expect(result.metadata.matches).toBeGreaterThan(0)
-      }),
-    ),
+  it.instance("finds matches in tmp instance", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      yield* Effect.promise(() => Bun.write(path.join(test.directory, "test.txt"), "line1\nline2\nline3"))
+      const info = yield* GrepTool
+      const grep = yield* info.init()
+      const result = yield* grep.execute(
+        {
+          pattern: "line",
+          path: test.directory,
+        },
+        ctx,
+      )
+      expect(result.metadata.matches).toBeGreaterThan(0)
+    }),
   )
 
-  it.live("supports exact file paths", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        const file = path.join(dir, "test.txt")
-        yield* Effect.promise(() => Bun.write(file, "line1\nline2\nline3"))
-        const info = yield* GrepTool
-        const grep = yield* info.init()
-        const result = yield* grep.execute(
-          {
-            pattern: "line2",
-            path: file,
-          },
-          ctx,
-        )
-        expect(result.metadata.matches).toBe(1)
-        expect(result.output).toContain(file)
-        expect(result.output).toContain("Line 2: line2")
-      }),
-    ),
+  it.instance("supports exact file paths", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const file = path.join(test.directory, "test.txt")
+      yield* Effect.promise(() => Bun.write(file, "line1\nline2\nline3"))
+      const info = yield* GrepTool
+      const grep = yield* info.init()
+      const result = yield* grep.execute(
+        {
+          pattern: "line2",
+          path: file,
+        },
+        ctx,
+      )
+      expect(result.metadata.matches).toBe(1)
+      expect(result.output).toContain(file)
+      expect(result.output).toContain("Line 2: line2")
+    }),
   )
 })

packages/opencode/test/tool/question.test.ts

@@ -6,7 +6,6 @@ import { SessionID, MessageID } from "../../src/session/schema"
 import { Agent } from "../../src/agent/agent"
 import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
 import { Truncate } from "@/tool/truncate"
-import { provideTmpdirInstance } from "../fixture/fixture"
 import { testEffect } from "../lib/effect"
 
 const ctx = {
@@ -34,56 +33,52 @@ const pending = Effect.fn("QuestionToolTest.pending")(function* (question: Quest
 })
 
 describe("tool.question", () => {
-  it.live("should successfully execute with valid question parameters", () =>
-    provideTmpdirInstance(() =>
-      Effect.gen(function* () {
-        const question = yield* Question.Service
-        const toolInfo = yield* QuestionTool
-        const tool = yield* toolInfo.init()
-        const questions = [
-          {
-            question: "What is your favorite color?",
-            header: "Color",
-            options: [
-              { label: "Red", description: "The color of passion" },
-              { label: "Blue", description: "The color of sky" },
-            ],
-            multiple: false,
-          },
-        ]
+  it.instance("should successfully execute with valid question parameters", () =>
+    Effect.gen(function* () {
+      const question = yield* Question.Service
+      const toolInfo = yield* QuestionTool
+      const tool = yield* toolInfo.init()
+      const questions = [
+        {
+          question: "What is your favorite color?",
+          header: "Color",
+          options: [
+            { label: "Red", description: "The color of passion" },
+            { label: "Blue", description: "The color of sky" },
+          ],
+          multiple: false,
+        },
+      ]
 
-        const fiber = yield* tool.execute({ questions }, ctx).pipe(Effect.forkScoped)
-        const item = yield* pending(question)
-        yield* question.reply({ requestID: item.id, answers: [["Red"]] })
+      const fiber = yield* tool.execute({ questions }, ctx).pipe(Effect.forkScoped)
+      const item = yield* pending(question)
+      yield* question.reply({ requestID: item.id, answers: [["Red"]] })
 
-        const result = yield* Fiber.join(fiber)
-        expect(result.title).toBe("Asked 1 question")
-      }),
-    ),
+      const result = yield* Fiber.join(fiber)
+      expect(result.title).toBe("Asked 1 question")
+    }),
   )
 
-  it.live("should now pass with a header longer than 12 but less than 30 chars", () =>
-    provideTmpdirInstance(() =>
-      Effect.gen(function* () {
-        const question = yield* Question.Service
-        const toolInfo = yield* QuestionTool
-        const tool = yield* toolInfo.init()
-        const questions = [
-          {
-            question: "What is your favorite animal?",
-            header: "This Header is Over 12",
-            options: [{ label: "Dog", description: "Man's best friend" }],
-          },
-        ]
+  it.instance("should now pass with a header longer than 12 but less than 30 chars", () =>
+    Effect.gen(function* () {
+      const question = yield* Question.Service
+      const toolInfo = yield* QuestionTool
+      const tool = yield* toolInfo.init()
+      const questions = [
+        {
+          question: "What is your favorite animal?",
+          header: "This Header is Over 12",
+          options: [{ label: "Dog", description: "Man's best friend" }],
+        },
+      ]
 
-        const fiber = yield* tool.execute({ questions }, ctx).pipe(Effect.forkScoped)
-        const item = yield* pending(question)
-        yield* question.reply({ requestID: item.id, answers: [["Dog"]] })
+      const fiber = yield* tool.execute({ questions }, ctx).pipe(Effect.forkScoped)
+      const item = yield* pending(question)
+      yield* question.reply({ requestID: item.id, answers: [["Dog"]] })
 
-        const result = yield* Fiber.join(fiber)
-        expect(result.output).toContain(`"What is your favorite animal?"="Dog"`)
-      }),
-    ),
+      const result = yield* Fiber.join(fiber)
+      expect(result.output).toContain(`"What is your favorite animal?"="Dog"`)
+    }),
   )
 
   // intentionally removed the zod validation due to tool call errors, hoping prompting is gonna be good enough

packages/opencode/test/tool/registry.test.ts

@@ -2,10 +2,9 @@ import { afterEach, describe, expect } from "bun:test"
 import path from "path"
 import fs from "fs/promises"
 import { Effect, Layer } from "effect"
-import { Instance } from "../../src/project/instance"
 import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
 import { ToolRegistry } from "@/tool/registry"
-import { disposeAllInstances, provideTmpdirInstance } from "../fixture/fixture"
+import { disposeAllInstances, TestInstance } from "../fixture/fixture"
 import { testEffect } from "../lib/effect"
 
 const node = CrossSpawnSpawner.defaultLayer
@@ -17,136 +16,133 @@ afterEach(async () => {
 })
 
 describe("tool.registry", () => {
-  it.live("loads tools from .opencode/tool (singular)", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        const opencode = path.join(dir, ".opencode")
-        const tool = path.join(opencode, "tool")
-        yield* Effect.promise(() => fs.mkdir(tool, { recursive: true }))
-        yield* Effect.promise(() =>
-          Bun.write(
-            path.join(tool, "hello.ts"),
-            [
-              "export default {",
-              "  description: 'hello tool',",
-              "  args: {},",
-              "  execute: async () => {",
-              "    return 'hello world'",
-              "  },",
-              "}",
-              "",
-            ].join("\n"),
-          ),
-        )
-        const registry = yield* ToolRegistry.Service
-        const ids = yield* registry.ids()
-        expect(ids).toContain("hello")
-      }),
-    ),
+  it.instance("loads tools from .opencode/tool (singular)", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const opencode = path.join(test.directory, ".opencode")
+      const tool = path.join(opencode, "tool")
+      yield* Effect.promise(() => fs.mkdir(tool, { recursive: true }))
+      yield* Effect.promise(() =>
+        Bun.write(
+          path.join(tool, "hello.ts"),
+          [
+            "export default {",
+            "  description: 'hello tool',",
+            "  args: {},",
+            "  execute: async () => {",
+            "    return 'hello world'",
+            "  },",
+            "}",
+            "",
+          ].join("\n"),
+        ),
+      )
+      const registry = yield* ToolRegistry.Service
+      const ids = yield* registry.ids()
+      expect(ids).toContain("hello")
+    }),
   )
 
-  it.live("loads tools from .opencode/tools (plural)", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        const opencode = path.join(dir, ".opencode")
-        const tools = path.join(opencode, "tools")
-        yield* Effect.promise(() => fs.mkdir(tools, { recursive: true }))
-        yield* Effect.promise(() =>
-          Bun.write(
-            path.join(tools, "hello.ts"),
-            [
-              "export default {",
-              "  description: 'hello tool',",
-              "  args: {},",
-              "  execute: async () => {",
-              "    return 'hello world'",
-              "  },",
-              "}",
-              "",
-            ].join("\n"),
-          ),
-        )
-        const registry = yield* ToolRegistry.Service
-        const ids = yield* registry.ids()
-        expect(ids).toContain("hello")
-      }),
-    ),
+  it.instance("loads tools from .opencode/tools (plural)", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const opencode = path.join(test.directory, ".opencode")
+      const tools = path.join(opencode, "tools")
+      yield* Effect.promise(() => fs.mkdir(tools, { recursive: true }))
+      yield* Effect.promise(() =>
+        Bun.write(
+          path.join(tools, "hello.ts"),
+          [
+            "export default {",
+            "  description: 'hello tool',",
+            "  args: {},",
+            "  execute: async () => {",
+            "    return 'hello world'",
+            "  },",
+            "}",
+            "",
+          ].join("\n"),
+        ),
+      )
+      const registry = yield* ToolRegistry.Service
+      const ids = yield* registry.ids()
+      expect(ids).toContain("hello")
+    }),
   )
 
-  it.live("loads tools with external dependencies without crashing", () =>
-    provideTmpdirInstance((dir) =>
-      Effect.gen(function* () {
-        const opencode = path.join(dir, ".opencode")
-        const tools = path.join(opencode, "tools")
-        yield* Effect.promise(() => fs.mkdir(tools, { recursive: true }))
-        yield* Effect.promise(() =>
-          Bun.write(
-            path.join(opencode, "package.json"),
-            JSON.stringify({
-              name: "custom-tools",
-              dependencies: {
-                "@opencode-ai/plugin": "^0.0.0",
-                cowsay: "^1.6.0",
-              },
-            }),
-          ),
-        )
-        yield* Effect.promise(() =>
-          Bun.write(
-            path.join(opencode, "package-lock.json"),
-            JSON.stringify({
-              name: "custom-tools",
-              lockfileVersion: 3,
-              packages: {
-                "": {
-                  dependencies: {
-                    "@opencode-ai/plugin": "^0.0.0",
-                    cowsay: "^1.6.0",
-                  },
+  it.instance("loads tools with external dependencies without crashing", () =>
+    Effect.gen(function* () {
+      const test = yield* TestInstance
+      const opencode = path.join(test.directory, ".opencode")
+      const tools = path.join(opencode, "tools")
+      yield* Effect.promise(() => fs.mkdir(tools, { recursive: true }))
+      yield* Effect.promise(() =>
+        Bun.write(
+          path.join(opencode, "package.json"),
+          JSON.stringify({
+            name: "custom-tools",
+            dependencies: {
+              "@opencode-ai/plugin": "^0.0.0",
+              cowsay: "^1.6.0",
+            },
+          }),
+        ),
+      )
+      yield* Effect.promise(() =>
+        Bun.write(
+          path.join(opencode, "package-lock.json"),
+          JSON.stringify({
+            name: "custom-tools",
+            lockfileVersion: 3,
+            packages: {
+              "": {
+                dependencies: {
+                  "@opencode-ai/plugin": "^0.0.0",
+                  cowsay: "^1.6.0",
                 },
               },
-            }),
-          ),
-        )
+            },
+          }),
+        ),
+      )
 
-        const cowsay = path.join(opencode, "node_modules", "cowsay")
-        yield* Effect.promise(() => fs.mkdir(cowsay, { recursive: true }))
-        yield* Effect.promise(() =>
-          Bun.write(
-            path.join(cowsay, "package.json"),
-            JSON.stringify({
-              name: "cowsay",
-              type: "module",
-              exports: "./index.js",
-            }),
-          ),
-        )
-        yield* Effect.promise(() =>
-          Bun.write(
-            path.join(cowsay, "index.js"),
-            ["export function say({ text }) {", "  return `moo ${text}`", "}", ""].join("\n"),
-          ),
-        )
-        yield* Effect.promise(() =>
-          Bun.write(
-            path.join(tools, "cowsay.ts"),
-            [
-              "import { say } from 'cowsay'",
-              "export default {",
-              "  description: 'tool that imports cowsay at top level',",
-              "  args: { text: { type: 'string' } },",
-              "  execute: async ({ text }: { text: string }) => {",
-              "    return say({ text })",
-              "  },",
-              "}",
-              "",
-            ].join("\n"),
-          ),
-        )
-        const registry = yield* ToolRegistry.Service
-        const ids = yield* registry.ids()
-        expect(ids).toContain("cowsay")
-      }),
-    ),
+      const cowsay = path.join(opencode, "node_modules", "cowsay")
+      yield* Effect.promise(() => fs.mkdir(cowsay, { recursive: true }))
+      yield* Effect.promise(() =>
+        Bun.write(
+          path.join(cowsay, "package.json"),
+          JSON.stringify({
+            name: "cowsay",
+            type: "module",
+            exports: "./index.js",
+          }),
+        ),
+      )
+      yield* Effect.promise(() =>
+        Bun.write(
+          path.join(cowsay, "index.js"),
+          ["export function say({ text }) {", "  return `moo ${text}`", "}", ""].join("\n"),
+        ),
+      )
+      yield* Effect.promise(() =>
+        Bun.write(
+          path.join(tools, "cowsay.ts"),
+          [
+            "import { say } from 'cowsay'",
+            "export default {",
+            "  description: 'tool that imports cowsay at top level',",
+            "  args: { text: { type: 'string' } },",
+            "  execute: async ({ text }: { text: string }) => {",
+            "    return say({ text })",
+            "  },",
+            "}",
+            "",
+          ].join("\n"),
+        ),
+      )
+      const registry = yield* ToolRegistry.Service
+      const ids = yield* registry.ids()
+      expect(ids).toContain("cowsay")
+    }),
   )
 })

packages/opencode/test/tool/write.test.ts

@@ -13,7 +13,7 @@ import { Tool } from "@/tool/tool"
 import { Agent } from "../../src/agent/agent"
 import { SessionID, MessageID } from "../../src/session/schema"
 import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
-import { disposeAllInstances, provideTmpdirInstance } from "../fixture/fixture"
+import { disposeAllInstances, provideTmpdirInstance, TestInstance } from "../fixture/fixture"
 import { testEffect } from "../lib/effect"
 
 const ctx = {
@@ -58,42 +58,39 @@ const run = Effect.fn("WriteToolTest.run")(function* (
 
 describe("tool.write", () => {
   describe("new file creation", () => {
-    it.live("writes content to new file", () =>
-      provideTmpdirInstance((dir) =>
-        Effect.gen(function* () {
-          const filepath = path.join(dir, "newfile.txt")
-          const result = yield* run({ filePath: filepath, content: "Hello, World!" })
+    it.instance("writes content to new file", () =>
+      Effect.gen(function* () {
+        const test = yield* TestInstance
+        const filepath = path.join(test.directory, "newfile.txt")
+        const result = yield* run({ filePath: filepath, content: "Hello, World!" })
 
-          expect(result.output).toContain("Wrote file successfully")
-          expect(result.metadata.exists).toBe(false)
+        expect(result.output).toContain("Wrote file successfully")
+        expect(result.metadata.exists).toBe(false)
 
-          const content = yield* Effect.promise(() => fs.readFile(filepath, "utf-8"))
-          expect(content).toBe("Hello, World!")
-        }),
-      ),
+        const content = yield* Effect.promise(() => fs.readFile(filepath, "utf-8"))
+        expect(content).toBe("Hello, World!")
+      }),
     )
 
-    it.live("creates parent directories if needed", () =>
-      provideTmpdirInstance((dir) =>
-        Effect.gen(function* () {
-          const filepath = path.join(dir, "nested", "deep", "file.txt")
-          yield* run({ filePath: filepath, content: "nested content" })
+    it.instance("creates parent directories if needed", () =>
+      Effect.gen(function* () {
+        const test = yield* TestInstance
+        const filepath = path.join(test.directory, "nested", "deep", "file.txt")
+        yield* run({ filePath: filepath, content: "nested content" })
 
-          const content = yield* Effect.promise(() => fs.readFile(filepath, "utf-8"))
-          expect(content).toBe("nested content")
-        }),
-      ),
+        const content = yield* Effect.promise(() => fs.readFile(filepath, "utf-8"))
+        expect(content).toBe("nested content")
+      }),
     )
 
-    it.live("handles relative paths by resolving to instance directory", () =>
-      provideTmpdirInstance((dir) =>
-        Effect.gen(function* () {
-          yield* run({ filePath: "relative.txt", content: "relative content" })
+    it.instance("handles relative paths by resolving to instance directory", () =>
+      Effect.gen(function* () {
+        const test = yield* TestInstance
+        yield* run({ filePath: "relative.txt", content: "relative content" })
 
-          const content = yield* Effect.promise(() => fs.readFile(path.join(dir, "relative.txt"), "utf-8"))
-          expect(content).toBe("relative content")
-        }),
-      ),
+        const content = yield* Effect.promise(() => fs.readFile(path.join(test.directory, "relative.txt"), "utf-8"))
+        expect(content).toBe("relative content")
+      }),
     )
   })