@cortexkit/aft-opencode 0.61.0 → 0.63.4

package/src/shared/rpc-client.ts

@@ -250,7 +250,7 @@ export class AftRpcClient {
     info: PortInfo,
     signal?: AbortSignal,
   ): Promise<T> {
-    const response = await this.fetchWithTimeout(
+    return this.fetchWithTimeout(
       `http://127.0.0.1:${info.port}/rpc/${method}`,
       {
         method: "POST",
@@ -258,12 +258,14 @@ export class AftRpcClient {
         body: JSON.stringify({ ...params, token: info.token }),
       },
       signal,
+      async (response) => {
+        if (!response.ok) {
+          const text = await response.text();
+          throw new Error(`RPC ${method} failed (${response.status}): ${text}`);
+        }
+        return (await response.json()) as T;
+      },
     );
-    if (!response.ok) {
-      const text = await response.text();
-      throw new Error(`RPC ${method} failed (${response.status}): ${text}`);
-    }
-    return (await response.json()) as T;
   }
 
   /**
@@ -467,39 +469,43 @@ export class AftRpcClient {
     signal?: AbortSignal,
   ): Promise<boolean> {
     try {
-      const response = await this.fetchWithTimeout(
+      return await this.fetchWithTimeout(
         `http://127.0.0.1:${port}/health`,
         { method: "GET" },
         signal,
+        async (response) => {
+          if (!response.ok) return false;
+          // Identity check: the port file records the owning pid and `/health`
+          // echoes the live server's pid. If they disagree, the port was recycled
+          // by a *different* AFT server (or an unrelated localhost service that
+          // happens to answer /health), so this port file is stale — reject it so
+          // we don't POST this file's token to the wrong server. Only enforced when
+          // both sides expose a pid (older port files omit it).
+          if (expectedPid !== undefined) {
+            try {
+              const body = (await response.json()) as { pid?: unknown };
+              if (typeof body?.pid === "number" && body.pid !== expectedPid) return false;
+            } catch {
+              // Non-JSON / unexpected body: not a healthy AFT server we trust.
+              return false;
+            }
+          }
+          if (expectedPid === undefined) await response.body?.cancel();
+          return true;
+        },
       );
-      if (!response.ok) return false;
-      // Identity check: the port file records the owning pid and `/health`
-      // echoes the live server's pid. If they disagree, the port was recycled
-      // by a *different* AFT server (or an unrelated localhost service that
-      // happens to answer /health), so this port file is stale — reject it so
-      // we don't POST this file's token to the wrong server. Only enforced when
-      // both sides expose a pid (older port files omit it).
-      if (expectedPid !== undefined) {
-        try {
-          const body = (await response.json()) as { pid?: unknown };
-          if (typeof body?.pid === "number" && body.pid !== expectedPid) return false;
-        } catch {
-          // Non-JSON / unexpected body: not a healthy AFT server we trust.
-          return false;
-        }
-      }
-      return true;
     } catch {
       throwIfAborted(signal);
       return false;
     }
   }
 
-  private async fetchWithTimeout(
+  private async fetchWithTimeout<T>(
     url: string,
     options: RequestInit,
-    signal?: AbortSignal,
-  ): Promise<Response> {
+    signal: AbortSignal | undefined,
+    consume: (response: Response) => Promise<T>,
+  ): Promise<T> {
     throwIfAborted(signal);
 
     const controller = new AbortController();
@@ -507,7 +513,8 @@ export class AftRpcClient {
     const onAbort = () => controller.abort();
     signal?.addEventListener("abort", onAbort, { once: true });
     try {
-      return await fetch(url, { ...options, signal: controller.signal });
+      const response = await fetch(url, { ...options, signal: controller.signal });
+      return await consume(response);
     } finally {
       clearTimeout(timeout);
       signal?.removeEventListener("abort", onAbort);

package/src/shared/rpc-notifications.ts

@@ -102,12 +102,14 @@ export function pushNotification(
       }
     }
     const mustKeep = new Set(newestPerSession.values());
-    const byNewest = [...queue].sort((a, b) => b.id - a.id);
     const kept: RpcNotification[] = [];
-    for (const notification of byNewest) {
+    // Push assigns monotonic ids and pruning preserves order, so walking backwards is newest-first.
+    for (let index = queue.length - 1; index >= 0; index--) {
+      const notification = queue[index];
+      if (!notification) continue;
       if (kept.length < 50 || mustKeep.has(notification.id)) kept.push(notification);
     }
-    queue = kept.sort((a, b) => a.id - b.id);
+    queue = kept.reverse();
   }
 }
 

package/src/shared/rpc-server.ts

@@ -5,6 +5,7 @@ import {
   readdirSync,
   readFileSync,
   renameSync,
+  statSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -64,6 +65,7 @@ interface WsData {
 
 const PORT_FILE_HEARTBEAT_MS = 15_000;
 const MAX_BODY_BYTES = 1_048_576;
+const UNREADABLE_TMP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const WS_AUTH_TIMEOUT_MS = 5_000;
 const WS_CLOSE_UNAUTHORIZED = 4401;
 
@@ -97,6 +99,8 @@ export class AftRpcServer {
   /** Unique per-instance ID — distinguishes our entry from duplicate plugin loads. */
   private instanceId: string;
   private sockets = new Set<BunServerWebSocket<WsData>>();
+  private stopped = false;
+  private cancelNodeStartup: (() => void) | null = null;
 
   constructor(storageDir: string, directory: string) {
     this.portsDir = rpcPortFileDir(storageDir, directory);
@@ -148,6 +152,8 @@ export class AftRpcServer {
   private async startNode(): Promise<number> {
     return new Promise((resolve, reject) => {
       const server = createServer((req, res) => this.dispatch(req, res));
+      this.nodeServer = server;
+      this.cancelNodeStartup = () => reject(new Error("RPC server stopped during startup"));
 
       server.on("error", (err) => {
         warn(`RPC server error: ${err.message}`);
@@ -155,6 +161,12 @@ export class AftRpcServer {
       });
 
       server.listen(0, "127.0.0.1", () => {
+        this.cancelNodeStartup = null;
+        if (this.stopped || this.nodeServer !== server) {
+          server.close();
+          reject(new Error("RPC server stopped during startup"));
+          return;
+        }
         const addr = server.address();
         if (!addr || typeof addr === "string") {
           reject(new Error("Failed to get server address"));
@@ -172,6 +184,7 @@ export class AftRpcServer {
   }
 
   private afterServerStarted(): void {
+    if (this.stopped) return;
     try {
       this.writePortFile();
       log(`RPC server listening on 127.0.0.1:${this.port}`);
@@ -219,7 +232,8 @@ export class AftRpcServer {
       return;
     }
     for (const entry of entries) {
-      if (!entry.endsWith(".json")) continue;
+      const temporary = entry.endsWith(".json.tmp");
+      if (!temporary && !entry.endsWith(".json")) continue;
       const filePath = join(this.portsDir, entry);
       if (filePath === this.portFilePath) continue;
       try {
@@ -227,7 +241,13 @@ export class AftRpcServer {
         // Unparsable file: stale tmp/corrupt leftover — remove. Parsable but
         // pid-less (legacy): keep, we cannot prove the owner is dead.
         if (record === null) {
-          unlinkSync(filePath);
+          // An unreadable temporary record may still be in the middle of a live write.
+          if (
+            !temporary ||
+            Date.now() - statSync(join(this.portsDir, entry)).mtimeMs >= UNREADABLE_TMP_MAX_AGE_MS
+          ) {
+            unlinkSync(filePath);
+          }
           continue;
         }
         if (record.pid !== undefined && !isPidAlive(record.pid)) {
@@ -254,6 +274,9 @@ export class AftRpcServer {
 
   /** Stop the server and clean up port file. */
   stop(): void {
+    this.stopped = true;
+    this.cancelNodeStartup?.();
+    this.cancelNodeStartup = null;
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
@@ -305,10 +328,30 @@ export class AftRpcServer {
       return json({ error: `Unknown method: ${method}` }, 404);
     }
 
-    const bodyText = await req.text();
-    if (bodyText.length > MAX_BODY_BYTES) {
+    const declaredLength = Number(req.headers.get("content-length"));
+    if (declaredLength > MAX_BODY_BYTES) {
       return new Response("Request too large", { status: 413 });
     }
+    const chunks: Uint8Array[] = [];
+    let bytes = 0;
+    const reader = req.body?.getReader();
+    if (reader) {
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          bytes += value.byteLength;
+          if (bytes > MAX_BODY_BYTES) {
+            void reader.cancel().catch(() => {});
+            return new Response("Request too large", { status: 413 });
+          }
+          chunks.push(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    }
+    const bodyText = Buffer.concat(chunks, bytes).toString("utf8");
 
     let params: Record<string, unknown> = {};
     try {
@@ -435,17 +478,32 @@ export class AftRpcServer {
       return;
     }
 
-    let body = "";
+    if (Number(req.headers["content-length"]) > MAX_BODY_BYTES) {
+      res.writeHead(413);
+      res.end("Request too large");
+      req.resume();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let oversized = false;
     req.on("data", (chunk: Buffer) => {
-      body += chunk.toString();
-      if (body.length > MAX_BODY_BYTES) {
+      if (oversized) return;
+      bytes += chunk.byteLength;
+      if (bytes > MAX_BODY_BYTES) {
+        oversized = true;
+        chunks.length = 0;
         res.writeHead(413);
         res.end("Request too large");
         req.destroy();
+        return;
       }
+      chunks.push(chunk);
     });
 
     req.on("end", () => {
+      if (oversized) return;
+      const body = Buffer.concat(chunks, bytes).toString("utf8");
       let params: Record<string, unknown> = {};
       try {
         if (body.length > 0) {

package/src/shared/session-cleanup.ts

@@ -0,0 +1,13 @@
+import { clearSessionBgState } from "../bg-notifications.js";
+import { clearSyncWatchAbort } from "../sync-watch-abort.js";
+import { clearSessionPermissions } from "../tools/permissions.js";
+
+/**
+ * A session can start another execution after one completes, so its state is
+ * released only when the host removes the session.
+ */
+export function releaseSessionState(sessionID: string): void {
+  clearSyncWatchAbort(sessionID);
+  clearSessionPermissions(sessionID);
+  clearSessionBgState(sessionID);
+}

package/src/shared/session-directory.ts

@@ -19,6 +19,8 @@
  * `packages/opencode/src/session/registry.ts`. Until then this
  * workaround makes AFT robust against the wrong cwd.
  */
+
+import type { AftTransportPool } from "@cortexkit/aft-bridge";
 import { Effect } from "effect";
 
 import { sessionWarn } from "../logger.js";
@@ -97,6 +99,7 @@ interface CacheEntry {
 const CACHE_MAX_ENTRIES = 200;
 const cache = new Map<string, CacheEntry>();
 const inflight = new Map<string, Promise<string | null>>();
+const lookupGenerations = new Map<string, object>();
 
 /**
  * Resolve the project directory the session was created with from the SDK's
@@ -136,12 +139,18 @@ export async function getSessionDirectory(
   return lookup;
 }
 
-/** Ignore late answers: a timed-out lookup must not overwrite a later retry. */
+/** A late success may repair its provisional answer, but never overwrite a newer lookup. */
 async function boundedLookup(
   client: unknown,
   sessionId: string,
   fallbackDirectory: string,
 ): Promise<string | null> {
+  const generation = {};
+  lookupGenerations.set(sessionId, generation);
+  if (lookupGenerations.size > CACHE_MAX_ENTRIES) {
+    const oldest = lookupGenerations.keys().next().value;
+    if (oldest !== undefined) lookupGenerations.delete(oldest);
+  }
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
     const timeout = new Promise<null>((resolve) => {
@@ -154,7 +163,16 @@ async function boundedLookup(
       }, LOOKUP_TIMEOUT_MS);
     });
     const directory = await Promise.race([
-      lookupSessionDirectory(client, sessionId, fallbackDirectory),
+      lookupSessionDirectory(client, sessionId, fallbackDirectory)
+        .then((directory) => {
+          if (lookupGenerations.get(sessionId) === generation && directory !== null) {
+            setCache(sessionId, directory);
+          }
+          return directory;
+        })
+        .finally(() => {
+          if (lookupGenerations.get(sessionId) === generation) lookupGenerations.delete(sessionId);
+        }),
       timeout,
     ]);
     setCache(sessionId, directory);
@@ -308,6 +326,7 @@ export function warmSessionDirectory(
  */
 const VERIFY_TTL_MS = 15_000;
 const verifyCache = new Map<string, { directory: string | null; verifiedAt: number }>();
+const verifyInflight = new Map<string, Promise<string | null>>();
 
 export async function verifySessionDirectory(
   client: unknown,
@@ -316,14 +335,32 @@ export async function verifySessionDirectory(
   if (!sessionId) return null;
   const hit = verifyCache.get(sessionId);
   if (hit && Date.now() - hit.verifiedAt < VERIFY_TTL_MS) return hit.directory;
+  const pending = verifyInflight.get(sessionId);
+  if (pending) return pending;
+  const lookup = boundedVerification(client, sessionId).finally(() => {
+    verifyInflight.delete(sessionId);
+  });
+  verifyInflight.set(sessionId, lookup);
+  return lookup;
+}
 
+async function boundedVerification(client: unknown, sessionId: string): Promise<string | null> {
   const c = client as OpenCodeClientShape;
   const sessionApi = c?.session;
   if (!sessionApi || typeof sessionApi.get !== "function") return null;
 
   let dir: string | null = null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
   try {
-    const result = await sessionApi.get({ path: { id: sessionId } });
+    const result = await Promise.race([
+      sessionApi.get({ path: { id: sessionId } }),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("Session verification timed out")),
+          LOOKUP_TIMEOUT_MS,
+        );
+      }),
+    ]);
     const session: SessionInfo | undefined =
       (result as { data?: SessionInfo } | undefined)?.data ?? (result as SessionInfo | undefined);
     if (session && typeof session.directory === "string" && session.directory.length > 0) {
@@ -334,6 +371,8 @@ export async function verifySessionDirectory(
     // failures: the next poll should retry (transient SDK errors must not
     // stick the sidebar on placeholder for the TTL window).
     return null;
+  } finally {
+    clearTimeout(timer);
   }
 
   verifyCache.set(sessionId, { directory: dir, verifiedAt: Date.now() });
@@ -346,9 +385,26 @@ export async function verifySessionDirectory(
   return dir;
 }
 
+/** Release transport routes on deletion without querying a session the host has already removed. */
+export async function closeDeletedSessionRoutes(
+  pool: AftTransportPool,
+  sessionId: string,
+  fallbackDirectory: string,
+): Promise<void> {
+  // A timeout may have bound a fallback before the stored root was known. Close both routes.
+  const roots = new Set(pool.activeBridges().map((bridge) => bridge.getCwd()));
+  roots.add(getSessionDirectoryCached(sessionId) ?? fallbackDirectory);
+  await Promise.allSettled([...roots].map((root) => pool.closeSession(root, sessionId)));
+  cache.delete(sessionId);
+  lookupGenerations.delete(sessionId);
+  verifyCache.delete(sessionId);
+}
+
 /** Test-only: clear the cache between unit tests. */
 export function _resetSessionDirectoryCacheForTest(): void {
   cache.clear();
   inflight.clear();
+  lookupGenerations.clear();
   verifyCache.clear();
+  verifyInflight.clear();
 }

package/src/shared/status.ts

@@ -28,13 +28,14 @@ export const NOT_STARTED_STATUS_TEXT = "Starts on the first tool call.";
 export function formatSemanticIndexLabel(
   semantic: Pick<
     AftStatusSnapshot["semantic_index"],
-    "status" | "stage" | "error" | "reason" | "backend_url"
+    "status" | "stage" | "error" | "reason" | "backend_url" | "pending_reason"
   >,
 ): string {
-  return formatSemanticIndexStatus(semantic.status, semantic.stage, semantic.error, {
+  const label = formatSemanticIndexStatus(semantic.status, semantic.stage, semantic.error, {
     reason: semantic.reason,
     backendUrl: semantic.backend_url,
   });
+  return semantic.pending_reason ? `${label} — ${semantic.pending_reason}` : label;
 }
 
 export interface StatusCompressionAggregate {
@@ -117,6 +118,17 @@ export interface AftStatusSnapshot {
     reason?: string | null;
     /** Configured remote embedding backend URL, when there is one. */
     backend_url?: string | null;
+    /** Operator-only coordination line; never an agent tool failure reason. */
+    pending_reason?: string | null;
+    coordination_error?: {
+      state: string;
+      kind: string;
+      reason: string;
+      detail: string;
+      retryable: boolean;
+      retry_scheduled: boolean;
+      retry_in_ms: number | null;
+    };
   };
   disk: {
     storage_dir: string | null;
@@ -323,6 +335,7 @@ export function coerceAftStatus(response: Record<string, unknown>): AftStatusSna
   const features = asRecord(response.features);
   const searchIndex = asRecord(response.search_index);
   const semanticIndex = asRecord(response.semantic_index);
+  const coordination = asRecord(semanticIndex.coordination_error);
   const semanticConfig = {
     ...asRecord(response.semantic),
     ...asRecord((response as { semantic_config?: unknown }).semantic_config),
@@ -370,6 +383,23 @@ export function coerceAftStatus(response: Record<string, unknown>): AftStatusSna
       error: readNullableString(semanticIndex.error),
       reason: readNullableString(semanticIndex.reason),
       backend_url: readNullableString(semanticIndex.backend_url),
+      ...(typeof semanticIndex.pending_reason === "string" &&
+      semanticIndex.pending_reason.length > 0
+        ? { pending_reason: semanticIndex.pending_reason }
+        : {}),
+      ...(Object.keys(coordination).length > 0
+        ? {
+            coordination_error: {
+              state: readString(coordination.state),
+              kind: readString(coordination.kind),
+              reason: readString(coordination.reason),
+              detail: readString(coordination.detail),
+              retryable: readBoolean(coordination.retryable),
+              retry_scheduled: readBoolean(coordination.retry_scheduled),
+              retry_in_ms: readOptionalNumber(coordination.retry_in_ms),
+            },
+          }
+        : {}),
     },
     disk: {
       storage_dir: readNullableString(disk.storage_dir),

package/src/shared/subagent-detect.ts

@@ -25,8 +25,9 @@
  * lookup must stay cheap and bounded:
  * - concurrent first calls for one session share a single lookup;
  * - a lookup that has not answered within LOOKUP_TIMEOUT_MS is abandoned and
- *   that call proceeds as primary, so a slow host can't delay a read;
- * - a failed or abandoned lookup is cached as "primary" for
+ *   that call proceeds with an unknown role, so a slow host delays a read by
+ *   at most LOOKUP_TIMEOUT_MS;
+ * - a failed or abandoned lookup is cached as unknown for
  *   FAILED_LOOKUP_RETRY_MS, then retried, so a struggling host is not asked on
  *   every call but the real answer is still picked up later.
  *
@@ -50,10 +51,12 @@ interface OpenCodeClientShape {
   };
 }
 
+export type SubagentStatus = boolean | "unknown";
+
 interface CacheEntry {
-  isSubagent: boolean;
+  isSubagent: SubagentStatus;
   /**
-   * When a provisional "primary" answer (recorded after a failed or timed-out
+   * When an unknown answer (recorded after a failed or timed-out
    * lookup) stops counting and the host is asked again. Absent for a real
    * answer, which never changes: a session's parent is fixed at creation.
    */
@@ -63,19 +66,25 @@ interface CacheEntry {
 const CACHE_MAX_ENTRIES = 200;
 /** Longest a caller waits for the host's session lookup. */
 export const LOOKUP_TIMEOUT_MS = 1_000;
-/** How long a failed or timed-out lookup is answered as "primary" before retrying. */
-export const FAILED_LOOKUP_RETRY_MS = 30_000;
+/**
+ * How long an unknown role (after a failed or timed-out lookup) is reused
+ * before the host is asked again. Short, because an unknown role is treated
+ * cautiously by the shell and stop handlers until the real answer arrives; not
+ * zero, because a host that keeps timing out would otherwise add up to
+ * LOOKUP_TIMEOUT_MS to every tool call.
+ */
+export const FAILED_LOOKUP_RETRY_MS = 5_000;
 const cache = new Map<string, CacheEntry>();
 /** One lookup per session at a time; concurrent first calls await it. */
-const inflight = new Map<string, Promise<boolean>>();
+const inflight = new Map<string, Promise<SubagentStatus>>();
 let now: () => number = () => Date.now();
 
 /**
- * Returns `true` when the given session has a non-empty `parentID`
- * (subagent). Returns `false` for primary sessions, when the SDK is
- * unavailable, or when the lookup fails or takes longer than
- * LOOKUP_TIMEOUT_MS; the false default keeps primary sessions working
- * exactly as before.
+ * Returns `true` only when the given session is known to have a non-empty
+ * `parentID` (subagent). Returns `false` for primary sessions, when the SDK is
+ * unavailable, and for an unknown role (the lookup failed or took longer than
+ * LOOKUP_TIMEOUT_MS). Callers whose safe default for an unknown role is the
+ * subagent behaviour use resolveSubagentStatus instead.
  *
  * A known answer is an O(1) cache hit. Otherwise at most one host lookup
  * per session is in flight, and it is bounded by LOOKUP_TIMEOUT_MS.
@@ -83,8 +92,24 @@ let now: () => number = () => Date.now();
 export async function resolveIsSubagent(
   client: unknown,
   sessionId: string | undefined,
-  _fallbackDirectory?: string,
+  fallbackDirectory?: string,
 ): Promise<boolean> {
+  return (await resolveSubagentStatus(client, sessionId, fallbackDirectory)) === true;
+}
+
+/**
+ * The session's role: `true` when a non-empty `parentID` marks a subagent,
+ * `false` when the host says it has no parent (or there is no session or no
+ * lookup API to ask), and "unknown" while the host lookup is failing or slow.
+ * The shell tool, the watch tool and the OpenCode 2 stop handler treat
+ * "unknown" like a subagent, so a slow lookup cannot strip a subagent of its
+ * foreground rule or its stop cleanup.
+ */
+export async function resolveSubagentStatus(
+  client: unknown,
+  sessionId: string | undefined,
+  _fallbackDirectory?: string,
+): Promise<SubagentStatus> {
   if (!sessionId) {
     sessionLog(undefined, "[subagent-detect] no sessionId provided → primary");
     return false;
@@ -110,18 +135,22 @@ export async function resolveIsSubagent(
 
 /**
  * Runs the host lookup, giving up after LOOKUP_TIMEOUT_MS. A real answer is
- * cached for good; a failure or timeout is cached as "primary" until
- * FAILED_LOOKUP_RETRY_MS has passed. The abandoned host call is left to
- * settle on its own; its late answer is ignored.
+ * cached for good; a failure or timeout is cached as "unknown" until
+ * FAILED_LOOKUP_RETRY_MS has passed. On OpenCode 2 the lookup is an Effect, and
+ * Effect.timeout interrupts it when the time is up, so no abandoned lookup
+ * keeps running. An OpenCode 1 lookup is a promise that cannot be cancelled;
+ * its late answer is ignored.
  */
-async function boundedLookup(client: unknown, sessionId: string): Promise<boolean> {
+async function boundedLookup(client: unknown, sessionId: string): Promise<SubagentStatus> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   const timedOut = new Promise<"timeout">((resolve) => {
     timer = setTimeout(() => resolve("timeout"), LOOKUP_TIMEOUT_MS);
   });
   let answer: boolean | "failed" | "timeout";
   try {
-    answer = await Promise.race([lookupSession(client, sessionId), timedOut]);
+    answer = isV2PluginContext(client)
+      ? await resolveV2(client, sessionId)
+      : await Promise.race([lookupSession(client, sessionId), timedOut]);
   } finally {
     clearTimeout(timer);
   }
@@ -132,11 +161,11 @@ async function boundedLookup(client: unknown, sessionId: string): Promise<boolea
   if (answer === "timeout") {
     sessionWarn(
       sessionId,
-      `[subagent-detect] session lookup did not answer within ${LOOKUP_TIMEOUT_MS}ms → primary for now`,
+      `[subagent-detect] session lookup did not answer within ${LOOKUP_TIMEOUT_MS}ms → unknown for now`,
     );
   }
-  setCache(sessionId, false, now() + FAILED_LOOKUP_RETRY_MS);
-  return false;
+  setCache(sessionId, "unknown", now() + FAILED_LOOKUP_RETRY_MS);
+  return "unknown";
 }
 
 /** The host's answer, or "failed" when the lookup threw. Never rejects. */
@@ -225,17 +254,16 @@ async function resolveV2(
   let session: SessionInfo | undefined;
   try {
     session = await Effect.runPromise(
-      context.session.get({ sessionID: sessionId }) as Effect.Effect<SessionInfo | undefined>,
+      Effect.timeout(context.session.get({ sessionID: sessionId }), LOOKUP_TIMEOUT_MS),
     );
   } catch (err) {
-    // Same policy as the V1 path: a failed lookup counts as primary only
-    // until FAILED_LOOKUP_RETRY_MS has passed.
     sessionWarn(
       sessionId,
       `[subagent-detect] OpenCode 2 session lookup failed: ${err instanceof Error ? err.message : String(err)}`,
     );
     return "failed";
   }
+  if (!session) return "failed";
   const isSubagent = typeof session?.parentID === "string" && session.parentID.length > 0;
   sessionLog(
     sessionId,
@@ -244,7 +272,7 @@ async function resolveV2(
   return isSubagent;
 }
 
-function setCache(sessionId: string, isSubagent: boolean, retryAfter?: number): void {
+function setCache(sessionId: string, isSubagent: SubagentStatus, retryAfter?: number): void {
   if (cache.has(sessionId)) cache.delete(sessionId);
   cache.set(sessionId, retryAfter === undefined ? { isSubagent } : { isSubagent, retryAfter });
   if (cache.size > CACHE_MAX_ENTRIES) {