Distillation

Date: Sep 8, 2026

• 🔴 [requested-investigation] (19:44) User requested a read-only, very thorough investigation in /home/byk/Code/opencode; explicitly instructed not to edit anything.
• 🟡 (19:44) User asked to trace how the legacy server version represented by current source returns HTTP 499 for GET /provider, GET /config/providers, GET /command, and GET /mcp when a project-scoped Instance bootstrap or cached service promise is aborted.
• 🟡 (19:44) User asked for exact source files/symbols, the likely shared dependency among the four routes, and APIs/code paths that dispose or reload one project Instance without restarting the server; requested concise file:line evidence and hypotheses ranked by confidence.
• 🟡 (19:45) Investigation located instance-related implementation files: packages/opencode/src/effect/instance-state.ts, packages/opencode/src/effect/instance-ref.ts, packages/opencode/src/effect/instance-registry.ts, packages/opencode/src/project/instance-store.ts, packages/opencode/src/project/instance-context.ts, packages/opencode/src/project/instance-runtime.ts, packages/opencode/src/server/routes/instance/httpapi/middleware/instance-context.ts, packages/opencode/src/server/routes/instance/httpapi/handlers/instance.ts, and packages/opencode/src/server/routes/instance/httpapi/groups/instance.ts.
• 🟡 (19:46) Repository-wide search found no direct HTTP 499 handling in packages/opencode/src/server; the only explicit new Response(null, { status: 499 }) match was unrelated console code at packages/console/app/src/routes/zen/util/handler.ts:464.
• 🟡 (19:46) GET /provider is declared by ProviderApi in packages/opencode/src/server/routes/instance/httpapi/groups/provider.ts:34-47; its group applies shared middleware in order at lines 91-93: InstanceContextMiddleware, WorkspaceRoutingMiddleware, and Authorization.
• 🟡 (19:47) providerHandlers in packages/opencode/src/server/routes/instance/httpapi/handlers/provider.ts:34-113 acquires stable services while constructing the handler layer: Config.Service at line 36, Provider.Service at line 37, and ProviderAuth.Service at line 38. ProviderHttpApi.list at lines 40-59 calls cfg.get() at line 41, ModelsDev.Service.use((s) => s.get()) at line 42, and provider.list() at line 49; the route is registered with .handle("list", list) at line 108.
• 🟡 (19:47) GET /command is declared as InstancePaths.command = "/command" in packages/opencode/src/server/routes/instance/httpapi/groups/instance.ts:43-56, with endpoint declaration at lines 139-148. The instance group applies InstanceContextMiddleware, WorkspaceRoutingMiddleware, and Authorization at lines 196-198.
• 🟡 (19:48) instanceHandlers in packages/opencode/src/server/routes/instance/httpapi/handlers/instance.ts:15-110 acquires Command.Service at line 18. InstanceHttpApi.command calls command.list() at lines 76-78 and is registered through .handle("command", getCommand) at line 104.
• 🟡 (19:49) GET /config/providers is declared by ConfigApi in packages/opencode/src/server/routes/instance/httpapi/groups/config.ts:12-65, specifically lines 38-47. Its group applies InstanceContextMiddleware, WorkspaceRoutingMiddleware, and Authorization at lines 55-57.
• 🟡 (19:50) configHandlers in packages/opencode/src/server/routes/instance/httpapi/handlers/config.ts:9-34 acquires Provider.Service at line 11 and Config.Service at line 12. ConfigHttpApi.providers calls providerSvc.list() at lines 24-29 and is registered via .handle("providers", providers) at line 32.
• 🟡 (19:51) GET /mcp is declared as McpPaths.status = "/mcp" in packages/opencode/src/server/routes/instance/httpapi/groups/mcp.ts:32-39, with endpoint declaration at lines 45-54. Its group applies InstanceContextMiddleware, WorkspaceRoutingMiddleware, and Authorization at lines 146-148.
• 🟡 (19:51) Early shared-path evidence: all four target GET routes are instance-scoped HttpApi routes and all four route groups apply InstanceContextMiddleware; this middleware is therefore a likely common dependency/failure boundary, while /provider and /config/providers additionally converge on Provider.Service/provider.list(). Investigation had not yet inspected the MCP handler or the implementation of the instance middleware/runtime/cache.
• 🟡 (19:48) A per-instance disposal API is declared as POST /instance/dispose via InstancePaths.dispose in packages/opencode/src/server/routes/instance/httpapi/groups/instance.ts:43-45 and endpoint lines 62-70. Its handler InstanceHttpApi.dispose in packages/opencode/src/server/routes/instance/httpapi/handlers/instance.ts:24-27 obtains InstanceState.context, passes it to markInstanceForDisposal, and returns true; registration is at line 97.
• 🟡 (19:50) Config updates also trigger project-instance replacement/disposal: ConfigHttpApi.update in packages/opencode/src/server/routes/instance/httpapi/handlers/config.ts:18-22 runs configSvc.update(ctx.payload), then markInstanceForDisposal(yield* InstanceState.context), and returns the payload.
• 🟡 (19:46) Repository guidance states that InstanceState from src/effect/instance-state.ts uses a ScopedCache keyed by directory for per-directory/project state, automatically cleans state on disposal, and should use Effect.addFinalizer or Effect.acquireRelease for cleanup. Guidance also states makeRuntime from src/effect/run-service.ts uses a shared memoMap to deduplicate layers, and src/project/bootstrap.ts wraps each service init() in Effect.forkDetach.