chore: initialize qiming workspace repository

qimingcode/packages/core/test/effect/cross-spawn-spawner.test.ts

@@ -0,0 +1,423 @@
+import { describe, expect } from "bun:test"
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { Effect, Exit, Stream } from "effect"
+import type * as PlatformError from "effect/PlatformError"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
+import { testEffect } from "../lib/effect"
+
+const live = CrossSpawnSpawner.defaultLayer
+const fx = testEffect(live)
+
+function js(code: string, opts?: ChildProcess.CommandOptions) {
+  return ChildProcess.make("node", ["-e", code], opts)
+}
+
+function decodeByteStream(stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>) {
+  return Stream.runCollect(stream).pipe(
+    Effect.map((chunks) => {
+      const total = chunks.reduce((acc, x) => acc + x.length, 0)
+      const out = new Uint8Array(total)
+      let off = 0
+      for (const chunk of chunks) {
+        out.set(chunk, off)
+        off += chunk.length
+      }
+      return new TextDecoder("utf-8").decode(out).trim()
+    }),
+  )
+}
+
+function alive(pid: number) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function tmpdir() {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-core-test-"))
+  return {
+    path: dir,
+    async [Symbol.asyncDispose]() {
+      await fs.rm(dir, { recursive: true, force: true })
+    },
+  }
+}
+
+async function gone(pid: number, timeout = 5_000) {
+  const end = Date.now() + timeout
+  while (Date.now() < end) {
+    if (!alive(pid)) return true
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+  return !alive(pid)
+}
+
+describe("cross-spawn spawner", () => {
+  describe("basic spawning", () => {
+    fx.effect(
+      "captures stdout",
+      Effect.gen(function* () {
+        const out = yield* ChildProcessSpawner.ChildProcessSpawner.use((svc) =>
+          svc.string(ChildProcess.make(process.execPath, ["-e", 'process.stdout.write("ok")'])),
+        )
+        expect(out).toBe("ok")
+      }),
+    )
+
+    fx.effect(
+      "captures multiple lines",
+      Effect.gen(function* () {
+        const handle = yield* js('console.log("line1"); console.log("line2"); console.log("line3")')
+        const out = yield* decodeByteStream(handle.stdout)
+        expect(out).toBe("line1\nline2\nline3")
+      }),
+    )
+
+    fx.effect(
+      "returns exit code",
+      Effect.gen(function* () {
+        const handle = yield* js("process.exit(0)")
+        const code = yield* handle.exitCode
+        expect(code).toBe(ChildProcessSpawner.ExitCode(0))
+      }),
+    )
+
+    fx.effect(
+      "returns non-zero exit code",
+      Effect.gen(function* () {
+        const handle = yield* js("process.exit(42)")
+        const code = yield* handle.exitCode
+        expect(code).toBe(ChildProcessSpawner.ExitCode(42))
+      }),
+    )
+  })
+
+  describe("cwd option", () => {
+    fx.effect(
+      "uses cwd when spawning commands",
+      Effect.gen(function* () {
+        const tmp = yield* Effect.acquireRelease(
+          Effect.promise(() => tmpdir()),
+          (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+        )
+        const out = yield* ChildProcessSpawner.ChildProcessSpawner.use((svc) =>
+          svc.string(
+            ChildProcess.make(process.execPath, ["-e", "process.stdout.write(process.cwd())"], { cwd: tmp.path }),
+          ),
+        )
+        expect(out).toBe(tmp.path)
+      }),
+    )
+
+    fx.effect(
+      "fails for invalid cwd",
+      Effect.gen(function* () {
+        const exit = yield* Effect.exit(
+          ChildProcess.make("echo", ["test"], { cwd: "/nonexistent/directory/path" }).asEffect(),
+        )
+        expect(Exit.isFailure(exit)).toBe(true)
+      }),
+    )
+  })
+
+  describe("env option", () => {
+    fx.effect(
+      "passes environment variables with extendEnv",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stdout.write(process.env.TEST_VAR ?? "")', {
+          env: { TEST_VAR: "test_value" },
+          extendEnv: true,
+        })
+        const out = yield* decodeByteStream(handle.stdout)
+        expect(out).toBe("test_value")
+      }),
+    )
+
+    fx.effect(
+      "passes multiple environment variables",
+      Effect.gen(function* () {
+        const handle = yield* js(
+          "process.stdout.write(`${process.env.VAR1}-${process.env.VAR2}-${process.env.VAR3}`)",
+          {
+            env: { VAR1: "one", VAR2: "two", VAR3: "three" },
+            extendEnv: true,
+          },
+        )
+        const out = yield* decodeByteStream(handle.stdout)
+        expect(out).toBe("one-two-three")
+      }),
+    )
+  })
+
+  describe("stderr", () => {
+    fx.effect(
+      "captures stderr output",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stderr.write("error message")')
+        const err = yield* decodeByteStream(handle.stderr)
+        expect(err).toBe("error message")
+      }),
+    )
+
+    fx.effect(
+      "captures both stdout and stderr",
+      Effect.gen(function* () {
+        const handle = yield* js(
+          [
+            "let pending = 2",
+            "const done = () => {",
+            "  pending -= 1",
+            "  if (pending === 0) setTimeout(() => process.exit(0), 0)",
+            "}",
+            'process.stdout.write("stdout\\n", done)',
+            'process.stderr.write("stderr\\n", done)',
+          ].join("\n"),
+        )
+        const [stdout, stderr] = yield* Effect.all([decodeByteStream(handle.stdout), decodeByteStream(handle.stderr)], {
+          concurrency: 2,
+        })
+        expect(stdout).toBe("stdout")
+        expect(stderr).toBe("stderr")
+      }),
+    )
+  })
+
+  describe("combined output (all)", () => {
+    fx.effect(
+      "captures stdout via .all when no stderr",
+      Effect.gen(function* () {
+        const handle = yield* ChildProcess.make("echo", ["hello from stdout"])
+        const all = yield* decodeByteStream(handle.all)
+        expect(all).toBe("hello from stdout")
+      }),
+    )
+
+    fx.effect(
+      "captures stderr via .all when no stdout",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stderr.write("hello from stderr")')
+        const all = yield* decodeByteStream(handle.all)
+        expect(all).toBe("hello from stderr")
+      }),
+    )
+  })
+
+  describe("stdin", () => {
+    fx.effect(
+      "allows providing standard input to a command",
+      Effect.gen(function* () {
+        const input = "a b c"
+        const stdin = Stream.make(Buffer.from(input, "utf-8"))
+        const handle = yield* js(
+          'process.stdin.setEncoding("utf8"); let out = ""; process.stdin.on("data", (chunk) => out += chunk); process.stdin.on("end", () => process.stdout.write(out))',
+          { stdin },
+        )
+        const out = yield* decodeByteStream(handle.stdout)
+        yield* handle.exitCode
+        expect(out).toBe("a b c")
+      }),
+    )
+  })
+
+  describe("process control", () => {
+    fx.effect(
+      "kills a running process",
+      Effect.gen(function* () {
+        const exit = yield* Effect.exit(
+          Effect.gen(function* () {
+            const handle = yield* js("setTimeout(() => {}, 10_000)")
+            yield* handle.kill()
+            return yield* handle.exitCode
+          }),
+        )
+        expect(Exit.isFailure(exit) ? true : exit.value !== ChildProcessSpawner.ExitCode(0)).toBe(true)
+      }),
+    )
+
+    fx.effect(
+      "kills a child when scope exits",
+      Effect.gen(function* () {
+        const pid = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const handle = yield* js("setInterval(() => {}, 10_000)")
+            return Number(handle.pid)
+          }),
+        )
+        const done = yield* Effect.promise(() => gone(pid))
+        expect(done).toBe(true)
+      }),
+    )
+
+    fx.effect(
+      "forceKillAfter escalates for stubborn processes",
+      Effect.gen(function* () {
+        if (process.platform === "win32") return
+
+        const started = Date.now()
+        const exit = yield* Effect.exit(
+          Effect.gen(function* () {
+            const handle = yield* js('process.on("SIGTERM", () => {}); setInterval(() => {}, 10_000)')
+            yield* handle.kill({ forceKillAfter: 100 })
+            return yield* handle.exitCode
+          }),
+        )
+
+        expect(Date.now() - started).toBeLessThan(1_000)
+        expect(Exit.isFailure(exit) ? true : exit.value !== ChildProcessSpawner.ExitCode(0)).toBe(true)
+      }),
+    )
+
+    fx.effect(
+      "isRunning reflects process state",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stdout.write("done")')
+        yield* handle.exitCode
+        const running = yield* handle.isRunning
+        expect(running).toBe(false)
+      }),
+    )
+  })
+
+  describe("error handling", () => {
+    fx.effect(
+      "fails for invalid command",
+      Effect.gen(function* () {
+        const exit = yield* Effect.exit(
+          Effect.gen(function* () {
+            const handle = yield* ChildProcess.make("nonexistent-command-12345")
+            return yield* handle.exitCode
+          }),
+        )
+        expect(Exit.isFailure(exit) ? true : exit.value !== ChildProcessSpawner.ExitCode(0)).toBe(true)
+      }),
+    )
+  })
+
+  describe("pipeline", () => {
+    fx.effect(
+      "pipes stdout of one command to stdin of another",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stdout.write("hello world")').pipe(
+          ChildProcess.pipeTo(
+            js(
+              'process.stdin.setEncoding("utf8"); let out = ""; process.stdin.on("data", (chunk) => out += chunk); process.stdin.on("end", () => process.stdout.write(out.toUpperCase()))',
+            ),
+          ),
+        )
+        const out = yield* decodeByteStream(handle.stdout)
+        yield* handle.exitCode
+        expect(out).toBe("HELLO WORLD")
+      }),
+    )
+
+    fx.effect(
+      "three-stage pipeline",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stdout.write("hello world")').pipe(
+          ChildProcess.pipeTo(
+            js(
+              'process.stdin.setEncoding("utf8"); let out = ""; process.stdin.on("data", (chunk) => out += chunk); process.stdin.on("end", () => process.stdout.write(out.toUpperCase()))',
+            ),
+          ),
+          ChildProcess.pipeTo(
+            js(
+              'process.stdin.setEncoding("utf8"); let out = ""; process.stdin.on("data", (chunk) => out += chunk); process.stdin.on("end", () => process.stdout.write(out.replaceAll(" ", "-")))',
+            ),
+          ),
+        )
+        const out = yield* decodeByteStream(handle.stdout)
+        yield* handle.exitCode
+        expect(out).toBe("HELLO-WORLD")
+      }),
+    )
+
+    fx.effect(
+      "pipes stderr with { from: 'stderr' }",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stderr.write("error")').pipe(
+          ChildProcess.pipeTo(
+            js(
+              'process.stdin.setEncoding("utf8"); let out = ""; process.stdin.on("data", (chunk) => out += chunk); process.stdin.on("end", () => process.stdout.write(out))',
+            ),
+            { from: "stderr" },
+          ),
+        )
+        const out = yield* decodeByteStream(handle.stdout)
+        yield* handle.exitCode
+        expect(out).toBe("error")
+      }),
+    )
+
+    fx.effect(
+      "pipes combined output with { from: 'all' }",
+      Effect.gen(function* () {
+        const handle = yield* js('process.stdout.write("stdout\\n"); process.stderr.write("stderr\\n")').pipe(
+          ChildProcess.pipeTo(
+            js(
+              'process.stdin.setEncoding("utf8"); let out = ""; process.stdin.on("data", (chunk) => out += chunk); process.stdin.on("end", () => process.stdout.write(out))',
+            ),
+            { from: "all" },
+          ),
+        )
+        const out = yield* decodeByteStream(handle.stdout)
+        yield* handle.exitCode
+        expect(out).toContain("stdout")
+        expect(out).toContain("stderr")
+      }),
+    )
+  })
+
+  describe("Windows-specific", () => {
+    fx.effect(
+      "uses shell routing on Windows",
+      Effect.gen(function* () {
+        if (process.platform !== "win32") return
+
+        const out = yield* ChildProcessSpawner.ChildProcessSpawner.use((svc) =>
+          svc.string(
+            ChildProcess.make("set", ["OPENCODE_TEST_SHELL"], {
+              shell: true,
+              extendEnv: true,
+              env: { OPENCODE_TEST_SHELL: "ok" },
+            }),
+          ),
+        )
+        expect(out).toContain("OPENCODE_TEST_SHELL=ok")
+      }),
+    )
+
+    fx.effect(
+      "runs cmd scripts with spaces on Windows without shell",
+      Effect.gen(function* () {
+        if (process.platform !== "win32") return
+
+        const tmp = yield* Effect.acquireRelease(
+          Effect.promise(() => tmpdir()),
+          (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+        )
+        const dir = path.join(tmp.path, "with space")
+        const file = path.join(dir, "echo cmd.cmd")
+
+        yield* Effect.promise(() => fs.mkdir(dir, { recursive: true }))
+        yield* Effect.promise(() => fs.writeFile(file, "@echo off\r\nif %~1==--stdio exit /b 0\r\nexit /b 7\r\n"))
+
+        const code = yield* ChildProcessSpawner.ChildProcessSpawner.use((svc) =>
+          svc.exitCode(
+            ChildProcess.make(file, ["--stdio"], {
+              stdin: "pipe",
+              stdout: "pipe",
+              stderr: "pipe",
+            }),
+          ),
+        )
+        expect(code).toBe(ChildProcessSpawner.ExitCode(0))
+      }),
+    )
+  })
+})

qimingcode/packages/core/test/effect/observability.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { resource } from "@opencode-ai/core/effect/observability"
+
+const otelResourceAttributes = process.env.OTEL_RESOURCE_ATTRIBUTES
+const opencodeClient = process.env.OPENCODE_CLIENT
+
+afterEach(() => {
+  if (otelResourceAttributes === undefined) delete process.env.OTEL_RESOURCE_ATTRIBUTES
+  else process.env.OTEL_RESOURCE_ATTRIBUTES = otelResourceAttributes
+
+  if (opencodeClient === undefined) delete process.env.OPENCODE_CLIENT
+  else process.env.OPENCODE_CLIENT = opencodeClient
+})
+
+describe("resource", () => {
+  test("parses and decodes OTEL resource attributes", () => {
+    process.env.OTEL_RESOURCE_ATTRIBUTES =
+      "service.namespace=anomalyco,team=platform%2Cobservability,label=hello%3Dworld,key%2Fname=value%20here"
+
+    expect(resource().attributes).toMatchObject({
+      "service.namespace": "anomalyco",
+      team: "platform,observability",
+      label: "hello=world",
+      "key/name": "value here",
+    })
+  })
+
+  test("drops OTEL resource attributes when any entry is invalid", () => {
+    process.env.OTEL_RESOURCE_ATTRIBUTES = "service.namespace=anomalyco,broken"
+
+    expect(resource().attributes["service.namespace"]).toBeUndefined()
+    expect(resource().attributes["opencode.client"]).toBeDefined()
+  })
+
+  test("keeps built-in attributes when env values conflict", () => {
+    process.env.OPENCODE_CLIENT = "cli"
+    process.env.OTEL_RESOURCE_ATTRIBUTES =
+      "opencode.client=web,service.instance.id=override,service.namespace=anomalyco"
+
+    expect(resource().attributes).toMatchObject({
+      "opencode.client": "cli",
+      "service.namespace": "anomalyco",
+    })
+    expect(resource().attributes["service.instance.id"]).not.toBe("override")
+  })
+})

qimingcode/packages/core/test/filesystem/filesystem.test.ts

@@ -0,0 +1,338 @@
+import { describe, test, expect } from "bun:test"
+import { Effect, Layer, FileSystem } from "effect"
+import { NodeFileSystem } from "@effect/platform-node"
+import { AppFileSystem } from "@opencode-ai/core/filesystem"
+import { testEffect } from "../lib/effect"
+import path from "path"
+
+const live = AppFileSystem.layer.pipe(Layer.provideMerge(NodeFileSystem.layer))
+const { effect: it } = testEffect(live)
+
+describe("AppFileSystem", () => {
+  describe("isDir", () => {
+    it(
+      "returns true for directories",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        expect(yield* fs.isDir(tmp)).toBe(true)
+      }),
+    )
+
+    it(
+      "returns false for files",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "test.txt")
+        yield* filesys.writeFileString(file, "hello")
+        expect(yield* fs.isDir(file)).toBe(false)
+      }),
+    )
+
+    it(
+      "returns false for non-existent paths",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        expect(yield* fs.isDir("/tmp/nonexistent-" + Math.random())).toBe(false)
+      }),
+    )
+  })
+
+  describe("isFile", () => {
+    it(
+      "returns true for files",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "test.txt")
+        yield* filesys.writeFileString(file, "hello")
+        expect(yield* fs.isFile(file)).toBe(true)
+      }),
+    )
+
+    it(
+      "returns false for directories",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        expect(yield* fs.isFile(tmp)).toBe(false)
+      }),
+    )
+  })
+
+  describe("readJson / writeJson", () => {
+    it(
+      "round-trips JSON data",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "data.json")
+        const data = { name: "test", count: 42, nested: { ok: true } }
+
+        yield* fs.writeJson(file, data)
+        const result = yield* fs.readJson(file)
+
+        expect(result).toEqual(data)
+      }),
+    )
+  })
+
+  describe("ensureDir", () => {
+    it(
+      "creates nested directories",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const nested = path.join(tmp, "a", "b", "c")
+
+        yield* fs.ensureDir(nested)
+
+        const info = yield* filesys.stat(nested)
+        expect(info.type).toBe("Directory")
+      }),
+    )
+
+    it(
+      "is idempotent",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const dir = path.join(tmp, "existing")
+        yield* filesys.makeDirectory(dir)
+
+        yield* fs.ensureDir(dir)
+
+        const info = yield* filesys.stat(dir)
+        expect(info.type).toBe("Directory")
+      }),
+    )
+  })
+
+  describe("writeWithDirs", () => {
+    it(
+      "creates parent directories if missing",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "deep", "nested", "file.txt")
+
+        yield* fs.writeWithDirs(file, "hello")
+
+        expect(yield* filesys.readFileString(file)).toBe("hello")
+      }),
+    )
+
+    it(
+      "writes directly when parent exists",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "direct.txt")
+
+        yield* fs.writeWithDirs(file, "world")
+
+        expect(yield* filesys.readFileString(file)).toBe("world")
+      }),
+    )
+
+    it(
+      "writes Uint8Array content",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "binary.bin")
+        const content = new Uint8Array([0x00, 0x01, 0x02, 0x03])
+
+        yield* fs.writeWithDirs(file, content)
+
+        const result = yield* filesys.readFile(file)
+        expect(new Uint8Array(result)).toEqual(content)
+      }),
+    )
+  })
+
+  describe("findUp", () => {
+    it(
+      "finds target in start directory",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        yield* filesys.writeFileString(path.join(tmp, "target.txt"), "found")
+
+        const result = yield* fs.findUp("target.txt", tmp)
+        expect(result).toEqual([path.join(tmp, "target.txt")])
+      }),
+    )
+
+    it(
+      "finds target in parent directories",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        yield* filesys.writeFileString(path.join(tmp, "marker"), "root")
+        const child = path.join(tmp, "a", "b")
+        yield* filesys.makeDirectory(child, { recursive: true })
+
+        const result = yield* fs.findUp("marker", child, tmp)
+        expect(result).toEqual([path.join(tmp, "marker")])
+      }),
+    )
+
+    it(
+      "returns empty array when not found",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const result = yield* fs.findUp("nonexistent", tmp, tmp)
+        expect(result).toEqual([])
+      }),
+    )
+  })
+
+  describe("up", () => {
+    it(
+      "finds multiple targets walking up",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        yield* filesys.writeFileString(path.join(tmp, "a.txt"), "a")
+        yield* filesys.writeFileString(path.join(tmp, "b.txt"), "b")
+        const child = path.join(tmp, "sub")
+        yield* filesys.makeDirectory(child)
+        yield* filesys.writeFileString(path.join(child, "a.txt"), "a-child")
+
+        const result = yield* fs.up({ targets: ["a.txt", "b.txt"], start: child, stop: tmp })
+
+        expect(result).toContain(path.join(child, "a.txt"))
+        expect(result).toContain(path.join(tmp, "a.txt"))
+        expect(result).toContain(path.join(tmp, "b.txt"))
+      }),
+    )
+  })
+
+  describe("glob", () => {
+    it(
+      "finds files matching pattern",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        yield* filesys.writeFileString(path.join(tmp, "a.ts"), "a")
+        yield* filesys.writeFileString(path.join(tmp, "b.ts"), "b")
+        yield* filesys.writeFileString(path.join(tmp, "c.json"), "c")
+
+        const result = yield* fs.glob("*.ts", { cwd: tmp })
+        expect(result.sort()).toEqual(["a.ts", "b.ts"])
+      }),
+    )
+
+    it(
+      "supports absolute paths",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        yield* filesys.writeFileString(path.join(tmp, "file.txt"), "hello")
+
+        const result = yield* fs.glob("*.txt", { cwd: tmp, absolute: true })
+        expect(result).toEqual([path.join(tmp, "file.txt")])
+      }),
+    )
+  })
+
+  describe("globMatch", () => {
+    it(
+      "matches patterns",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        expect(fs.globMatch("*.ts", "foo.ts")).toBe(true)
+        expect(fs.globMatch("*.ts", "foo.json")).toBe(false)
+        expect(fs.globMatch("src/**", "src/a/b.ts")).toBe(true)
+      }),
+    )
+  })
+
+  describe("globUp", () => {
+    it(
+      "finds files walking up directories",
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        yield* filesys.writeFileString(path.join(tmp, "root.md"), "root")
+        const child = path.join(tmp, "a", "b")
+        yield* filesys.makeDirectory(child, { recursive: true })
+        yield* filesys.writeFileString(path.join(child, "leaf.md"), "leaf")
+
+        const result = yield* fs.globUp("*.md", child, tmp)
+        expect(result).toContain(path.join(child, "leaf.md"))
+        expect(result).toContain(path.join(tmp, "root.md"))
+      }),
+    )
+  })
+
+  describe("built-in passthrough", () => {
+    it(
+      "exists works",
+      Effect.gen(function* () {
+        yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "exists.txt")
+        yield* filesys.writeFileString(file, "yes")
+
+        expect(yield* filesys.exists(file)).toBe(true)
+        expect(yield* filesys.exists(file + ".nope")).toBe(false)
+      }),
+    )
+
+    it(
+      "remove works",
+      Effect.gen(function* () {
+        yield* AppFileSystem.Service
+        const filesys = yield* FileSystem.FileSystem
+        const tmp = yield* filesys.makeTempDirectoryScoped()
+        const file = path.join(tmp, "delete-me.txt")
+        yield* filesys.writeFileString(file, "bye")
+
+        yield* filesys.remove(file)
+
+        expect(yield* filesys.exists(file)).toBe(false)
+      }),
+    )
+  })
+
+  describe("pure helpers", () => {
+    test("mimeType returns correct types", () => {
+      expect(AppFileSystem.mimeType("file.json")).toBe("application/json")
+      expect(AppFileSystem.mimeType("image.png")).toBe("image/png")
+      expect(AppFileSystem.mimeType("unknown.qzx")).toBe("application/octet-stream")
+    })
+
+    test("contains checks path containment", () => {
+      expect(AppFileSystem.contains("/a/b", "/a/b/c")).toBe(true)
+      expect(AppFileSystem.contains("/a/b", "/a/c")).toBe(false)
+    })
+
+    test("overlaps detects overlapping paths", () => {
+      expect(AppFileSystem.overlaps("/a/b", "/a/b/c")).toBe(true)
+      expect(AppFileSystem.overlaps("/a/b/c", "/a/b")).toBe(true)
+      expect(AppFileSystem.overlaps("/a", "/b")).toBe(false)
+    })
+  })
+})

qimingcode/packages/core/test/fixture/effect-flock-worker.ts

@@ -0,0 +1,63 @@
+import fs from "fs/promises"
+import os from "os"
+import { Effect, Layer } from "effect"
+import { AppFileSystem } from "@opencode-ai/core/filesystem"
+import { EffectFlock } from "@opencode-ai/core/util/effect-flock"
+import { Global } from "@opencode-ai/core/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)
+})

qimingcode/packages/core/test/fixture/flock-worker.ts

@@ -0,0 +1,72 @@
+import fs from "fs/promises"
+import { Flock } from "@opencode-ai/core/util/flock"
+
+type Msg = {
+  key: string
+  dir: string
+  staleMs?: number
+  timeoutMs?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  holdMs?: number
+  ready?: string
+  active?: string
+  done?: string
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+function input() {
+  const raw = process.argv[2]
+  if (!raw) {
+    throw new Error("Missing flock worker input")
+  }
+
+  return JSON.parse(raw) as Msg
+}
+
+async function job(input: Msg) {
+  if (input.ready) {
+    await fs.writeFile(input.ready, String(process.pid))
+  }
+
+  if (input.active) {
+    await fs.writeFile(input.active, String(process.pid), { flag: "wx" })
+  }
+
+  try {
+    if (input.holdMs && input.holdMs > 0) {
+      await sleep(input.holdMs)
+    }
+
+    if (input.done) {
+      await fs.appendFile(input.done, "1\n")
+    }
+  } finally {
+    if (input.active) {
+      await fs.rm(input.active, { force: true })
+    }
+  }
+}
+
+async function main() {
+  const msg = input()
+
+  await Flock.withLock(msg.key, () => job(msg), {
+    dir: msg.dir,
+    staleMs: msg.staleMs,
+    timeoutMs: msg.timeoutMs,
+    baseDelayMs: msg.baseDelayMs,
+    maxDelayMs: msg.maxDelayMs,
+  })
+}
+
+await main().catch((err) => {
+  const text = err instanceof Error ? (err.stack ?? err.message) : String(err)
+  process.stderr.write(text)
+  process.exit(1)
+})

qimingcode/packages/core/test/fixture/tmpdir.ts

@@ -0,0 +1,13 @@
+import fs from "fs/promises"
+import { tmpdir as osTmpdir } from "os"
+import path from "path"
+
+export const tmpdir = async () => {
+  const dir = await fs.mkdtemp(path.join(osTmpdir(), "opencode-core-test-"))
+  return {
+    path: dir,
+    async [Symbol.asyncDispose]() {
+      await fs.rm(dir, { recursive: true, force: true })
+    },
+  }
+}

qimingcode/packages/core/test/lib/effect.ts

@@ -0,0 +1,53 @@
+import { test, type TestOptions } from "bun:test"
+import { Cause, Effect, Exit, Layer } from "effect"
+import type * as Scope from "effect/Scope"
+import * as TestClock from "effect/testing/TestClock"
+import * as TestConsole from "effect/testing/TestConsole"
+
+type Body<A, E, R> = Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>)
+
+const body = <A, E, R>(value: Body<A, E, R>) => Effect.suspend(() => (typeof value === "function" ? value() : value))
+
+const run = <A, E, R, E2>(value: Body<A, E, R | Scope.Scope>, layer: Layer.Layer<R, E2>) =>
+  Effect.gen(function* () {
+    const exit = yield* body(value).pipe(Effect.scoped, Effect.provide(layer), Effect.exit)
+    if (Exit.isFailure(exit)) {
+      for (const err of Cause.prettyErrors(exit.cause)) {
+        yield* Effect.logError(err)
+      }
+    }
+    return yield* exit
+  }).pipe(Effect.runPromise)
+
+const make = <R, E>(testLayer: Layer.Layer<R, E>, liveLayer: Layer.Layer<R, E>) => {
+  const effect = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test(name, () => run(value, testLayer), opts)
+
+  effect.only = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.only(name, () => run(value, testLayer), opts)
+
+  effect.skip = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.skip(name, () => run(value, testLayer), opts)
+
+  const live = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test(name, () => run(value, liveLayer), opts)
+
+  live.only = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.only(name, () => run(value, liveLayer), opts)
+
+  live.skip = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.skip(name, () => run(value, liveLayer), opts)
+
+  return { effect, live }
+}
+
+// Test environment with TestClock and TestConsole
+const testEnv = Layer.mergeAll(TestConsole.layer, TestClock.layer())
+
+// Live environment - uses real clock, but keeps TestConsole for output capture
+const liveEnv = TestConsole.layer
+
+export const it = make(testEnv, liveEnv)
+
+export const testEffect = <R, E>(layer: Layer.Layer<R, E>) =>
+  make(Layer.provideMerge(layer, testEnv), Layer.provideMerge(layer, liveEnv))

qimingcode/packages/core/test/npm-config.test.ts

@@ -0,0 +1,51 @@
+import path from "path"
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { NpmConfig } from "@opencode-ai/core/npm-config"
+import { tmpdir } from "./fixture/tmpdir"
+
+describe("NpmConfig.load", () => {
+  test("reads registry from project .npmrc", async () => {
+    await using tmp = await tmpdir()
+    await Bun.write(path.join(tmp.path, ".npmrc"), "registry=https://registry.example.test/\n")
+
+    const config = await Effect.runPromise(NpmConfig.load(tmp.path))
+
+    expect(config.registry).toBe("https://registry.example.test/")
+  })
+
+  test("reads scoped registries from project .npmrc", async () => {
+    await using tmp = await tmpdir()
+    await Bun.write(path.join(tmp.path, ".npmrc"), "@acme:registry=https://npm.acme.test/\n")
+
+    const config = await Effect.runPromise(NpmConfig.load(tmp.path))
+
+    expect(config["@acme:registry"]).toBe("https://npm.acme.test/")
+  })
+
+  test("flattens boolean and list options", async () => {
+    await using tmp = await tmpdir()
+    await Bun.write(path.join(tmp.path, ".npmrc"), "ignore-scripts=true\nomit[]=dev\nomit[]=optional\n")
+
+    const config = await Effect.runPromise(NpmConfig.load(tmp.path))
+
+    expect(config.ignoreScripts).toBe(true)
+    expect(config.omit).toEqual(["dev", "optional"])
+  })
+})
+
+describe("NpmConfig.registry", () => {
+  test("normalizes configured registry without trailing slash", async () => {
+    await using tmp = await tmpdir()
+    await Bun.write(path.join(tmp.path, ".npmrc"), "registry=https://registry.example.test/\n")
+
+    await expect(Effect.runPromise(NpmConfig.registry(tmp.path))).resolves.toBe("https://registry.example.test")
+  })
+
+  test("leaves configured registry without trailing slash unchanged", async () => {
+    await using tmp = await tmpdir()
+    await Bun.write(path.join(tmp.path, ".npmrc"), "registry=https://registry.example.test\n")
+
+    await expect(Effect.runPromise(NpmConfig.registry(tmp.path))).resolves.toBe("https://registry.example.test")
+  })
+})

qimingcode/packages/core/test/npm.test.ts

@@ -0,0 +1,56 @@
+import fs from "fs/promises"
+import path from "path"
+import { describe, expect, test } from "bun:test"
+import { Npm } from "@opencode-ai/core/npm"
+import { tmpdir } from "./fixture/tmpdir"
+
+const win = process.platform === "win32"
+
+const writePackage = (dir: string, pkg: Record<string, unknown>) =>
+  Bun.write(
+    path.join(dir, "package.json"),
+    JSON.stringify({
+      version: "1.0.0",
+      ...pkg,
+    }),
+  )
+
+describe("Npm.sanitize", () => {
+  test("keeps normal scoped package specs unchanged", () => {
+    expect(Npm.sanitize("@opencode/acme")).toBe("@opencode/acme")
+    expect(Npm.sanitize("@opencode/acme@1.0.0")).toBe("@opencode/acme@1.0.0")
+    expect(Npm.sanitize("prettier")).toBe("prettier")
+  })
+
+  test("handles git https specs", () => {
+    const spec = "acme@git+https://github.com/opencode/acme.git"
+    const expected = win ? "acme@git+https_//github.com/opencode/acme.git" : spec
+    expect(Npm.sanitize(spec)).toBe(expected)
+  })
+})
+
+describe("Npm.install", () => {
+  test("respects omit from project .npmrc", async () => {
+    await using tmp = await tmpdir()
+
+    await writePackage(tmp.path, {
+      name: "fixture",
+      dependencies: {
+        "prod-pkg": "file:./prod-pkg",
+      },
+      devDependencies: {
+        "dev-pkg": "file:./dev-pkg",
+      },
+    })
+    await Bun.write(path.join(tmp.path, ".npmrc"), "omit=dev\n")
+    await fs.mkdir(path.join(tmp.path, "prod-pkg"))
+    await fs.mkdir(path.join(tmp.path, "dev-pkg"))
+    await writePackage(path.join(tmp.path, "prod-pkg"), { name: "prod-pkg" })
+    await writePackage(path.join(tmp.path, "dev-pkg"), { name: "dev-pkg" })
+
+    await Npm.install(tmp.path)
+
+    await expect(fs.stat(path.join(tmp.path, "node_modules", "prod-pkg"))).resolves.toBeDefined()
+    await expect(fs.stat(path.join(tmp.path, "node_modules", "dev-pkg"))).rejects.toThrow()
+  })
+})

qimingcode/packages/core/test/util/effect-flock.test.ts

@@ -0,0 +1,389 @@
+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/core/filesystem"
+import { EffectFlock } from "@opencode-ai/core/util/effect-flock"
+import { Global } from "@opencode-ai/core/global"
+import { Hash } from "@opencode-ai/core/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)
+      // oxlint-disable-next-line no-base-to-string -- Exit has a useful toString for test assertions
+      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,
+  )
+})

qimingcode/packages/core/test/util/flock.test.ts

@@ -0,0 +1,426 @@
+import { describe, expect, test } from "bun:test"
+import fs from "fs/promises"
+import { spawn } from "child_process"
+import path from "path"
+import os from "os"
+import { Flock } from "@opencode-ai/core/util/flock"
+import { Hash } from "@opencode-ai/core/util/hash"
+
+type Msg = {
+  key: string
+  dir: string
+  staleMs?: number
+  timeoutMs?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  holdMs?: number
+  ready?: string
+  active?: string
+  done?: string
+}
+
+const root = path.join(import.meta.dir, "../..")
+const worker = path.join(import.meta.dir, "../fixture/flock-worker.ts")
+
+async function tmpdir() {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "flock-test-"))
+  return {
+    path: dir,
+    async [Symbol.asyncDispose]() {
+      await fs.rm(dir, { recursive: true, force: true })
+    },
+  }
+}
+
+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 wait(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}`)
+}
+
+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 readJson<T>(p: string): Promise<T> {
+  return JSON.parse(await fs.readFile(p, "utf8"))
+}
+
+describe("util.flock", () => {
+  test("enforces mutual exclusion under process contention", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const done = path.join(tmp.path, "done.log")
+    const active = path.join(tmp.path, "active")
+    const key = "flock:stress"
+    const n = 16
+
+    const out = await Promise.all(
+      Array.from({ length: n }, () =>
+        run({
+          key,
+          dir,
+          done,
+          active,
+          holdMs: 30,
+          staleMs: 1_000,
+          timeoutMs: 15_000,
+        }),
+      ),
+    )
+
+    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)
+  }, 20_000)
+
+  test("times out while waiting when lock is still healthy", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:timeout"
+    const ready = path.join(tmp.path, "ready")
+    const proc = spawnWorker({
+      key,
+      dir,
+      ready,
+      holdMs: 20_000,
+      staleMs: 10_000,
+      timeoutMs: 30_000,
+    })
+
+    try {
+      await wait(ready, 5_000)
+      const seen: string[] = []
+      const err = await Flock.withLock(key, async () => {}, {
+        dir,
+        staleMs: 10_000,
+        timeoutMs: 1_000,
+        onWait: (tick) => {
+          seen.push(tick.key)
+        },
+      }).catch((err) => err)
+
+      expect(err).toBeInstanceOf(Error)
+      if (!(err instanceof Error)) throw err
+      expect(err.message).toContain("Timed out waiting for lock")
+      expect(seen.length).toBeGreaterThan(0)
+      expect(seen.every((x) => x === key)).toBe(true)
+    } finally {
+      await stopWorker(proc).catch(() => undefined)
+      await new Promise((resolve) => proc.on("close", resolve))
+    }
+  }, 15_000)
+
+  test("recovers after a crashed lock owner", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:crash"
+    const ready = path.join(tmp.path, "ready")
+    const proc = spawnWorker({
+      key,
+      dir,
+      ready,
+      holdMs: 20_000,
+      staleMs: 500,
+      timeoutMs: 30_000,
+    })
+
+    await wait(ready, 5_000)
+    await stopWorker(proc)
+    await new Promise((resolve) => proc.on("close", resolve))
+
+    let hit = false
+    await Flock.withLock(
+      key,
+      async () => {
+        hit = true
+      },
+      {
+        dir,
+        staleMs: 500,
+        timeoutMs: 8_000,
+      },
+    )
+
+    expect(hit).toBe(true)
+  }, 20_000)
+
+  test("breaks stale lock dirs when heartbeat is missing", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:missing-heartbeat"
+    const lockDir = lock(dir, key)
+
+    await fs.mkdir(lockDir, { recursive: true })
+    const old = new Date(Date.now() - 2_000)
+    await fs.utimes(lockDir, old, old)
+
+    let hit = false
+    await Flock.withLock(
+      key,
+      async () => {
+        hit = true
+      },
+      {
+        dir,
+        staleMs: 200,
+        timeoutMs: 3_000,
+      },
+    )
+
+    expect(hit).toBe(true)
+  })
+
+  test("recovers when a stale breaker claim was left behind", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:stale-breaker"
+    const lockDir = lock(dir, key)
+    const breaker = lockDir + ".breaker"
+
+    await fs.mkdir(lockDir, { recursive: true })
+    await fs.mkdir(breaker)
+
+    const old = new Date(Date.now() - 2_000)
+    await fs.utimes(lockDir, old, old)
+    await fs.utimes(breaker, old, old)
+
+    let hit = false
+    await Flock.withLock(
+      key,
+      async () => {
+        hit = true
+      },
+      {
+        dir,
+        staleMs: 200,
+        timeoutMs: 3_000,
+      },
+    )
+
+    expect(hit).toBe(true)
+    expect(await exists(breaker)).toBe(false)
+  })
+
+  test("fails clearly if lock dir is removed while held", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:compromised"
+    const lockDir = lock(dir, key)
+
+    const err = await Flock.withLock(
+      key,
+      async () => {
+        await fs.rm(lockDir, {
+          recursive: true,
+          force: true,
+        })
+      },
+      {
+        dir,
+        staleMs: 1_000,
+        timeoutMs: 3_000,
+      },
+    ).catch((err) => err)
+
+    expect(err).toBeInstanceOf(Error)
+    if (!(err instanceof Error)) throw err
+    expect(err.message).toContain("compromised")
+
+    let hit = false
+    await Flock.withLock(
+      key,
+      async () => {
+        hit = true
+      },
+      {
+        dir,
+        staleMs: 200,
+        timeoutMs: 3_000,
+      },
+    )
+    expect(hit).toBe(true)
+  })
+
+  test("writes owner metadata while lock is held", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:meta"
+    const file = path.join(lock(dir, key), "meta.json")
+
+    await Flock.withLock(
+      key,
+      async () => {
+        const json = await 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")
+      },
+      {
+        dir,
+        staleMs: 1_000,
+        timeoutMs: 3_000,
+      },
+    )
+  })
+
+  test("supports acquire with await using", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:acquire"
+    const lockDir = lock(dir, key)
+
+    {
+      await using _ = await Flock.acquire(key, {
+        dir,
+        staleMs: 1_000,
+        timeoutMs: 3_000,
+      })
+      expect(await exists(lockDir)).toBe(true)
+    }
+
+    expect(await exists(lockDir)).toBe(false)
+  })
+
+  test("refuses token mismatch release and recovers from stale", async () => {
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:token"
+    const lockDir = lock(dir, key)
+    const meta = path.join(lockDir, "meta.json")
+
+    const err = await Flock.withLock(
+      key,
+      async () => {
+        const json = await readJson<{ token?: string }>(meta)
+        json.token = "tampered"
+        await fs.writeFile(meta, JSON.stringify(json, null, 2))
+      },
+      {
+        dir,
+        staleMs: 500,
+        timeoutMs: 3_000,
+      },
+    ).catch((err) => err)
+
+    expect(err).toBeInstanceOf(Error)
+    if (!(err instanceof Error)) throw err
+    expect(err.message).toContain("token mismatch")
+    expect(await exists(lockDir)).toBe(true)
+
+    let hit = false
+    await Flock.withLock(
+      key,
+      async () => {
+        hit = true
+      },
+      {
+        dir,
+        staleMs: 500,
+        timeoutMs: 6_000,
+      },
+    )
+    expect(hit).toBe(true)
+  })
+
+  test("fails clearly on unwritable lock roots", async () => {
+    if (process.platform === "win32") return
+
+    await using tmp = await tmpdir()
+    const dir = path.join(tmp.path, "locks")
+    const key = "flock:perm"
+
+    await fs.mkdir(dir, { recursive: true })
+    await fs.chmod(dir, 0o500)
+
+    try {
+      const err = await Flock.withLock(key, async () => {}, {
+        dir,
+        staleMs: 100,
+        timeoutMs: 500,
+      }).catch((err) => err)
+
+      expect(err).toBeInstanceOf(Error)
+      if (!(err instanceof Error)) throw err
+      const text = err.message
+      expect(text.includes("EACCES") || text.includes("EPERM")).toBe(true)
+    } finally {
+      await fs.chmod(dir, 0o700)
+    }
+  })
+})