fix: add idle-timeout Instance disposal for serve mode memory

[sjawhar]

Issue for this PR

Fixes #13041

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

In serve mode, each unique workspace directory creates an Instance that spawns LSP servers, MCP clients, file watchers, and ~26 state entries. These are cached forever and never cleaned up, even after all sessions disconnect — causing unbounded memory growth (2.9GB+ per session as reported in #13041).

This PR adds automatic idle-timeout disposal:

Instance idle-timeout disposal (instance.ts):

• Reference counting via acquire()/release() tracks active provide() calls per directory
• When refs drop to 0, schedules disposal after OPENCODE_IDLE_TIMEOUT ms (default 5 min)
• New provide() calls cancel any pending idle timer
• Instance.list() returns cached instances with ref counts for observability
• Instance.disposeByDirectory(dir) for API-driven disposal

Race condition fix (state.ts):

• Detaches state entries from the registry before running disposal callbacks, so new Instances arriving during disposal get fresh state instead of references to disposing/disposed state

Configuration (flag.ts):

• OPENCODE_IDLE_TIMEOUT env var (ms, default 300000 = 5 min, set to 0 to disable)
• Dynamic getter so the value is read at access time, not module load time

API endpoints (routes/global.ts):

• GET /global/instances — list cached instances with ref counts
• POST /global/instances/dispose — dispose a specific instance by directory

Tests (instance-idle.test.ts):

• 8 tests covering: basic provide, list, idle disposal, timer cancellation, fresh instance after disposal, disposeByDirectory, concurrent refs, dispose-within-provide

How did you verify your code works?

• bun run typecheck passes
• 8 new unit tests all pass
• Manual testing in serve mode: instances dispose after 5 min idle, re-create on next request, memory is reclaimed

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Potential Duplicate/Related PRs Found:

1. fix(web): dispose idle MCP server instances to prevent process accumulation #15326 - fix(web): dispose idle MCP server instances to prevent process accumulation

   • Related to idle disposal of server instances, though focused on MCP servers specifically. May address a subset of the broader memory issue.

2. fix: resolve memory leak issues across multiple subsystems #14650 - fix: resolve memory leak issues across multiple subsystems

   • Addresses memory leak problems which may overlap with the unbounded memory growth issue in Per-session MCP server and LSP duplication multiplies memory usage across concurrent sessions #13041 that this PR fixes.

These are related to memory/disposal management but have different scopes. #16616 (current PR) appears to be the most comprehensive solution targeting the specific serve mode instance caching issue with idle-timeout disposal.

[Morzaram]

Why does yours have 58 files to fix this? Majority being MD?

[sjawhar]

Good catch — those were internal tooling files (.sisyphus/) that shouldn't have been tracked. Cleaned up, the diff now only contains the 2 relevant source files (instance.ts + flag.ts) plus the test file.

[sjawhar]

Closing: instance idle timeout was addressed as part of broader memory leak and serve hardening work.