@tanstack/ai-sandbox 0.2.1 → 0.2.3

package/src/middleware.ts

@@ -24,15 +24,18 @@ import {
   provideSandboxPolicy,
 } from './capabilities'
 import { computeWorkspaceHash } from './key'
+import { buildFileHookEvent, resolveFileEvents } from './file-diff'
 import { ProjectionCapability, provideWorkspaceProjection } from './projection'
 import { resolveSecret } from './secrets'
 import { watchWorkspace } from './watch'
 import { DEFAULT_WORKSPACE_ROOT } from './bootstrap'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 import type {
   AbortInfo,
   ChatMiddlewareContext,
   DefinedChatMiddleware,
   SandboxFileEvent,
+  SandboxFileHookEvent,
 } from '@tanstack/ai'
 import type { SandboxHandle } from './contracts'
 import type {
@@ -47,10 +50,38 @@ interface SandboxRunState {
   handle: SandboxHandle
   ensureCtx: SandboxEnsureContext
   watcher?: SandboxWatchHandle
+  /** In-flight `enriched.diff()` promises queued by the `fileEvents.diff`
+   * watcher callback, awaited before teardown so a pending diff isn't
+   * dropped when the run finishes/aborts/errors mid-computation. */
+  pendingDiffs: Array<Promise<void>>
+  /** Logger captured at setup, so terminal hooks can log watcher teardown. */
+  logger?: InternalLogger
 }
 
 const runState = new WeakMap<object, SandboxRunState>()
 
+/**
+ * Stop the watcher and drain any in-flight `diff()` promises before teardown,
+ * so the final file's diff isn't dropped when a run finishes/aborts/errors
+ * mid-computation. The `pendingDiffs` await is the load-bearing line — without
+ * it a deferred diff resolves after the run is gone and its chunk is lost.
+ */
+async function drainWatcher(
+  state: SandboxRunState,
+  phase: 'finish' | 'abort' | 'error',
+): Promise<void> {
+  // Guard `stop()`: a rejecting watcher teardown must NOT propagate out of
+  // here, or the caller skips the `definition.destroy(...)` that follows —
+  // leaking the sandbox on exactly the abort path that must ALWAYS tear down.
+  try {
+    await state.watcher?.stop()
+  } catch (error) {
+    state.logger?.warn('sandbox watcher stop failed', { phase, error })
+  }
+  await Promise.allSettled(state.pendingDiffs)
+  if (state.watcher) state.logger?.sandbox('sandbox watcher stopped', { phase })
+}
+
 /** Defensively pull tenant scoping out of the runtime context, if present. */
 function tenantFrom(
   context: unknown,
@@ -77,11 +108,14 @@ function buildEnsureCtx(ctx: ChatMiddlewareContext): SandboxEnsureContext {
 /**
  * Dispatch a sandbox file event to the per-type hooks declared on the
  * definition. Errors in individual hooks are swallowed so one bad hook
- * cannot break the run.
+ * cannot break the run — but are logged under the `errors` category first, so
+ * a throwing hook is observable (matching the run-scoped path in the engine
+ * and the behavior the observability docs promise).
  */
 async function dispatchDefinitionHooks(
   hooks: SandboxHooks | undefined,
-  event: SandboxFileEvent,
+  event: SandboxFileHookEvent,
+  logger?: InternalLogger,
 ): Promise<void> {
   if (!hooks) return
   const typed = (
@@ -95,8 +129,14 @@ async function dispatchDefinitionHooks(
     if (!fn) continue
     try {
       await fn(event)
-    } catch {
-      // swallowed — one bad hook must not break the run
+    } catch (error) {
+      // swallowed — one bad hook must not break the run — but logged so the
+      // failure isn't invisible.
+      logger?.errors('sandbox file hook failed', {
+        path: event.path,
+        type: event.type,
+        error,
+      })
     }
   }
 }
@@ -122,6 +162,45 @@ export function withSandbox(
       provideSandbox(ctx, handle)
       if (definition.policy) provideSandboxPolicy(ctx, definition.policy)
 
+      // Pull the runtime (and its logger) up front so `baseSha` capture and
+      // hook dispatch below can log through the same `sandbox`/`errors`
+      // categories the engine uses.
+      const runtime = getSandboxRuntime(ctx, { optional: true })
+      const logger = runtime?.logger
+
+      const watchRoot = definition.workspace?.root ?? DEFAULT_WORKSPACE_ROOT
+      let baseSha = ''
+      try {
+        const shaRes = await handle.process.exec('git rev-parse HEAD', {
+          cwd: watchRoot,
+        })
+        if (shaRes.exitCode === 0) {
+          baseSha = shaRes.stdout.trim()
+          logger?.sandbox('sandbox git baseline captured', {
+            root: watchRoot,
+            baseSha,
+          })
+        } else {
+          // Non-zero exit: either not a git repository (non-git workspace) or a
+          // repo with no commits (no HEAD). Expected, but it silently degrades
+          // every subsequent diff to a full-file add-patch, so surface it
+          // under `sandbox` (with stderr) rather than leaving nothing to grep.
+          logger?.sandbox('sandbox git baseline unavailable (non-zero exit)', {
+            root: watchRoot,
+            exitCode: shaRes.exitCode,
+            stderr: shaRes.stderr,
+          })
+        }
+      } catch (error) {
+        // exec rejected (git not on PATH, exec seam broken) → baseSha stays ''
+        // and accessors fall back, but this is a real anomaly, not a plain
+        // non-git workspace, so warn.
+        logger?.warn('sandbox git baseline capture failed', {
+          root: watchRoot,
+          error,
+        })
+      }
+
       const workspace = definition.workspace
       if (workspace !== undefined) {
         const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT
@@ -149,19 +228,59 @@ export function withSandbox(
       const hooks = definition.hooks
       await hooks?.onReady?.(handle)
 
+      const fe = resolveFileEvents(definition.fileEvents)
+      const pendingDiffs: Array<Promise<void>> = []
       let watcher: SandboxWatchHandle | undefined
-      if (definition.fileEvents !== false) {
-        const runtime = getSandboxRuntime(ctx, { optional: true })
+      if (fe.enabled) {
         watcher = await watchWorkspace(handle, {
           onEvent: (event: SandboxFileEvent) => {
-            void dispatchDefinitionHooks(hooks, event)
-            runtime?.emit(event)
+            const enriched = buildFileHookEvent(
+              handle,
+              watchRoot,
+              baseSha,
+              event,
+              logger,
+            )
+            void dispatchDefinitionHooks(hooks, enriched, logger)
+            runtime?.emit(enriched)
+            if (fe.diff) {
+              pendingDiffs.push(
+                enriched
+                  .diff()
+                  .then((diff) => {
+                    runtime?.emitFileDiff({ path: event.path, diff })
+                  })
+                  .catch((error: unknown) => {
+                    logger?.warn('sandbox file diff emit failed', {
+                      path: event.path,
+                      error,
+                    })
+                  }),
+              )
+            }
           },
+          // Watch the SAME root the enrichment layer relativizes against
+          // (`buildFileHookEvent(handle, watchRoot, …)` and the `baseSha`
+          // capture). Without this the watcher defaults to `/workspace` while
+          // enrichment uses `watchRoot`, so a custom `workspace.root` makes the
+          // two look at different directories and git pathspecs break.
+          root: watchRoot,
           ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+          ...(logger !== undefined ? { logger } : {}),
+        })
+        logger?.sandbox('sandbox watcher started', {
+          root: watchRoot,
+          diff: fe.diff,
         })
       }
 
-      runState.set(ctx, { handle, ensureCtx, ...(watcher ? { watcher } : {}) })
+      runState.set(ctx, {
+        handle,
+        ensureCtx,
+        pendingDiffs,
+        ...(watcher ? { watcher } : {}),
+        ...(logger !== undefined ? { logger } : {}),
+      })
     },
 
     async onFinish(ctx) {
@@ -169,7 +288,7 @@ export function withSandbox(
       if (!state) return
       const { handle, ensureCtx } = state
 
-      await state.watcher?.stop()
+      await drainWatcher(state, 'finish')
 
       const lifecycle = definition.lifecycle
 
@@ -203,7 +322,7 @@ export function withSandbox(
       const state = runState.get(ctx)
       if (!state) return
 
-      await state.watcher?.stop()
+      await drainWatcher(state, 'abort')
 
       // ALWAYS tear down on an explicit abort, regardless of `destroyOnComplete`.
       // The in-sandbox agent process is not killed by closing its IO stream
@@ -219,7 +338,7 @@ export function withSandbox(
       const state = runState.get(ctx)
       if (!state) return
 
-      await state.watcher?.stop()
+      await drainWatcher(state, 'error')
       await definition.hooks?.onError?.(info.error)
 
       // On failure, only tear down when the lifecycle says so; otherwise leave

package/src/sandbox.ts

@@ -10,7 +10,7 @@ import { bootstrapWorkspace } from './bootstrap'
 import { resolveAllSecrets } from './secrets'
 import { computeSandboxKey } from './key'
 import { InMemoryLockStore, InMemorySandboxStore } from './store'
-import type { SandboxFileEvent } from '@tanstack/ai'
+import type { SandboxFileHookEvent } from '@tanstack/ai'
 import type { SandboxHandle, SandboxProvider } from './contracts'
 import type { SandboxKeyInput } from './key'
 import type { LockStore, SandboxStore } from './store'
@@ -22,10 +22,10 @@ import type { WorkspaceDefinition } from './workspace'
  * create/change/delete during a chat run; lifecycle hooks fire server-side.
  */
 export interface SandboxHooks {
-  onFile?: (e: SandboxFileEvent) => void | Promise<void>
-  onFileCreate?: (e: SandboxFileEvent) => void | Promise<void>
-  onFileChange?: (e: SandboxFileEvent) => void | Promise<void>
-  onFileDelete?: (e: SandboxFileEvent) => void | Promise<void>
+  onFile?: (e: SandboxFileHookEvent) => void | Promise<void>
+  onFileCreate?: (e: SandboxFileHookEvent) => void | Promise<void>
+  onFileChange?: (e: SandboxFileHookEvent) => void | Promise<void>
+  onFileDelete?: (e: SandboxFileHookEvent) => void | Promise<void>
   onReady?: (handle: SandboxHandle) => void | Promise<void>
   onError?: (err: unknown) => void | Promise<void>
   onDestroy?: () => void | Promise<void>
@@ -59,8 +59,9 @@ export interface SandboxConfig {
   lifecycle?: SandboxLifecycle
   /** Sandbox-scoped file/lifecycle hooks. */
   hooks?: SandboxHooks
-  /** Watch the workspace for file events (default true). Set false to disable. */
-  fileEvents?: boolean
+  /** Watch the workspace for file events (default true). `false` disables the
+   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */
+  fileEvents?: boolean | { diff?: boolean }
 }
 
 /** Context passed to `ensure()` by `withSandbox` (or advanced callers). */
@@ -83,8 +84,9 @@ export interface SandboxDefinition {
   readonly lifecycle?: SandboxLifecycle
   /** Sandbox-scoped file/lifecycle hooks. */
   readonly hooks?: SandboxHooks
-  /** Watch the workspace for file events (default true). Set false to disable. */
-  readonly fileEvents?: boolean
+  /** Watch the workspace for file events (default true). `false` disables the
+   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */
+  readonly fileEvents?: boolean | { diff?: boolean }
   /** Compound instance key for a given run context. */
   key: (ctx: SandboxEnsureContext) => string
   /** Resume-or-create the sandbox for this thread/run. */

package/src/watch.ts

@@ -19,6 +19,7 @@
 import { DEFAULT_WORKSPACE_ROOT } from './bootstrap'
 import type { SandboxHandle } from './contracts'
 import type { SandboxFileEvent } from '@tanstack/ai'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 
 export type { SandboxFileEvent } from '@tanstack/ai'
 /** @deprecated alias retained for the low-level watch API. */
@@ -39,6 +40,12 @@ export interface WatchOptions {
   ignore?: Array<string>
   /** Stop watching when this signal aborts. */
   signal?: AbortSignal
+  /**
+   * Optional logger. When present, a failed `find` poll (non-zero exit or a
+   * thrown exec) is logged instead of silently degrading the snapshot — the
+   * failure mode a plain exec-poll watcher hides.
+   */
+  logger?: InternalLogger
 }
 
 export interface SandboxWatchHandle {
@@ -75,16 +82,28 @@ export function diffSnapshots(
   return events
 }
 
-/** Build the `find` command that prints `mtime\tsize\tpath` for every file. */
-function buildFindCommand(root: string, ignore: Array<string>): string {
+/**
+ * Build the `find` command that prints `mtime\tsize\tpath` for every file.
+ * Searches `.` (relative to the exec `cwd`) rather than an absolute root: a
+ * provider's `exec` maps only `cwd` onto the real filesystem, not literal path
+ * arguments, so `find <virtual-root>` would look at a non-existent host path on
+ * mapped-root providers (e.g. local-process). Emitted `%p` values are
+ * root-normalized in {@link parseFindOutput}.
+ */
+function buildFindCommand(ignore: Array<string>): string {
   const prunes = ignore
     .map((entry) => `-not -path ${q(`*/${entry}/*`)}`)
     .join(' ')
-  return `find ${q(root)} -type f ${prunes} -printf '%T@\\t%s\\t%p\\n'`
+  return `find . -type f ${prunes} -printf '%T@\\t%s\\t%p\\n'`
 }
 
-/** Parse `find -printf` output into a `Map<path, signature>`. */
-function parseFindOutput(stdout: string): Map<string, string> {
+/**
+ * Parse `find -printf` output into a `Map<path, signature>`. `find .` prints
+ * paths like `./sub/file`; map them back under `root` so event paths match the
+ * native-watch shape (`<root>/sub/file`).
+ */
+function parseFindOutput(stdout: string, root: string): Map<string, string> {
+  const base = root.replace(/\/+$/, '')
   const snapshot = new Map<string, string>()
   for (const line of stdout.split('\n')) {
     if (line === '') continue
@@ -93,7 +112,8 @@ function parseFindOutput(stdout: string): Map<string, string> {
     if (firstTab === -1 || secondTab === -1) continue
     const mtime = line.slice(0, firstTab)
     const size = line.slice(firstTab + 1, secondTab)
-    const path = line.slice(secondTab + 1)
+    const rel = line.slice(secondTab + 1).replace(/^\.\/?/, '')
+    const path = rel === '' ? base : `${base}/${rel}`
     snapshot.set(path, `${mtime}\t${size}`)
   }
   return snapshot
@@ -131,17 +151,49 @@ async function startNativeWatch(
   handle: SandboxHandle,
   options: WatchOptions & { root: string; ignore: Array<string> },
 ): Promise<SandboxWatchHandle> {
-  const { onEvent, root, ignore } = options
+  const { onEvent, root, ignore, logger } = options
   const watch = handle.fs.watch
   if (!watch) throw new Error('native watch is unavailable on this provider')
   // Seed the set of existing files so the first event per path is classified
   // correctly (create vs change).
-  const known = await collectPaths(handle, root, ignore)
+  const seed = await collectPaths(handle, root, ignore, logger)
+  const known = seed.files
+  // If the ROOT list failed, `known` is untrustworthy — every pre-existing
+  // file would misclassify as `create` on its first edit. Re-seed lazily on
+  // the next event(s): by the time real activity arrives the fs has usually
+  // recovered, and re-listing then establishes the baseline. Dedupe concurrent
+  // re-seeds behind a single in-flight promise.
+  // ponytail: a file genuinely CREATED in the narrow window between the failed
+  // seed and the first event gets picked up by the re-seed and so mislabels as
+  // `change` once. That's strictly better than the whole-run mislabel a
+  // never-recovered empty seed causes, and `diff()` is correct regardless.
+  let seeded = seed.rootOk
+  let reseeding: Promise<void> | null = null
+  const ensureSeeded = (): Promise<void> => {
+    if (seeded) return Promise.resolve()
+    if (!reseeding) {
+      reseeding = collectPaths(handle, root, ignore, logger).then((r) => {
+        if (r.rootOk) {
+          for (const p of r.files) known.add(p)
+          seeded = true
+          logger?.sandbox(
+            'sandbox watch: re-seeded after failed initial seed',
+            {
+              root,
+            },
+          )
+        }
+        reseeding = null
+      })
+    }
+    return reseeding
+  }
 
   const subscription = await watch(root, (raw) => {
     const path = raw.path
     if (isIgnored(path, ignore)) return
     void (async () => {
+      await ensureSeeded()
       const exists = await handle.fs.exists(path)
       const timestamp = Date.now()
       if (!exists) {
@@ -153,14 +205,28 @@ async function startNativeWatch(
         known.add(path)
         onEvent({ type: 'create', path, timestamp })
       }
-    })().catch(() => undefined)
+    })().catch((error: unknown) => {
+      // A failed classify (e.g. `fs.exists` threw) drops this file's event —
+      // log it so a missing diff isn't silent (the whole point of the watcher).
+      logger?.warn('sandbox watch: native event classify failed', {
+        path,
+        error,
+      })
+    })
   })
 
-  const onAbort = (): void => void subscription.stop().catch(() => undefined)
+  // A failed `subscription.stop()` can leak an OS-level watch — log rather
+  // than swallow it silently.
+  const logStopFailure = (error: unknown): void =>
+    logger?.warn('sandbox watch: native subscription.stop() failed', {
+      root,
+      error,
+    })
+  const onAbort = (): void => void subscription.stop().catch(logStopFailure)
   options.signal?.addEventListener('abort', onAbort, { once: true })
   // The signal may have aborted during the awaits above (the once-listener
   // would have missed it) — tear down now if so.
-  if (options.signal?.aborted) void subscription.stop().catch(() => undefined)
+  if (options.signal?.aborted) void subscription.stop().catch(logStopFailure)
 
   return {
     stop: async () => {
@@ -179,33 +245,154 @@ async function startPollWatch(
     intervalMs: number
   },
 ): Promise<SandboxWatchHandle> {
-  const { onEvent, root, ignore, intervalMs } = options
-  const command = buildFindCommand(root, ignore)
+  const { onEvent, root, ignore, intervalMs, logger } = options
+  const command = buildFindCommand(ignore)
   const controller = new AbortController()
 
-  const snapshot = async (): Promise<Map<string, string>> => {
-    const result = await handle.process.exec(command, {
-      cwd: root,
-      signal: controller.signal,
+  // A poll result: the parsed snapshot plus whether `find` completed cleanly.
+  // `null` means the poll produced no usable output at all (thrown exec, or a
+  // non-zero exit with empty stdout) — callers preserve the previous snapshot.
+  // Collapsing a failed poll to `{}` would make the next diff fabricate a
+  // `delete` for every tracked file (and a `create` for each on recovery) —
+  // one transient `find` blip would fan a phantom storm out to hooks/stream.
+  interface Poll {
+    map: Map<string, string>
+    /** `false` when `find` exited non-zero but still printed rows (partial). */
+    complete: boolean
+  }
+  // Escalate a steady-state poll throw to `warn` after this many in a row.
+  const STEADY_STATE_THROW_WARN_AFTER = 3
+  let consecutiveThrows = 0
+  const snapshot = async (isInitial = false): Promise<Poll | null> => {
+    let result
+    try {
+      result = await handle.process.exec(command, {
+        cwd: root,
+        signal: controller.signal,
+      })
+      consecutiveThrows = 0 // exec returned (any exit code) — the seam is alive
+    } catch (error) {
+      // Thrown exec — container not ready, `find` seam rejects, or a
+      // mid-teardown abort. Treat as a failed poll so BOTH the initial seed
+      // and every tick preserve `previous` instead of rejecting setup (which
+      // would crash the run and leak the sandbox) or the interval.
+      if (isInitial) {
+        // The INITIAL poll can't be a teardown (a pre-aborted signal is guarded
+        // in `watchWorkspace`), so a throw here is an unambiguous anomaly (`find`
+        // missing, container never ready) that leaves the watcher dead for the
+        // whole run — surface it at `warn`.
+        logger?.warn('sandbox watch: initial `find` poll threw', {
+          root,
+          error,
+        })
+      } else if (controller.signal.aborted) {
+        // Mid-teardown abort — expected, stay quiet.
+        logger?.sandbox('sandbox watch: `find` poll threw during teardown', {
+          root,
+          error,
+        })
+      } else {
+        // Steady-state throw while NOT tearing down. One is usually a transient
+        // blip (→ `sandbox`), but a run of them means the exec seam is wedged:
+        // every poll returns null and the watcher emits nothing for the rest of
+        // the run. That silent-death case escalates to `warn` (on by default).
+        consecutiveThrows += 1
+        if (consecutiveThrows >= STEADY_STATE_THROW_WARN_AFTER) {
+          logger?.warn('sandbox watch: `find` poll threw repeatedly', {
+            root,
+            error,
+            consecutiveThrows,
+          })
+        } else {
+          logger?.sandbox('sandbox watch: `find` poll threw', { root, error })
+        }
+      }
+      return null
+    }
+    if (result.exitCode === 0) {
+      return { map: parseFindOutput(result.stdout, root), complete: true }
+    }
+    // Non-zero exit doesn't mean "no data": GNU `find` exits >0 on the first
+    // permission-denied entry it hits mid-traversal (common in containers, and
+    // the ignore list is a `-not -path` filter, not `-prune`, so `find` still
+    // descends into unreadable dirs) yet still prints every readable file. Use
+    // that partial output — marked `complete: false` so the tick merges rather
+    // than diffs it — instead of blinding the watcher for the whole run. Only a
+    // non-zero exit with NO output is a truly failed poll.
+    if (result.stdout !== '') {
+      logger?.sandbox(
+        'sandbox watch: `find` non-zero exit with partial output',
+        { root, exitCode: result.exitCode, stderr: result.stderr },
+      )
+      return { map: parseFindOutput(result.stdout, root), complete: false }
+    }
+    logger?.warn('sandbox watch: `find` poll exited non-zero with no output', {
+      root,
+      exitCode: result.exitCode,
+      stderr: result.stderr,
     })
-    return result.exitCode === 0
-      ? parseFindOutput(result.stdout)
-      : new Map<string, string>()
+    return null
   }
 
-  let previous = await snapshot()
+  // `null` until the first poll that yields usable output. A failed INITIAL
+  // poll must NOT seed an empty baseline — the first successful poll would then
+  // diff against `{}` and fabricate a `create` for every pre-existing file. So
+  // the first non-null snapshot is adopted as the baseline WITHOUT diffing.
+  let previous: Map<string, string> | null = null
+  // Whether `previous` was established from a COMPLETE poll. A baseline seeded
+  // from a PARTIAL poll is provisional — files unreadable during that poll are
+  // absent from it and would later fabricate `create`s when they recover — so
+  // the first complete poll re-baselines without diffing.
+  let seededFromComplete = false
+  {
+    const poll = await snapshot(true)
+    if (poll) {
+      previous = poll.map
+      seededFromComplete = poll.complete
+    }
+  }
   const state = { running: true }
 
   const tick = async (): Promise<void> => {
     if (!state.running) return
     try {
-      const next = await snapshot()
+      const poll = await snapshot()
+      // Failed poll — keep `previous` and retry next tick (see `snapshot`).
+      if (poll === null) return
+      if (previous === null) {
+        // First usable snapshot after a failed initial poll — seed, don't diff.
+        previous = poll.map
+        seededFromComplete = poll.complete
+        return
+      }
+      if (!seededFromComplete && poll.complete) {
+        // First complete poll after a provisional (partial) seed — re-baseline
+        // WITHOUT diffing, so files merely unreadable at seed time don't
+        // fabricate `create`s. (Real creates during this degraded-startup
+        // window are missed — an acceptable trade for not fabricating events.)
+        logger?.sandbox(
+          'sandbox watch: re-baselined after provisional partial seed',
+          { root },
+        )
+        previous = poll.map
+        seededFromComplete = true
+        return
+      }
+      // A partial (non-`complete`) poll can't distinguish "deleted" from
+      // "transiently unreadable this poll", so MERGE it over `previous`: pick
+      // up new/changed files without fabricating a `delete` for a path this
+      // poll simply couldn't see. A real deletion still surfaces on the next
+      // complete poll.
+      const next = poll.complete
+        ? poll.map
+        : new Map([...previous, ...poll.map])
       for (const event of diffSnapshots(previous, next, Date.now())) {
         onEvent(event)
       }
       previous = next
-    } catch {
-      // transient exec failure (e.g. mid-teardown) — try again next tick
+    } catch (error) {
+      // Defensive: a throw from diff dispatch — preserve `previous`, retry.
+      logger?.sandbox('sandbox watch: tick failed', { root, error })
     }
   }
 
@@ -231,26 +418,41 @@ async function startPollWatch(
   return { stop }
 }
 
-/** Recursively collect file paths under `root`, honoring `ignore`. */
+/**
+ * Recursively collect file paths under `root`, honoring `ignore`. `rootOk` is
+ * `false` when the ROOT `list` itself failed — the seed is then untrustworthy
+ * (empty/partial), which the native watcher uses to trigger a lazy re-seed. A
+ * failed *subdirectory* list is logged but doesn't flip `rootOk` (its files are
+ * simply absent, a smaller misclassification surface).
+ */
 async function collectPaths(
   handle: SandboxHandle,
   root: string,
   ignore: Array<string>,
-): Promise<Set<string>> {
+  logger?: InternalLogger,
+): Promise<{ files: Set<string>; rootOk: boolean }> {
   const files = new Set<string>()
-  const walk = async (dir: string): Promise<void> => {
+  let rootOk = true
+  const walk = async (dir: string, isRoot: boolean): Promise<void> => {
     let entries: Awaited<ReturnType<SandboxHandle['fs']['list']>>
     try {
       entries = await handle.fs.list(dir)
-    } catch {
+    } catch (error) {
+      // A dir we can't list is seeded as empty, so its existing files would
+      // later misclassify as `create` on first edit — log rather than hide it.
+      if (isRoot) rootOk = false
+      logger?.warn('sandbox watch: failed to list directory while seeding', {
+        dir,
+        error,
+      })
       return
     }
     for (const entry of entries) {
       if (ignore.includes(entry.name)) continue
-      if (entry.type === 'dir') await walk(entry.path)
+      if (entry.type === 'dir') await walk(entry.path, false)
       else files.add(entry.path)
     }
   }
-  await walk(root)
-  return files
+  await walk(root, true)
+  return { files, rootOk }
 }