feat(core): discover AGENTS.md up to the home directory

packages/core/package.json

@@ -25,7 +25,6 @@
   },
   "imports": {
     "#sqlite": {
-      "workerd": "./src/database/sqlite.workerd.ts",
       "bun": "./src/database/sqlite.bun.ts",
       "node": "./src/database/sqlite.node.ts",
       "default": "./src/database/sqlite.bun.ts"

packages/core/src/config/plugin/instruction.ts

@@ -27,8 +27,10 @@ export const Plugin = define({
       const changes = yield* PubSub.sliding<string>(1)
       const lock = Semaphore.makeUnsafe(1)
       const start = yield* fs.resolve(location.directory)
-      const stop = yield* fs.resolve(location.project.directory)
-      const project = discovery.project && FSUtil.contains(stop, start)
+      const root = yield* fs.resolve(location.project.directory)
+      const home = yield* fs.resolve(global.home)
+      const project = discovery.project && FSUtil.contains(root, start)
+      const stop = FSUtil.contains(home, start) ? home : root
       const globalFile = yield* fs.resolve(join(global.config, "AGENTS.md"))
       const loaded: { current: Loaded } = { current: { type: "available", files: [] } }
 

packages/core/src/database/database.ts

@@ -1,9 +1,8 @@
 export * as Database from "./database"
 
 import { EffectDrizzleSqlite } from "@opencode-ai/effect-drizzle-sqlite"
-import { sqliteLayer, supportsForeignKeyToggle, supportsTuningPragmas } from "#sqlite"
+import { sqliteLayer } from "#sqlite"
 import { Context, Effect, Layer, Schema } from "effect"
-import type { SqlClient } from "effect/unstable/sql"
 import { Global } from "@opencode-ai/util/global"
 import { isAbsolute, join } from "path"
 import { DatabaseMigration } from "./migration"
@@ -28,15 +27,12 @@ const databaseLayer = Layer.effect(
   Effect.gen(function* () {
     const db = yield* makeDatabase
 
-    if (supportsTuningPragmas) {
-      yield* db.run("PRAGMA journal_mode = WAL")
-      yield* db.run("PRAGMA synchronous = NORMAL")
-      yield* db.run("PRAGMA busy_timeout = 5000")
-      yield* db.run("PRAGMA cache_size = -64000")
-      yield* db.run("PRAGMA wal_checkpoint(PASSIVE)")
-    }
-    // Durable Object SQLite always enforces foreign keys and rejects the pragma.
-    if (supportsForeignKeyToggle) yield* db.run("PRAGMA foreign_keys = ON")
+    yield* db.run("PRAGMA journal_mode = WAL")
+    yield* db.run("PRAGMA synchronous = NORMAL")
+    yield* db.run("PRAGMA busy_timeout = 5000")
+    yield* db.run("PRAGMA cache_size = -64000")
+    yield* db.run("PRAGMA foreign_keys = ON")
+    yield* db.run("PRAGMA wal_checkpoint(PASSIVE)")
     yield* DatabaseMigration.apply(db)
 
     return { db }
@@ -47,19 +43,14 @@ export function layer(options: Options = { path: ":memory:" }) {
   return Layer.unwrap(
     Effect.gen(function* () {
       const global = yield* Global.Service
+      const provide = (filename: string) => databaseLayer.pipe(Layer.provide(sqliteLayer({ filename })))
       const filename = options.path ?? ":memory:"
-      if (filename === ":memory:" || isAbsolute(filename)) return layerWith(sqliteLayer({ filename }))
-      return layerWith(sqliteLayer({ filename: join(global.data, filename) }))
+      if (filename === ":memory:" || isAbsolute(filename)) return provide(filename)
+      return provide(join(global.data, filename))
     }),
   )
 }
 
-// Builds the database service over an already-configured SqlClient layer for
-// runtimes that receive database storage instead of opening a filesystem path.
-export function layerWith(sqlite: Layer.Layer<SqlClient.SqlClient>) {
-  return databaseLayer.pipe(Layer.provide(sqlite))
-}
-
 export function configured(options?: Options) {
   return makeGlobalNode({ service: Service, layer: layer(options), deps: [Global.node] })
 }

packages/core/src/database/migration.ts

@@ -2,7 +2,6 @@ export * as DatabaseMigration from "./migration"
 
 import { sql } from "drizzle-orm"
 import { Effect, Semaphore } from "effect"
-import { supportsForeignKeyToggle } from "#sqlite"
 import type { EffectDrizzleSqlite } from "@opencode-ai/effect-drizzle-sqlite"
 import { migrations } from "./migration.gen"
 import schema from "./schema.gen"
@@ -21,10 +20,8 @@ export type Migration = {
 export function apply(db: Database) {
   return lock.withPermit(
     Effect.gen(function* () {
-      // OpenCode owns the unprefixed table namespace. Embedders sharing this
-      // database may own underscore-prefixed tables, which bootstrap ignores.
       const tables = yield* db.all<{ name: string }>(
-        sql`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND substr(name, 1, 1) <> '_'`,
+        sql`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'`,
       )
       if (tables.some((table) => table.name === "session" || table.name === "session_v2"))
         return yield* applyOnly(db, migrations)
@@ -106,15 +103,9 @@ export function applyOnly(db: Database, input: Migration[]) {
         })
         continue
       }
-      // Durable Object SQLite rejects the foreign_keys toggle; the closest
-      // allowlisted relaxation is deferring enforcement to transaction commit.
-      const relaxForeignKeys = supportsForeignKeyToggle
-        ? db.run(sql`PRAGMA foreign_keys = OFF`)
-        : db.run(sql`PRAGMA defer_foreign_keys = ON`)
-      const restoreForeignKeys = supportsForeignKeyToggle ? db.run(sql`PRAGMA foreign_keys = ON`) : Effect.void
-      yield* relaxForeignKeys
+      yield* db.run(sql`PRAGMA foreign_keys = OFF`)
       yield* apply.pipe(
-        Effect.ensuring(restoreForeignKeys.pipe(Effect.orDie)),
+        Effect.ensuring(db.run(sql`PRAGMA foreign_keys = ON`).pipe(Effect.orDie)),
         Effect.tapError((error) =>
           Effect.logError("database migration failed", {
             migration: migration.id,

packages/core/src/database/sqlite.bun.ts

@@ -13,11 +13,6 @@ const ATTR_DB_SYSTEM_NAME = "db.system.name"
 const TypeId = "~@opencode-ai/core/database/SqliteBun" as const
 type TypeId = typeof TypeId
 
-export const supportsTuningPragmas = true
-
-// Foreign keys default OFF and can be toggled per connection.
-export const supportsForeignKeyToggle = true
-
 interface SqliteClient extends SqlClient.SqlClient {
   readonly [TypeId]: TypeId
   readonly config: Config

packages/core/src/database/sqlite.node.ts

@@ -13,11 +13,6 @@ const ATTR_DB_SYSTEM_NAME = "db.system.name"
 const TypeId = "~@opencode-ai/core/database/SqliteNode" as const
 type TypeId = typeof TypeId
 
-export const supportsTuningPragmas = true
-
-// Foreign keys default OFF and can be toggled per connection.
-export const supportsForeignKeyToggle = true
-
 interface SqliteClient extends SqlClient.SqlClient {
   readonly [TypeId]: TypeId
   readonly config: Config

packages/core/src/database/sqlite.workerd.ts

@@ -1,254 +0,0 @@
-import { drizzle } from "drizzle-orm/durable-sqlite"
-import { Context, Effect, Exit, Fiber, Layer, Scope, Semaphore, Stream } from "effect"
-import { identity } from "effect/Function"
-import { Reactivity } from "effect/unstable/reactivity"
-import { SqlClient, Statement } from "effect/unstable/sql"
-import type { Connection } from "effect/unstable/sql/SqlConnection"
-import { classifySqliteError, SqlError, UnknownError } from "effect/unstable/sql/SqlError"
-import { Sqlite } from "./sqlite"
-
-const ATTR_DB_SYSTEM_NAME = "db.system.name"
-
-const TypeId = "~@opencode-ai/core/database/SqliteWorkerd" as const
-type TypeId = typeof TypeId
-
-// Durable Object SQLite only allowlists introspection pragmas; journal_mode,
-// synchronous, busy_timeout, cache_size, and wal_checkpoint all throw, and
-// foreign keys are already enforced by default (SQLITE_DEFAULT_FOREIGN_KEYS=1).
-export const supportsTuningPragmas = false
-
-// Durable Object SQLite rejects `PRAGMA foreign_keys`: enforcement is always
-// on (SQLITE_DEFAULT_FOREIGN_KEYS=1) and only `defer_foreign_keys` is
-// allowlisted for migrations that must relax checking inside a transaction.
-export const supportsForeignKeyToggle = false
-
-// Minimal structural types for the Durable Object storage API so this adapter
-// does not depend on @cloudflare/workers-types (whose ambient globals conflict
-// with @types/bun). Shapes match the SqlStorage and DurableObjectStorage docs.
-type SqlStorageValue = ArrayBuffer | string | number | null
-
-interface SqlStorageCursor {
-  readonly columnNames: Array<string>
-  raw(): IterableIterator<Array<SqlStorageValue>>
-  toArray(): Array<Record<string, SqlStorageValue>>
-}
-
-export interface SqlStorage {
-  exec(query: string, ...bindings: Array<unknown>): SqlStorageCursor
-}
-
-export interface DurableObjectStorage {
-  readonly sql: SqlStorage
-  transaction<T>(closure: (txn: { rollback(): void }) => Promise<T>): Promise<T>
-  transactionSync<T>(closure: () => T): T
-}
-
-interface SqliteClient extends SqlClient.SqlClient {
-  readonly [TypeId]: TypeId
-  readonly config: Config
-  readonly updateValues: never
-}
-
-interface Config {
-  readonly storage: DurableObjectStorage
-  readonly spanAttributes?: Record<string, unknown>
-  readonly transformResultNames?: (str: string) => string
-  readonly transformQueryNames?: (str: string) => string
-}
-
-// sql.exec() rejects BEGIN/COMMIT/SAVEPOINT, so SqlClient.make's default
-// transaction SQL can never run. withTransaction is replaced below with a
-// DurableObjectStorage.transaction-backed implementation; this service only
-// tracks the active transaction connection for statements and nesting checks.
-const WorkerdTransaction = Context.Service<SqlClient.TransactionConnection, SqlClient.TransactionConnection.Service>(
-  "@opencode-ai/core/database/SqliteWorkerdTransaction",
-)
-
-const transactionError = (message: string) =>
-  new SqlError({
-    reason: new UnknownError({ cause: new Error(message), message, operation: "transaction" }),
-  })
-
-const makeWithTransaction =
-  (
-    storage: DurableObjectStorage,
-    connection: Connection,
-    semaphore: Semaphore.Semaphore,
-  ): SqlClient.SqlClient["withTransaction"] =>
-  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | SqlError, R> =>
-    Effect.withFiber((fiber) => {
-      const services = fiber.context
-      if (Context.getOption(services, WorkerdTransaction)._tag === "Some")
-        return Effect.fail(
-          transactionError("Nested transactions are not supported by Cloudflare Durable Object SQLite storage"),
-        )
-      const effectWithTxn = Effect.provideContext(
-        effect,
-        Context.add(services, WorkerdTransaction, [connection, 0] as const),
-      )
-      return semaphore.withPermits(1)(
-        Effect.callback((resume) => {
-          let interrupted = false
-          const promise = storage
-            .transaction(
-              (txn) =>
-                new Promise<void>((resolve) => {
-                  if (interrupted) return resolve()
-                  resume(
-                    Effect.onExit(effectWithTxn, (exit) => {
-                      if (Exit.isFailure(exit)) txn.rollback()
-                      resolve()
-                      // wait for the transaction to complete
-                      return Effect.promise(() => promise)
-                    }),
-                  )
-                }),
-            )
-            .catch((cause) =>
-              resume(
-                Effect.fail(
-                  new SqlError({
-                    reason: classifySqliteError(cause, { message: "Failed transaction", operation: "transaction" }),
-                  }),
-                ),
-              ),
-            )
-          return Effect.suspend(() => {
-            interrupted = true
-            return Effect.promise(() => promise)
-          })
-        }),
-      )
-    })
-
-const make = (options: Config) =>
-  Effect.gen(function* () {
-    const native = (yield* Sqlite.Native) as DurableObjectStorage
-
-    const compiler = Statement.makeCompilerSqlite(options.transformQueryNames)
-    const transformRows = options.transformResultNames
-      ? Statement.defaultTransforms(options.transformResultNames).array
-      : undefined
-
-    // SqlClient.SafeIntegers is ignored: Durable Object SQLite has no bigint
-    // mode and always returns integers as numbers. Blobs come back as
-    // ArrayBuffer and are normalized to Uint8Array to match the other adapters.
-    function* runIterator(query: string, params: ReadonlyArray<unknown> = []) {
-      const cursor = native.sql.exec(query, ...params)
-      const columns = cursor.columnNames
-      for (const row of cursor.raw()) {
-        const record: Record<string, unknown> = {}
-        for (let i = 0; i < columns.length; i++) {
-          const value = row[i]
-          record[columns[i]] = value instanceof ArrayBuffer ? new Uint8Array(value) : value
-        }
-        yield record
-      }
-    }
-
-    const run = (query: string, params: ReadonlyArray<unknown> = []) =>
-      Effect.try({
-        try: () => Array.from(runIterator(query, params)),
-        catch: (cause) =>
-          new SqlError({
-            reason: classifySqliteError(cause, { message: "Failed to execute statement", operation: "execute" }),
-          }),
-      })
-
-    const runValues = (query: string, params: ReadonlyArray<unknown> = []) =>
-      Effect.try({
-        try: () =>
-          Array.from(native.sql.exec(query, ...params).raw(), (row) =>
-            row.map((value) => (value instanceof ArrayBuffer ? new Uint8Array(value) : value)),
-          ),
-        catch: (cause) =>
-          new SqlError({
-            reason: classifySqliteError(cause, { message: "Failed to execute statement", operation: "execute" }),
-          }),
-      })
-
-    const connection = identity<Connection>({
-      execute(query, params, transformRows) {
-        return transformRows ? Effect.map(run(query, params), transformRows) : run(query, params)
-      },
-      executeRaw(query, params) {
-        return run(query, params)
-      },
-      executeValues(query, params) {
-        return runValues(query, params)
-      },
-      executeValuesUnprepared(query, params) {
-        return runValues(query, params)
-      },
-      executeUnprepared(query, params, transformRows) {
-        return this.execute(query, params, transformRows)
-      },
-      executeStream() {
-        return Stream.die("executeStream not implemented")
-      },
-    })
-
-    const semaphore = yield* Semaphore.make(1)
-    const acquirer = semaphore.withPermits(1)(Effect.succeed(connection))
-    const transactionAcquirer = Effect.uninterruptibleMask((restore) => {
-      const fiber = Fiber.getCurrent()!
-      const scope = Context.getUnsafe(fiber.context, Scope.Scope)
-      return Effect.as(
-        Effect.tap(restore(semaphore.take(1)), () => Scope.addFinalizer(scope, semaphore.release(1))),
-        connection,
-      )
-    })
-
-    const client = Object.assign(
-      (yield* SqlClient.make({
-        acquirer,
-        compiler,
-        transactionAcquirer,
-        transactionService: WorkerdTransaction,
-        spanAttributes: [
-          ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
-          [ATTR_DB_SYSTEM_NAME, "sqlite"],
-        ],
-        transformRows,
-      })) as SqliteClient,
-      {
-        [TypeId]: TypeId,
-        config: options,
-        withTransaction: makeWithTransaction(native, connection, semaphore),
-        // Durable Object SQLite rejects BEGIN/COMMIT/SAVEPOINT; consumers such
-        // as the drizzle session must route through withTransaction instead.
-        transactionStatements: false,
-      },
-    )
-
-    return client
-  })
-
-// Defends against the shared path-based Database.layer, which passes a
-// filename instead of storage when resolved under the workerd condition.
-const nativeLayer = (config: Config) =>
-  config.storage
-    ? Layer.succeed(Sqlite.Native, config.storage)
-    : Layer.effect(
-        Sqlite.Native,
-        Effect.die(
-          "workerd sqlite cannot open a database from a path; use Database.layerWith(sqliteLayer({ storage }))",
-        ),
-      )
-
-const clientLayer = (config: Config) => Layer.effect(SqlClient.SqlClient, make(config))
-
-const drizzleLayer = Layer.effect(
-  Sqlite.Drizzle,
-  Effect.gen(function* () {
-    const native = (yield* Sqlite.Native) as DurableObjectStorage
-    return drizzle(native) as unknown as Sqlite.DrizzleClient
-  }),
-)
-
-export const sqliteLayer = (config: Config) => {
-  const native = nativeLayer(config)
-  return Layer.merge(native, Layer.merge(clientLayer(config), drizzleLayer).pipe(Layer.provide(native))).pipe(
-    Layer.provide(Reactivity.layer),
-  )
-}

packages/core/src/models-dev.ts

@@ -1,8 +1,11 @@
-import { Context, Duration, Effect, Layer, Option, Schedule, Schema, Semaphore } from "effect"
+import path from "path"
+import { Context, Duration, Effect, Layer, Option, Schedule, Schema } from "effect"
 import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import { ModelsDev } from "@opencode-ai/schema/models-dev"
 import { Money } from "@opencode-ai/schema/money"
 import { App } from "./app"
+import { Global } from "@opencode-ai/util/global"
+import { Flock } from "@opencode-ai/util/flock"
 import { Hash } from "@opencode-ai/util/hash"
 import { FSUtil } from "@opencode-ai/util/fs-util"
 import { Bus } from "./bus"
@@ -10,7 +13,6 @@ import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { httpClient } from "@opencode-ai/util/effect/app-node-platform"
 import { Model } from "./model"
 import { Provider } from "./provider"
-import { KV } from "./kv"
 
 export const CatalogModelStatus = Schema.Literals(["alpha", "beta", "deprecated"])
 export type CatalogModelStatus = typeof CatalogModelStatus.Type
@@ -535,18 +537,6 @@ export type Options = typeof Options.Type
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/ModelsDev") {}
 
-const CatalogJson = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown))
-const Cache = Schema.Struct({
-  updatedAt: Schema.Number,
-  body: CatalogJson,
-})
-const defaultSource = "https://models.opencode.ai"
-
-function cacheKey(source: string) {
-  if (source === defaultSource) return "models-dev:catalog"
-  return `models-dev:catalog:${Hash.fast(source)}`
-}
-
 export const layer = (options?: Options) =>
   Layer.effect(
     Service,
@@ -554,7 +544,7 @@ export const layer = (options?: Options) =>
       const fs = yield* FSUtil.Service
       const bus = yield* Bus.Service
       const app = yield* App.Metadata
-      const kv = yield* KV.Service
+      const global = yield* Global.Service
       const http = HttpClient.filterStatusOk(
         (yield* HttpClient.HttpClient).pipe(
           HttpClient.retryTransient({
@@ -565,28 +555,21 @@ export const layer = (options?: Options) =>
         ),
       )
 
-      const source = options?.url || defaultSource
+      const source = options?.url || "https://models.opencode.ai"
       const fetch = options?.fetch ?? true
       const userAgent = App.useragent(app)
-      const key = cacheKey(source)
+      const filepath = path.join(
+        global.cache,
+        source === "https://models.opencode.ai" ? "models.json" : `models-${Hash.fast(source)}.json`,
+      )
       const ttl = Duration.minutes(5)
-      const lock = Semaphore.makeUnsafe(1)
-
-      const loadFromCache = Effect.fnUntraced(function* () {
-        const value = yield* kv.get(key)
-        const cached = Schema.decodeUnknownOption(Cache)(value)
-        if (Option.isSome(cached))
-          return {
-            catalog: cached.value.body as Record<string, SourceProvider>,
-            updatedAt: cached.value.updatedAt,
-          }
-        if (value !== undefined) yield* kv.remove(key)
-      })
+      const lockKey = `models-dev:${filepath}`
 
       const fresh = Effect.fnUntraced(function* () {
-        const cached = yield* loadFromCache()
-        if (!cached) return false
-        return Date.now() - cached.updatedAt < Duration.toMillis(ttl)
+        const stat = yield* fs.stat(filepath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+        if (!stat) return false
+        const mtime = Option.getOrElse(stat.mtime, () => new Date(0)).getTime()
+        return Date.now() - mtime < Duration.toMillis(ttl)
       })
 
       const fetchApi = Effect.fn("ModelsDev.fetchApi")(function* () {
@@ -598,12 +581,15 @@ export const layer = (options?: Options) =>
         )
       })
 
-      const loadFromFile = options?.file
-        ? fs.readJson(options.file).pipe(
-            Effect.map((input) => input as Record<string, SourceProvider>),
-            Effect.catch(() => Effect.succeed(undefined)),
-          )
-        : Effect.succeed(undefined)
+      const loadFromDisk = fs.readJson(options?.file ?? filepath).pipe(
+        Effect.map((input) => input as Record<string, SourceProvider>),
+        Effect.catch((error) => {
+          if (options?.file === undefined && error._tag === "FileSystemError" && error.method === "readJson") {
+            return fs.remove(filepath, { force: true }).pipe(Effect.ignore, Effect.as(undefined))
+          }
+          return Effect.succeed(undefined)
+        }),
+      )
 
       const loadSnapshot = Effect.sync(() =>
         typeof OPENCODE_MODELS_DEV === "undefined" ? undefined : OPENCODE_MODELS_DEV,
@@ -611,27 +597,33 @@ export const layer = (options?: Options) =>
 
       const fetchAndWrite = Effect.fn("ModelsDev.fetchAndWrite")(function* () {
         const text = yield* fetchApi()
-        const catalog = (yield* Schema.decodeUnknownEffect(CatalogJson)(text)) as Record<string, SourceProvider>
-        yield* kv.set(key, { updatedAt: Date.now(), body: text })
-        return catalog
+        const tempfile = `${filepath}.${process.pid}.${Date.now()}.tmp`
+        yield* fs.writeWithDirs(tempfile, text).pipe(
+          Effect.andThen(fs.rename(tempfile, filepath)),
+          Effect.catch((error) =>
+            Effect.gen(function* () {
+              yield* fs.remove(tempfile, { force: true }).pipe(Effect.ignore)
+              return yield* Effect.fail(error)
+            }),
+          ),
+        )
+        return text
       })
 
       const populate = Effect.gen(function* () {
-        const fromFile = yield* loadFromFile
-        if (fromFile) return normalize(fromFile)
-        const cached = options?.file ? undefined : yield* loadFromCache()
-        if (cached) return normalize(cached.catalog)
+        const fromDisk = yield* loadFromDisk
+        if (fromDisk) return normalize(fromDisk)
         const bundled = yield* loadSnapshot
         if (bundled) return normalize(bundled)
         if (!fetch) return []
-        const catalog = yield* lock.withPermit(
+        // Flock is cross-process: concurrent opencode CLIs can race on this cache file.
+        const text = yield* Effect.scoped(
           Effect.gen(function* () {
-            const stored = options?.file ? undefined : yield* loadFromCache()
-            if (stored) return stored.catalog
+            yield* Flock.effect(lockKey)
             return yield* fetchAndWrite()
           }),
         )
-        return normalize(catalog)
+        return normalize(JSON.parse(text) as Record<string, SourceProvider>)
       }).pipe(Effect.withSpan("ModelsDev.populate"), Effect.orDie)
 
       const [cachedGet, invalidate] = yield* Effect.cachedInvalidateWithTTL(populate, Duration.infinity)
@@ -639,19 +631,21 @@ export const layer = (options?: Options) =>
       const get = (): Effect.Effect<readonly Snapshot[]> => cachedGet
 
       const refresh = Effect.fn("ModelsDev.refresh")(function* (force = false) {
-        yield* lock
-          .withPermit(
-            Effect.gen(function* () {
-              if (!force && (yield* fresh())) return
-              yield* fetchAndWrite()
-              yield* invalidate
-              yield* bus.publish(ModelsDev.Event.Refreshed, {})
-            }),
-          )
-          .pipe(
-            Effect.tapCause((cause) => Effect.logError("Failed to fetch models.dev", { cause: cause })),
-            Effect.ignore,
-          )
+        if (!force && (yield* fresh())) return
+        yield* Effect.scoped(
+          Effect.gen(function* () {
+            yield* Flock.effect(lockKey)
+            // Re-check under the lock: another process may have refreshed between
+            // our outer check and lock acquisition.
+            if (!force && (yield* fresh())) return
+            yield* fetchAndWrite()
+            yield* invalidate
+            yield* bus.publish(ModelsDev.Event.Refreshed, {})
+          }),
+        ).pipe(
+          Effect.tapCause((cause) => Effect.logError("Failed to fetch models.dev", { cause: cause })),
+          Effect.ignore,
+        )
       })
 
       if (fetch && !process.argv.includes("--get-yargs-completions")) {
@@ -667,7 +661,7 @@ export function configured(options?: Options) {
   return makeGlobalNode({
     service: Service,
     layer: layer(options),
-    deps: [FSUtil.node, Bus.node, App.node, KV.node, httpClient],
+    deps: [FSUtil.node, Bus.node, App.node, Global.node, httpClient],
   })
 }
 

packages/core/test/database-migration.test.ts

@@ -84,19 +84,6 @@ describe("DatabaseMigration", () => {
     ).rejects.toThrow("Database is not empty and has no session table")
   })
 
-  test("bootstraps alongside underscore-prefixed embedder tables", async () => {
-    await run(
-      Effect.gen(function* () {
-        const db = yield* makeDb
-        yield* db.run(sql`CREATE TABLE _embedder_state (id text PRIMARY KEY)`)
-        yield* DatabaseMigration.apply(db)
-        expect(yield* db.get(sql`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'session_v2'`)).toEqual(
-          { name: "session_v2" },
-        )
-      }),
-    )
-  })
-
   test("applies generic migrations once and records their order", async () => {
     await run(
       Effect.gen(function* () {

packages/core/test/instruction-discovery.test.ts

@@ -24,6 +24,7 @@ const it = testEffect(Layer.empty)
 
 const instructionLayer = (input: {
   config?: string
+  home?: string
   locationServiceLayer: Layer.Layer<Location.Service>
   filesystemLayer?: Layer.Layer<FSUtil.Service>
   project?: boolean
@@ -34,7 +35,15 @@ const instructionLayer = (input: {
       LayerNode.group([InstructionDiscovery.node, Bus.node, FSUtil.node, Global.node, Location.node, Watcher.node]),
       [
         [InstructionDiscovery.node, InstructionDiscovery.configured({ project: input.project })],
-        [Global.node, input.config ? Global.layerWith({ config: input.config }) : tempGlobalLayer],
+        [
+          Global.node,
+          input.config || input.home
+            ? Global.layerWith({
+                ...(input.config ? { config: input.config } : {}),
+                ...(input.home ? { home: input.home } : {}),
+              })
+            : tempGlobalLayer,
+        ],
         [Location.node, input.locationServiceLayer],
         [Watcher.node, watcher],
         ...(input.filesystemLayer ? [[FSUtil.node, input.filesystemLayer] as const] : []),
@@ -112,10 +121,13 @@ describe("ConfigInstructionPlugin.Plugin", () => {
     ).pipe(
       Effect.flatMap((tmp) => {
         const global = path.join(tmp.path, "global")
-        const project = path.join(tmp.path, "project")
+        const home = path.join(tmp.path, "home")
+        const shared = path.join(home, "code")
+        const project = path.join(shared, "repo")
         const directory = path.join(project, "packages", "core")
         const outside = path.join(tmp.path, "AGENTS.md")
         const globalFile = path.join(global, "AGENTS.md")
+        const sharedFile = path.join(shared, "AGENTS.md")
         const projectFile = path.join(project, "AGENTS.md")
         const packageFile = path.join(directory, "AGENTS.md")
         return Effect.gen(function* () {
@@ -124,6 +136,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
             await fs.mkdir(directory, { recursive: true })
             await fs.writeFile(outside, "outside")
             await fs.writeFile(globalFile, "global")
+            await fs.writeFile(sharedFile, "shared")
             await fs.writeFile(projectFile, "project")
             await fs.writeFile(packageFile, "package")
           })
@@ -135,13 +148,20 @@ describe("ConfigInstructionPlugin.Plugin", () => {
             { path: packageFile, type: "file" },
             { path: path.join(project, "packages", "AGENTS.md"), type: "file" },
             { path: projectFile, type: "file" },
+            { path: sharedFile, type: "file" },
+            { path: path.join(home, "AGENTS.md"), type: "file" },
           ])
+          expect(yield* watcher.subscriptions()).not.toContainEqual({
+            path: path.join(tmp.path, "AGENTS.md"),
+            type: "file",
+          })
           const initialized = yield* readInitial(yield* discovery.load())
           expect(initialized.text).toBe(
             [
               `Instructions from: ${globalFile}\nglobal`,
               `Instructions from: ${packageFile}\npackage`,
               `Instructions from: ${projectFile}\nproject`,
+              `Instructions from: ${sharedFile}\nshared`,
             ].join("\n\n"),
           )
           expect(initialized.text).not.toContain("outside")
@@ -159,6 +179,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
               "These instructions replace all previously loaded ambient instructions.",
               `Instructions from: ${globalFile}\nglobal`,
               `Instructions from: ${projectFile}\nproject`,
+              `Instructions from: ${sharedFile}\nshared`,
             ].join("\n\n"),
           )
 
@@ -166,6 +187,8 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           yield* emitAndWait({ type: "delete", path: globalFile })
           yield* Effect.promise(() => fs.rm(projectFile))
           yield* emitAndWait({ type: "delete", path: projectFile })
+          yield* Effect.promise(() => fs.rm(sharedFile))
+          yield* emitAndWait({ type: "delete", path: sharedFile })
           expect((yield* readUpdate(yield* discovery.load(), initialized)).text).toBe(
             "Previously loaded instructions no longer apply.",
           )
@@ -173,6 +196,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           Effect.provide(
             instructionLayer({
               config: global,
+              home,
               locationServiceLayer: Layer.succeed(
                 Location.Service,
                 Location.Service.of(
@@ -215,15 +239,17 @@ describe("ConfigInstructionPlugin.Plugin", () => {
     ),
   )
 
-  it.live("discovers a newly created instruction file in an intermediate directory", () =>
+  it.live("discovers a newly created instruction file above the project root", () =>
     Effect.acquireRelease(
       Effect.promise(() => tmpdir()),
       (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
     ).pipe(
       Effect.flatMap((tmp) => {
-        const project = path.join(tmp.path, "project")
-        const intermediate = path.join(project, "packages", "AGENTS.md")
-        const directory = path.join(project, "packages", "core")
+        const home = path.join(tmp.path, "home")
+        const shared = path.join(home, "code")
+        const project = path.join(shared, "repo")
+        const intermediate = path.join(shared, "AGENTS.md")
+        const directory = path.join(project, "core")
         const projectFile = path.join(project, "AGENTS.md")
         return Effect.gen(function* () {
           yield* Effect.promise(() => fs.mkdir(directory, { recursive: true }))
@@ -235,7 +261,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           yield* emitAndWait({ type: "create", path: intermediate })
 
           expect((yield* readInitial(yield* discovery.load())).text).toBe(
-            [`Instructions from: ${intermediate}\nintermediate`, `Instructions from: ${projectFile}\nproject`].join(
+            [`Instructions from: ${projectFile}\nproject`, `Instructions from: ${intermediate}\nintermediate`].join(
               "\n\n",
             ),
           )
@@ -243,6 +269,48 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           Effect.provide(
             instructionLayer({
               config: path.join(tmp.path, "global"),
+              home,
+              locationServiceLayer: Layer.succeed(
+                Location.Service,
+                Location.Service.of(
+                  location(
+                    { directory: AbsolutePath.make(directory) },
+                    { projectDirectory: AbsolutePath.make(project) },
+                  ),
+                ),
+              ),
+            }),
+          ),
+        )
+      }),
+    ),
+  )
+
+  it.live("stops instruction candidates at the project root outside home", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) => {
+        const global = path.join(tmp.path, "global")
+        const home = path.join(tmp.path, "home")
+        const project = path.join(tmp.path, "scratch", "repo")
+        const directory = path.join(project, "packages", "core")
+        return Effect.gen(function* () {
+          yield* Effect.promise(() => fs.mkdir(directory, { recursive: true }))
+          yield* start()
+          const watcher = yield* Watcher.Test
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: path.join(global, "AGENTS.md"), type: "file" },
+            { path: path.join(directory, "AGENTS.md"), type: "file" },
+            { path: path.join(project, "packages", "AGENTS.md"), type: "file" },
+            { path: path.join(project, "AGENTS.md"), type: "file" },
+          ])
+        }).pipe(
+          Effect.provide(
+            instructionLayer({
+              config: global,
+              home,
               locationServiceLayer: Layer.succeed(
                 Location.Service,
                 Location.Service.of(

packages/core/test/models.test.ts

@@ -1,17 +1,19 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, beforeEach, afterAll, test } from "bun:test"
 import { Money } from "@opencode-ai/schema/money"
 import { Effect, Layer, Ref } from "effect"
 import { HttpClient, HttpClientResponse } from "effect/unstable/http"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNodePlatform } from "@opencode-ai/util/effect/app-node-platform"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
-import { KV } from "@opencode-ai/core/kv"
+import { Global } from "@opencode-ai/util/global"
 import { Model } from "@opencode-ai/core/model"
 import { ModelsDev } from "@opencode-ai/core/models-dev"
 import { Provider } from "@opencode-ai/core/provider"
 import { it } from "./lib/effect"
+import { readFile, rm, writeFile, utimes, mkdir } from "fs/promises"
+import path from "path"
 
-const cacheKey = "models-dev:catalog"
+const cacheFile = path.join(Global.Path.cache, "models.json")
 
 test("normalizes permissive interleaved values to compatibility", () => {
   expect(Model.compatibility("reasoning_text")).toEqual({ reasoningField: "reasoning_text" })
@@ -162,18 +164,7 @@ const makeMockClient = (state: Ref.Ref<MockState>) =>
     }),
   )
 
-interface MockCache {
-  readonly values: Map<string, KV.Value>
-}
-
-const makeMockKV = (cache: MockCache) =>
-  Layer.mock(KV.Service, {
-    get: (key) => Effect.sync(() => cache.values.get(key)),
-    set: (key, value) => Effect.sync(() => cache.values.set(key, value)).pipe(Effect.asVoid),
-    remove: (key) => Effect.sync(() => cache.values.delete(key)).pipe(Effect.asVoid),
-  })
-
-const buildLayer = (state: Ref.Ref<MockState>, cache: MockCache, options: ModelsDev.Options = { fetch: false }) =>
+const buildLayer = (state: Ref.Ref<MockState>, options: ModelsDev.Options = { fetch: false }) =>
   // Layer.fresh is required because the ModelsDev implementation is a module-level Layer constant,
   // and Effect.provide uses a process-global MemoMap by default — without fresh,
   // every test would reuse the cachedInvalidateWithTTL state from the first run.
@@ -181,20 +172,31 @@ const buildLayer = (state: Ref.Ref<MockState>, cache: MockCache, options: Models
     AppNodeBuilder.build(ModelsDev.node, [
       [ModelsDev.node, ModelsDev.configured(options)],
       [LayerNodePlatform.httpClient, Layer.succeed(HttpClient.HttpClient, makeMockClient(state))],
-      [KV.node, makeMockKV(cache)],
     ]),
   )
 
-const makeCache = (): MockCache => ({ values: new Map() })
+const writeCacheText = (text: string, mtimeMs?: number) =>
+  Effect.promise(async () => {
+    await mkdir(Global.Path.cache, { recursive: true })
+    await writeFile(cacheFile, text)
+    if (mtimeMs !== undefined) {
+      const t = mtimeMs / 1000
+      await utimes(cacheFile, t, t)
+    }
+  })
 
-const writeCacheText = (cache: MockCache, text: string, updatedAt = Date.now()) =>
-  cache.values.set(cacheKey, { updatedAt, body: text })
+const writeCache = (data: object, mtimeMs?: number) => writeCacheText(JSON.stringify(data), mtimeMs)
 
-const writeCache = (cache: MockCache, data: object, updatedAt?: number) =>
-  writeCacheText(cache, JSON.stringify(data), updatedAt)
+const provided = <A, E>(state: Ref.Ref<MockState>, eff: Effect.Effect<A, E, ModelsDev.Service>) =>
+  eff.pipe(Effect.provide(buildLayer(state)))
 
-const provided = <A, E>(state: Ref.Ref<MockState>, cache: MockCache, eff: Effect.Effect<A, E, ModelsDev.Service>) =>
-  eff.pipe(Effect.provide(buildLayer(state, cache)))
+beforeEach(async () => {
+  await rm(cacheFile, { force: true })
+})
+
+afterAll(async () => {
+  await rm(cacheFile, { force: true })
+})
 
 const initialState: MockState = {
   body: JSON.stringify(fixture),
@@ -203,14 +205,12 @@ const initialState: MockState = {
 }
 
 describe("ModelsDev Service", () => {
-  it.live("get() returns normalized snapshots from KV when a cache entry exists", () =>
+  it.live("get() returns normalized snapshots from disk when cache file exists", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make(initialState)
       const result = yield* provided(
         state,
-        cache,
         ModelsDev.Service.use((s) => s.get()),
       )
       expect(result).toEqual(fixtureSnapshot)
@@ -219,13 +219,11 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("get() returns empty catalog when KV is empty, fetch disabled, and no bundled snapshot is injected", () =>
+  it.live("get() returns empty catalog when disk empty, fetch disabled, and no bundled snapshot is injected", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
       const state = yield* Ref.make(initialState)
       const result = yield* provided(
         state,
-        cache,
         ModelsDev.Service.use((s) => s.get()),
       )
       expect(result).toEqual([])
@@ -234,15 +232,14 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("get() recovers from a corrupted KV entry by fetching a fresh catalog", () =>
+  it.live("get() recovers from a corrupted cache file by fetching a fresh catalog", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCacheText(cache, "{")
+      yield* writeCacheText("{")
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
-      const context = yield* Layer.build(buildLayer(state, cache, { fetch: true }))
+      const context = yield* Layer.build(buildLayer(state, { fetch: true }))
       const result = yield* ModelsDev.Service.use((s) => s.get()).pipe(Effect.provide(context))
       expect(result).toEqual(fixture2Snapshot)
-      expect(cache.values.get(cacheKey)).toMatchObject({ body: JSON.stringify(fixture2) })
+      expect(yield* Effect.promise(() => readFile(cacheFile, "utf8"))).toBe(JSON.stringify(fixture2))
       const final = yield* Ref.get(state)
       expect(final.calls.length).toBe(1)
     }),
@@ -250,10 +247,9 @@ describe("ModelsDev Service", () => {
 
   it.live("uses the default models URL when the configured URL is empty", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
       const state = yield* Ref.make(initialState)
       yield* ModelsDev.Service.use((service) => service.get()).pipe(
-        Effect.provide(buildLayer(state, cache, { url: "", fetch: true })),
+        Effect.provide(buildLayer(state, { url: "", fetch: true })),
       )
       expect((yield* Ref.get(state)).calls[0]?.url).toBe("https://models.opencode.ai/api.json")
     }),
@@ -261,31 +257,32 @@ describe("ModelsDev Service", () => {
 
   it.live("get() is single-flight under concurrent calls", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
+      yield* writeCache(fixture)
       const state = yield* Ref.make(initialState)
-      const results = yield* Effect.gen(function* () {
-        const svc = yield* ModelsDev.Service
-        return yield* Effect.all([svc.get(), svc.get(), svc.get(), svc.get(), svc.get()], {
-          concurrency: "unbounded",
-        })
-      }).pipe(Effect.provide(buildLayer(state, cache, { fetch: true })))
+      const results = yield* provided(
+        state,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          return yield* Effect.all([svc.get(), svc.get(), svc.get(), svc.get(), svc.get()], {
+            concurrency: "unbounded",
+          })
+        }),
+      )
       for (const result of results) expect(result).toEqual(fixtureSnapshot)
-      expect((yield* Ref.get(state)).calls.length).toBe(1)
     }),
   )
 
-  it.live("get() caches across calls (later KV writes are ignored until invalidate)", () =>
+  it.live("get() caches across calls (later disk writes are ignored until invalidate)", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make(initialState)
       const first = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           const a = yield* svc.get()
-          writeCache(cache, fixture2)
+          // mutate disk between calls — cache should mask the change
+          yield* writeCache(fixture2)
           const b = yield* svc.get()
           return { a, b }
         }),
@@ -297,12 +294,10 @@ describe("ModelsDev Service", () => {
 
   it.live("refresh(true) fetches via HttpClient and updates the cache", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
       const result = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           const before = yield* svc.get()
@@ -313,7 +308,6 @@ describe("ModelsDev Service", () => {
       )
       expect(result.before).toEqual(fixtureSnapshot)
       expect(result.after).toEqual(fixture2Snapshot)
-      expect(cache.values.get(cacheKey)).toMatchObject({ body: JSON.stringify(fixture2) })
       const final = yield* Ref.get(state)
       expect(final.calls.length).toBe(1)
       expect(final.calls[0].url).toContain("/api.json")
@@ -321,14 +315,13 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("refresh(false) skips fetch when the KV entry is fresh", () =>
+  it.live("refresh(false) skips fetch when on-disk file is fresh", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture, Date.now() - 1000)
+      // Fresh: mtime within the 5-minute TTL.
+      yield* writeCache(fixture, Date.now() - 1000)
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
       yield* provided(
         state,
-        cache,
         ModelsDev.Service.use((s) => s.refresh(false)),
       )
       const final = yield* Ref.get(state)
@@ -336,14 +329,13 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("refresh(false) fetches when the KV entry is stale", () =>
+  it.live("refresh(false) fetches when on-disk file is stale", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture, Date.now() - 10 * 60 * 1000)
+      // Stale: mtime 10 minutes ago, beyond the 5-minute TTL.
+      yield* writeCache(fixture, Date.now() - 10 * 60 * 1000)
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
       const after = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           yield* svc.refresh(false)
@@ -358,12 +350,10 @@ describe("ModelsDev Service", () => {
 
   it.live("refresh swallows HTTP errors and leaves cache intact", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make({ ...initialState, status: 500, body: "boom" })
       const result = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           yield* svc.refresh(true)

packages/core/test/sqlite-workerd.test.ts

@@ -1,137 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { Database } from "bun:sqlite"
-import { Effect, Layer } from "effect"
-import { SqlClient } from "effect/unstable/sql"
-import { SqlError } from "effect/unstable/sql/SqlError"
-import { sqliteLayer } from "@opencode-ai/core/database/sqlite.workerd"
-import type { DurableObjectStorage } from "@opencode-ai/core/database/sqlite.workerd"
-import { tempGlobalLayer } from "./fixture/global"
-
-// Emulates the Durable Object storage API over bun:sqlite so the adapter can
-// be verified without workerd or Cloudflare runtime dependencies.
-const makeFakeStorage = () => {
-  const native = new Database(":memory:")
-  const toSqlStorageValue = (value: unknown) => {
-    if (!(value instanceof Uint8Array)) return value as ArrayBuffer | string | number | null
-    const buffer = new ArrayBuffer(value.byteLength)
-    new Uint8Array(buffer).set(value)
-    return buffer
-  }
-  const storage: DurableObjectStorage = {
-    sql: {
-      exec(query: string, ...bindings: Array<unknown>) {
-        const statement = native.query(query)
-        const rows = (statement.values(...(bindings as never[])) ?? []).map((row) => row.map(toSqlStorageValue))
-        const columnNames = statement.columnNames
-        return {
-          columnNames,
-          raw: () => rows[Symbol.iterator](),
-          toArray: () => rows.map((row) => Object.fromEntries(columnNames.map((name, i) => [name, row[i]]))),
-        }
-      },
-    },
-    transaction<T>(closure: (txn: { rollback(): void }) => Promise<T>): Promise<T> {
-      native.run("BEGIN")
-      let rolledBack = false
-      return closure({ rollback: () => (rolledBack = true) }).then(
-        (result) => {
-          native.run(rolledBack ? "ROLLBACK" : "COMMIT")
-          return result
-        },
-        (error) => {
-          native.run("ROLLBACK")
-          throw error
-        },
-      )
-    },
-    transactionSync<T>(closure: () => T): T {
-      return native.transaction(closure)()
-    },
-  }
-  return storage
-}
-
-const run = <A, E>(storage: DurableObjectStorage, effect: Effect.Effect<A, E, SqlClient.SqlClient>) =>
-  Effect.runPromise(effect.pipe(Effect.provide(sqliteLayer({ storage })), Effect.scoped))
-
-describe("sqlite.workerd", () => {
-  test("executes statements with bindings and maps rows to records", async () => {
-    const rows = await run(
-      makeFakeStorage(),
-      Effect.gen(function* () {
-        const sql = yield* SqlClient.SqlClient
-        yield* sql`CREATE TABLE item (id INTEGER PRIMARY KEY, name TEXT NOT NULL)`
-        yield* sql`INSERT INTO item (id, name) VALUES (${1}, ${"one"}), (${2}, ${"two"})`
-        return yield* sql<{ id: number; name: string }>`SELECT id, name FROM item ORDER BY id`
-      }),
-    )
-    expect(rows).toEqual([
-      { id: 1, name: "one" },
-      { id: 2, name: "two" },
-    ])
-  })
-
-  test("normalizes ArrayBuffer blob values to Uint8Array", async () => {
-    const rows = await run(
-      makeFakeStorage(),
-      Effect.gen(function* () {
-        const sql = yield* SqlClient.SqlClient
-        yield* sql`CREATE TABLE blob (data BLOB NOT NULL)`
-        yield* sql`INSERT INTO blob (data) VALUES (${new Uint8Array([1, 2, 3])})`
-        return yield* sql<{ data: Uint8Array }>`SELECT data FROM blob`
-      }),
-    )
-    expect(rows[0].data).toBeInstanceOf(Uint8Array)
-    expect(Array.from(rows[0].data)).toEqual([1, 2, 3])
-  })
-
-  test("withTransaction commits on success and rolls back on failure", async () => {
-    const storage = makeFakeStorage()
-    const count = await run(
-      storage,
-      Effect.gen(function* () {
-        const sql = yield* SqlClient.SqlClient
-        yield* sql`CREATE TABLE t (value TEXT NOT NULL)`
-        yield* sql.withTransaction(sql`INSERT INTO t (value) VALUES (${"kept"})`)
-        yield* sql
-          .withTransaction(
-            Effect.gen(function* () {
-              yield* sql`INSERT INTO t (value) VALUES (${"discarded"})`
-              return yield* Effect.fail("rollback")
-            }),
-          )
-          .pipe(Effect.ignore)
-        return yield* sql<{ count: number }>`SELECT count(*) AS count FROM t`
-      }),
-    )
-    expect(count[0].count).toBe(1)
-  })
-
-  test("nested withTransaction fails with SqlError", async () => {
-    const error = await run(
-      makeFakeStorage(),
-      Effect.gen(function* () {
-        const sql = yield* SqlClient.SqlClient
-        yield* sql`CREATE TABLE t (value TEXT NOT NULL)`
-        return yield* sql
-          .withTransaction(sql.withTransaction(sql`INSERT INTO t (value) VALUES (${"nested"})`))
-          .pipe(Effect.flip)
-      }),
-    )
-    expect(error).toBeInstanceOf(SqlError)
-  })
-
-  test("boots the full database layer with migrations over injected storage", async () => {
-    const storage = makeFakeStorage()
-    const core = await import("@opencode-ai/core/database/database")
-    await Effect.runPromise(
-      Effect.scoped(Layer.build(core.Database.layerWith(sqliteLayer({ storage })).pipe(Layer.provide(tempGlobalLayer)))),
-    )
-    const names = storage.sql
-      .exec("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")
-      .toArray()
-      .map((row) => row.name)
-    expect(names).toContain("migration")
-    expect(names).toContain("session_v2")
-  })
-})

packages/www/content/docs/(Configure)/instructions.mdx

@@ -19,8 +19,9 @@ V2 loads:
 
 1. The global file at `$XDG_CONFIG_HOME/opencode/AGENTS.md`, normally
    `~/.config/opencode/AGENTS.md`.
-2. Every `AGENTS.md` from the current Location up to and including the project
-   root.
+2. Every `AGENTS.md` from the current Location up to and including the home
+   directory when the Location is inside it. For Locations outside home, the
+   scan stops at the project root.
 
 For example, when the Location is `packages/web`, OpenCode can load all three
 project files below:
@@ -35,9 +36,9 @@ my-project/
 ```
 
 The files are combined rather than selecting a single winner. They are rendered
-in this order: global, then project files from the Location toward the project
+in this order: global, then files from the Location toward home or the project
 root. OpenCode does not resolve conflicts between their contents, so keep broad
-guidance global and put scoped guidance in the relevant project directory.
+guidance global and put scoped guidance in the relevant directory.
 
 If the Location is outside the project root, only the global file is loaded.
 Setting `OPENCODE_DISABLE_PROJECT_CONFIG=1` also skips project `AGENTS.md`

packages/www/content/docs/migrate-v1.mdx

@@ -504,8 +504,8 @@ require a V2 rewrite. See [Skills](/skills).
 
 ### Instruction files
 
-Existing `AGENTS.md` files stay in place. V2 discovers the global `~/.config/opencode/AGENTS.md` and project `AGENTS.md`
-files from the current directory up to the project root.
+Existing `AGENTS.md` files stay in place. V2 discovers the global `~/.config/opencode/AGENTS.md` and ambient `AGENTS.md`
+files from the current directory up to home. For projects outside home, discovery stops at the project root.
 
 If a V1 setup relied on a `CLAUDE.md` fallback, move that guidance into the applicable `AGENTS.md`. V2 currently only
 discovers `AGENTS.md`; because non-API V1 behavior is intended to remain compatible, also run `/report` with the affected