diff --git a/bun.lock b/bun.lock
index fe5d42d7cc..a6f9891dd1 100644
--- a/bun.lock
+++ b/bun.lock
@@ -527,9 +527,11 @@
         "mime-types": "3.0.2",
         "minimatch": "10.2.5",
         "semver": "catalog:",
+        "xdg-basedir": "5.1.0",
         "zod": "catalog:",
       },
       "devDependencies": {
+        "@types/bun": "catalog:",
         "@types/semver": "catalog:",
       },
     },
diff --git a/packages/opencode/src/acp/agent.ts b/packages/opencode/src/acp/agent.ts
index 09f8663ed0..8ac09e4bb3 100644
--- a/packages/opencode/src/acp/agent.ts
+++ b/packages/opencode/src/acp/agent.ts
@@ -34,7 +34,7 @@ import {
 import { Log } from "../util/log"
 import { pathToFileURL } from "url"
 import { Filesystem } from "../util/filesystem"
-import { Hash } from "../util/hash"
+import { Hash } from "@opencode-ai/shared/util/hash"
 import { ACPSessionManager } from "./session"
 import type { ACPConfig } from "./types"
 import { Provider } from "../provider/provider"
diff --git a/packages/opencode/src/cli/cmd/tui/plugin/runtime.ts b/packages/opencode/src/cli/cmd/tui/plugin/runtime.ts
index 2f7fd51643..7f12106b2c 100644
--- a/packages/opencode/src/cli/cmd/tui/plugin/runtime.ts
+++ b/packages/opencode/src/cli/cmd/tui/plugin/runtime.ts
@@ -34,7 +34,7 @@ import { hasTheme, upsertTheme } from "../context/theme"
 import { Global } from "@/global"
 import { Filesystem } from "@/util/filesystem"
 import { Process } from "@/util/process"
-import { Flock } from "@/util/flock"
+import { Flock } from "@opencode-ai/shared/util/flock"
 import { Flag } from "@/flag/flag"
 import { INTERNAL_TUI_PLUGINS, type InternalTuiPlugin } from "./internal"
 import { setupSlots, Slot as View } from "./slots"
diff --git a/packages/opencode/src/config/config.ts b/packages/opencode/src/config/config.ts
index f8205bac26..915e604e90 100644
--- a/packages/opencode/src/config/config.ts
+++ b/packages/opencode/src/config/config.ts
@@ -34,7 +34,7 @@ import type { ConsoleState } from "./console-state"
 import { AppFileSystem } from "@opencode-ai/shared/filesystem"
 import { InstanceState } from "@/effect/instance-state"
 import { Context, Duration, Effect, Exit, Fiber, Layer, Option } from "effect"
-import { Flock } from "@/util/flock"
+import { Flock } from "@opencode-ai/shared/util/flock"
 import { isPathPluginSpec, parsePluginSpecifier, resolvePathPluginTarget } from "@/plugin/shared"
 import { Npm } from "../npm"
 import { InstanceRef } from "@/effect/instance-ref"
diff --git a/packages/opencode/src/global/index.ts b/packages/opencode/src/global/index.ts
index 869019e2ce..32d5153213 100644
--- a/packages/opencode/src/global/index.ts
+++ b/packages/opencode/src/global/index.ts
@@ -3,6 +3,7 @@ import { xdgData, xdgCache, xdgConfig, xdgState } from "xdg-basedir"
 import path from "path"
 import os from "os"
 import { Filesystem } from "../util/filesystem"
+import { Flock } from "@opencode-ai/shared/util/flock"
 
 const app = "opencode"
 
@@ -26,6 +27,9 @@ export namespace Global {
   }
 }
 
+// Initialize Flock with global state path
+Flock.setGlobal({ state })
+
 await Promise.all([
   fs.mkdir(Global.Path.data, { recursive: true }),
   fs.mkdir(Global.Path.config, { recursive: true }),
diff --git a/packages/opencode/src/npm/index.ts b/packages/opencode/src/npm/index.ts
index 5b708431c6..e648fd899c 100644
--- a/packages/opencode/src/npm/index.ts
+++ b/packages/opencode/src/npm/index.ts
@@ -6,7 +6,7 @@ import { Log } from "../util/log"
 import path from "path"
 import { readdir, rm } from "fs/promises"
 import { Filesystem } from "@/util/filesystem"
-import { Flock } from "@/util/flock"
+import { Flock } from "@opencode-ai/shared/util/flock"
 import { Arborist } from "@npmcli/arborist"
 
 export namespace Npm {
diff --git a/packages/opencode/src/plugin/install.ts b/packages/opencode/src/plugin/install.ts
index b6bac42a7f..8dd8212965 100644
--- a/packages/opencode/src/plugin/install.ts
+++ b/packages/opencode/src/plugin/install.ts
@@ -10,7 +10,7 @@ import {
 import { ConfigPaths } from "@/config/paths"
 import { Global } from "@/global"
 import { Filesystem } from "@/util/filesystem"
-import { Flock } from "@/util/flock"
+import { Flock } from "@opencode-ai/shared/util/flock"
 import { isRecord } from "@/util/record"
 
 import { parsePluginSpecifier, readPackageThemes, readPluginPackage, resolvePluginTarget } from "./shared"
diff --git a/packages/opencode/src/plugin/meta.ts b/packages/opencode/src/plugin/meta.ts
index cbfaf6ae15..f408954690 100644
--- a/packages/opencode/src/plugin/meta.ts
+++ b/packages/opencode/src/plugin/meta.ts
@@ -4,7 +4,7 @@ import { fileURLToPath } from "url"
 import { Flag } from "@/flag/flag"
 import { Global } from "@/global"
 import { Filesystem } from "@/util/filesystem"
-import { Flock } from "@/util/flock"
+import { Flock } from "@opencode-ai/shared/util/flock"
 
 import { parsePluginSpecifier, pluginSource } from "./shared"
 
diff --git a/packages/opencode/src/provider/models.ts b/packages/opencode/src/provider/models.ts
index 2d787588b0..55f137aa0b 100644
--- a/packages/opencode/src/provider/models.ts
+++ b/packages/opencode/src/provider/models.ts
@@ -6,8 +6,8 @@ import { Installation } from "../installation"
 import { Flag } from "../flag/flag"
 import { lazy } from "@/util/lazy"
 import { Filesystem } from "../util/filesystem"
-import { Flock } from "@/util/flock"
-import { Hash } from "@/util/hash"
+import { Flock } from "@opencode-ai/shared/util/flock"
+import { Hash } from "@opencode-ai/shared/util/hash"
 
 // Try to import bundled snapshot (generated at build time)
 // Falls back to undefined in dev mode when snapshot doesn't exist
diff --git a/packages/opencode/src/provider/provider.ts b/packages/opencode/src/provider/provider.ts
index 8833cfd05f..9ec5dfc6b5 100644
--- a/packages/opencode/src/provider/provider.ts
+++ b/packages/opencode/src/provider/provider.ts
@@ -6,7 +6,7 @@ import { mapValues, mergeDeep, omit, pickBy, sortBy } from "remeda"
 import { NoSuchModelError, type Provider as SDK } from "ai"
 import { Log } from "../util/log"
 import { Npm } from "../npm"
-import { Hash } from "../util/hash"
+import { Hash } from "@opencode-ai/shared/util/hash"
 import { Plugin } from "../plugin"
 import { NamedError } from "@opencode-ai/shared/util/error"
 import { type LanguageModelV3 } from "@ai-sdk/provider"
diff --git a/packages/opencode/src/snapshot/index.ts b/packages/opencode/src/snapshot/index.ts
index 2b21f7e895..9378e309aa 100644
--- a/packages/opencode/src/snapshot/index.ts
+++ b/packages/opencode/src/snapshot/index.ts
@@ -6,7 +6,7 @@ import z from "zod"
 import * as CrossSpawnSpawner from "@/effect/cross-spawn-spawner"
 import { InstanceState } from "@/effect/instance-state"
 import { AppFileSystem } from "@opencode-ai/shared/filesystem"
-import { Hash } from "@/util/hash"
+import { Hash } from "@opencode-ai/shared/util/hash"
 import { Config } from "../config/config"
 import { Global } from "../global"
 import { Log } from "../util/log"
diff --git a/packages/opencode/test/fixture/flock-worker.ts b/packages/opencode/test/fixture/flock-worker.ts
index ac05fe810c..9954d290cc 100644
--- a/packages/opencode/test/fixture/flock-worker.ts
+++ b/packages/opencode/test/fixture/flock-worker.ts
@@ -1,5 +1,5 @@
 import fs from "fs/promises"
-import { Flock } from "../../src/util/flock"
+import { Flock } from "@opencode-ai/shared/util/flock"
 
 type Msg = {
   key: string
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 1bb1ca47ef..252b381d48 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -5,7 +5,9 @@
   "type": "module",
   "license": "MIT",
   "private": true,
-  "scripts": {},
+  "scripts": {
+    "test": "bun test"
+  },
   "bin": {
     "opencode": "./bin/opencode"
   },
@@ -14,7 +16,8 @@
   },
   "imports": {},
   "devDependencies": {
-    "@types/semver": "catalog:"
+    "@types/semver": "catalog:",
+    "@types/bun": "catalog:"
   },
   "dependencies": {
     "@effect/platform-node": "catalog:",
@@ -23,6 +26,7 @@
     "mime-types": "3.0.2",
     "minimatch": "10.2.5",
     "semver": "catalog:",
+    "xdg-basedir": "5.1.0",
     "zod": "catalog:"
   },
   "overrides": {
diff --git a/packages/shared/src/global.ts b/packages/shared/src/global.ts
new file mode 100644
index 0000000000..538cc091b5
--- /dev/null
+++ b/packages/shared/src/global.ts
@@ -0,0 +1,42 @@
+import path from "path"
+import { xdgData, xdgCache, xdgConfig, xdgState } from "xdg-basedir"
+import os from "os"
+import { Context, Effect, Layer } from "effect"
+
+export namespace Global {
+  export class Service extends Context.Service<Service, Interface>()("@opencode/Global") {}
+
+  export interface Interface {
+    readonly home: string
+    readonly data: string
+    readonly cache: string
+    readonly config: string
+    readonly state: string
+    readonly bin: string
+    readonly log: string
+  }
+
+  export const layer = Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const app = "opencode"
+      const home = process.env.OPENCODE_TEST_HOME ?? os.homedir()
+      const data = path.join(xdgData!, app)
+      const cache = path.join(xdgCache!, app)
+      const cfg = path.join(xdgConfig!, app)
+      const state = path.join(xdgState!, app)
+      const bin = path.join(cache, "bin")
+      const log = path.join(data, "log")
+
+      return Service.of({
+        home,
+        data,
+        cache,
+        config: cfg,
+        state,
+        bin,
+        log,
+      })
+    }),
+  )
+}
diff --git a/packages/shared/src/npm.ts b/packages/shared/src/npm.ts
new file mode 100644
index 0000000000..994ec04dae
--- /dev/null
+++ b/packages/shared/src/npm.ts
@@ -0,0 +1,247 @@
+import path from "path"
+import semver from "semver"
+import { Arborist } from "@npmcli/arborist"
+import { Effect, Schema, Context, Layer, Option, FileSystem } from "effect"
+import { NodeFileSystem } from "@effect/platform-node"
+import { AppFileSystem } from "./filesystem"
+import { Global } from "./global"
+import { Flock } from "./util/flock"
+
+export namespace Npm {
+  export class InstallFailedError extends Schema.TaggedErrorClass<InstallFailedError>()("NpmInstallFailedError", {
+    pkg: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  }) {}
+
+  export interface EntryPoint {
+    readonly directory: string
+    readonly entrypoint: Option.Option<string>
+  }
+
+  export interface Interface {
+    readonly add: (pkg: string) => Effect.Effect<EntryPoint, InstallFailedError>
+    readonly install: (dir: string) => Effect.Effect<void>
+    readonly outdated: (pkg: string, cachedVersion: string) => Effect.Effect<boolean>
+    readonly which: (pkg: string) => Effect.Effect<Option.Option<string>>
+  }
+
+  export class Service extends Context.Service<Service, Interface>()("@opencode/Npm") {}
+
+  const illegal = process.platform === "win32" ? new Set(["<", ">", ":", '"', "|", "?", "*"]) : undefined
+
+  export function sanitize(pkg: string) {
+    if (!illegal) return pkg
+    return Array.from(pkg, (char) => (illegal.has(char) || char.charCodeAt(0) < 32 ? "_" : char)).join("")
+  }
+
+  const resolveEntryPoint = (name: string, dir: string): EntryPoint => {
+    let entrypoint: Option.Option<string>
+    try {
+      const resolved = typeof Bun !== "undefined" ? import.meta.resolve(name, dir) : import.meta.resolve(dir)
+      entrypoint = Option.some(resolved)
+    } catch {
+      entrypoint = Option.none()
+    }
+    return {
+      directory: dir,
+      entrypoint,
+    }
+  }
+
+  interface ArboristNode {
+    name: string
+    path: string
+  }
+
+  interface ArboristTree {
+    edgesOut: Map<string, { to?: ArboristNode }>
+  }
+  export const layer = Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const afs = yield* AppFileSystem.Service
+      const global = yield* Global.Service
+      const fs = yield* FileSystem.FileSystem
+      const directory = (pkg: string) => path.join(global.cache, "packages", sanitize(pkg))
+
+      const outdated = Effect.fn("Npm.outdated")(function* (pkg: string, cachedVersion: string) {
+        const response = yield* Effect.tryPromise({
+          try: () => fetch(`https://registry.npmjs.org/${pkg}`),
+          catch: () => undefined,
+        }).pipe(Effect.orElseSucceed(() => undefined))
+
+        if (!response || !response.ok) {
+          return false
+        }
+
+        const data = yield* Effect.tryPromise({
+          try: () => response.json() as Promise<{ "dist-tags"?: { latest?: string } }>,
+          catch: () => undefined,
+        }).pipe(Effect.orElseSucceed(() => undefined))
+
+        const latestVersion = data?.["dist-tags"]?.latest
+        if (!latestVersion) {
+          return false
+        }
+
+        const range = /[\s^~*xX<>|=]/.test(cachedVersion)
+        if (range) return !semver.satisfies(latestVersion, cachedVersion)
+
+        return semver.lt(cachedVersion, latestVersion)
+      })
+
+      const add = Effect.fn("Npm.add")(function* (pkg: string) {
+        const dir = directory(pkg)
+        yield* Flock.effect(`npm-install:${dir}`)
+
+        const arborist = new Arborist({
+          path: dir,
+          binLinks: true,
+          progress: false,
+          savePrefix: "",
+          ignoreScripts: true,
+        })
+
+        const tree = yield* Effect.tryPromise({
+          try: () => arborist.loadVirtual().catch(() => undefined),
+          catch: () => undefined,
+        }).pipe(Effect.orElseSucceed(() => undefined)) as Effect.Effect<ArboristTree | undefined>
+
+        if (tree) {
+          const first = tree.edgesOut.values().next().value?.to
+          if (first) {
+            return resolveEntryPoint(first.name, first.path)
+          }
+        }
+
+        const result = yield* Effect.tryPromise({
+          try: () =>
+            arborist.reify({
+              add: [pkg],
+              save: true,
+              saveType: "prod",
+            }),
+          catch: (cause) => new InstallFailedError({ pkg, cause }),
+        }) as Effect.Effect<ArboristTree, InstallFailedError>
+
+        const first = result.edgesOut.values().next().value?.to
+        if (!first) {
+          return yield* new InstallFailedError({ pkg })
+        }
+
+        return resolveEntryPoint(first.name, first.path)
+      }, Effect.scoped)
+
+      const install = Effect.fn("Npm.install")(function* (dir: string) {
+        yield* Flock.effect(`npm-install:${dir}`)
+
+        const reify = Effect.fnUntraced(function* () {
+          const arb = new Arborist({
+            path: dir,
+            binLinks: true,
+            progress: false,
+            savePrefix: "",
+            ignoreScripts: true,
+          })
+          yield* Effect.tryPromise({
+            try: () => arb.reify().catch(() => {}),
+            catch: () => {},
+          }).pipe(Effect.orElseSucceed(() => {}))
+        })
+
+        const nodeModulesExists = yield* afs.existsSafe(path.join(dir, "node_modules"))
+        if (!nodeModulesExists) {
+          yield* reify()
+          return
+        }
+
+        const pkg = yield* afs.readJson(path.join(dir, "package.json")).pipe(Effect.orElseSucceed(() => ({})))
+        const lock = yield* afs.readJson(path.join(dir, "package-lock.json")).pipe(Effect.orElseSucceed(() => ({})))
+
+        const pkgAny = pkg as any
+        const lockAny = lock as any
+
+        const declared = new Set([
+          ...Object.keys(pkgAny?.dependencies || {}),
+          ...Object.keys(pkgAny?.devDependencies || {}),
+          ...Object.keys(pkgAny?.peerDependencies || {}),
+          ...Object.keys(pkgAny?.optionalDependencies || {}),
+        ])
+
+        const root = lockAny?.packages?.[""] || {}
+        const locked = new Set([
+          ...Object.keys(root?.dependencies || {}),
+          ...Object.keys(root?.devDependencies || {}),
+          ...Object.keys(root?.peerDependencies || {}),
+          ...Object.keys(root?.optionalDependencies || {}),
+        ])
+
+        for (const name of declared) {
+          if (!locked.has(name)) {
+            yield* reify()
+            return
+          }
+        }
+      }, Effect.scoped)
+
+      const which = Effect.fn("Npm.which")(function* (pkg: string) {
+        const dir = directory(pkg)
+        const binDir = path.join(dir, "node_modules", ".bin")
+
+        const pick = Effect.fnUntraced(function* () {
+          const files = yield* fs.readDirectory(binDir).pipe(Effect.catch(() => Effect.succeed([] as string[])))
+
+          if (files.length === 0) return Option.none<string>()
+          if (files.length === 1) return Option.some(files[0])
+
+          const pkgJson = yield* afs.readJson(path.join(dir, "node_modules", pkg, "package.json")).pipe(Effect.option)
+
+          if (Option.isSome(pkgJson)) {
+            const parsed = pkgJson.value as { bin?: string | Record<string, string> }
+            if (parsed?.bin) {
+              const unscoped = pkg.startsWith("@") ? pkg.split("/")[1] : pkg
+              const bin = parsed.bin
+              if (typeof bin === "string") return Option.some(unscoped)
+              const keys = Object.keys(bin)
+              if (keys.length === 1) return Option.some(keys[0])
+              return bin[unscoped] ? Option.some(unscoped) : Option.some(keys[0])
+            }
+          }
+
+          return Option.some(files[0])
+        })
+
+        return yield* Effect.gen(function* () {
+          const bin = yield* pick()
+          if (Option.isSome(bin)) {
+            return Option.some(path.join(binDir, bin.value))
+          }
+
+          yield* fs.remove(path.join(dir, "package-lock.json")).pipe(Effect.orElseSucceed(() => {}))
+
+          yield* add(pkg)
+
+          const resolved = yield* pick()
+          if (Option.isNone(resolved)) return Option.none<string>()
+          return Option.some(path.join(binDir, resolved.value))
+        }).pipe(
+          Effect.scoped,
+          Effect.orElseSucceed(() => Option.none<string>()),
+        )
+      })
+
+      return Service.of({
+        add,
+        install,
+        outdated,
+        which,
+      })
+    }),
+  )
+
+  export const defaultLayer = layer.pipe(
+    Layer.provide(AppFileSystem.layer),
+    Layer.provide(Global.layer),
+    Layer.provide(NodeFileSystem.layer),
+  )
+}
diff --git a/packages/shared/src/types.d.ts b/packages/shared/src/types.d.ts
new file mode 100644
index 0000000000..b5d667f1d9
--- /dev/null
+++ b/packages/shared/src/types.d.ts
@@ -0,0 +1,44 @@
+declare module "@npmcli/arborist" {
+  export interface ArboristOptions {
+    path: string
+    binLinks?: boolean
+    progress?: boolean
+    savePrefix?: string
+    ignoreScripts?: boolean
+  }
+
+  export interface ArboristNode {
+    name: string
+    path: string
+  }
+
+  export interface ArboristEdge {
+    to?: ArboristNode
+  }
+
+  export interface ArboristTree {
+    edgesOut: Map<string, ArboristEdge>
+  }
+
+  export interface ReifyOptions {
+    add?: string[]
+    save?: boolean
+    saveType?: "prod" | "dev" | "optional" | "peer"
+  }
+
+  export class Arborist {
+    constructor(options: ArboristOptions)
+    loadVirtual(): Promise<ArboristTree | undefined>
+    reify(options?: ReifyOptions): Promise<ArboristTree>
+  }
+}
+
+declare var Bun:
+  | {
+      file(path: string): {
+        text(): Promise<string>
+        json(): Promise<unknown>
+      }
+      write(path: string, content: string | Uint8Array): Promise<void>
+    }
+  | undefined
diff --git a/packages/opencode/src/util/flock.ts b/packages/shared/src/util/flock.ts
similarity index 93%
rename from packages/opencode/src/util/flock.ts
rename to packages/shared/src/util/flock.ts
index 74c7905ebb..4a1df1dee7 100644
--- a/packages/opencode/src/util/flock.ts
+++ b/packages/shared/src/util/flock.ts
@@ -2,11 +2,25 @@ import path from "path"
 import os from "os"
 import { randomBytes, randomUUID } from "crypto"
 import { mkdir, readFile, rm, stat, utimes, writeFile } from "fs/promises"
-import { Global } from "@/global"
-import { Hash } from "@/util/hash"
+import { Hash } from "./hash"
+import { Effect } from "effect"
+
+export type FlockGlobal = {
+  state: string
+}
 
 export namespace Flock {
-  const root = path.join(Global.Path.state, "locks")
+  let global: FlockGlobal | undefined
+
+  export function setGlobal(g: FlockGlobal) {
+    global = g
+  }
+
+  const root = () => {
+    if (!global) throw new Error("Flock global not set")
+    return path.join(global.state, "locks")
+  }
+
   // Defaults for callers that do not provide timing options.
   const defaultOpts = {
     staleMs: 60_000,
@@ -301,7 +315,7 @@ export namespace Flock {
       baseDelayMs: input.baseDelayMs ?? defaultOpts.baseDelayMs,
       maxDelayMs: input.maxDelayMs ?? defaultOpts.maxDelayMs,
     }
-    const dir = input.dir ?? root
+    const dir = input.dir ?? root()
 
     await mkdir(dir, { recursive: true })
     const lockfile = path.join(dir, Hash.fast(key) + ".lock")
@@ -330,4 +344,11 @@ export namespace Flock {
     input.signal?.throwIfAborted()
     return await fn()
   }
+
+  export const effect = Effect.fn("Flock.effect")(function* (key: string) {
+    return yield* Effect.acquireRelease(
+      Effect.promise((signal) => Flock.acquire(key, { signal })),
+      (foo) => Effect.promise(() => foo.release()),
+    ).pipe(Effect.asVoid)
+  })
 }
diff --git a/packages/opencode/src/util/hash.ts b/packages/shared/src/util/hash.ts
similarity index 100%
rename from packages/opencode/src/util/hash.ts
rename to packages/shared/src/util/hash.ts
diff --git a/packages/shared/test/filesystem/filesystem.test.ts b/packages/shared/test/filesystem/filesystem.test.ts
new file mode 100644
index 0000000000..ce990d3795
--- /dev/null
+++ b/packages/shared/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/shared/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* () {
+        const fs = 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* () {
+        const fs = 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)
+    })
+  })
+})
diff --git a/packages/shared/test/fixture/flock-worker.ts b/packages/shared/test/fixture/flock-worker.ts
new file mode 100644
index 0000000000..9954d290cc
--- /dev/null
+++ b/packages/shared/test/fixture/flock-worker.ts
@@ -0,0 +1,72 @@
+import fs from "fs/promises"
+import { Flock } from "@opencode-ai/shared/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)
+})
diff --git a/packages/shared/test/lib/effect.ts b/packages/shared/test/lib/effect.ts
new file mode 100644
index 0000000000..131ec5cc6b
--- /dev/null
+++ b/packages/shared/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))
diff --git a/packages/shared/test/npm.test.ts b/packages/shared/test/npm.test.ts
new file mode 100644
index 0000000000..4443d2985c
--- /dev/null
+++ b/packages/shared/test/npm.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test"
+import { Npm } from "@opencode-ai/shared/npm"
+
+const win = process.platform === "win32"
+
+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)
+  })
+})
diff --git a/packages/opencode/test/util/flock.test.ts b/packages/shared/test/util/flock.test.ts
similarity index 80%
rename from packages/opencode/test/util/flock.test.ts
rename to packages/shared/test/util/flock.test.ts
index fedbfb0697..f1053dfd2b 100644
--- a/packages/opencode/test/util/flock.test.ts
+++ b/packages/shared/test/util/flock.test.ts
@@ -1,14 +1,10 @@
 import { describe, expect, test } from "bun:test"
 import fs from "fs/promises"
+import { spawn } from "child_process"
 import path from "path"
-import { Flock } from "../../src/util/flock"
-import { Hash } from "../../src/util/hash"
-import { Process } from "../../src/util/process"
-import { Filesystem } from "../../src/util/filesystem"
-import { tmpdir } from "../fixture/fixture"
-
-const root = path.join(import.meta.dir, "../..")
-const worker = path.join(import.meta.dir, "../fixture/flock-worker.ts")
+import os from "os"
+import { Flock } from "@opencode-ai/shared/util/flock"
+import { Hash } from "@opencode-ai/shared/util/hash"
 
 type Msg = {
   key: string
@@ -23,6 +19,19 @@ type Msg = {
   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")
 }
@@ -51,21 +60,55 @@ async function wait(file: string, timeout = 3_000) {
 }
 
 function run(msg: Msg) {
-  return Process.run([process.execPath, worker, JSON.stringify(msg)], {
-    cwd: root,
-    nothrow: true,
+  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 spawn(msg: Msg) {
-  return Process.spawn([process.execPath, worker, JSON.stringify(msg)], {
+function spawnWorker(msg: Msg) {
+  return spawn(process.execPath, [worker, JSON.stringify(msg)], {
     cwd: root,
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
+    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()
@@ -104,7 +147,7 @@ describe("util.flock", () => {
     const dir = path.join(tmp.path, "locks")
     const key = "flock:timeout"
     const ready = path.join(tmp.path, "ready")
-    const proc = spawn({
+    const proc = spawnWorker({
       key,
       dir,
       ready,
@@ -131,8 +174,8 @@ describe("util.flock", () => {
       expect(seen.length).toBeGreaterThan(0)
       expect(seen.every((x) => x === key)).toBe(true)
     } finally {
-      await Process.stop(proc).catch(() => undefined)
-      await proc.exited.catch(() => undefined)
+      await stopWorker(proc).catch(() => undefined)
+      await new Promise((resolve) => proc.on("close", resolve))
     }
   }, 15_000)
 
@@ -141,7 +184,7 @@ describe("util.flock", () => {
     const dir = path.join(tmp.path, "locks")
     const key = "flock:crash"
     const ready = path.join(tmp.path, "ready")
-    const proc = spawn({
+    const proc = spawnWorker({
       key,
       dir,
       ready,
@@ -151,8 +194,8 @@ describe("util.flock", () => {
     })
 
     await wait(ready, 5_000)
-    await Process.stop(proc)
-    await proc.exited.catch(() => undefined)
+    await stopWorker(proc)
+    await new Promise((resolve) => proc.on("close", resolve))
 
     let hit = false
     await Flock.withLock(
@@ -276,7 +319,7 @@ describe("util.flock", () => {
     await Flock.withLock(
       key,
       async () => {
-        const json = await Filesystem.readJson<{
+        const json = await readJson<{
           token?: unknown
           pid?: unknown
           hostname?: unknown
@@ -324,7 +367,7 @@ describe("util.flock", () => {
     const err = await Flock.withLock(
       key,
       async () => {
-        const json = await Filesystem.readJson<{ token?: string }>(meta)
+        const json = await readJson<{ token?: string }>(meta)
         json.token = "tampered"
         await fs.writeFile(meta, JSON.stringify(json, null, 2))
       },