feat(shared): add Effect-idiomatic file lock (EffectFlock) (#22681)

3 files changed, 730 insertions, 0 deletions

diff --git a/packages/shared/src/util/effect-flock.ts b/packages/shared/src/util/effect-flock.ts
new file mode 100644
index 000000000..d728c0ef1
--- /dev/null
+++ b/packages/shared/src/util/effect-flock.ts
@@ -0,0 +1,278 @@
+import path from "path"
+import os from "os"
+import { randomUUID } from "crypto"
+import { Context, Effect, Function, Layer, Option, Schedule, Schema } from "effect"
+import type { FileSystem, Scope } from "effect"
+import type { PlatformError } from "effect/PlatformError"
+import { AppFileSystem } from "../filesystem"
+import { Global } from "../global"
+import { Hash } from "./hash"
+
+export namespace EffectFlock {
+  // ---------------------------------------------------------------------------
+  // Errors
+  // ---------------------------------------------------------------------------
+
+  export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>()("LockTimeoutError", {
+    key: Schema.String,
+  }) {}
+
+  export class LockCompromisedError extends Schema.TaggedErrorClass<LockCompromisedError>()("LockCompromisedError", {
+    detail: Schema.String,
+  }) {}
+
+  class ReleaseError extends Schema.TaggedErrorClass<ReleaseError>()("ReleaseError", {
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  }) {
+    override get message() {
+      return this.detail
+    }
+  }
+
+  /** Internal: signals "lock is held, retry later". Never leaks to callers. */
+  class NotAcquired extends Schema.TaggedErrorClass<NotAcquired>()("NotAcquired", {}) {}
+
+  export type LockError = LockTimeoutError | LockCompromisedError
+
+  // ---------------------------------------------------------------------------
+  // Timing (baked in — no caller ever overrides these)
+  // ---------------------------------------------------------------------------
+
+  const STALE_MS = 60_000
+  const TIMEOUT_MS = 5 * 60_000
+  const BASE_DELAY_MS = 100
+  const MAX_DELAY_MS = 2_000
+  const HEARTBEAT_MS = Math.max(100, Math.floor(STALE_MS / 3))
+
+  const retrySchedule = Schedule.exponential(BASE_DELAY_MS, 1.7).pipe(
+    Schedule.either(Schedule.spaced(MAX_DELAY_MS)),
+    Schedule.jittered,
+    Schedule.while((meta) => meta.elapsed < TIMEOUT_MS),
+  )
+
+  // ---------------------------------------------------------------------------
+  // Lock metadata schema
+  // ---------------------------------------------------------------------------
+
+  const LockMetaJson = Schema.fromJsonString(
+    Schema.Struct({
+      token: Schema.String,
+      pid: Schema.Number,
+      hostname: Schema.String,
+      createdAt: Schema.String,
+    }),
+  )
+
+  const decodeMeta = Schema.decodeUnknownSync(LockMetaJson)
+  const encodeMeta = Schema.encodeSync(LockMetaJson)
+
+  // ---------------------------------------------------------------------------
+  // Service
+  // ---------------------------------------------------------------------------
+
+  export interface Interface {
+    readonly acquire: (key: string, dir?: string) => Effect.Effect<void, LockError, Scope.Scope>
+    readonly withLock: {
+      (key: string, dir?: string): <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E | LockError, R>
+      <A, E, R>(body: Effect.Effect<A, E, R>, key: string, dir?: string): Effect.Effect<A, E | LockError, R>
+    }
+  }
+
+  export class Service extends Context.Service<Service, Interface>()("EffectFlock") {}
+
+  // ---------------------------------------------------------------------------
+  // Layer
+  // ---------------------------------------------------------------------------
+
+  function wall() {
+    return performance.timeOrigin + performance.now()
+  }
+
+  const mtimeMs = (info: FileSystem.File.Info) => Option.getOrElse(info.mtime, () => new Date(0)).getTime()
+
+  const isPathGone = (e: PlatformError) => e.reason._tag === "NotFound" || e.reason._tag === "Unknown"
+
+  export const layer: Layer.Layer<Service, never, Global.Service | AppFileSystem.Service> = Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const global = yield* Global.Service
+      const fs = yield* AppFileSystem.Service
+      const lockRoot = path.join(global.state, "locks")
+      const hostname = os.hostname()
+      const ensuredDirs = new Set<string>()
+
+      // -- helpers (close over fs) --
+
+      const safeStat = (file: string) =>
+        fs.stat(file).pipe(
+          Effect.catchIf(isPathGone, () => Effect.void),
+          Effect.orDie,
+        )
+
+      const forceRemove = (target: string) => fs.remove(target, { recursive: true }).pipe(Effect.ignore)
+
+      /** Atomic mkdir — returns true if created, false if already exists, dies on other errors. */
+      const atomicMkdir = (dir: string) =>
+        fs.makeDirectory(dir, { mode: 0o700 }).pipe(
+          Effect.as(true),
+          Effect.catchIf(
+            (e) => e.reason._tag === "AlreadyExists",
+            () => Effect.succeed(false),
+          ),
+          Effect.orDie,
+        )
+
+      /** Write with exclusive create — compromised error if file already exists. */
+      const exclusiveWrite = (filePath: string, content: string, lockDir: string, detail: string) =>
+        fs.writeFileString(filePath, content, { flag: "wx" }).pipe(
+          Effect.catch(() =>
+            Effect.gen(function* () {
+              yield* forceRemove(lockDir)
+              return yield* new LockCompromisedError({ detail })
+            }),
+          ),
+        )
+
+      const cleanStaleBreaker = Effect.fnUntraced(function* (breakerPath: string) {
+        const bs = yield* safeStat(breakerPath)
+        if (bs && wall() - mtimeMs(bs) > STALE_MS) yield* forceRemove(breakerPath)
+        return false
+      })
+
+      const ensureDir = Effect.fnUntraced(function* (dir: string) {
+        if (ensuredDirs.has(dir)) return
+        yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.orDie)
+        ensuredDirs.add(dir)
+      })
+
+      const isStale = Effect.fnUntraced(function* (lockDir: string, heartbeatPath: string, metaPath: string) {
+        const now = wall()
+
+        const hb = yield* safeStat(heartbeatPath)
+        if (hb) return now - mtimeMs(hb) > STALE_MS
+
+        const meta = yield* safeStat(metaPath)
+        if (meta) return now - mtimeMs(meta) > STALE_MS
+
+        const dir = yield* safeStat(lockDir)
+        if (!dir) return false
+
+        return now - mtimeMs(dir) > STALE_MS
+      })
+
+      // -- single lock attempt --
+
+      type Handle = { token: string; metaPath: string; heartbeatPath: string; lockDir: string }
+
+      const tryAcquireLockDir = Effect.fn("EffectFlock.tryAcquire")(function* (lockDir: string) {
+        const token = randomUUID()
+        const metaPath = path.join(lockDir, "meta.json")
+        const heartbeatPath = path.join(lockDir, "heartbeat")
+
+        // Atomic mkdir — the POSIX lock primitive
+        const created = yield* atomicMkdir(lockDir)
+
+        if (!created) {
+          if (!(yield* isStale(lockDir, heartbeatPath, metaPath))) return yield* new NotAcquired()
+
+          // Stale — race for breaker ownership
+          const breakerPath = lockDir + ".breaker"
+
+          const claimed = yield* fs.makeDirectory(breakerPath, { mode: 0o700 }).pipe(
+            Effect.as(true),
+            Effect.catchIf(
+              (e) => e.reason._tag === "AlreadyExists",
+              () => cleanStaleBreaker(breakerPath),
+            ),
+            Effect.catchIf(isPathGone, () => Effect.succeed(false)),
+            Effect.orDie,
+          )
+
+          if (!claimed) return yield* new NotAcquired()
+
+          // We own the breaker — double-check staleness, nuke, recreate
+          const recreated = yield* Effect.gen(function* () {
+            if (!(yield* isStale(lockDir, heartbeatPath, metaPath))) return false
+            yield* forceRemove(lockDir)
+            return yield* atomicMkdir(lockDir)
+          }).pipe(Effect.ensuring(forceRemove(breakerPath)))
+
+          if (!recreated) return yield* new NotAcquired()
+        }
+
+        // We own the lock dir — write heartbeat + meta with exclusive create
+        yield* exclusiveWrite(heartbeatPath, "", lockDir, "heartbeat already existed")
+
+        const metaJson = encodeMeta({ token, pid: process.pid, hostname, createdAt: new Date().toISOString() })
+        yield* exclusiveWrite(metaPath, metaJson, lockDir, "meta.json already existed")
+
+        return { token, metaPath, heartbeatPath, lockDir } satisfies Handle
+      })
+
+      // -- retry wrapper (preserves Handle type) --
+
+      const acquireHandle = (lockfile: string, key: string): Effect.Effect<Handle, LockError> =>
+        tryAcquireLockDir(lockfile).pipe(
+          Effect.retry({
+            while: (err) => err._tag === "NotAcquired",
+            schedule: retrySchedule,
+          }),
+          Effect.catchTag("NotAcquired", () => Effect.fail(new LockTimeoutError({ key }))),
+        )
+
+      // -- release --
+
+      const release = (handle: Handle) =>
+        Effect.gen(function* () {
+          const raw = yield* fs.readFileString(handle.metaPath).pipe(
+            Effect.catch((err) => {
+              if (isPathGone(err)) return Effect.die(new ReleaseError({ detail: "metadata missing" }))
+              return Effect.die(err)
+            }),
+          )
+
+          const parsed = yield* Effect.try({
+            try: () => decodeMeta(raw),
+            catch: (cause) => new ReleaseError({ detail: "metadata invalid", cause }),
+          }).pipe(Effect.orDie)
+
+          if (parsed.token !== handle.token) return yield* Effect.die(new ReleaseError({ detail: "token mismatch" }))
+
+          yield* forceRemove(handle.lockDir)
+        })
+
+      // -- build service --
+
+      const acquire = Effect.fn("EffectFlock.acquire")(function* (key: string, dir?: string) {
+        const lockDir = dir ?? lockRoot
+        yield* ensureDir(lockDir)
+
+        const lockfile = path.join(lockDir, Hash.fast(key) + ".lock")
+
+        // acquireRelease: acquire is uninterruptible, release is guaranteed
+        const handle = yield* Effect.acquireRelease(acquireHandle(lockfile, key), (handle) => release(handle))
+
+        // Heartbeat fiber — scoped, so it's interrupted before release runs
+        yield* fs
+          .utimes(handle.heartbeatPath, new Date(), new Date())
+          .pipe(Effect.ignore, Effect.repeat(Schedule.spaced(HEARTBEAT_MS)), Effect.forkScoped)
+      })
+
+      const withLock: Interface["withLock"] = Function.dual(
+        (args) => Effect.isEffect(args[0]),
+        <A, E, R>(body: Effect.Effect<A, E, R>, key: string, dir?: string): Effect.Effect<A, E | LockError, R> =>
+          Effect.scoped(
+            Effect.gen(function* () {
+              yield* acquire(key, dir)
+              return yield* body
+            }),
+          ),
+      )
+
+      return Service.of({ acquire, withLock })
+    }),
+  )
+
+  export const live = layer.pipe(Layer.provide(AppFileSystem.defaultLayer))
+}
diff --git a/packages/shared/test/fixture/effect-flock-worker.ts b/packages/shared/test/fixture/effect-flock-worker.ts
new file mode 100644
index 000000000..7fd2e144a
--- /dev/null
+++ b/packages/shared/test/fixture/effect-flock-worker.ts
@@ -0,0 +1,64 @@
+import fs from "fs/promises"
+import path from "path"
+import os from "os"
+import { Effect, Layer } from "effect"
+import { AppFileSystem } from "@opencode-ai/shared/filesystem"
+import { EffectFlock } from "@opencode-ai/shared/util/effect-flock"
+import { Global } from "@opencode-ai/shared/global"
+
+type Msg = {
+  key: string
+  dir: string
+  holdMs?: number
+  ready?: string
+  active?: string
+  done?: string
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms))
+}
+
+const msg: Msg = JSON.parse(process.argv[2]!)
+
+const testGlobal = Layer.succeed(
+  Global.Service,
+  Global.Service.of({
+    home: os.homedir(),
+    data: os.tmpdir(),
+    cache: os.tmpdir(),
+    config: os.tmpdir(),
+    state: os.tmpdir(),
+    bin: os.tmpdir(),
+    log: os.tmpdir(),
+  }),
+)
+
+const testLayer = EffectFlock.layer.pipe(Layer.provide(testGlobal), Layer.provide(AppFileSystem.defaultLayer))
+
+async function job() {
+  if (msg.ready) await fs.writeFile(msg.ready, String(process.pid))
+  if (msg.active) await fs.writeFile(msg.active, String(process.pid), { flag: "wx" })
+
+  try {
+    if (msg.holdMs && msg.holdMs > 0) await sleep(msg.holdMs)
+    if (msg.done) await fs.appendFile(msg.done, "1\n")
+  } finally {
+    if (msg.active) await fs.rm(msg.active, { force: true })
+  }
+}
+
+await Effect.runPromise(
+  Effect.gen(function* () {
+    const flock = yield* EffectFlock.Service
+    yield* flock.withLock(
+      Effect.promise(() => job()),
+      msg.key,
+      msg.dir,
+    )
+  }).pipe(Effect.provide(testLayer)),
+).catch((err) => {
+  const text = err instanceof Error ? (err.stack ?? err.message) : String(err)
+  process.stderr.write(text)
+  process.exit(1)
+})
diff --git a/packages/shared/test/util/effect-flock.test.ts b/packages/shared/test/util/effect-flock.test.ts
new file mode 100644
index 000000000..6e094c2e1
--- /dev/null
+++ b/packages/shared/test/util/effect-flock.test.ts
@@ -0,0 +1,388 @@
+import { describe, expect } from "bun:test"
+import { spawn } from "child_process"
+import fs from "fs/promises"
+import path from "path"
+import os from "os"
+import { Cause, Effect, Exit, Layer } from "effect"
+import { testEffect } from "../lib/effect"
+import { AppFileSystem } from "@opencode-ai/shared/filesystem"
+import { EffectFlock } from "@opencode-ai/shared/util/effect-flock"
+import { Global } from "@opencode-ai/shared/global"
+import { Hash } from "@opencode-ai/shared/util/hash"
+
+function lock(dir: string, key: string) {
+  return path.join(dir, Hash.fast(key) + ".lock")
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms))
+}
+
+async function exists(file: string) {
+  return fs
+    .stat(file)
+    .then(() => true)
+    .catch(() => false)
+}
+
+async function readJson<T>(p: string): Promise<T> {
+  return JSON.parse(await fs.readFile(p, "utf8"))
+}
+
+// ---------------------------------------------------------------------------
+// Worker subprocess helpers
+// ---------------------------------------------------------------------------
+
+type Msg = {
+  key: string
+  dir: string
+  holdMs?: number
+  ready?: string
+  active?: string
+  done?: string
+}
+
+const root = path.join(import.meta.dir, "../..")
+const worker = path.join(import.meta.dir, "../fixture/effect-flock-worker.ts")
+
+function run(msg: Msg) {
+  return new Promise<{ code: number; stdout: Buffer; stderr: Buffer }>((resolve) => {
+    const proc = spawn(process.execPath, [worker, JSON.stringify(msg)], { cwd: root })
+    const stdout: Buffer[] = []
+    const stderr: Buffer[] = []
+    proc.stdout?.on("data", (data) => stdout.push(Buffer.from(data)))
+    proc.stderr?.on("data", (data) => stderr.push(Buffer.from(data)))
+    proc.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr) })
+    })
+  })
+}
+
+function spawnWorker(msg: Msg) {
+  return spawn(process.execPath, [worker, JSON.stringify(msg)], {
+    cwd: root,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+}
+
+function stopWorker(proc: ReturnType<typeof spawnWorker>) {
+  if (proc.exitCode !== null || proc.signalCode !== null) return Promise.resolve()
+  if (process.platform !== "win32" || !proc.pid) {
+    proc.kill()
+    return Promise.resolve()
+  }
+  return new Promise<void>((resolve) => {
+    const killProc = spawn("taskkill", ["/pid", String(proc.pid), "/T", "/F"])
+    killProc.on("close", () => {
+      proc.kill()
+      resolve()
+    })
+  })
+}
+
+async function waitForFile(file: string, timeout = 3_000) {
+  const stop = Date.now() + timeout
+  while (Date.now() < stop) {
+    if (await exists(file)) return
+    await sleep(20)
+  }
+  throw new Error(`Timed out waiting for file: ${file}`)
+}
+
+// ---------------------------------------------------------------------------
+// Test layer
+// ---------------------------------------------------------------------------
+
+const testGlobal = Layer.succeed(
+  Global.Service,
+  Global.Service.of({
+    home: os.homedir(),
+    data: os.tmpdir(),
+    cache: os.tmpdir(),
+    config: os.tmpdir(),
+    state: os.tmpdir(),
+    bin: os.tmpdir(),
+    log: os.tmpdir(),
+  }),
+)
+
+const testLayer = EffectFlock.layer.pipe(Layer.provide(testGlobal), Layer.provide(AppFileSystem.defaultLayer))
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("util.effect-flock", () => {
+  const it = testEffect(testLayer)
+
+  it.live(
+    "acquire and release via scoped Effect",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+      const lockDir = lock(dir, "eflock:acquire")
+
+      yield* Effect.scoped(flock.acquire("eflock:acquire", dir))
+
+      expect(yield* Effect.promise(() => exists(lockDir))).toBe(false)
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "withLock data-first",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+
+      let hit = false
+      yield* flock.withLock(
+        Effect.sync(() => {
+          hit = true
+        }),
+        "eflock:df",
+        dir,
+      )
+      expect(hit).toBe(true)
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "withLock pipeable",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+
+      let hit = false
+      yield* Effect.sync(() => {
+        hit = true
+      }).pipe(flock.withLock("eflock:pipe", dir))
+      expect(hit).toBe(true)
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "writes owner metadata",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+      const key = "eflock:meta"
+      const file = path.join(lock(dir, key), "meta.json")
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          yield* flock.acquire(key, dir)
+          const json = yield* Effect.promise(() =>
+            readJson<{ token?: unknown; pid?: unknown; hostname?: unknown; createdAt?: unknown }>(file),
+          )
+          expect(typeof json.token).toBe("string")
+          expect(typeof json.pid).toBe("number")
+          expect(typeof json.hostname).toBe("string")
+          expect(typeof json.createdAt).toBe("string")
+        }),
+      )
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "breaks stale lock dirs",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+      const key = "eflock:stale"
+      const lockDir = lock(dir, key)
+
+      yield* Effect.promise(async () => {
+        await fs.mkdir(lockDir, { recursive: true })
+        const old = new Date(Date.now() - 120_000)
+        await fs.utimes(lockDir, old, old)
+      })
+
+      let hit = false
+      yield* flock.withLock(
+        Effect.sync(() => {
+          hit = true
+        }),
+        key,
+        dir,
+      )
+      expect(hit).toBe(true)
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "recovers from stale breaker",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+      const key = "eflock:stale-breaker"
+      const lockDir = lock(dir, key)
+      const breaker = lockDir + ".breaker"
+
+      yield* Effect.promise(async () => {
+        await fs.mkdir(lockDir, { recursive: true })
+        await fs.mkdir(breaker)
+        const old = new Date(Date.now() - 120_000)
+        await fs.utimes(lockDir, old, old)
+        await fs.utimes(breaker, old, old)
+      })
+
+      let hit = false
+      yield* flock.withLock(
+        Effect.sync(() => {
+          hit = true
+        }),
+        key,
+        dir,
+      )
+      expect(hit).toBe(true)
+      expect(yield* Effect.promise(() => exists(breaker))).toBe(false)
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "detects compromise when lock dir removed",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+      const key = "eflock:compromised"
+      const lockDir = lock(dir, key)
+
+      const result = yield* flock
+        .withLock(
+          Effect.promise(() => fs.rm(lockDir, { recursive: true, force: true })),
+          key,
+          dir,
+        )
+        .pipe(Effect.exit)
+
+      expect(Exit.isFailure(result)).toBe(true)
+      expect(Exit.isFailure(result) ? Cause.pretty(result.cause) : "").toContain("missing")
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "detects token mismatch",
+    Effect.gen(function* () {
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+      const key = "eflock:token"
+      const lockDir = lock(dir, key)
+      const meta = path.join(lockDir, "meta.json")
+
+      const result = yield* flock
+        .withLock(
+          Effect.promise(async () => {
+            const json = await readJson<{ token?: string }>(meta)
+            json.token = "tampered"
+            await fs.writeFile(meta, JSON.stringify(json, null, 2))
+          }),
+          key,
+          dir,
+        )
+        .pipe(Effect.exit)
+
+      expect(Exit.isFailure(result)).toBe(true)
+      expect(Exit.isFailure(result) ? Cause.pretty(result.cause) : "").toContain("token mismatch")
+      expect(yield* Effect.promise(() => exists(lockDir))).toBe(true)
+      yield* Effect.promise(() => fs.rm(tmp, { recursive: true, force: true }))
+    }),
+  )
+
+  it.live(
+    "fails on unwritable lock roots",
+    Effect.gen(function* () {
+      if (process.platform === "win32") return
+      const flock = yield* EffectFlock.Service
+      const tmp = yield* Effect.promise(() => fs.mkdtemp(path.join(os.tmpdir(), "eflock-test-")))
+      const dir = path.join(tmp, "locks")
+
+      yield* Effect.promise(async () => {
+        await fs.mkdir(dir, { recursive: true })
+        await fs.chmod(dir, 0o500)
+      })
+
+      const result = yield* flock.withLock(Effect.void, "eflock:perm", dir).pipe(Effect.exit)
+      expect(String(result)).toContain("PermissionDenied")
+      yield* Effect.promise(() => fs.chmod(dir, 0o700).then(() => fs.rm(tmp, { recursive: true, force: true })))
+    }),
+  )
+
+  it.live(
+    "enforces mutual exclusion under process contention",
+    () =>
+      Effect.promise(async () => {
+        const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "eflock-stress-"))
+        const dir = path.join(tmp, "locks")
+        const done = path.join(tmp, "done.log")
+        const active = path.join(tmp, "active")
+        const n = 16
+
+        try {
+          const out = await Promise.all(
+            Array.from({ length: n }, () => run({ key: "eflock:stress", dir, done, active, holdMs: 30 })),
+          )
+
+          expect(out.map((x) => x.code)).toEqual(Array.from({ length: n }, () => 0))
+          expect(out.map((x) => x.stderr.toString()).filter(Boolean)).toEqual([])
+
+          const lines = (await fs.readFile(done, "utf8"))
+            .split("\n")
+            .map((x) => x.trim())
+            .filter(Boolean)
+          expect(lines.length).toBe(n)
+        } finally {
+          await fs.rm(tmp, { recursive: true, force: true })
+        }
+      }),
+    60_000,
+  )
+
+  it.live(
+    "recovers after a crashed lock owner",
+    () =>
+      Effect.promise(async () => {
+        const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "eflock-crash-"))
+        const dir = path.join(tmp, "locks")
+        const ready = path.join(tmp, "ready")
+
+        const proc = spawnWorker({ key: "eflock:crash", dir, ready, holdMs: 120_000 })
+
+        try {
+          await waitForFile(ready, 5_000)
+          await stopWorker(proc)
+          await new Promise((resolve) => proc.on("close", resolve))
+
+          // Backdate lock files so they're past STALE_MS (60s)
+          const lockDir = lock(dir, "eflock:crash")
+          const old = new Date(Date.now() - 120_000)
+          await fs.utimes(lockDir, old, old).catch(() => {})
+          await fs.utimes(path.join(lockDir, "heartbeat"), old, old).catch(() => {})
+          await fs.utimes(path.join(lockDir, "meta.json"), old, old).catch(() => {})
+
+          const done = path.join(tmp, "done.log")
+          const result = await run({ key: "eflock:crash", dir, done, holdMs: 10 })
+          expect(result.code).toBe(0)
+          expect(result.stderr.toString()).toBe("")
+        } finally {
+          await stopWorker(proc).catch(() => {})
+          await fs.rm(tmp, { recursive: true, force: true })
+        }
+      }),
+    30_000,
+  )
+})