refactor(config): simplify loading and fallbacks

.changeset/nested-instruction-reinjection.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/core": patch
+---
+
+Nested AGENTS.md instructions are re-injected after compaction. Previously the in-memory dedup claim outlived the synthetic message that compaction dropped from model-visible history, so nested instructions were silently lost for the rest of the process lifetime. The claim now only guards in-flight loads; the synthetic message metadata in durable history is the sole lasting ledger, so any history truncation (compaction, revert) self-heals on the next read in that subtree.

packages/core/src/config.ts

@@ -449,21 +449,16 @@ type Edit = { readonly path: (string | number)[]; readonly value: unknown }
 
 function changes(before: unknown, after: unknown, path: (string | number)[] = []): Edit[] {
   if (Object.is(before, after)) return []
-  if (
-    before !== null &&
-    after !== null &&
-    typeof before === "object" &&
-    typeof after === "object" &&
-    !Array.isArray(before) &&
-    !Array.isArray(after)
-  ) {
-    const previous = before as Record<string, unknown>
-    const next = after as Record<string, unknown>
-    return [...new Set([...Object.keys(previous), ...Object.keys(next)])].flatMap((key) => {
-      if (!(key in next)) return [{ path: [...path, key], value: undefined }]
-      if (!(key in previous)) return [{ path: [...path, key], value: next[key] }]
-      return changes(previous[key], next[key], [...path, key])
+  if (isRecord(before) && isRecord(after)) {
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])].flatMap((key) => {
+      if (!(key in after)) return [{ path: [...path, key], value: undefined }]
+      if (!(key in before)) return [{ path: [...path, key], value: after[key] }]
+      return changes(before[key], after[key], [...path, key])
     })
   }
   return [{ path, value: after }]
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}

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

@@ -54,7 +54,7 @@ export const Plugin = define({
       "ConfigSkillPlugin.watchDirectory",
     )(function* (directory: string) {
       const target = path.resolve(directory)
-      const resolved = yield* fs.realPath(directory).pipe(Effect.catch(() => Effect.succeed(undefined)))
+      const resolved = yield* fs.realPath(directory).pipe(Effect.orElseSucceed(() => undefined))
       if (resolved) {
         yield* watch(resolved, "directory")
         if (resolved !== target) yield* watch(target, "file")
@@ -65,7 +65,7 @@ export const Plugin = define({
       if (
         yield* fs.realPath(directory).pipe(
           Effect.as(true),
-          Effect.catch(() => Effect.succeed(false)),
+          Effect.orElseSucceed(() => false),
         )
       ) {
         if (missing) yield* FiberMap.remove(watches, `file:${path.resolve(missing)}`)
@@ -124,11 +124,11 @@ export const Plugin = define({
       for (const directory of directories) {
         const files = yield* fs
           .scan("{*.md,**/SKILL.md}", { cwd: directory, absolute: true, include: "file", symlink: true, dot: true })
-          .pipe(Effect.catch(() => Effect.succeed([] as string[])))
+          .pipe(Effect.orElseSucceed(() => [] as string[]))
         for (const filepath of files.toSorted()) {
-          const resolved = yield* fs.realPath(filepath).pipe(Effect.catch(() => Effect.succeed(filepath)))
+          const resolved = yield* fs.realPath(filepath).pipe(Effect.orElseSucceed(() => filepath))
           if (!roots.some((root) => FSUtil.contains(root, resolved))) yield* watch(path.dirname(resolved), "directory")
-          const content = yield* fs.readFileStringSafe(filepath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+          const content = yield* fs.readFileStringSafe(filepath).pipe(Effect.orElseSucceed(() => undefined))
           if (!content) continue
           const parsed = SkillFile.parse(directory, filepath, content)
           if (parsed._tag === "Skipped") {

packages/core/src/session/instructions.ts

@@ -37,15 +37,17 @@ const layer = Layer.effect(
     // root so opening a subdirectory still describes paths from the project root.
     const root = yield* fs.resolve(location.project.directory)
     // Same-step parallel reads settle concurrently, so an in-memory claim guards each
-    // Session/path pair before any filesystem work. The durable history check below covers
-    // paths injected in earlier steps after this Location layer was reopened.
-    const injected = yield* Ref.make<Map<SessionSchema.ID, Set<string>>>(new Map())
+    // Session/path pair while a load is in flight. The claim is released once the load
+    // settles: the synthetic message metadata scanned below is the only lasting ledger,
+    // so paths whose synthetics drop out of model-visible history (compaction, revert)
+    // are re-discovered and re-injected instead of staying silently lost.
+    const inFlight = yield* Ref.make<Map<SessionSchema.ID, Set<string>>>(new Map())
 
     const load = Effect.fn("SessionInstructions.load")(function* (input: {
       readonly sessionID: SessionSchema.ID
       readonly paths: ReadonlyArray<string>
     }) {
-      const claimed = yield* Ref.modify(injected, (map) => {
+      const claimed = yield* Ref.modify(inFlight, (map) => {
         const existing = map.get(input.sessionID) ?? new Set<string>()
         const newlyClaimed = input.paths.filter((path) => !existing.has(path))
         if (newlyClaimed.length === 0) return [newlyClaimed, map]
@@ -54,30 +56,43 @@ const layer = Layer.effect(
         return [newlyClaimed, next]
       })
       if (claimed.length === 0) return
-      const alreadyInjected = yield* previouslyInjected(store, input.sessionID)
-      const toInject = claimed.filter((path) => !alreadyInjected.has(path))
-      if (toInject.length === 0) return
-      const files = yield* Effect.forEach(
-        toInject,
-        (path) =>
-          fs
-            .readFileStringSafe(path)
-            .pipe(Effect.map((content) => (content === undefined ? undefined : { path, content }))),
-        { concurrency: "unbounded" },
+      yield* Effect.gen(function* () {
+        const alreadyInjected = yield* previouslyInjected(store, input.sessionID)
+        const toInject = claimed.filter((path) => !alreadyInjected.has(path))
+        if (toInject.length === 0) return
+        const files = yield* Effect.forEach(
+          toInject,
+          (path) =>
+            fs
+              .readFileStringSafe(path)
+              .pipe(Effect.map((content) => (content === undefined ? undefined : { path, content }))),
+          { concurrency: "unbounded" },
+        )
+        const readable = files.filter((file): file is { path: string; content: string } => file !== undefined)
+        if (readable.length === 0) return
+        // Publish directly rather than through Session.synthetic: a Location-scoped layer
+        // cannot depend on Session (it routes through LocationServiceMap, forming a type
+        // cycle with this node). The durable publish commits the synthetic and its metadata
+        // ledger atomically, so releasing the claim afterwards cannot readmit the paths.
+        yield* bus.publish(SessionEvent.Synthetic, {
+          sessionID: input.sessionID,
+          text: readable.map((file) => `Instructions from: ${file.path}\n${file.content}`).join("\n\n"),
+          description: `Loaded ${readable.map((file) => describePath(root, file.path)).join(", ")}`,
+          metadata: { instruction: { paths: readable.map((file) => file.path) } },
+        })
+      }).pipe(
+        Effect.ensuring(
+          Ref.update(inFlight, (map) => {
+            const existing = map.get(input.sessionID)
+            if (!existing) return map
+            const remaining = new Set([...existing].filter((path) => !claimed.includes(path)))
+            const next = new Map(map)
+            if (remaining.size === 0) next.delete(input.sessionID)
+            else next.set(input.sessionID, remaining)
+            return next
+          }),
+        ),
       )
-      const readable = files.filter((file): file is { path: string; content: string } => file !== undefined)
-      if (readable.length === 0) return
-      // Publish directly rather than through Session.synthetic: a Location-scoped layer
-      // cannot depend on Session (it routes through LocationServiceMap, forming a type
-      // cycle with this node). The durable publish is what makes the synthetic visible on
-      // the next projected history reload. The dedup ledger lives on the synthetic message
-      // metadata so it survives across Location layer restarts.
-      yield* bus.publish(SessionEvent.Synthetic, {
-        sessionID: input.sessionID,
-        text: readable.map((file) => `Instructions from: ${file.path}\n${file.content}`).join("\n\n"),
-        description: `Loaded ${readable.map((file) => describePath(root, file.path)).join(", ")}`,
-        metadata: { instruction: { paths: readable.map((file) => file.path) } },
-      })
     })
 
     return Service.of({ load })

packages/core/src/skill/discovery.ts

@@ -157,7 +157,7 @@ const layer = Layer.effect(
               const current =
                 version === undefined
                   ? undefined
-                  : yield* fs.readFileStringSafe(versionFile).pipe(Effect.catch(() => Effect.succeed(undefined)))
+                  : yield* fs.readFileStringSafe(versionFile).pipe(Effect.orElseSucceed(() => undefined))
               if (version === undefined || current === version) {
                 yield* Effect.forEach(files, (file) => download(file.url, file.destination), {
                   concurrency: fileConcurrency,

packages/core/src/wellknown.ts

@@ -106,6 +106,10 @@ const layer = Layer.effect(
     const bus = yield* Bus.Service
     const cache = yield* Ref.make(new Map<string, Entry>())
     const lock = Semaphore.makeUnsafe(1)
+    const loadEntry = Effect.fn("WellKnown.loadEntry")(function* (origin: string) {
+      const manifest = yield* inspect(origin).pipe(Effect.provideService(HttpClient.HttpClient, http))
+      return { origin, integrationID: Integration.ID.make(origin), manifest }
+    })
 
     const load = Effect.fn("WellKnown.load")(function* () {
       const value = yield* kv.get(sourcesKey)
@@ -114,10 +118,7 @@ const layer = Layer.effect(
       const entries = yield* Effect.forEach(origins, (origin) => {
         const cached = current.get(origin)
         if (cached) return Effect.succeed(cached)
-        return inspect(origin).pipe(
-          Effect.provideService(HttpClient.HttpClient, http),
-          Effect.map((manifest) => ({ origin, integrationID: Integration.ID.make(origin), manifest })),
-        )
+        return loadEntry(origin)
       })
       yield* Ref.set(cache, new Map(entries.map((entry) => [entry.origin, entry])))
       return entries
@@ -129,12 +130,7 @@ const layer = Layer.effect(
           const value = yield* kv.get(sourcesKey)
           const origins = Schema.is(Sources)(value) ? value : []
           if (!origins.length) return false
-          const entries = yield* Effect.forEach(origins, (origin) =>
-            inspect(origin).pipe(
-              Effect.provideService(HttpClient.HttpClient, http),
-              Effect.map((manifest) => ({ origin, integrationID: Integration.ID.make(origin), manifest })),
-            ),
-          )
+          const entries = yield* Effect.forEach(origins, loadEntry)
           const next = new Map(entries.map((entry) => [entry.origin, entry]))
           const changed = !isDeepStrictEqual(Ref.getUnsafe(cache), next)
           if (!changed) return false
@@ -153,9 +149,9 @@ const layer = Layer.effect(
         return yield* lock.withPermit(
           Effect.gen(function* () {
             const origin = value.replace(/\/+$/, "")
-            const manifest = yield* inspect(origin).pipe(Effect.provideService(HttpClient.HttpClient, http))
-            if (!manifest.auth) return yield* Effect.fail(new Error(`No authentication method found at ${origin}`))
-            const entry = { origin, integrationID: Integration.ID.make(origin), manifest }
+            const entry = yield* loadEntry(origin)
+            if (!entry.manifest.auth)
+              return yield* Effect.fail(new Error(`No authentication method found at ${origin}`))
             const sources = yield* kv.get(sourcesKey)
             const origins = Schema.is(Sources)(sources) ? sources : []
             yield* kv.set(sourcesKey, Array.from(new Set([...origins, origin])))

packages/core/test/session-instructions.test.ts

@@ -233,6 +233,37 @@ describe("SessionInstructions", () => {
       }),
   )
 
+  it.effect("re-injects nested instructions dropped from history by compaction", () =>
+    Effect.gen(function* () {
+      const location = yield* Location.Service
+      const dir = location.directory
+      const subPath = path.resolve(dir, "sub", "AGENTS.md")
+      yield* mkdir(path.resolve(dir, "sub"))
+      yield* writeAgents(path.resolve(dir, "AGENTS.md"), "root-instructions")
+      yield* writeAgents(subPath, "sub-instructions")
+      yield* Effect.promise(() => fs.writeFile(path.resolve(dir, "sub", "file.txt"), "content"))
+
+      const session = yield* Session.Service
+      const registry = yield* Tool.Service
+      const bus = yield* Bus.Service
+      const sessionID = (yield* session.create({ location: Location.Ref.make({ directory: dir }) })).id
+
+      yield* executeTool(registry, readCall(sessionID, "call-before", "sub/file.txt"))
+      expect(yield* synthetics(sessionID)).toHaveLength(1)
+
+      // A completed compaction truncates model-visible history at its boundary, dropping
+      // the synthetic that carried sub's instructions.
+      yield* bus.publish(SessionEvent.Compaction.Started, { sessionID, reason: "manual", recent: "" })
+      yield* bus.publish(SessionEvent.Compaction.Ended, { sessionID, reason: "manual", text: "summary", recent: "" })
+      expect(yield* synthetics(sessionID)).toHaveLength(0)
+
+      // The model no longer has the rules, so the next read under the subtree must
+      // re-inject them rather than trusting a stale in-memory claim.
+      yield* executeTool(registry, readCall(sessionID, "call-after", "sub/file.txt"))
+      expect(yield* synthetics(sessionID)).toHaveLength(1)
+    }),
+  )
+
   it.effect("listing the Location root directory injects no instructions", () =>
     Effect.gen(function* () {
       const location = yield* Location.Service