@librechat/agents 3.2.42 → 3.2.44

package/src/tools/__tests__/CloudflareSandboxExecution.test.ts

@@ -10,6 +10,7 @@ import {
   createCloudflareBashProgrammaticToolCallingTool,
   createCloudflareProgrammaticToolCallingTool,
 } from '../cloudflare/CloudflareProgrammaticToolCalling';
+import { isWorkspaceClientTimeoutError } from '../local/workspaceFS';
 import { createCloudflareBridgeRuntime } from '../cloudflare/CloudflareBridgeRuntime';
 import { resolveLocalToolsForBinding } from '../local/resolveLocalExecutionTools';
 import { spawnLocalProcess } from '../local/LocalExecutionEngine';
@@ -388,6 +389,197 @@ describe('Cloudflare sandbox execution backend', () => {
     expect(received).not.toHaveProperty('signal');
   });
 
+  it('rejects with a client-side timeout when sandbox readFile stalls', async () => {
+    // The native-DO file-IO RPCs (readFile/writeFile/listFiles/...) have the same
+    // stall hazard exec() does: no signal, no enforced timeout. A cold/unresponsive
+    // container otherwise hangs the host await until the run-level abort, burning
+    // the whole budget on one read (observed live: a `read_file` stalled ~552s).
+    jest.useFakeTimers();
+    try {
+      let readCalls = 0;
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          readFile: () => {
+            readCalls += 1;
+            return new Promise<string>(() => undefined);
+          },
+        }),
+      });
+
+      const error = (fs.readFile as (p: string) => Promise<unknown>)(
+        '/workspace/a.txt'
+      ).catch((e: unknown) => e);
+      // Client backstop = clientFsTimeoutMs(1000) = 6000ms; advance past it.
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await error;
+      // Must be the DISTINGUISHABLE timeout error so ENOENT-only callers rethrow
+      // it instead of mistaking a stalled read for a missing file.
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+      expect((settled as Error).message).toMatch(/client-side timeout/);
+      expect(readCalls).toBe(1);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('keeps the backstop active while draining a streamed file read', async () => {
+    // sandbox.readFile resolves to { content: ReadableStream } whose stream never
+    // ends. The race must cover the drain (normalizeReadFileContent), not just the
+    // initial RPC, or read_file/open/stat still hang to the run-level abort.
+    jest.useFakeTimers();
+    try {
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          readFile: async () => ({
+            content: new ReadableStream<Uint8Array>({
+              // start() never enqueues or closes -> the drain stalls forever.
+              start() {},
+            }),
+          }),
+        }),
+      });
+
+      const error = (fs.readFile as (p: string) => Promise<unknown>)(
+        '/workspace/a.txt'
+      ).catch((e: unknown) => e);
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await error;
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('rethrows a stat directory-probe timeout instead of falling through to readFile', async () => {
+    // findChildInfo returns nothing -> the directory probe (listFiles) runs; if it
+    // STALLS it must surface, not fall through to the readFile branch (which would
+    // burn a SECOND full backstop, ~2x the timeout, before the caller sees it).
+    jest.useFakeTimers();
+    try {
+      let readFileCalls = 0;
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          listFiles: (dir) =>
+            dir === '/workspace/probe-me'
+              ? new Promise(() => undefined) // the probe stalls
+              : Promise.resolve([]), // findChildInfo's parent listing returns fast
+          readFile: () => {
+            readFileCalls += 1;
+            return Promise.resolve('');
+          },
+        }),
+      });
+
+      const error = fs.stat('/workspace/probe-me').catch((e: unknown) => e);
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await error;
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+      // Must NOT have fallen through to the readFile probe.
+      expect(readFileCalls).toBe(0);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('bounds execute_code temp-dir setup RPCs (mkdir/writeFile) that stall', async () => {
+    jest.useFakeTimers();
+    try {
+      const sandbox = createRuntime({
+        // exec would resolve fine; the stall is in the pre-exec mkdir setup.
+        mkdir: () => new Promise<{ ok: true }>(() => undefined),
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("hi")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+      await jest.advanceTimersByTimeAsync(6500);
+      await assertion;
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('still cleans up the temp dir when execute_code setup (writeFile) times out', async () => {
+    // The setup RPCs are inside the try, so a stalled writeFile still triggers
+    // the finally cleanup — otherwise the late (uncancellable) write leaves an
+    // orphaned .lc-exec/<uuid> dir behind on every cold-container failure.
+    jest.useFakeTimers();
+    try {
+      const execCommands: string[] = [];
+      const sandbox = createRuntime({
+        mkdir: async () => ({ ok: true }),
+        writeFile: () => new Promise<{ ok: true }>(() => undefined), // stalls
+        exec: async (command) => {
+          execCommands.push(command);
+          return { exitCode: 0, stdout: '', stderr: '' };
+        },
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("hi")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      ).catch((e: unknown) => e);
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await promise;
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+      // Cleanup must have been issued despite the setup failure.
+      expect(execCommands.some((c) => c.startsWith('rm -rf'))).toBe(true);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('rejects with a client-side timeout when sandbox listFiles stalls', async () => {
+    jest.useFakeTimers();
+    try {
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          listFiles: () =>
+            new Promise<t.CloudflareSandboxFileInfo[]>(() => undefined),
+        }),
+      });
+
+      const promise = (fs.readdir as (p: string) => Promise<unknown>)(
+        '/workspace/sub'
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+      await jest.advanceTimersByTimeAsync(6500);
+      await assertion;
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('does not time out a native FS RPC that returns in time', async () => {
+    jest.useFakeTimers();
+    try {
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({ readFile: async () => 'contents' }),
+      });
+
+      const result = await (
+        fs.readFile as (p: string, e: 'utf8') => Promise<string>
+      )('/workspace/a.txt', 'utf8');
+      expect(result).toBe('contents');
+      // The backstop timer must have been cleared, not left dangling.
+      expect(jest.getTimerCount()).toBe(0);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
   it('passes call-specific timeouts to the Cloudflare spawn wrapper', async () => {
     let execCommand = '';
     let execTimeout: number | undefined;

package/src/tools/__tests__/LocalExecutionTools.test.ts

@@ -37,6 +37,8 @@ import {
   _resetSyntaxCheckProbeCacheForTests,
 } from '../local/syntaxCheck';
 import { resolveLocalToolsForBinding } from '../local/resolveLocalExecutionTools';
+import { WorkspaceClientTimeoutError } from '../local/workspaceFS';
+import type { WorkspaceFS } from '../local/workspaceFS';
 import { LocalFileCheckpointerImpl } from '../local/FileCheckpointer';
 import { createCompileCheckTool } from '../local/CompileCheckTool';
 import { runBashAstChecks } from '../local/bashAst';
@@ -2317,6 +2319,58 @@ describe('comprehensive review (round 14) — Codex P1 #37 + P2 #38/#40/#41', ()
       ).rejects.toThrow(/syntax check failed.*reverted/i);
       expect(await fsp.readFile(file, 'utf8')).toBe(original);
     });
+
+    it('write_file: still reverts when the strict validation READ times out', async () => {
+      // A stalled validation read must not leave the just-written bytes on disk —
+      // strict mode's revert contract still applies when validation is
+      // inconclusive due to a timeout (here a brand-new file -> unlink).
+      const cwd = await createTempDir();
+      const file = join(cwd, 'config.json');
+      const unlinked: string[] = [];
+      let written = false;
+      const fakeFs = {
+        readFile: async () => {
+          if (!written) {
+            // write_file pre-read: the file does not exist yet.
+            throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+          }
+          // jsonCheck's post-write validation read stalls.
+          throw new WorkspaceClientTimeoutError(
+            'cloudflare sandbox readFile exceeded 6000ms client-side timeout'
+          );
+        },
+        writeFile: async () => {
+          written = true;
+        },
+        mkdir: async () => undefined,
+        unlink: async (p: string) => {
+          unlinked.push(p);
+        },
+        stat: async () => ({ isFile: () => true, size: 1 }),
+        readdir: async () => [],
+        realpath: async (p: string) => p,
+      } as unknown as WorkspaceFS;
+
+      const bundle = createLocalCodingToolBundle({
+        cwd,
+        postEditSyntaxCheck: 'strict',
+        exec: { fs: fakeFs },
+      });
+      const writeTool = bundle.tools.find(
+        (tt) => tt.name === Constants.WRITE_FILE
+      );
+      await expect(
+        writeTool!.invoke({
+          id: 'wf-strict-read-timeout',
+          name: Constants.WRITE_FILE,
+          args: { path: file, content: '{"ok": true}\n' },
+          type: 'tool_call',
+        })
+      ).rejects.toThrow(/client-side timeout/);
+      // strict mode attempted the revert (brand-new file -> unlink), rather than
+      // leaving the unvalidated write on disk.
+      expect(unlinked.length).toBeGreaterThan(0);
+    });
   });
 
   describe('fallbackGrep skip sentinels do not count as matches (Codex P2 [43])', () => {

package/src/tools/cloudflare/CloudflareSandboxExecutionEngine.ts

@@ -5,6 +5,10 @@ import type { WriteFileOptions, MakeDirectoryOptions, Stats } from 'fs';
 import type { ChildProcessWithoutNullStreams } from 'child_process';
 import type { FileHandle } from 'fs/promises';
 import type { WorkspaceFS, ReaddirEntry } from '@/tools/local/workspaceFS';
+import {
+  WorkspaceClientTimeoutError,
+  isWorkspaceClientTimeoutError,
+} from '@/tools/local/workspaceFS';
 import type * as t from '@/types';
 import {
   LOCAL_SPAWN_TIMEOUT_MS,
@@ -140,6 +144,18 @@ export function clientExecTimeoutMs(timeoutMs: number): number {
   return outerTimeoutMs(timeoutMs) + 5000;
 }
 
+/**
+ * Client-side backstop timeout for a native-DO sandbox FILE-IO RPC
+ * (`readFile`/`writeFile`/`listFiles`/`mkdir`/`deleteFile`). Unlike `exec()`
+ * there is no in-sandbox `timeout(1)` layer for these to honor, so this is just a
+ * few seconds of headroom over the configured tool timeout — enough that a normal
+ * (even large, byte-capped) read completes, while a stalled/cold container can't
+ * outlast it. See `withClientTimeout` for why the native DO RPC needs this.
+ */
+export function clientFsTimeoutMs(timeoutMs: number): number {
+  return timeoutMs + 5000;
+}
+
 /**
  * Bound a `sandbox.exec()` await with a CLIENT-SIDE timeout.
  *
@@ -188,8 +204,8 @@ export async function withClientTimeout<T>(
           // only then abort a signal-aware exec, whose resulting AbortError must
           // not surface to the caller instead of the timeout.
           reject(
-            new Error(
-              `${label} exceeded ${timeoutMs}ms client-side timeout (sandbox exec did not return)`
+            new WorkspaceClientTimeoutError(
+              `${label} exceeded ${timeoutMs}ms client-side timeout (sandbox RPC did not return)`
             )
           );
           options.onTimeout?.();
@@ -412,12 +428,17 @@ function createDirent(info: t.CloudflareSandboxFileInfo): ReaddirEntry {
 
 async function findChildInfo(
   sandbox: t.CloudflareSandboxRuntime,
-  filePath: string
+  filePath: string,
+  timeoutMs: number
 ): Promise<t.CloudflareSandboxFileInfo | undefined> {
   const parent = path.dirname(filePath);
   const basename = path.basename(filePath);
   const entries = normalizeFileList(
-    await sandbox.listFiles(parent, { includeHidden: true })
+    await withClientTimeout(
+      sandbox.listFiles(parent, { includeHidden: true }),
+      timeoutMs,
+      'cloudflare sandbox listFiles'
+    )
   );
   return entries.find((entry) => {
     const absolute = entryAbsolutePath(entry, parent);
@@ -429,13 +450,29 @@ export function createCloudflareWorkspaceFS(
   config: t.CloudflareSandboxExecutionConfig
 ): WorkspaceFS {
   const workspaceRoot = getCloudflareWorkspaceRoot(config);
+  // Native-DO file-IO RPCs have the SAME stall hazard as exec() (PR #252): no
+  // `signal`, no reliably-enforced timeout, so a cold/unresponsive container
+  // hangs the host await until the run-level abort — burning the whole budget on
+  // one read (observed: a `read_file` that stalled ~552s before the wall-clock
+  // budget killed it). Bound every native FS RPC with the same client-side
+  // backstop the exec sites use.
+  const fsTimeoutMs = clientFsTimeoutMs(config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const bound = <T>(op: Promise<T>, label: string): Promise<T> =>
+    withClientTimeout(op, fsTimeoutMs, `cloudflare sandbox ${label}`);
 
   const fs: WorkspaceFS = {
     readFile: (async (filePath: string, encoding?: 'utf8') => {
       const sandbox = await resolveCloudflareSandbox(config);
       const resolved = toSandboxPath(filePath, workspaceRoot);
-      const buffer = await normalizeReadFileContent(
-        await sandbox.readFile(resolved, encoding ? { encoding } : undefined)
+      // Wrap the stream drain (normalizeReadFileContent) inside the backstop too:
+      // a sandbox.readFile that resolves to a { content: ReadableStream } can
+      // still stall mid-drain after the RPC promise settled.
+      const buffer = await bound(
+        (async (): Promise<Buffer> =>
+          normalizeReadFileContent(
+            await sandbox.readFile(resolved, encoding ? { encoding } : undefined)
+          ))(),
+        'readFile'
       );
       return encoding != null ? buffer.toString(encoding) : buffer;
     }) as WorkspaceFS['readFile'],
@@ -447,29 +484,46 @@ export function createCloudflareWorkspaceFS(
       const sandbox = await resolveCloudflareSandbox(config);
       const resolved = toSandboxPath(filePath, workspaceRoot);
       const normalized = normalizeWriteFileContent(content);
-      await sandbox.writeFile(resolved, normalized.content, normalized.options);
+      await bound(
+        sandbox.writeFile(resolved, normalized.content, normalized.options),
+        'writeFile'
+      );
     },
     stat: async (filePath: string) => {
       const sandbox = await resolveCloudflareSandbox(config);
       const resolved = toSandboxPath(filePath, workspaceRoot);
       if (resolved === workspaceRoot) {
         const entries = normalizeFileList(
-          await sandbox.listFiles(resolved, { includeHidden: true })
+          await bound(
+            sandbox.listFiles(resolved, { includeHidden: true }),
+            'listFiles'
+          )
         );
         return createStats({ size: entries.length, type: 'directory' });
       }
-      const info = await findChildInfo(sandbox, resolved);
+      const info = await findChildInfo(sandbox, resolved, fsTimeoutMs);
       if (info != null) {
         return createStats({ size: info.size, type: info.type });
       }
       try {
         const entries = normalizeFileList(
-          await sandbox.listFiles(resolved, { includeHidden: true })
+          await bound(
+            sandbox.listFiles(resolved, { includeHidden: true }),
+            'listFiles'
+          )
         );
         return createStats({ size: entries.length, type: 'directory' });
-      } catch {
-        const buffer = await normalizeReadFileContent(
-          await sandbox.readFile(resolved)
+      } catch (error) {
+        // A directory-probe timeout is a stalled container, not "not a directory".
+        // Don't fall through to the readFile branch — that would wait through a
+        // SECOND full backstop (~2x the timeout) before surfacing.
+        if (isWorkspaceClientTimeoutError(error)) {
+          throw error;
+        }
+        const buffer = await bound(
+          (async (): Promise<Buffer> =>
+            normalizeReadFileContent(await sandbox.readFile(resolved)))(),
+          'readFile'
         );
         return createStats({ size: buffer.length, type: 'file' });
       }
@@ -478,7 +532,10 @@ export function createCloudflareWorkspaceFS(
       const sandbox = await resolveCloudflareSandbox(config);
       const resolved = toSandboxPath(filePath, workspaceRoot);
       const entries = normalizeFileList(
-        await sandbox.listFiles(resolved, { includeHidden: true })
+        await bound(
+          sandbox.listFiles(resolved, { includeHidden: true }),
+          'listFiles'
+        )
       );
       if (options?.withFileTypes === true) {
         return entries.map(createDirent);
@@ -487,21 +544,29 @@ export function createCloudflareWorkspaceFS(
     }) as WorkspaceFS['readdir'],
     mkdir: async (filePath: string, options?: MakeDirectoryOptions) => {
       const sandbox = await resolveCloudflareSandbox(config);
-      await sandbox.mkdir(toSandboxPath(filePath, workspaceRoot), {
-        recursive: options?.recursive,
-      });
+      await bound(
+        sandbox.mkdir(toSandboxPath(filePath, workspaceRoot), {
+          recursive: options?.recursive,
+        }),
+        'mkdir'
+      );
     },
     realpath: async (filePath: string) =>
       toSandboxPath(filePath, workspaceRoot),
     unlink: async (filePath: string) => {
       const sandbox = await resolveCloudflareSandbox(config);
-      await sandbox.deleteFile(toSandboxPath(filePath, workspaceRoot));
+      await bound(
+        sandbox.deleteFile(toSandboxPath(filePath, workspaceRoot)),
+        'deleteFile'
+      );
     },
     open: async (filePath: string, _flags: 'r') => {
       const sandbox = await resolveCloudflareSandbox(config);
       const resolved = toSandboxPath(filePath, workspaceRoot);
-      const buffer = await normalizeReadFileContent(
-        await sandbox.readFile(resolved)
+      const buffer = await bound(
+        (async (): Promise<Buffer> =>
+          normalizeReadFileContent(await sandbox.readFile(resolved)))(),
+        'readFile'
       );
       return {
         read: async (
@@ -832,18 +897,29 @@ export async function executeCloudflareCode(
     input.args,
     ctx.shell
   );
-  await ctx.sandbox.mkdir(tempDir, { recursive: true });
-  if (runtime.source != null) {
-    await ctx.sandbox.writeFile(
-      path.join(tempDir, runtime.fileName),
-      runtime.source,
-      {
-        encoding: 'utf8',
-      }
-    );
-  }
   let execSucceeded = false;
   try {
+    // Bound the temp-dir setup RPCs (they run BEFORE the bounded exec): a
+    // native-DO stall here would hang the host on a single mkdir/writeFile and
+    // burn the run budget. Keep them INSIDE the try so the finally cleanup still
+    // removes .lc-exec/<uuid> if setup throws — the uncancellable write can land
+    // late on a cold container, so an orphaned dir would otherwise accumulate.
+    await withClientTimeout(
+      ctx.sandbox.mkdir(tempDir, { recursive: true }),
+      clientFsTimeoutMs(ctx.timeoutMs),
+      'cloudflare sandbox mkdir'
+    );
+    if (runtime.source != null) {
+      await withClientTimeout(
+        ctx.sandbox.writeFile(
+          path.join(tempDir, runtime.fileName),
+          runtime.source,
+          { encoding: 'utf8' }
+        ),
+        clientFsTimeoutMs(ctx.timeoutMs),
+        'cloudflare sandbox writeFile'
+      );
+    }
     const result = await execWithClientTimeout(
       ctx.sandbox,
       withInSandboxTimeout(runtime.command, ctx.timeoutMs),

package/src/tools/local/CompileCheckTool.ts

@@ -27,6 +27,7 @@ import { resolve } from 'path';
 import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type { WorkspaceFS } from './workspaceFS';
+import { isWorkspaceClientTimeoutError } from './workspaceFS';
 import type * as t from '@/types';
 import {
   getLocalCwd,
@@ -74,7 +75,12 @@ async function pathExists(fs: WorkspaceFS, p: string): Promise<boolean> {
   try {
     await fs.stat(p);
     return true;
-  } catch {
+  } catch (error) {
+    // A stalled-RPC timeout is not "absent" — don't let it pick a weaker/wrong
+    // toolchain after waiting through the backstop; surface it.
+    if (isWorkspaceClientTimeoutError(error)) {
+      throw error;
+    }
     return false;
   }
 }
@@ -94,7 +100,12 @@ async function detect(cwd: string, fs: WorkspaceFS): Promise<Detection> {
   if (await pathExists(fs, resolve(cwd, 'package.json'))) {
     const pkgRaw = await fs
       .readFile(resolve(cwd, 'package.json'), 'utf8')
-      .catch(() => '');
+      .catch((error) => {
+        if (isWorkspaceClientTimeoutError(error)) {
+          throw error;
+        }
+        return '';
+      });
     if (pkgRaw.includes('"typescript"')) {
       return {
         kind: 'typescript',
@@ -124,7 +135,12 @@ async function detect(cwd: string, fs: WorkspaceFS): Promise<Detection> {
   ) {
     const pyToml = await fs
       .readFile(resolve(cwd, 'pyproject.toml'), 'utf8')
-      .catch(() => '');
+      .catch((error) => {
+        if (isWorkspaceClientTimeoutError(error)) {
+          throw error;
+        }
+        return '';
+      });
     if (pyToml.includes('mypy')) {
       return {
         kind: 'python-mypy',

package/src/tools/local/FileCheckpointer.ts

@@ -1,7 +1,7 @@
 import { dirname } from 'path';
 import type { WorkspaceFS } from './workspaceFS';
 import type * as t from '@/types';
-import { nodeWorkspaceFS } from './workspaceFS';
+import { isWorkspaceClientTimeoutError, nodeWorkspaceFS } from './workspaceFS';
 
 type Snapshot = { kind: 'absent' } | { kind: 'present'; content: Buffer };
 
@@ -41,7 +41,12 @@ export class LocalFileCheckpointerImpl implements t.LocalFileCheckpointer {
     let info;
     try {
       info = await this.fs.stat(absolutePath);
-    } catch {
+    } catch (error) {
+      // A stalled-RPC timeout is NOT "file absent" — snapshotting it as absent
+      // would delete an existing file on revert. Surface it instead.
+      if (isWorkspaceClientTimeoutError(error)) {
+        throw error;
+      }
       this.snapshots.set(absolutePath, { kind: 'absent' });
       return;
     }
@@ -60,7 +65,14 @@ export class LocalFileCheckpointerImpl implements t.LocalFileCheckpointer {
     let restored = 0;
     for (const [path, snapshot] of this.snapshots.entries()) {
       if (snapshot.kind === 'absent') {
-        await this.fs.unlink(path).catch(() => undefined);
+        await this.fs.unlink(path).catch((error) => {
+          // A timed-out delete did NOT happen — surface it rather than counting
+          // the path as restored (which would falsely claim the workspace is
+          // back to its pre-write state).
+          if (isWorkspaceClientTimeoutError(error)) {
+            throw error;
+          }
+        });
         restored++;
         continue;
       }
@@ -68,7 +80,11 @@ export class LocalFileCheckpointerImpl implements t.LocalFileCheckpointer {
         await this.fs.mkdir(dirname(path), { recursive: true });
         await this.fs.writeFile(path, snapshot.content);
         restored++;
-      } catch {
+      } catch (error) {
+        // A timed-out restore left the bad write in place — surface it.
+        if (isWorkspaceClientTimeoutError(error)) {
+          throw error;
+        }
         // Best-effort: ignore individual restore failures so the rest
         // of the rewind continues.
       }