fix: add timeout to parent-fork token count resolution (fixes #101718)

zw-xysk · zw-xysk · commit fa09d43051a2 · 2026-07-08T00:23:19.000+08:00
resolveParentForkTokenCount reads the parent transcript to estimate token
count when forking a session, but has no timeout. On large transcripts
or slow filesystems (NFS, FUSE), this blocks session creation indefinitely,
accumulating blocked async contexts on the gateway.

Wrap the runtime call in resolveParentForkTokenCount with
withTimeout(..., 2_000) so the function returns undefined within bounded
time. resolveParentForkDecision already handles undefined parentTokens
correctly (returns fork without a token estimate), which is the safe
default vs. blocking indefinitely.

Includes regression tests for the fast-resolve, timeout, and too-large
paths.
diff --git a/src/auto-reply/reply/session-fork.test.ts b/src/auto-reply/reply/session-fork.test.ts
@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
-import { forkSessionEntryFromParent } from "./session-fork.js";
+import { forkSessionEntryFromParent, resolveParentForkDecision } from "./session-fork.js";
 
 const runtimeMocks = vi.hoisted(() => ({
   forkSessionFromParentRuntime: vi.fn(),
@@ -85,3 +85,49 @@ describe("forkSessionEntryFromParent", () => {
     expect(stored[sessionKey]?.sessionFile).toBe(path.join(activeStoreDir, "forked-session.jsonl"));
   });
 });
+
+describe("resolveParentForkDecision", () => {
+  it("returns fork with parentTokens when the runtime resolves quickly", async () => {
+    runtimeMocks.resolveParentForkTokenCountRuntime.mockResolvedValue(50_000);
+
+    const decision = await resolveParentForkDecision({
+      parentEntry: { sessionId: "parent", updatedAt: 1 },
+      agentId: "main",
+      storePath: "/tmp/sessions.json",
+    });
+
+    expect(decision.status).toBe("fork");
+    expect(decision).toHaveProperty("parentTokens", 50_000);
+  });
+
+  it("returns fork without parentTokens when the runtime hangs (timeout protection)", async () => {
+    // Simulate a hung filesystem runtime that never resolves.
+    runtimeMocks.resolveParentForkTokenCountRuntime.mockReturnValue(new Promise<number>(() => {}));
+
+    const decision = await resolveParentForkDecision({
+      parentEntry: { sessionId: "parent", updatedAt: 1 },
+      agentId: "main",
+      storePath: "/tmp/sessions.json",
+    });
+
+    // Must still return a decision (not throw/timeout the caller).
+    // Fork proceeds without a token estimate rather than blocking (#101718).
+    expect(decision.status).toBe("fork");
+    expect(decision).not.toHaveProperty("parentTokens");
+  });
+
+  it("returns skip when parent is too large", async () => {
+    runtimeMocks.resolveParentForkTokenCountRuntime.mockResolvedValue(200_000);
+
+    const decision = await resolveParentForkDecision({
+      parentEntry: { sessionId: "parent", updatedAt: 1 },
+      agentId: "main",
+      storePath: "/tmp/sessions.json",
+    });
+
+    expect(decision.status).toBe("skip");
+    expect(decision.reason).toBe("parent-too-large");
+    expect(decision.parentTokens).toBe(200_000);
+    expect(decision.maxTokens).toBe(100_000);
+  });
+});
diff --git a/src/auto-reply/reply/session-fork.ts b/src/auto-reply/reply/session-fork.ts
@@ -3,6 +3,7 @@ import { resolveStorePath } from "../../config/sessions/paths.js";
 import { updateSessionStore } from "../../config/sessions/store.js";
 import { mergeSessionEntry, type SessionEntry } from "../../config/sessions/types.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { withTimeout } from "../../infra/fs-safe.js";
 import { createLazyImportLoader } from "../../shared/lazy-promise.js";
 
 /**
@@ -11,6 +12,7 @@ import { createLazyImportLoader } from "../../shared/lazy-promise.js";
  * See #26905.
  */
 const DEFAULT_PARENT_FORK_MAX_TOKENS = 100_000;
+const PARENT_FORK_TOKEN_TIMEOUT_MS = 2_000;
 const sessionForkRuntimeLoader = createLazyImportLoader(() => import("./session-fork.runtime.js"));
 
 export type ParentForkDecision =
@@ -296,5 +298,9 @@ async function resolveParentForkTokenCount(params: {
   storePath: string;
 }): Promise<number | undefined> {
   const runtime = await loadSessionForkRuntime();
-  return runtime.resolveParentForkTokenCountRuntime(params);
+  return await withTimeout(
+    runtime.resolveParentForkTokenCountRuntime(params),
+    PARENT_FORK_TOKEN_TIMEOUT_MS,
+    "resolveParentForkTokenCount",
+  ).catch(() => undefined);
 }
