[Windows] Startup crash when opening multiple instances: EBUSY: failed copying files... package bun-pty

[mynameistito]

Description

I am experiencing a crash when attempting to open a second instance of OpenCode while the opencode-pty plugin is enabled.

The first instance boots correctly. However, launching a second instance triggers a BunInstallFailedError. The logs indicate an EBUSY error regarding bun-pty, suggesting a file locking issue where the first instance is holding onto the dependency files, preventing the second instance from verifying or copying them from the cache.

Steps to Reproduce

1. Enable opencode-pty in opencode.json.
2. Open a project in OpenCode (Instance A) - Success.
3. Attempt to open a second project in a new window (Instance B) - Failure.
4. Instance B crashes with a TUI bootstrap failure.

Expected Behavior

Multiple instances of OpenCode should be able to run simultaneously with the opencode-pty plugin enabled, as they do without the plugin.

Actual Behavior

The second instance fails to bootstrap. The process terminates with a BunInstallFailedError.

Logs

INFO  2026-01-18T01:16:55 +5294ms service=bun code=1 stdout=bun add v1.3.5 (1e86cebd)
...
installed opencode-pty@0.1.4

91 packages installed [5.40s]
Failed to install 1 package
 stderr=Resolving dependencies
Resolved, downloaded and extracted [1]
EBUSY: failed copying files from cache to destination for package bun-pty
Saved lockfile
 done
ERROR 2026-01-18T01:16:55 +3ms service=server error=BunInstallFailedError Caused by: Command failed with exit code 1 failed

Console Output:

{
  "name": "BunInstallFailedError",
  "data": {
    "pkg": "opencode-pty",
    "version": "latest"
  }
}

Environment

• OS: Windows 10 x64
• OpenCode Version: 1.1.25
• Bun Version: 1.3.6
• Plugin Version: opencode-pty@0.1.4 (latest)

Configuration

Here is my current opencode.jsonc:
https://gist.github.com/mynameistito/6198ccbbeee48503f3a6d201f3e4caf4

Additional Context

The error EBUSY: failed copying files from cache to destination for package bun-pty suggests that the native binary for the PTY is currently locked by the OS (used by the first OpenCode instance), preventing Bun from performing its installation/integrity check for the second instance.

---

[shekohex]

Hi @mynameistito, thank you for the detailed report!

After investigating the root cause, we've identified that this is a file-locking issue specific to Windows and stems from how the OpenCode (Host Application) handles plugin management during startup.

Root Cause

1. Windows File Locking: When the first instance of OpenCode starts, it loads opencode-pty and locks its native binaries (via bun-pty). On Windows, native files (like .dll or PTY drivers) cannot be modified or overwritten while they are in use by another process.
2. Aggressive Installation Logic: Currently, the OpenCode host attempts to verify/install plugins on every startup. When a second instance tries to run bun add, it attempts to access or sync these same files. Since they are locked by the first instance, Windows throws an EBUSY error, leading to the crash.
3. "latest" Tag Mismatch: Using the default latest version triggers this check every time because of a logic mismatch in the Host's installation routine, which fails to recognize the cached version as a match for "latest".

Workaround

You can likely bypass this by specifying an exact version for the plugin in your opencode.json instead of letting it default to latest. For example:

"plugin": [
  "opencode-pty@0.1.4" // Replace with the current version
]

This should allow the Host to see that the requested version is already present and skip the installation attempt entirely.

Permanent Fix

The definitive fix needs to be implemented in the OpenCode Host repository. We need to:

• Improve the version-check logic to skip bun add if a functional version already exists.
• Remove the --force flag from routine startup checks.
• Implement a cross-process lock to handle multiple instances gracefully.

We'll be looking into addressing this in the core OpenCode repository.

[mynameistito]

Hi @shekohex,

Thank you for the quick response and the detailed explanation of the file-locking mechanics on Windows. I appreciate the deep dive into how the Host handles the latest tag.

However, I’m still a bit confused as to why this behavior is exclusively occurring with the opencode-pty plugin in my setup. To test your theory, I checked my other active plugins, all of which are currently set to @latest in my opencode.jsonc:

• opencode-antigravity-auth@latest
• @franlol/opencode-md-table-formatter@latest
• opencode-anthropic-auth@latest
• @tarquinen/opencode-dcp@latest

If the root cause was a general logic flaw in the OpenCode Host where it attempts an aggressive bun add / integrity check on every startup for any plugin marked @latest, I would expect all of these plugins to trigger the same EBUSY error when I open a second instance.

Instead, I can open multiple instances and projects perfectly fine with all those plugins active on @latest. The crash only happens—and it happens consistently—the moment opencode-pty is enabled.

Correction on the workaround: I previously mentioned pinning opencode-pty to 0.1.4 fixed it, but I’ve realized that pinning it does not fix the issue if my other plugins are still set to @latest. The crash only stops if I pin this plugin AND ensure no other plugins are on, or if they are all pinned.

This suggests that while the Host's "latest" check might be the trigger, there is something unique about how opencode-pty (or its bun-pty dependency) interacts with the OS. It seems to be the only plugin that creates a persistent or exclusive file lock that actually prevents a second instance from even performing a basic version verification for any plugin on @latest.

A few specific questions that might help narrow this down:

1. Native vs. JS-only: Are the other plugins I listed perhaps "pure" JS/TS, while opencode-pty is hitting this because of the native PTY binaries? If so, why does Bun need to "copy files from cache" for a native package that is already installed and in use, but skips that conflict for others?
2. Handle Management: Is bun-pty holding an open handle to a driver or .exe that Windows refuses to share even for a read-only integrity check?

It feels like a conflict that is specific to this plugin's architecture. If it were truly just a general Host issue, I shouldn't be able to run my other 4 plugins on @latest across multiple tabs, but I can (as long as opencode-pty isn't active).

I'd love to get your take on why this specific plugin is so much more "sensitive" to multiple instances than the others.

[shekohex]

Hi @mynameistito,

Thank you for the fantastic follow-up and the clear confirmation! You’ve pinpointed the exact architectural difference that causes this: Native Binaries vs. Pure JS.

The Root Cause (Confirmed)

You are exactly right—pure JS/TS plugins don't hit this issue because Windows allows multiple processes to read and verify them without restriction. However, opencode-pty depends on bun-pty, which includes native binaries (like .dll files). When Instance A loads these binaries into memory, Windows places an exclusive lock on them.

Because the OpenCode Host currently triggers a bun add (or integrity check) on startup for any plugin set to @latest, Instance B's Bun process attempts to access the locked PTY binaries and crashes with EBUSY.

The Permanent Fix Plan

We have a two-part plan to solve this once and for all:

1. Host Logic (Short-term): We will be opening an issue in the OpenCode Host repository to address the "aggressive installation logic." We need to move away from running bun add on every boot and instead implement a smarter resolution check that only triggers an installation if the version is missing or an update is explicitly requested.

2. Built-in PTY (Long-term): Bun has recently introduced a built-in Bun.Terminal API (starting from v1.3.5) for native PTY support. You can check the official documentation here.

   Once the OpenCode Host updates to a version of Bun with stable Windows PTY support, we will migrate opencode-pty to use this built-in module. Since the PTY logic will then live inside the bun binary itself (instead of an external .dll in node_modules), there will be no external file-locking conflicts.

Thank you again for your patience and for helping us narrow this down so precisely!

[mynameistito]

Hi @shekohex,

That confirms my suspicion! It makes perfect sense that the native binaries in bun-pty are what’s causing the exclusive lock that Windows is so protective of.

However, I’m concerned about relying on a fix in the OpenCode Host repository or waiting for a migration to Bun.Terminal. Platform-level changes to installation logic and Bun runtime updates typically have much longer release cycles—we could be looking at a significant wait time before those changes reach stable users. In the meantime, the plugin is effectively "directory-poisoning" Windows users: a single active PTY session in Instance A prevents Instance B from even verifying its other, unrelated @latest plugins because Bun crashes on the directory scan.

The Case for "Shadow Copying" in the Plugin:
Instead of waiting for the Host to become less aggressive, we can make the plugin resilient today by adopting the standard pattern used by Windows IDE plugins: Shadow Copying. By moving the binaries to a temporary location before loading them, we keep the plugins/opencode-pty folder completely unlocked.

Here is a rough sketch of how I'm thinking we could modify src/plugin/pty/manager.ts:

// 1. Remove top-level eager import of "bun-pty"
// import { spawn } from "bun-pty"; 

let ptyModule: any = null;

export class PTYManager {
  private async ensureLoaded() {
    if (ptyModule) return ptyModule;

    if (process.platform === "win32") {
      // 2. Logic to copy native binaries to %TEMP% to avoid EBUSY
      const tempDir = path.join(os.tmpdir(), "opencode-pty", crypto.randomUUID());
      await copyBinaries(modulePath, tempDir); 
      ptyModule = await import(path.join(tempDir, "index.js"));
    } else {
      ptyModule = await import("bun-pty");
    }
    return ptyModule;
  }

  async spawn(opts: SpawnOptions): Promise<PTYSessionInfo> {
    const { spawn } = await this.ensureLoaded();
    // ... existing spawn logic
  }
}

Why this is the superior short-term fix:

• Host Harmony: The Host's "aggressive installation logic" can scan, verify, or even update the plugin folder while it's running, because the active binary is a temporary copy elsewhere.
• Zero Locking: It eliminates the EBUSY crash for multi-instance users immediately.
• Independence: It doesn't require a Bun update or a Host repository PR.

I've already mapped out the manager.ts logic and think this would be a relatively low-footprint change. Given the potential lag in the Host's roadmap, would you be open to a PR implementing this shadow copy strategy? It seems like the most proactive way to fix this for Windows users right now.

[shekohex]

Looks promising, but I don't have a windows VM right now to test this at the moment.

However there are two options to at least get you unblocked until I get my hands on a windows computer.

1. You clone the repo, and implement the fix, with the help of opencode itself ofc.
2. You can use a local copy of the plugin instead of npm, this plugin is not updated frequently as it is already stable enough. You clone the repo locally somewhere and use the file:///abs/path/to/opencode-pty in your plugin array. See the README instructions on that part.

It's an interesting bug, and only could be reproduced on windows.

[mynameistito]

Hi @shekohex,

I've implemented the Shadow Copying solution we discussed and submitted it as a Pull Request: #8.

I've tested the logic by refactoring the PTYManager to lazy-load bun-pty only after the native .dll has been shadow-copied to a temporary directory. This should completely eliminate the EBUSY crashes during OpenCode's startup verification on Windows, even when multiple instances are running.

Looking forward to your feedback!