fix(provider): use ProviderID type for pending OAuth map key

- Convert InstanceState to namespace export pattern
- Change pending OAuth state from Record to Map for type-safe lookups

packages/opencode/EFFECT_MIGRATION_PLAN.md

@@ -0,0 +1,399 @@
+# Effect migration
+
+Practical path for adopting Effect in opencode.
+
+## Aim
+
+Move `packages/opencode` toward Effect one domain at a time. Treat the migration as successful when the core path for a domain is Effect-based, even if temporary promise wrappers still exist at the edges.
+
+---
+
+## Decide
+
+Use these defaults unless a domain gives us a good reason not to.
+
+- Migrate one module or domain at a time
+- Preserve compatibility mainly at boundaries, not throughout internals
+- Prefer adapter-layer-first work for mutable or request-scoped systems
+- Treat CLI, server, and jobs as runtime boundaries
+- Use the shared managed runtime only as a bridge during migration
+
+This keeps the work incremental and lets us remove compatibility code later instead of freezing it into every layer.
+
+---
+
+## Slice work
+
+Pick migration units that can own a clear service boundary and a small runtime story.
+
+Good early candidates:
+
+- CRUD-like domains with stable storage and HTTP boundaries
+- Modules that already have a natural service shape
+- Areas where a promise facade can stay temporarily at the public edge
+
+Harder candidates:
+
+- `Instance`-like systems with async local state
+- Request-scoped mutable state
+- Modules that implicitly depend on ambient context or lifecycle ordering
+
+---
+
+## Start at boundaries
+
+Begin by extracting an Effect service behind the existing module boundary. Keep old call sites working by adding a thin promise facade only where needed.
+
+Current example:
+
+- `packages/opencode/src/account/service.ts` holds the Effect-native service
+- `packages/opencode/src/account/index.ts` keeps a promise-facing facade
+- `packages/opencode/src/cli/cmd/account.ts` already uses `AccountService` directly
+- `packages/opencode/src/config/config.ts` and `packages/opencode/src/share/share-next.ts` still use the facade
+
+This is the preferred first move for most domains.
+
+---
+
+## Bridge runtime
+
+Use a shared app runtime only to help mixed code coexist while we migrate. Do not treat it as the final architecture by default.
+
+Current bridge:
+
+- `packages/opencode/src/effect/runtime.ts`
+
+Near-term rule:
+
+- Effect-native entrypoints can run effects directly
+- Legacy promise namespaces can call into the shared runtime
+- New domains should not depend on broad global runtime access unless they are explicitly boundary adapters
+
+As more boundaries become Effect-native, the shared runtime should shrink instead of becoming more central.
+
+---
+
+## Handle state
+
+Treat async local state and mutable contextual systems as adapter problems first. Do not force `Instance`-style behavior directly into pure domain services on the first pass.
+
+Recommended approach:
+
+- Keep current mutable/contextual machinery behind a small adapter
+- Expose a narrower Effect service above that adapter
+- Move ambient reads and writes to the edge of the module
+- Delay deeper context redesign until the boundary is stable
+
+For `Instance`-like code, the first win is usually isolating state access, not eliminating it.
+
+---
+
+## Wrap `Instance`
+
+Keep `Instance` backed by AsyncLocalStorage for now. Do not force a full ALS replacement before we have a clearer service boundary.
+
+- Add an Effect-facing interface over the current ALS-backed implementation first
+- Point new Effect code at that interface
+- Let untouched legacy code keep using raw `Instance`
+
+We may split mutable state from read-only context as the design settles. If that happens, state can migrate on its own path and then depend on the Effect-facing context version instead of raw ALS directly.
+
+**Instance.state** - Most modules use `Instance.state()` for scoped mutable state, so we should not try to replace `Instance` itself too early. Start by wrapping it in an adapter and exposing an Effect service above the current machinery. Over time, state should move onto an Effectful abstraction of our own, with `ScopedCache` as the most likely fit for per-instance state that needs keyed lookup and cleanup. It can stay scoped by the current instance key during transition, usually the directory today, while domains can still add finer keys like `SessionID` inside their own state where needed.
+
+This keeps the first step small, lowers risk, and avoids redesigning request context too early.
+
+---
+
+## Shape APIs
+
+Prefer an Effect-first core and a compatibility shell at the edge.
+
+Guidance:
+
+- Name the service after the domain, like `AccountService`
+- Keep methods small and domain-shaped, not transport-shaped
+- Return `Effect` from the core service
+- Use promise helpers only in legacy namespaces or boundary adapters
+- Keep error types explicit when the domain already has stable error shapes
+
+Small pattern:
+
+```ts
+export class FooService extends ServiceMap.Service<FooService, FooService.Service>()("@opencode/Foo") {
+  static readonly layer = Layer.effect(
+    FooService,
+    Effect.gen(function* () {
+      return FooService.of({
+        get: Effect.fn("FooService.get")(function* (id: FooID) {
+          return yield* ...
+        }),
+      })
+    }),
+  )
+}
+```
+
+Temporary facade pattern:
+
+```ts
+function runPromise<A>(f: (service: FooService.Service) => Effect.Effect<A, FooError>) {
+  return runtime.runPromise(FooService.use(f))
+}
+
+export namespace Foo {
+  export function get(id: FooID) {
+    return runPromise((service) => service.get(id))
+  }
+}
+```
+
+---
+
+## Use Repo carefully
+
+A `Repo` layer is often useful, but it should stay a tool, not a rule.
+
+Tradeoffs:
+
+- `Repo` helps when storage concerns are real and reusable
+- `Repo` can clarify error mapping and persistence boundaries
+- `Repo` can also add ceremony for thin modules or one-step workflows
+
+Current leaning:
+
+- Use a `Repo` when it simplifies storage-heavy domains
+- Skip it when a direct service implementation stays clearer
+- Revisit consistency after a few more migrations, not before
+
+`packages/opencode/src/account/repo.ts` is a reasonable pattern for storage-backed domains, but it should not become mandatory yet.
+
+---
+
+## Test safely
+
+Keep tests stable while internals move. Prefer preserving current test surfaces until a domain has fully crossed its main boundary.
+
+Practical guidance:
+
+- Keep existing promise-based tests passing first
+- Add focused tests for new service behavior where it reduces risk
+- Move boundary tests later, after the internal service shape settles
+- Avoid rewriting test helpers and runtime wiring in the same PR as a domain extraction
+
+This lowers risk and makes the migration easier to review.
+
+---
+
+## Roll out
+
+Use a phased roadmap.
+
+### Phase 0
+
+Set conventions and prove the boundary pattern.
+
+- Keep `account` as the reference example, but not the template for every case
+- Document the temporary runtime bridge and when to use it
+- Prefer one or two more CRUD-like domains next
+
+### Phase 1
+
+Migrate easy and medium domains one at a time.
+
+- Extract service
+- Keep boundary facade if needed
+- Convert one runtime entrypoint to direct Effect use
+- Collapse internal promise plumbing inside the domain
+
+### Phase 2
+
+Tackle context-heavy systems with adapters first.
+
+- Isolate async local state behind Effect-facing adapters
+- Move lifecycle and mutable state reads to runtime edges
+- Convert core domain logic before trying to redesign shared context
+
+### Phase 3
+
+Reduce bridges and compatibility surfaces.
+
+- Remove facades that no longer serve external callers
+- Narrow the shared runtime bridge
+- Standardize remaining service and error shapes where it now feels earned
+
+---
+
+## Check progress
+
+Use these signals to judge whether a domain is really migrated.
+
+A domain is in good shape when:
+
+- Its core logic runs through an Effect service
+- Internal callers prefer the Effect API
+- Compatibility wrappers exist only at real boundaries
+- CLI, server, or job entrypoints can run the Effect path directly
+- The shared runtime is only a temporary connector, not the center of the design
+
+A domain is not done just because it has an Effect service somewhere in the stack.
+
+---
+
+## Candidate ranking
+
+Ranked by feasibility and payoff. Account is already migrated and serves as the reference.
+
+### Tier 1 — Easy wins
+
+| #   | Module         | Lines | Shape                                  | Why                                                                                                |
+| --- | -------------- | ----- | -------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| 1   | **Auth**       | 74    | File CRUD (get/set/remove)             | Zero ambient state, zero deps besides Filesystem. Trivial win to prove the pattern beyond account. |
+| 2   | **Question**   | 168   | ask/reply/reject + Instance.state Map  | Clean service boundary, single pending Map. Nearly identical to Permission but simpler.            |
+| 3   | **Permission** | 210   | ask/respond/list + session-scoped Maps | Pending + approved Maps, already uses branded IDs. Session-scoped state maps to Effect context.    |
+| 4   | **Scheduler**  | 62    | register/unregister tasks with timers  | `Effect.repeat` / `Effect.schedule` is a natural fit. Tiny surface area.                           |
+
+### Tier 2 — Medium complexity, high payoff
+
+| #   | Module           | Lines | Shape                                           | Why                                                                                                       |
+| --- | ---------------- | ----- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| 5   | **Pty**          | 318   | Session lifecycle (create/remove/resize/write)  | Process + subscriber cleanup maps to `Effect.acquireRelease`. Buffer/subscriber state is instance-scoped. |
+| 6   | **Bus**          | 106   | Pub/sub with instance-scoped subscriptions      | Fiber-based subscription cleanup would eliminate manual `off()` patterns throughout the codebase.         |
+| 7   | **Snapshot**     | 417   | Git snapshot/patch/restore                      | Heavy subprocess I/O. Effect error handling and retry would help. No ambient state.                       |
+| 8   | **Worktree**     | 673   | Git worktree create/remove/reset                | Stateless, all subprocess-based. Good `Effect.fn` candidate but larger surface.                           |
+| 9   | **Installation** | 304   | Version check + upgrade across package managers | Multiple fallback paths (npm/brew/choco/scoop). Effect's error channel shines here.                       |
+
+### Tier 3 — Harder, migrate after patterns are settled
+
+| #   | Module   | Lines | Shape                                           | Why                                                                                                                 |
+| --- | -------- | ----- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| 10  | **File** | 655   | File ops with cache state                       | Background fetch side-effects would benefit from Fiber management. Mutable cache (files/dirs Maps) adds complexity. |
+| 11  | **LSP**  | 487   | Client lifecycle: spawning → connected → broken | Effect resource management fits, but multi-state transitions are tricky.                                            |
+| 12  | **MCP**  | 981   | Client lifecycle + OAuth flows                  | Largest single module. OAuth state spans multiple functions (startAuth → finishAuth). High payoff but highest risk. |
+
+### Avoid early
+
+These are too large, too foundational, or too pervasive to migrate without significant prior experience:
+
+- **Provider** (~1400 lines) — provider-specific branching, AI SDK abstractions, complex model selection
+- **Session** (~900 lines) — complex relational queries, branching logic, many dependents
+- **Config** — pervasive dependency across codebase, complex precedence rules
+- **Project / Instance** — foundational bootstrap, async local state, everything depends on it
+
+### Patterns to watch for
+
+**Instance.state** — Most modules use `Instance.state()` for scoped mutable state. Don't try to replace Instance itself early; wrap it in an adapter that exposes an Effect service above the existing machinery.
+
+**Bus.subscribe + manual off()** — Pervasive throughout the codebase. Migrating Bus (candidate #6) unlocks Fiber-based cleanup everywhere, but it's infrastructure, not a domain win. Consider it after a few domain migrations prove the pattern.
+
+**Database.use / Database.transaction** — Already resembles Effect context (provide/use pattern). Could become an Effect Layer, but this is infrastructure work best deferred until multiple domains are Effect-native.
+
+**Process subprocess patterns** — Snapshot, Worktree, Installation all shell out to git or package managers. These are natural `Effect.tryPromise` / `Effect.fn` targets with error mapping.
+
+---
+
+## Effect modules to use
+
+Effect already provides battle-tested replacements for several homegrown patterns. Prefer these over custom code as domains migrate.
+
+### PubSub → replaces Bus
+
+`PubSub` provides bounded/unbounded pub/sub with backpressure strategies. Subscriptions are scoped — cleanup is automatic when the subscriber's Scope closes, eliminating every manual `off()` call.
+
+```ts
+const pubsub = yield * PubSub.unbounded<Event>()
+yield * PubSub.publish(pubsub, event)
+// subscriber — automatically cleaned up when scope ends
+const dequeue = yield * PubSub.subscribe(pubsub)
+const event = yield * Queue.take(dequeue)
+```
+
+Don't migrate Bus first. Migrate domain modules, then swap Bus once there are enough Effect-native consumers.
+
+### Schedule → replaces Scheduler
+
+The custom 62-line Scheduler reinvents `Effect.repeat`. Effect's `Schedule` is composable and supports spaced intervals, exponential backoff, cron expressions, and more.
+
+```ts
+yield * effect.pipe(Effect.repeat(Schedule.spaced("30 seconds")))
+```
+
+### SubscriptionRef → replaces state + Bus.publish on mutation
+
+Several modules follow the pattern: mutate `Instance.state`, then `Bus.publish` to notify listeners. `SubscriptionRef` is a `Ref` that emits changes as a `Stream`, combining both in one primitive.
+
+```ts
+const ref = yield * SubscriptionRef.make(initialState)
+// writer
+yield * SubscriptionRef.update(ref, (s) => ({ ...s, count: s.count + 1 }))
+// reader — stream of every state change
+yield * SubscriptionRef.changes(ref).pipe(Stream.runForEach(handleUpdate))
+```
+
+### Ref / SynchronizedRef → replaces Instance.state Maps
+
+`Ref<A>` provides atomic read/write/update for concurrent-safe state. `SynchronizedRef` adds mutual exclusion for complex multi-step updates. Use these inside Effect services instead of raw mutable Maps.
+
+### Scope + acquireRelease → replaces manual resource cleanup
+
+Pty sessions, LSP clients, and MCP clients all have manual try/finally cleanup. `Effect.acquireRelease` ties resource lifecycle to Scope, making cleanup declarative and leak-proof.
+
+```ts
+const pty = yield * Effect.acquireRelease(createPty(options), (session) => destroyPty(session))
+```
+
+### ChildProcess → replaces shell-outs
+
+Effect's `ChildProcess` provides type-safe subprocess execution with template literals and stream-based stdout/stderr. Useful for Snapshot, Worktree, and Installation modules.
+
+```ts
+const result = yield * ChildProcess.make`git diff --stat`.pipe(ChildProcess.spawn, ChildProcess.string)
+```
+
+Note: in `effect/unstable/process` — API may shift.
+
+### FileSystem → replaces custom Filesystem utils
+
+Cross-platform file I/O with stream support. Available via `effect/FileSystem` with a `NodeFileSystem` layer.
+
+### KeyValueStore → replaces file-based Auth JSON
+
+Abstracted key-value storage with file, memory, and browser backends. Auth's 74-line file CRUD could become a one-liner with `KeyValueStore`.
+
+Available via `effect/unstable/persistence` — API may shift.
+
+### HttpClient → replaces custom fetch calls
+
+Full HTTP client with typed errors, request builders, and platform-aware layers. Useful when migrating Share and ControlPlane modules.
+
+Available via `effect/unstable/http` — API may shift.
+
+### HttpApi → replaces Hono
+
+Effect's `HttpApi` provides schema-driven HTTP APIs with OpenAPI generation, type-safe routing, and middleware. Long-term candidate to replace the Hono server layer entirely. This is a larger lift — defer until multiple domain services are Effect-native and the boundary pattern is well-proven.
+
+Available via `effect/unstable/httpapi` — API may shift.
+
+### Schema → replaces Zod (partially)
+
+Effect's `Schema` provides encoding/decoding, validation, and type derivation deeply integrated with Effect. Internal code can migrate to Schema as domains move to Effect services. However, the plugin API (`@opencode-ai/plugin`) uses Zod and must continue to accept Zod schemas at the boundary. Keep Zod-to-Schema bridges at plugin/SDK edges.
+
+### Cache → replaces manual caching
+
+The File module maintains mutable Maps (files/dirs) with a fetching flag for deduplication. `Cache` provides memoization with TTL and automatic deduplication, replacing this pattern.
+
+### Pool → for resource-heavy clients
+
+LSP client management (spawning/connected/broken state machine) could benefit from `Pool` for automatic acquisition, health checking, and release.
+
+---
+
+## Follow next
+
+Recommended medium-term order:
+
+1. Continue with CRUD-like or storage-backed modules
+2. Convert boundary entrypoints in CLI, server, and jobs as services become available
+3. Move into `Instance`-adjacent systems with adapter layers, not direct rewrites
+4. Remove promise facades after direct callers have moved
+
+This keeps momentum while reserving the hardest context work for when the team has a clearer house style.

packages/opencode/src/auth/index.ts

@@ -1,73 +1,41 @@
-import path from "path"
-import { Global } from "../global"
-import z from "zod"
-import { Filesystem } from "../util/filesystem"
+import { Effect } from "effect"
+import { runtime } from "@/effect/runtime"
+import {
+  Api as ApiSchema,
+  AuthService,
+  type AuthServiceError,
+  Info as InfoSchema,
+  Oauth as OauthSchema,
+  WellKnown as WellKnownSchema,
+  type Info as AuthInfo,
+} from "./service"
 
-export const OAUTH_DUMMY_KEY = "opencode-oauth-dummy-key"
+export { OAUTH_DUMMY_KEY } from "./service"
+
+function runPromise<A>(f: (service: AuthService.Service) => Effect.Effect<A, AuthServiceError>) {
+  return runtime.runPromise(AuthService.use(f))
+}
 
 export namespace Auth {
-  export const Oauth = z
-    .object({
-      type: z.literal("oauth"),
-      refresh: z.string(),
-      access: z.string(),
-      expires: z.number(),
-      accountId: z.string().optional(),
-      enterpriseUrl: z.string().optional(),
-    })
-    .meta({ ref: "OAuth" })
-
-  export const Api = z
-    .object({
-      type: z.literal("api"),
-      key: z.string(),
-    })
-    .meta({ ref: "ApiAuth" })
-
-  export const WellKnown = z
-    .object({
-      type: z.literal("wellknown"),
-      key: z.string(),
-      token: z.string(),
-    })
-    .meta({ ref: "WellKnownAuth" })
-
-  export const Info = z.discriminatedUnion("type", [Oauth, Api, WellKnown]).meta({ ref: "Auth" })
-  export type Info = z.infer<typeof Info>
-
-  const filepath = path.join(Global.Path.data, "auth.json")
+  export const Oauth = OauthSchema
+  export const Api = ApiSchema
+  export const WellKnown = WellKnownSchema
+  export const Info = InfoSchema
+  export type Info = AuthInfo
 
   export async function get(providerID: string) {
-    const auth = await all()
-    return auth[providerID]
+    return runPromise((service) => service.get(providerID))
   }
 
   export async function all(): Promise<Record<string, Info>> {
-    const data = await Filesystem.readJson<Record<string, unknown>>(filepath).catch(() => ({}))
-    return Object.entries(data).reduce(
-      (acc, [key, value]) => {
-        const parsed = Info.safeParse(value)
-        if (!parsed.success) return acc
-        acc[key] = parsed.data
-        return acc
-      },
-      {} as Record<string, Info>,
-    )
+    return runPromise((service) => service.all())
   }
 
   export async function set(key: string, info: Info) {
-    const normalized = key.replace(/\/+$/, "")
-    const data = await all()
-    if (normalized !== key) delete data[key]
-    delete data[normalized + "/"]
-    await Filesystem.writeJson(filepath, { ...data, [normalized]: info }, 0o600)
+    return runPromise((service) => service.set(key, info))
   }
 
   export async function remove(key: string) {
-    const normalized = key.replace(/\/+$/, "")
-    const data = await all()
-    delete data[key]
-    delete data[normalized]
-    await Filesystem.writeJson(filepath, data, 0o600)
+    return runPromise((service) => service.remove(key))
   }
 }

packages/opencode/src/auth/service.ts

@@ -0,0 +1,114 @@
+import path from "path"
+import { Effect, Layer, Schema, ServiceMap } from "effect"
+import z from "zod"
+import { Global } from "../global"
+import { Filesystem } from "../util/filesystem"
+
+export const OAUTH_DUMMY_KEY = "opencode-oauth-dummy-key"
+
+export const Oauth = z
+  .object({
+    type: z.literal("oauth"),
+    refresh: z.string(),
+    access: z.string(),
+    expires: z.number(),
+    accountId: z.string().optional(),
+    enterpriseUrl: z.string().optional(),
+  })
+  .meta({ ref: "OAuth" })
+
+export const Api = z
+  .object({
+    type: z.literal("api"),
+    key: z.string(),
+  })
+  .meta({ ref: "ApiAuth" })
+
+export const WellKnown = z
+  .object({
+    type: z.literal("wellknown"),
+    key: z.string(),
+    token: z.string(),
+  })
+  .meta({ ref: "WellKnownAuth" })
+
+export const Info = z.discriminatedUnion("type", [Oauth, Api, WellKnown]).meta({ ref: "Auth" })
+export type Info = z.infer<typeof Info>
+
+export class AuthServiceError extends Schema.TaggedErrorClass<AuthServiceError>()("AuthServiceError", {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+const file = path.join(Global.Path.data, "auth.json")
+
+const fail = (message: string) => (cause: unknown) => new AuthServiceError({ message, cause })
+
+export namespace AuthService {
+  export interface Service {
+    readonly get: (providerID: string) => Effect.Effect<Info | undefined, AuthServiceError>
+    readonly all: () => Effect.Effect<Record<string, Info>, AuthServiceError>
+    readonly set: (key: string, info: Info) => Effect.Effect<void, AuthServiceError>
+    readonly remove: (key: string) => Effect.Effect<void, AuthServiceError>
+  }
+}
+
+export class AuthService extends ServiceMap.Service<AuthService, AuthService.Service>()("@opencode/Auth") {
+  static readonly layer = Layer.effect(
+    AuthService,
+    Effect.gen(function* () {
+      const all = Effect.fn("AuthService.all")(() =>
+        Effect.tryPromise({
+          try: async () => {
+            const data = await Filesystem.readJson<Record<string, unknown>>(file).catch(() => ({}))
+            return Object.entries(data).reduce(
+              (acc, [key, value]) => {
+                const parsed = Info.safeParse(value)
+                if (!parsed.success) return acc
+                acc[key] = parsed.data
+                return acc
+              },
+              {} as Record<string, Info>,
+            )
+          },
+          catch: fail("Failed to read auth data"),
+        }),
+      )
+
+      const get = Effect.fn("AuthService.get")(function* (providerID: string) {
+        return (yield* all())[providerID]
+      })
+
+      const set = Effect.fn("AuthService.set")(function* (key: string, info: Info) {
+        const norm = key.replace(/\/+$/, "")
+        const data = yield* all()
+        if (norm !== key) delete data[key]
+        delete data[norm + "/"]
+        yield* Effect.tryPromise({
+          try: () => Filesystem.writeJson(file, { ...data, [norm]: info }, 0o600),
+          catch: fail("Failed to write auth data"),
+        })
+      })
+
+      const remove = Effect.fn("AuthService.remove")(function* (key: string) {
+        const norm = key.replace(/\/+$/, "")
+        const data = yield* all()
+        delete data[key]
+        delete data[norm]
+        yield* Effect.tryPromise({
+          try: () => Filesystem.writeJson(file, data, 0o600),
+          catch: fail("Failed to write auth data"),
+        })
+      })
+
+      return AuthService.of({
+        get,
+        all,
+        set,
+        remove,
+      })
+    }),
+  )
+
+  static readonly defaultLayer = AuthService.layer
+}

packages/opencode/src/effect/runtime.ts

@@ -1,4 +1,5 @@
-import { ManagedRuntime } from "effect"
+import { Layer, ManagedRuntime } from "effect"
 import { AccountService } from "@/account/service"
+import { AuthService } from "@/auth/service"
 
-export const runtime = ManagedRuntime.make(AccountService.defaultLayer)
+export const runtime = ManagedRuntime.make(Layer.mergeAll(AccountService.defaultLayer, AuthService.defaultLayer))

packages/opencode/src/project/instance.ts

@@ -1,3 +1,4 @@
+import { Effect } from "effect"
 import { Log } from "@/util/log"
 import { Context } from "../util/context"
 import { Project } from "./project"
@@ -5,6 +6,7 @@ import { State } from "./state"
 import { iife } from "@/util/iife"
 import { GlobalBus } from "@/bus/global"
 import { Filesystem } from "@/util/filesystem"
+import { InstanceState } from "@/util/instance-state"
 
 interface Context {
   directory: string
@@ -106,7 +108,7 @@ export const Instance = {
   async reload(input: { directory: string; init?: () => Promise<any>; project?: Project.Info; worktree?: string }) {
     const directory = Filesystem.resolve(input.directory)
     Log.Default.info("reloading instance", { directory })
-    await State.dispose(directory)
+    await Promise.all([State.dispose(directory), Effect.runPromise(InstanceState.dispose(directory))])
     cache.delete(directory)
     const next = track(directory, boot({ ...input, directory }))
     emit(directory)
@@ -114,7 +116,7 @@ export const Instance = {
   },
   async dispose() {
     Log.Default.info("disposing instance", { directory: Instance.directory })
-    await State.dispose(Instance.directory)
+    await Promise.all([State.dispose(Instance.directory), Effect.runPromise(InstanceState.dispose(Instance.directory))])
     cache.delete(Instance.directory)
     emit(Instance.directory)
   },

packages/opencode/src/provider/auth-service.ts

@@ -0,0 +1,160 @@
+import { Effect, Layer, Record, ServiceMap, Struct } from "effect"
+import { Instance } from "@/project/instance"
+import { Plugin } from "../plugin"
+import { filter, fromEntries, map, pipe } from "remeda"
+import type { AuthOuathResult } from "@opencode-ai/plugin"
+import { NamedError } from "@opencode-ai/util/error"
+import * as Auth from "@/auth/service"
+import { InstanceState } from "@/util/instance-state"
+import { ProviderID } from "./schema"
+import z from "zod"
+
+export type Method = {
+  type: "oauth" | "api"
+  label: string
+}
+
+export type Authorization = {
+  url: string
+  method: "auto" | "code"
+  instructions: string
+}
+
+export const OauthMissing = NamedError.create(
+  "ProviderAuthOauthMissing",
+  z.object({
+    providerID: ProviderID.zod,
+  }),
+)
+
+export const OauthCodeMissing = NamedError.create(
+  "ProviderAuthOauthCodeMissing",
+  z.object({
+    providerID: ProviderID.zod,
+  }),
+)
+
+export const OauthCallbackFailed = NamedError.create("ProviderAuthOauthCallbackFailed", z.object({}))
+
+export type ProviderAuthError =
+  | Auth.AuthServiceError
+  | InstanceType<typeof OauthMissing>
+  | InstanceType<typeof OauthCodeMissing>
+  | InstanceType<typeof OauthCallbackFailed>
+
+export namespace ProviderAuthService {
+  export interface Service {
+    /** Get available auth methods for each provider (e.g. OAuth, API key). */
+    readonly methods: () => Effect.Effect<Record<string, Method[]>>
+
+    /** Start an OAuth authorization flow for a provider. Returns the URL to redirect to. */
+    readonly authorize: (input: { providerID: ProviderID; method: number }) => Effect.Effect<Authorization | undefined>
+
+    /** Complete an OAuth flow after the user has authorized. Exchanges the code/callback for credentials. */
+    readonly callback: (input: {
+      providerID: ProviderID
+      method: number
+      code?: string
+    }) => Effect.Effect<void, ProviderAuthError>
+
+    /** Set an API key directly for a provider (no OAuth flow). */
+    readonly api: (input: { providerID: ProviderID; key: string }) => Effect.Effect<void, Auth.AuthServiceError>
+  }
+}
+
+export class ProviderAuthService extends ServiceMap.Service<ProviderAuthService, ProviderAuthService.Service>()(
+  "@opencode/ProviderAuth",
+) {
+  static readonly layer = Layer.effect(
+    ProviderAuthService,
+    Effect.gen(function* () {
+      const auth = yield* Auth.AuthService
+      const state = yield* InstanceState.make({
+        lookup: () =>
+          Effect.promise(async () => {
+            const methods = pipe(
+              await Plugin.list(),
+              filter((x) => x.auth?.provider !== undefined),
+              map((x) => [x.auth!.provider, x.auth!] as const),
+              fromEntries(),
+            )
+            return { methods, pending: new Map<ProviderID, AuthOuathResult>() }
+          }),
+      })
+
+      const methods = Effect.fn("ProviderAuthService.methods")(function* () {
+        const x = yield* InstanceState.get(state)
+        return Record.map(x.methods, (y) => y.methods.map((z): Method => Struct.pick(z, ["type", "label"])))
+      })
+
+      const authorize = Effect.fn("ProviderAuthService.authorize")(function* (input: {
+        providerID: ProviderID
+        method: number
+      }) {
+        const authHook = (yield* InstanceState.get(state)).methods[input.providerID]
+        const method = authHook.methods[input.method]
+        if (method.type !== "oauth") return
+        const result = yield* Effect.promise(() => method.authorize())
+
+        const s = yield* InstanceState.get(state)
+        s.pending.set(input.providerID, result)
+        return {
+          url: result.url,
+          method: result.method,
+          instructions: result.instructions,
+        }
+      })
+
+      const callback = Effect.fn("ProviderAuthService.callback")(function* (input: {
+        providerID: ProviderID
+        method: number
+        code?: string
+      }) {
+        const match = (yield* InstanceState.get(state)).pending.get(input.providerID)
+        if (!match) return yield* Effect.fail(new OauthMissing({ providerID: input.providerID }))
+
+        if (match.method === "code" && !input.code)
+          return yield* Effect.fail(new OauthCodeMissing({ providerID: input.providerID }))
+
+        const result = yield* Effect.promise(() =>
+          match.method === "code" ? match.callback(input.code!) : match.callback(),
+        )
+
+        if (!result || result.type !== "success") return yield* Effect.fail(new OauthCallbackFailed({}))
+
+        if ("key" in result) {
+          yield* auth.set(input.providerID, {
+            type: "api",
+            key: result.key,
+          })
+        }
+
+        if ("refresh" in result) {
+          yield* auth.set(input.providerID, {
+            type: "oauth",
+            access: result.access,
+            refresh: result.refresh,
+            expires: result.expires,
+            ...(result.accountId ? { accountId: result.accountId } : {}),
+          })
+        }
+      })
+
+      const api = Effect.fn("ProviderAuthService.api")(function* (input: { providerID: ProviderID; key: string }) {
+        yield* auth.set(input.providerID, {
+          type: "api",
+          key: input.key,
+        })
+      })
+
+      return ProviderAuthService.of({
+        methods,
+        authorize,
+        callback,
+        api,
+      })
+    }),
+  )
+
+  static readonly defaultLayer = ProviderAuthService.layer.pipe(Layer.provide(Auth.AuthService.defaultLayer))
+}

packages/opencode/src/provider/auth.ts

@@ -1,24 +1,20 @@
-import { Instance } from "@/project/instance"
-import { Plugin } from "../plugin"
-import { map, filter, pipe, fromEntries, mapValues } from "remeda"
+import { Effect, ManagedRuntime } from "effect"
 import z from "zod"
+
 import { fn } from "@/util/fn"
-import type { AuthOuathResult, Hooks } from "@opencode-ai/plugin"
-import { NamedError } from "@opencode-ai/util/error"
-import { Auth } from "@/auth"
+import * as S from "./auth-service"
 import { ProviderID } from "./schema"
 
-export namespace ProviderAuth {
-  const state = Instance.state(async () => {
-    const methods = pipe(
-      await Plugin.list(),
-      filter((x) => x.auth?.provider !== undefined),
-      map((x) => [x.auth!.provider, x.auth!] as const),
-      fromEntries(),
-    )
-    return { methods, pending: {} as Record<string, AuthOuathResult> }
-  })
+// Separate runtime: ProviderAuthService can't join the shared runtime because
+// runtime.ts → auth-service.ts → provider/auth.ts creates a circular import.
+// AuthService is stateless file I/O so the duplicate instance is harmless.
+const rt = ManagedRuntime.make(S.ProviderAuthService.defaultLayer)
 
+function runPromise<A>(f: (service: S.ProviderAuthService.Service) => Effect.Effect<A, S.ProviderAuthError>) {
+  return rt.runPromise(S.ProviderAuthService.use(f))
+}
+
+export namespace ProviderAuth {
   export const Method = z
     .object({
       type: z.union([z.literal("oauth"), z.literal("api")]),
@@ -30,15 +26,7 @@ export namespace ProviderAuth {
   export type Method = z.infer<typeof Method>
 
   export async function methods() {
-    const s = await state().then((x) => x.methods)
-    return mapValues(s, (x) =>
-      x.methods.map(
-        (y): Method => ({
-          type: y.type,
-          label: y.label,
-        }),
-      ),
-    )
+    return runPromise((service) => service.methods())
   }
 
   export const Authorization = z
@@ -57,19 +45,7 @@ export namespace ProviderAuth {
       providerID: ProviderID.zod,
       method: z.number(),
     }),
-    async (input): Promise<Authorization | undefined> => {
-      const auth = await state().then((s) => s.methods[input.providerID])
-      const method = auth.methods[input.method]
-      if (method.type === "oauth") {
-        const result = await method.authorize()
-        await state().then((s) => (s.pending[input.providerID] = result))
-        return {
-          url: result.url,
-          method: result.method,
-          instructions: result.instructions,
-        }
-      }
-    },
+    async (input): Promise<Authorization | undefined> => runPromise((service) => service.authorize(input)),
   )
 
   export const callback = fn(
@@ -78,44 +54,7 @@ export namespace ProviderAuth {
       method: z.number(),
       code: z.string().optional(),
     }),
-    async (input) => {
-      const match = await state().then((s) => s.pending[input.providerID])
-      if (!match) throw new OauthMissing({ providerID: input.providerID })
-      let result
-
-      if (match.method === "code") {
-        if (!input.code) throw new OauthCodeMissing({ providerID: input.providerID })
-        result = await match.callback(input.code)
-      }
-
-      if (match.method === "auto") {
-        result = await match.callback()
-      }
-
-      if (result?.type === "success") {
-        if ("key" in result) {
-          await Auth.set(input.providerID, {
-            type: "api",
-            key: result.key,
-          })
-        }
-        if ("refresh" in result) {
-          const info: Auth.Info = {
-            type: "oauth",
-            access: result.access,
-            refresh: result.refresh,
-            expires: result.expires,
-          }
-          if (result.accountId) {
-            info.accountId = result.accountId
-          }
-          await Auth.set(input.providerID, info)
-        }
-        return
-      }
-
-      throw new OauthCallbackFailed({})
-    },
+    async (input) => runPromise((service) => service.callback(input)),
   )
 
   export const api = fn(
@@ -123,26 +62,10 @@ export namespace ProviderAuth {
       providerID: ProviderID.zod,
       key: z.string(),
     }),
-    async (input) => {
-      await Auth.set(input.providerID, {
-        type: "api",
-        key: input.key,
-      })
-    },
+    async (input) => runPromise((service) => service.api(input)),
   )
 
-  export const OauthMissing = NamedError.create(
-    "ProviderAuthOauthMissing",
-    z.object({
-      providerID: ProviderID.zod,
-    }),
-  )
-  export const OauthCodeMissing = NamedError.create(
-    "ProviderAuthOauthCodeMissing",
-    z.object({
-      providerID: ProviderID.zod,
-    }),
-  )
-
-  export const OauthCallbackFailed = NamedError.create("ProviderAuthOauthCallbackFailed", z.object({}))
+  export import OauthMissing = S.OauthMissing
+  export import OauthCodeMissing = S.OauthCodeMissing
+  export import OauthCallbackFailed = S.OauthCallbackFailed
 }

packages/opencode/src/util/instance-state.ts

@@ -0,0 +1,50 @@
+import { Effect, ScopedCache, Scope } from "effect"
+
+import { Instance } from "@/project/instance"
+
+const TypeId = Symbol.for("@opencode/InstanceState")
+
+type Task = (key: string) => Effect.Effect<void>
+
+const tasks = new Set<Task>()
+
+export namespace InstanceState {
+  export interface State<A, E = never, R = never> {
+    readonly [TypeId]: typeof TypeId
+    readonly cache: ScopedCache.ScopedCache<string, A, E, R>
+  }
+
+  export const make = <A, E = never, R = never>(input: {
+    lookup: (key: string) => Effect.Effect<A, E, R>
+    release?: (value: A, key: string) => Effect.Effect<void>
+  }): Effect.Effect<State<A, E, R>, never, R | Scope.Scope> =>
+    Effect.gen(function* () {
+      const cache = yield* ScopedCache.make<string, A, E, R>({
+        capacity: Number.POSITIVE_INFINITY,
+        lookup: (key) =>
+          Effect.acquireRelease(input.lookup(key), (value) => (input.release ? input.release(value, key) : Effect.void)),
+      })
+
+      const task: Task = (key) => ScopedCache.invalidate(cache, key)
+      tasks.add(task)
+      yield* Effect.addFinalizer(() => Effect.sync(() => void tasks.delete(task)))
+
+      return {
+        [TypeId]: TypeId,
+        cache,
+      }
+    })
+
+  export const get = <A, E, R>(self: State<A, E, R>) => ScopedCache.get(self.cache, Instance.directory)
+
+  export const has = <A, E, R>(self: State<A, E, R>) => ScopedCache.has(self.cache, Instance.directory)
+
+  export const invalidate = <A, E, R>(self: State<A, E, R>) =>
+    ScopedCache.invalidate(self.cache, Instance.directory)
+
+  export const dispose = (key: string) =>
+    Effect.all(
+      [...tasks].map((task) => task(key)),
+      { concurrency: "unbounded" },
+    )
+}

packages/opencode/test/project/state.test.ts

@@ -0,0 +1,87 @@
+import { expect, test } from "bun:test"
+
+import { State } from "../../src/project/state"
+
+test("State.create caches values for the same key", async () => {
+  let key = "a"
+  let n = 0
+  const state = State.create(
+    () => key,
+    () => ({ n: ++n }),
+  )
+
+  const a = state()
+  const b = state()
+
+  expect(a).toBe(b)
+  expect(n).toBe(1)
+
+  await State.dispose("a")
+})
+
+test("State.create isolates values by key", async () => {
+  let key = "a"
+  let n = 0
+  const state = State.create(
+    () => key,
+    () => ({ n: ++n }),
+  )
+
+  const a = state()
+  key = "b"
+  const b = state()
+  key = "a"
+  const c = state()
+
+  expect(a).toBe(c)
+  expect(a).not.toBe(b)
+  expect(n).toBe(2)
+
+  await State.dispose("a")
+  await State.dispose("b")
+})
+
+test("State.dispose clears a key and runs cleanup", async () => {
+  const seen: string[] = []
+  let key = "a"
+  let n = 0
+  const state = State.create(
+    () => key,
+    () => ({ n: ++n }),
+    async (value) => {
+      seen.push(String(value.n))
+    },
+  )
+
+  const a = state()
+  await State.dispose("a")
+  const b = state()
+
+  expect(a).not.toBe(b)
+  expect(seen).toEqual(["1"])
+
+  await State.dispose("a")
+})
+
+test("State.create dedupes concurrent promise initialization", async () => {
+  const gate = Promise.withResolvers<void>()
+  let n = 0
+  const state = State.create(
+    () => "a",
+    async () => {
+      n += 1
+      await gate.promise
+      return { n }
+    },
+  )
+
+  const task = Promise.all([state(), state()])
+  await Promise.resolve()
+  expect(n).toBe(1)
+
+  gate.resolve()
+  const [a, b] = await task
+  expect(a).toBe(b)
+
+  await State.dispose("a")
+})

packages/opencode/test/provider/auth.test.ts

@@ -0,0 +1,20 @@
+import { afterEach, expect, test } from "bun:test"
+import { Auth } from "../../src/auth"
+import { ProviderAuth } from "../../src/provider/auth"
+import { ProviderID } from "../../src/provider/schema"
+
+afterEach(async () => {
+  await Auth.remove("test-provider-auth")
+})
+
+test("ProviderAuth.api persists auth via AuthService", async () => {
+  await ProviderAuth.api({
+    providerID: ProviderID.make("test-provider-auth"),
+    key: "sk-test",
+  })
+
+  expect(await Auth.get("test-provider-auth")).toEqual({
+    type: "api",
+    key: "sk-test",
+  })
+})

packages/opencode/test/util/instance-state.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, expect, test } from "bun:test"
+import { Effect } from "effect"
+
+import { Instance } from "../../src/project/instance"
+import { InstanceState } from "../../src/util/instance-state"
+import { tmpdir } from "../fixture/fixture"
+
+async function access<A, E>(state: InstanceState.State<A, E>, dir: string) {
+  return Instance.provide({
+    directory: dir,
+    fn: () => Effect.runPromise(InstanceState.get(state)),
+  })
+}
+
+afterEach(async () => {
+  await Instance.disposeAll()
+})
+
+test("InstanceState caches values for the same instance", async () => {
+  await using tmp = await tmpdir()
+  let n = 0
+
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const state = yield* InstanceState.make({
+          lookup: () => Effect.sync(() => ({ n: ++n })),
+        })
+
+        const a = yield* Effect.promise(() => access(state, tmp.path))
+        const b = yield* Effect.promise(() => access(state, tmp.path))
+
+        expect(a).toBe(b)
+        expect(n).toBe(1)
+      }),
+    ),
+  )
+})
+
+test("InstanceState isolates values by directory", async () => {
+  await using a = await tmpdir()
+  await using b = await tmpdir()
+  let n = 0
+
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const state = yield* InstanceState.make({
+          lookup: (dir) => Effect.sync(() => ({ dir, n: ++n })),
+        })
+
+        const x = yield* Effect.promise(() => access(state, a.path))
+        const y = yield* Effect.promise(() => access(state, b.path))
+        const z = yield* Effect.promise(() => access(state, a.path))
+
+        expect(x).toBe(z)
+        expect(x).not.toBe(y)
+        expect(n).toBe(2)
+      }),
+    ),
+  )
+})
+
+test("InstanceState is disposed on instance reload", async () => {
+  await using tmp = await tmpdir()
+  const seen: string[] = []
+  let n = 0
+
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const state = yield* InstanceState.make({
+          lookup: () => Effect.sync(() => ({ n: ++n })),
+          release: (value) =>
+            Effect.sync(() => {
+              seen.push(String(value.n))
+            }),
+        })
+
+        const a = yield* Effect.promise(() => access(state, tmp.path))
+        yield* Effect.promise(() => Instance.reload({ directory: tmp.path }))
+        const b = yield* Effect.promise(() => access(state, tmp.path))
+
+        expect(a).not.toBe(b)
+        expect(seen).toEqual(["1"])
+      }),
+    ),
+  )
+})
+
+test("InstanceState is disposed on disposeAll", async () => {
+  await using a = await tmpdir()
+  await using b = await tmpdir()
+  const seen: string[] = []
+
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const state = yield* InstanceState.make({
+          lookup: (dir) => Effect.sync(() => ({ dir })),
+          release: (value) =>
+            Effect.sync(() => {
+              seen.push(value.dir)
+            }),
+        })
+
+        yield* Effect.promise(() => access(state, a.path))
+        yield* Effect.promise(() => access(state, b.path))
+        yield* Effect.promise(() => Instance.disposeAll())
+
+        expect(seen.sort()).toEqual([a.path, b.path].sort())
+      }),
+    ),
+  )
+})
+
+test("InstanceState dedupes concurrent lookups for the same directory", async () => {
+  await using tmp = await tmpdir()
+  let n = 0
+
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const state = yield* InstanceState.make({
+          lookup: () =>
+            Effect.promise(async () => {
+              n += 1
+              await Bun.sleep(10)
+              return { n }
+            }),
+        })
+
+        const [a, b] = yield* Effect.promise(() => Promise.all([access(state, tmp.path), access(state, tmp.path)]))
+        expect(a).toBe(b)
+        expect(n).toBe(1)
+      }),
+    ),
+  )
+})