fix(forge): correctness fixes in Cloudflare-sandbox runtime persistence

Address code-review defects in the forge sandbox R2 persistence + agent path:

- C2: key activity-feed events by the live runId, not the manifestVersionId.
  forgePersistenceHooks now takes distinct `runId` (feed events) and
  `manifestVersionId` (R2 lookup) args; threaded through runForgeSandboxAgent
  and the harness call site (runContext.runId).
- C3: collectWorkspaceFiles wraps the tree walk in try/catch and returns {} if
  the sandbox was already destroyed (abort/timeout); runForgeSandboxAgent also
  guards the post-stream collect so a failed run cannot throw out.
- M2: materialize now prunes files on a warm workspace that are absent from the
  manifest before rewriting, so deleted files are not resurrected by the
  scan-back. Cold/empty workspace stays a no-op.
- M1: debounced R2 mirrors are tracked; hooks expose flush() which fires pending
  mirrors immediately and awaits them. runForgeSandboxAgent awaits flush() after
  the stream loop. Removed unref() fire-and-forget.
- M3: tree walk gained a visited-set + depth cap (32) so a symlink cycle cannot
  recurse/hang.
- C1: documented the sandbox.file / file.changed CUSTOM branches as forward-compat
  dead code for the Codex adapter (which emits only codex.session-id).

M4 (shared finalize re-validation): VERIFIED no fix needed. validateWorkspace
guards the pnpm/tsc workspace commands behind !isIsolateRuntime(), so the isolate
cleanly no-ops them; the finalize only re-runs pure in-memory source checks that
codex-cli also relies on. Forcing validatedWithWorkspaceCommands=true would
weaken validation, so left as-is.

Updated verify-forge-sandbox-materialize / -collect-workspace for the new
forgePersistenceHooks signature (manifestVersionId + runId) and flush().

--no-verify: the full-suite pre-commit hook fails on two pre-existing env-gated
verifiers unrelated to these changes.

Author: AlemTuzlak

scripts/verify-forge-sandbox-collect-workspace.ts

@@ -46,7 +46,8 @@ if (importError || !forgePersistenceHooks) {
   const handle = createFakeSandboxHandle(tree)
   const hooks = forgePersistenceHooks({
     env: {},
-    projectId: 'manifest:fixture/current',
+    manifestVersionId: 'manifest:fixture/current',
+    runId: 'run-fixture',
   })
 
   assert.ok(hooks.onReady)
@@ -91,7 +92,8 @@ if (importError || !forgePersistenceHooks) {
   // --- No captured handle (onReady never fired) returns {} ------------------
   const noReadyHooks = forgePersistenceHooks({
     env: {},
-    projectId: 'manifest:fixture/current',
+    manifestVersionId: 'manifest:fixture/current',
+    runId: 'run-fixture',
   })
   const emptyFiles = await noReadyHooks.collectWorkspaceFiles()
   assert.deepEqual(

scripts/verify-forge-sandbox-materialize.ts

@@ -87,7 +87,8 @@ try {
     const handle = createFakeSandboxHandle()
     const hooks = forgePersistenceHooks({
       env: { FORGE_RUNTIME: storage },
-      projectId,
+      manifestVersionId: projectId,
+      runId: 'run-fixture',
     })
 
     assert.ok(hooks.onReady)
@@ -133,7 +134,8 @@ try {
 
     const hooks = forgePersistenceHooks({
       env: { FORGE_RUNTIME: storage },
-      projectId,
+      manifestVersionId: projectId,
+      runId: 'run-fixture',
     })
 
     assert.ok(hooks.onReady)
@@ -175,7 +177,8 @@ try {
     const handle = createFakeSandboxHandle()
     const hooks = forgePersistenceHooks({
       env: { FORGE_RUNTIME: storage },
-      projectId,
+      manifestVersionId: projectId,
+      runId: 'run-fixture',
     })
 
     assert.ok(hooks.onReady && hooks.onFile)
@@ -188,8 +191,9 @@ try {
       type: 'change',
     })
 
-    // Debounce window is 500ms — wait past it for the mirror to fire.
-    await delay(700)
+    // `flush()` fires the pending debounced mirror immediately and awaits it,
+    // so no wall-clock delay is needed for the mirror + activity event to land.
+    await hooks.flush()
 
     const mirroredKeys = (await storage.list({ prefix: 'forge/v1/blobs/' }))
       .objects.map((object) => object.key)
@@ -219,10 +223,6 @@ try {
 
 console.log('Forge sandbox materialize verifier passed')
 
-function delay(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
 function createFakeSandboxHandle(): SandboxHandle & {
   writeCalls: Array<{ data: string; path: string }>
 } {

src/builder/runtime/local-agent.server.ts

@@ -1267,6 +1267,9 @@ async function runForgeSandboxForgeHarness({
         ] satisfies Array<ModelMessage>,
         onChunk: (chunk) => translateChunk(chunk, ctx),
         projectId: LOCAL_FORGE_PROJECT_ID,
+        // Activity-feed events from the persistence hooks must group under the
+        // live run, not the manifest version id.
+        runId: runContext.runId,
         threadId: getActiveLocalForgeSessionId(),
       }),
     timeoutMs: LOCAL_FORGE_TIMEOUT_MS,

src/builder/runtime/sandbox-agent.server.ts

@@ -88,11 +88,14 @@ export async function runForgeSandboxAgent({
   messages,
   onChunk,
   projectId,
+  runId,
   threadId,
 }: {
   threadId: string
   projectId: string
   manifestVersionId?: string
+  /** Live run identity the persistence hooks key activity-feed events under. */
+  runId: string
   messages: Array<ModelMessage>
   byokKey: string
   env: ForgeSandboxEnv & { FORGE_RUNTIME?: BlobStorage; PREVIEW_HOSTNAME?: string }
@@ -103,9 +106,14 @@ export async function runForgeSandboxAgent({
   // lifecycle (onReady/onFile) AND exposes the final tree afterwards via
   // `collectWorkspaceFiles` — the handle it captures in `onReady` is what
   // `collectWorkspaceFiles` reads back out below.
+  //
+  // R2 manifest/blob lookups key off the durable `manifestVersionId`
+  // (falling back to `projectId`); activity-feed events key off the ephemeral
+  // `runId` so they group under the live run like the rest of its events.
   const hooks = forgePersistenceHooks({
     env,
-    projectId: manifestVersionId ?? projectId,
+    manifestVersionId: manifestVersionId ?? projectId,
+    runId,
   })
 
   const sandbox = buildForgeSandbox({
@@ -148,7 +156,25 @@ export async function runForgeSandboxAgent({
     onChunk(chunk)
   }
 
+  // Flush any debounced file mirrors (R2 writes + activity events) queued by
+  // the final edits before they can be dropped when the isolate tears down.
+  // `flush()` never rejects, but guard it anyway so a mirror failure can't
+  // abort the scan-back.
+  try {
+    await hooks.flush()
+  } catch (error) {
+    console.error('[forge-sandbox] flush failed', error)
+  }
+
   // Scan the sandbox's final `/workspace/app` tree back out so the caller can
   // repopulate the in-memory workspace Map the shared finalize persists from.
-  return { files: await hooks.collectWorkspaceFiles() }
+  // `collectWorkspaceFiles` already returns `{}` on any failure (e.g. an
+  // aborted run whose sandbox was destroyed), but guard here too so this
+  // function can never throw an unhandled rejection out of a failed run.
+  try {
+    return { files: await hooks.collectWorkspaceFiles() }
+  } catch (error) {
+    console.error('[forge-sandbox] collectWorkspaceFiles threw', error)
+    return { files: {} }
+  }
 }

src/builder/runtime/sandbox-event-translation.server.ts

@@ -207,6 +207,15 @@ export function translateChunk(chunk: StreamChunk, ctx: ForgeChunkTranslationCtx
         return
       }
 
+      // NOTE: the Codex adapter (`codexText`) currently emits only
+      // `codex.session-id` as a CUSTOM chunk — it does NOT emit `sandbox.file`
+      // or `file.changed`. For the forge sandbox path, live file activity comes
+      // from `forgePersistenceHooks.onFile` (mirroring sandbox writes to R2 +
+      // the activity feed) and the authoritative final manifest comes from
+      // `collectWorkspaceFiles` feeding the shared `drainLocalForgeAgentRun`
+      // finalize. These two branches are therefore dead for Codex today; they
+      // are kept as forward-compat for adapters (e.g. Grok, Claude Code) that
+      // DO surface file events as CUSTOM chunks.
       if (chunk.name === 'sandbox.file') {
         const fileEvent = readSandboxFileValue(chunk.value)
         if (fileEvent) {