[FEATURE]: File locks / Vim-style locks for OpenCode locks #4278

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Feature request: File locks / Vim-style locks for OpenCode

Summary

Add support for file locking in sst/opencode, ideally with Vim-style behavior (lock/swap files), so that:

• Multiple OpenCode clients and/or agents don’t stomp on each other’s changes
• We have a foundation for safe concurrent agents working against the same workspace

Motivation

Right now, multiple editors/agents interacting with the same repo can easily end up overwriting each other’s changes, especially when:

• Running multiple agents/tools in parallel that all use OpenCode
• Using OpenCode alongside a human editor
• Running long-lived operations (refactors, codegen, formatting) that touch many files

Vim-style file locks (or equivalent) would allow OpenCode to:

• Detect when a file is already “owned” by another process/session
• Warn or prevent conflicting edits
• Provide a basis for coordinating multiple agents that operate concurrently

This is particularly useful for building multi-agent workflows on top of sst/opencode, where several agents may read/write the same files in overlapping time windows.

Proposed behavior (high-level)

I’m not attached to any specific API – this is more about desired semantics. A few ideas:

1. Advisory file locks

• opencode (or underlying file layer) exposes an API to:
  • Acquire a lock for a given path: lock(path, options)
  • Release a lock: unlock(path)
  • Optionally check lock status: isLocked(path) or similar
• Locks are per-file (and maybe optionally per-directory / glob)
• If a lock is held:
  • Other writers either fail fast with a clear error, or
  • Block until the lock is released (configurable)

2. Vim-like UX semantics

Vim-style semantics could look like:

• When a file is opened for editing, a lock/marker is created, e.g.:
  • .filename.lock or .filename.swp
• If another OpenCode session tries to open the same file:
  • It receives a “file is already locked” signal
  • It can decide whether to:
    • Open read-only
    • Take over the lock (force)
    • Abort

This doesn’t have to be literally Vim’s format, just the same idea: a simple, visible, file-based lock mechanism that plays nicely in a shared workspace.

3. Concurrency support for agents

With locks in place, higher-level orchestration could:

• Assign different files / directories to different agents safely
• Use lock acquisition failure as a signal to back off or reschedule work
• Run multiple agents in parallel without worrying about silent overwrites

Example desired flow for agents:

1. Agent A wants to edit src/foo.ts → acquire lock.
2. While Agent A holds the lock:
   • Agent B attempting to edit src/foo.ts either:
     • Fails with a structured “locked” error, or
     • Waits up to a configurable timeout
3. On success or failure, agents can coordinate based on lock state.

API ideas (sketch)

One possible direction (purely illustrative):

// Advisory lock
const lock = await opencode.lockFile("src/foo.ts", {
  mode: "exclusive",   // "exclusive" | "shared"
  wait: true,
  timeoutMs: 5000,
});

// Use the file safely here...

await lock.release();   // or opencode.unlockFile("src/foo.ts");