address copilot R3: tighten JSDoc + restore AutoReply trace span

R3 caught two issues:

1. JSDoc overstated the cross-root guard. The runtime check only catches
   a non-empty cache that lacks root; it does not catch a cache that has
   been mixed (root present plus entries from a different root). Detecting
   that would require tagging the cache. JSDoc rewritten to be honest:
   the guard is partial, intended usage is one cache per root, and a
   Map<root,Set> is the correct shape if disjoint roots must share state.

2. AutoReply lost its 'SessionAutoReply.isDescendant' trace span when the
   walk delegated to a plain arrow function. Restored Effect.fn wrapper so
   traces still show the AutoReply-specific call site alongside the inner
   Session.isDescendantOf span. No behavior change, only observability.

PR feedback: #16
- comment 3163766945 (JSDoc overstates guard scope)
- comment 3163766986 (lost trace span name)

Author: tesdal

packages/opencode/src/session/auto-reply/auto-reply.ts

@@ -48,11 +48,17 @@ export const make = Effect.fn("SessionAutoReply.make")(function* (config: Config
 
   // Reused across calls so the parent walk is traversed at most once per
   // descendant id. Session.isDescendantOf auto-seeds `rootSessionID` on every
-  // call, so an empty Set is the simplest seed.
+  // call, so an empty Set is the simplest seed. Wrapped in Effect.fn so
+  // AutoReply-specific lineage checks remain identifiable in traces alongside
+  // the inner Session.isDescendantOf span.
   const descendants = new Set<SessionID>()
 
-  const isDescendant = (sid: SessionID) =>
-    session.isDescendantOf(sid, config.rootSessionID, { maxDepth: MAX_LINEAGE_DEPTH, cache: descendants })
+  const isDescendant = Effect.fn("SessionAutoReply.isDescendant")(function* (sid: SessionID) {
+    return yield* session.isDescendantOf(sid, config.rootSessionID, {
+      maxDepth: MAX_LINEAGE_DEPTH,
+      cache: descendants,
+    })
+  })
 
   const bump = (kind: "question" | "permission", sid: SessionID) => {
     if (kind === "question") stats.autoRejectedQuestions++

packages/opencode/src/session/session.ts

@@ -383,12 +383,16 @@ export interface Interface {
    * accumulator: every confirmed descendant in the walked chain is added to
    * the set. The cache is auto-seeded with `root` on every call, so callers
    * can pass a fresh `new Set()` and reuse it across calls without seeding.
-   * Caches MUST NOT be shared across different roots — if a non-empty cache
-   * is passed that does not already contain `root`, the call dies with a
-   * clear error instead of returning silently-wrong results from another
-   * lineage's accumulated entries. Callers that issue many `isDescendantOf`
-   * calls against the same root (e.g. SessionAutoReply) should reuse one
-   * cache so the parent chain is traversed at most once per node.
+   *
+   * Cache reuse is only safe within a single root. As a partial guard, if a
+   * non-empty cache is passed that does not already contain `root`, the call
+   * dies — that case can only arise from a cache leaked from another lineage.
+   * The guard does NOT catch caches that have been mixed (root present plus
+   * entries from a different root); detecting that would require tagging the
+   * cache. Each `SessionAutoReply` instance owns its own cache, which is the
+   * intended usage. If you have a use case that needs disjoint roots to
+   * share a cache, build a `Map<root, Set<SessionID>>` outside this helper
+   * and pass the per-root inner Set.
    */
   readonly isDescendantOf: (
     sid: SessionID,