@librechat/agents 3.2.42 → 3.2.43

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.
       }

package/src/tools/local/LocalCodingTools.ts

@@ -3,6 +3,7 @@ import { createTwoFilesPatch } from 'diff';
 import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
+import { isWorkspaceClientTimeoutError } from './workspaceFS';
 import {
   createLocalBashProgrammaticToolCallingTool,
   createLocalProgrammaticToolCallingTool,
@@ -294,8 +295,14 @@ async function revertStrictWrite(
     } else {
       await fs.unlink(path);
     }
-  } catch {
-    /* best-effort: caller still sees the original syntax error */
+  } catch (error) {
+    // A timed-out revert leaves the rejected write on disk — the caller would
+    // otherwise claim "reverted to pre-write state" while the bad bytes remain.
+    // Surface it; for other failures stay best-effort (caller sees the original
+    // syntax error).
+    if (isWorkspaceClientTimeoutError(error)) {
+      throw error;
+    }
   }
 }
 
@@ -538,7 +545,12 @@ export function createLocalWriteFileTool(
         before = decoded.text;
         encoding = decoded;
         existed = true;
-      } catch {
+      } catch (error) {
+        // A stalled-RPC timeout is NOT "file absent" — treating it as such would
+        // overwrite an existing file with fresh content. Surface it instead.
+        if (isWorkspaceClientTimeoutError(error)) {
+          throw error;
+        }
         existed = false;
       }
 
@@ -546,7 +558,21 @@ export function createLocalWriteFileTool(
       const finalText = encodeFile(input.content, encoding);
       await fs.writeFile(path, finalText, 'utf8');
 
-      const syntax = await maybeRunSyntaxCheck(path, config);
+      let syntax;
+      try {
+        syntax = await maybeRunSyntaxCheck(path, config);
+      } catch (error) {
+        // A validation-read timeout must still honor strict mode's revert
+        // contract: restore the pre-write state before surfacing (best-effort —
+        // the revert may itself time out on the same stalled container).
+        if (
+          isWorkspaceClientTimeoutError(error) &&
+          config.postEditSyntaxCheck === 'strict'
+        ) {
+          await revertStrictWrite(fs, path, existed, before, encoding);
+        }
+        throw error;
+      }
 
       const diff = existed
         ? summariseDiff(path, before, input.content)
@@ -642,7 +668,20 @@ export function createLocalEditFileTool(
       const finalText = encodeFile(next, encoding);
       await fs.writeFile(path, finalText, 'utf8');
 
-      const syntax = await maybeRunSyntaxCheck(path, config);
+      let syntax;
+      try {
+        syntax = await maybeRunSyntaxCheck(path, config);
+      } catch (error) {
+        // As in write_file: a validation-read timeout still triggers strict
+        // mode's revert (edit_file always operates on an existing file).
+        if (
+          isWorkspaceClientTimeoutError(error) &&
+          config.postEditSyntaxCheck === 'strict'
+        ) {
+          await revertStrictWrite(fs, path, true, original, encoding);
+        }
+        throw error;
+      }
 
       const diff = summariseDiff(path, original, next);
       const fuzzy = strategiesUsed.some((s) => s !== 'exact');
@@ -826,7 +865,12 @@ async function* walkFiles(
     let entries;
     try {
       entries = await fs.readdir(dir, { withFileTypes: true });
-    } catch {
+    } catch (error) {
+      // A stalled-RPC timeout must surface, not be silently skipped as an
+      // unreadable directory — that would corrupt search results ("no matches").
+      if (isWorkspaceClientTimeoutError(error)) {
+        throw error;
+      }
       continue;
     }
     for (const entry of entries) {
@@ -1009,7 +1053,12 @@ async function fallbackGrep(
     let stat;
     try {
       stat = await fs.stat(file);
-    } catch {
+    } catch (error) {
+      // A stalled-RPC timeout must surface, not be skipped — skipping a file can
+      // report "no matches" even when the (unreadable-due-to-stall) file matched.
+      if (isWorkspaceClientTimeoutError(error)) {
+        throw error;
+      }
       continue;
     }
     if (stat.size > FALLBACK_GREP_MAX_FILE_BYTES) {
@@ -1021,7 +1070,11 @@ async function fallbackGrep(
     let content;
     try {
       content = await fs.readFile(file, 'utf8');
-    } catch {
+    } catch (error) {
+      // As above: a client-timeout means a stalled read, not an unreadable file.
+      if (isWorkspaceClientTimeoutError(error)) {
+        throw error;
+      }
       continue;
     }
     if (content.includes('\0')) {

package/src/tools/local/__tests__/FileCheckpointer.test.ts

@@ -3,6 +3,10 @@ import { join } from 'path';
 import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'fs/promises';
 import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
 import { LocalFileCheckpointerImpl } from '../FileCheckpointer';
+import {
+  WorkspaceClientTimeoutError,
+  type WorkspaceFS,
+} from '../workspaceFS';
 
 /**
  * Pins the LocalFileCheckpointer's per-Run snapshot/rewind contract.
@@ -63,6 +67,44 @@ describe('LocalFileCheckpointerImpl', () => {
     await expect(stat(file)).rejects.toThrow();
   });
 
+  it('rethrows a client-timeout from stat instead of snapshotting as absent', async () => {
+    // A stalled stat() must NOT be recorded as "absent" — that would delete an
+    // existing file on rewind. The timeout has to surface.
+    const fs = {
+      stat: async () => {
+        throw new WorkspaceClientTimeoutError(
+          'cloudflare sandbox listFiles exceeded 6000ms client-side timeout'
+        );
+      },
+    } as unknown as WorkspaceFS;
+    const cp = new LocalFileCheckpointerImpl(32 * 1024 * 1024, fs);
+
+    await expect(cp.captureBeforeWrite('/workspace/a.txt')).rejects.toThrow(
+      /client-side timeout/
+    );
+    // Nothing was snapshotted, so rewind is a no-op (no spurious deletion).
+    expect(await cp.rewind()).toBe(0);
+  });
+
+  it('rewind rethrows a client-timeout from a restore write instead of claiming success', async () => {
+    // A stalled restore write leaves the bad bytes on disk — rewind must surface
+    // the timeout, not silently count the path as restored.
+    const fs = {
+      stat: async () => ({ isFile: () => true, size: 5 }),
+      readFile: async () => Buffer.from('orig\n'),
+      mkdir: async () => undefined,
+      writeFile: async () => {
+        throw new WorkspaceClientTimeoutError(
+          'cloudflare sandbox writeFile exceeded 6000ms client-side timeout'
+        );
+      },
+    } as unknown as WorkspaceFS;
+    const cp = new LocalFileCheckpointerImpl(32 * 1024 * 1024, fs);
+
+    await cp.captureBeforeWrite('/workspace/a.txt'); // snapshots 'present'
+    await expect(cp.rewind()).rejects.toThrow(/client-side timeout/);
+  });
+
   it('rewinds across multiple files in a single pass', async () => {
     const a = join(dir, 'multi-a.txt');
     const b = join(dir, 'multi-b.txt');

package/src/tools/local/syntaxCheck.ts

@@ -18,6 +18,7 @@
 
 import { extname } from 'path';
 import type * as t from '@/types';
+import { isWorkspaceClientTimeoutError } from './workspaceFS';
 import {
   getSpawn,
   getWorkspaceFS,
@@ -168,7 +169,13 @@ const jsonCheck: SyntaxChecker = async (path, config) => {
   // file → catch returns undefined → ok: true) or read a different
   // file with the same absolute path. Codex P1 #24.
   const fs = getWorkspaceFS(config);
-  const raw = await fs.readFile(path, 'utf8').catch(() => undefined);
+  const raw = await fs.readFile(path, 'utf8').catch((error) => {
+    // A stalled read must not pass the syntax gate as ok:true — surface it.
+    if (isWorkspaceClientTimeoutError(error)) {
+      throw error;
+    }
+    return undefined;
+  });
   if (raw == null) return { ok: true };
   try {
     JSON.parse(raw);
@@ -237,7 +244,12 @@ export async function runPostEditSyntaxCheck(
       };
     }
     return result;
-  } catch {
+  } catch (error) {
+    // Don't swallow a stalled-RPC timeout as "no checker outcome" (which would
+    // let the write through without a real syntax gate) — surface it.
+    if (isWorkspaceClientTimeoutError(error)) {
+      throw error;
+    }
     return null;
   }
 }

package/src/tools/local/workspaceFS.ts

@@ -39,6 +39,33 @@ export type ReaddirEntry = {
   isSymbolicLink(): boolean;
 };
 
+/**
+ * Thrown when a {@link WorkspaceFS} operation is abandoned by a client-side
+ * backstop timeout (a stalled remote/sandbox RPC that never returned). This is
+ * DISTINCT from "file not found": callers that catch generic FS failures as
+ * absence — e.g. a pre-read before an overwrite, or a `stat` before snapshotting
+ * — MUST rethrow this so a stalled read isn't mistaken for a missing file (which
+ * would otherwise overwrite an existing file or snapshot it as absent).
+ */
+export class WorkspaceClientTimeoutError extends Error {
+  readonly code = 'WORKSPACE_CLIENT_TIMEOUT';
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkspaceClientTimeoutError';
+  }
+}
+
+export function isWorkspaceClientTimeoutError(
+  error: unknown
+): error is WorkspaceClientTimeoutError {
+  return (
+    error instanceof WorkspaceClientTimeoutError ||
+    (typeof error === 'object' &&
+      error !== null &&
+      (error as { code?: unknown }).code === 'WORKSPACE_CLIENT_TIMEOUT')
+  );
+}
+
 export interface WorkspaceFS {
   readFile(path: string, encoding: 'utf8'): Promise<string>;
   readFile(path: string): Promise<Buffer>;