Normalize instance lifecycle wiring (#25501)

Author: kitlangton

packages/opencode/src/cli/bootstrap.ts

@@ -1,8 +1,9 @@
 import { Instance } from "../project/instance"
 import { InstanceRuntime } from "../project/instance-runtime"
+import { WithInstance } from "../project/with-instance"
 
 export async function bootstrap<T>(directory: string, cb: () => Promise<T>) {
-  return Instance.provide({
+  return WithInstance.provide({
     directory,
     fn: async () => {
       try {

packages/opencode/src/cli/cmd/agent.ts

@@ -10,6 +10,7 @@ import fs from "fs/promises"
 import { Filesystem } from "@/util/filesystem"
 import matter from "gray-matter"
 import { Instance } from "../../project/instance"
+import { WithInstance } from "../../project/with-instance"
 import { EOL } from "os"
 import type { Argv } from "yargs"
 
@@ -61,7 +62,7 @@ const AgentCreateCommand = cmd({
         describe: "model to use in the format of provider/model",
       }),
   async handler(args) {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         const cliPath = args.path
@@ -236,7 +237,7 @@ const AgentListCommand = cmd({
   command: "list",
   describe: "list all available agents",
   async handler() {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         const agents = await AppRuntime.runPromise(Agent.Service.use((svc) => svc.list()))

packages/opencode/src/cli/cmd/github.ts

@@ -20,6 +20,7 @@ import { UI } from "../ui"
 import { cmd } from "./cmd"
 import { ModelsDev } from "@/provider/models"
 import { Instance } from "@/project/instance"
+import { WithInstance } from "@/project/with-instance"
 import { bootstrap } from "../bootstrap"
 import { SessionShare } from "@/share/session"
 import { Session } from "@/session/session"
@@ -203,7 +204,7 @@ export const GithubInstallCommand = cmd({
   command: "install",
   describe: "install the GitHub agent",
   async handler() {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         {

packages/opencode/src/cli/cmd/mcp.ts

@@ -10,6 +10,7 @@ import { McpOAuthProvider } from "../../mcp/oauth-provider"
 import { Config } from "@/config/config"
 import { ConfigMCP } from "../../config/mcp"
 import { Instance } from "../../project/instance"
+import { WithInstance } from "../../project/with-instance"
 import { Installation } from "../../installation"
 import { InstallationVersion } from "@opencode-ai/core/installation/version"
 import path from "path"
@@ -114,7 +115,7 @@ export const McpListCommand = cmd({
   aliases: ["ls"],
   describe: "list MCP servers and their status",
   async handler() {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         UI.empty()
@@ -186,7 +187,7 @@ export const McpAuthCommand = cmd({
       })
       .command(McpAuthListCommand),
   async handler(args) {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         UI.empty()
@@ -318,7 +319,7 @@ export const McpAuthListCommand = cmd({
   aliases: ["ls"],
   describe: "list OAuth-capable MCP servers and their auth status",
   async handler() {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         UI.empty()
@@ -357,7 +358,7 @@ export const McpLogoutCommand = cmd({
       type: "string",
     }),
   async handler(args) {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         UI.empty()
@@ -448,7 +449,7 @@ export const McpAddCommand = cmd({
   command: "add",
   describe: "add an MCP server",
   async handler() {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         UI.empty()
@@ -618,7 +619,7 @@ export const McpDebugCommand = cmd({
       demandOption: true,
     }),
   async handler(args) {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         UI.empty()

packages/opencode/src/cli/cmd/providers.ts

@@ -13,7 +13,7 @@ import os from "os"
 import { Config } from "@/config/config"
 import { Global } from "@opencode-ai/core/global"
 import { Plugin } from "../../plugin"
-import { Instance } from "../../project/instance"
+import { WithInstance } from "../../project/with-instance"
 import type { Hooks } from "@opencode-ai/plugin"
 import { Process } from "@/util/process"
 import { text } from "node:stream/consumers"
@@ -303,7 +303,7 @@ export const ProvidersLoginCommand = cmd({
         type: "string",
       }),
   async handler(args) {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: process.cwd(),
       async fn() {
         UI.empty()

packages/opencode/src/cli/cmd/tui/plugin/runtime.ts

@@ -16,7 +16,7 @@ import { TuiConfig } from "@/cli/cmd/tui/config/tui"
 import * as Log from "@opencode-ai/core/util/log"
 import { errorData, errorMessage } from "@/util/error"
 import { isRecord } from "@/util/record"
-import { Instance } from "@/project/instance"
+import { WithInstance } from "@/project/with-instance"
 import {
   readPackageThemes,
   readPluginId,
@@ -790,7 +790,7 @@ async function addPluginBySpec(state: RuntimeState | undefined, raw: string) {
     state.pending.delete(spec)
     return true
   }
-  const ready = await Instance.provide({
+  const ready = await WithInstance.provide({
     directory: state.directory,
     fn: () => resolveExternalPlugins([cfg], () => TuiConfig.waitForDependencies()),
   }).catch((error) => {
@@ -986,7 +986,7 @@ async function load(input: { api: Api; config: TuiConfig.Info }) {
   }
   runtime = next
   try {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: cwd,
       fn: async () => {
         const records = Flag.OPENCODE_PURE ? [] : (config.plugin_origins ?? [])

packages/opencode/src/cli/cmd/tui/worker.ts

@@ -1,8 +1,8 @@
 import { Installation } from "@/installation"
 import { Server } from "@/server/server"
 import * as Log from "@opencode-ai/core/util/log"
-import { Instance } from "@/project/instance"
 import { InstanceRuntime } from "@/project/instance-runtime"
+import { WithInstance } from "@/project/with-instance"
 import { Rpc } from "@/util/rpc"
 import { upgrade } from "@/cli/upgrade"
 import { Config } from "@/config/config"
@@ -77,7 +77,7 @@ export const rpc = {
     return { url: server.url.toString() }
   },
   async checkUpgrade(input: { directory: string }) {
-    await Instance.provide({
+    await WithInstance.provide({
       directory: input.directory,
       fn: async () => {
         await upgrade().catch(() => {})

packages/opencode/src/effect/app-runtime.ts

@@ -40,7 +40,7 @@ import { Command } from "@/command"
 import { Truncate } from "@/tool/truncate"
 import { ToolRegistry } from "@/tool/registry"
 import { Format } from "@/format"
-import { InstanceRuntime } from "@/project/instance-runtime"
+import { InstanceLayer } from "@/project/instance-layer"
 import { Project } from "@/project/project"
 import { Vcs } from "@/project/vcs"
 import { Workspace } from "@/control-plane/workspace"
@@ -93,17 +93,16 @@ export const AppLayer = Layer.mergeAll(
   Truncate.defaultLayer,
   ToolRegistry.defaultLayer,
   Format.defaultLayer,
-  InstanceRuntime.layer,
   Project.defaultLayer,
   Vcs.defaultLayer,
   Workspace.defaultLayer,
-  Worktree.defaultLayer,
+  Worktree.appLayer,
   Pty.defaultLayer,
   Installation.defaultLayer,
   ShareNext.defaultLayer,
   SessionShare.defaultLayer,
   SyncEvent.defaultLayer,
-).pipe(Layer.provideMerge(Observability.layer))
+).pipe(Layer.provideMerge(InstanceLayer.layer), Layer.provideMerge(Observability.layer))
 
 const rt = ManagedRuntime.make(AppLayer, { memoMap })
 type Runtime = Pick<typeof rt, "runSync" | "runPromise" | "runPromiseExit" | "runFork" | "runCallback" | "dispose">

packages/opencode/src/project/instance-layer.ts

@@ -0,0 +1,11 @@
+import { Effect, Layer } from "effect"
+import { InstanceStore } from "./instance-store"
+
+export const layer = Layer.unwrap(
+  Effect.promise(async () => {
+    const { InstanceBootstrap } = await import("./bootstrap")
+    return InstanceStore.defaultLayer.pipe(Layer.provide(InstanceBootstrap.defaultLayer))
+  }),
+)
+
+export * as InstanceLayer from "./instance-layer"

packages/opencode/src/project/instance-runtime.ts

@@ -1,27 +1,16 @@
-import { makeRuntime } from "@/effect/run-service"
+import { AppRuntime } from "@/effect/app-runtime"
 import { type InstanceContext } from "./instance-context"
 import { InstanceStore, type LoadInput } from "./instance-store"
-import { Effect, Layer } from "effect"
 
-// Production InstanceStore wiring plus a bridge for Promise/ALS callers that
-// cannot yet yield InstanceStore.Service. This keeps InstanceStore itself
-// low-level while still giving legacy Hono and CLI paths the production
-// bootstrap implementation. Delete the Promise helpers once those callers are
-// migrated to Effect boundaries that provide InstanceStore directly.
-// Keep the bootstrap implementation import lazy: Instance is imported broadly,
-// and importing the app bootstrap graph at module load can trigger ESM cycles.
-export const layer = Layer.unwrap(
-  Effect.promise(async () => {
-    const { InstanceBootstrap } = await import("./bootstrap")
-    return InstanceStore.defaultLayer.pipe(Layer.provide(InstanceBootstrap.defaultLayer))
-  }),
-)
+// Bridge for Promise/ALS callers that cannot yet yield InstanceStore.Service.
+// Delete this module once those callers are migrated to Effect boundaries that
+// provide InstanceStore directly.
 
-const runtime = makeRuntime(InstanceStore.Service, layer)
-
-export const load = (input: LoadInput) => runtime.runPromise((store) => store.load(input))
-export const disposeInstance = (ctx: InstanceContext) => runtime.runPromise((store) => store.dispose(ctx))
-export const disposeAllInstances = () => runtime.runPromise((store) => store.disposeAll())
-export const reloadInstance = (input: LoadInput) => runtime.runPromise((store) => store.reload(input))
+export const load = (input: LoadInput) => AppRuntime.runPromise(InstanceStore.Service.use((store) => store.load(input)))
+export const disposeInstance = (ctx: InstanceContext) =>
+  AppRuntime.runPromise(InstanceStore.Service.use((store) => store.dispose(ctx)))
+export const disposeAllInstances = () => AppRuntime.runPromise(InstanceStore.Service.use((store) => store.disposeAll()))
+export const reloadInstance = (input: LoadInput) =>
+  AppRuntime.runPromise(InstanceStore.Service.use((store) => store.reload(input)))
 
 export * as InstanceRuntime from "./instance-runtime"