@cursor/july 0.1.102 → 0.1.103

package/src/internal/session-engine.ts

@@ -28,6 +28,9 @@ import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channe
 import {
   AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
   agentStoreKeys,
+  DEPLOYMENT_STORE_MOUNT_PATH,
+  type FileSink,
+  USER_STORE_MOUNT_PATH,
 } from "../files.js";
 import {
   cursorHostedFiles,
@@ -70,6 +73,7 @@ import {
   type RunnerTurnRequest,
   type SendMessageFn,
   type SendMessageOptions,
+  type SessionContext,
   type SessionEvent,
   type SessionEventPayload,
   type SessionInfo,
@@ -116,6 +120,7 @@ import {
   resolveV2Key,
   V2EngineError,
 } from "./continuation-identity.js";
+import { describeError } from "./describe-error.js";
 import { isDevMode } from "./dev-mode.js";
 import { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
@@ -152,6 +157,7 @@ import {
   SCHEDULE_CHANNEL_PREFIX,
 } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
+import { applyAuthoredResult } from "./result-output.js";
 import type { AgentRunner, SteerAckOutcome } from "./sdk-runner.js";
 import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
@@ -173,16 +179,30 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
+  buildCloudWorkspaceSection,
   ensureOwnGitRoot,
   isNestedInGitRepo,
   materializeWorkspace,
   SERVER_TOOLS_MCP_SERVER_NAME,
   writeWorkspaceFiles,
 } from "./workspace.js";
+import { syncWorkspaceToStore } from "./workspace-sync.js";
 
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 
+/** Authored surfaces mirrored onto the Agent Store before a first cloud prompt. */
+type CloudSyncSurface = "skills" | "workspace";
+
+/** The Agent Store cloud turns read authored files from, and where the VM mounts it. */
+interface CloudStoreTarget {
+  sink: FileSink;
+  mountPath: string;
+  skillsPrefix: string;
+  workspacePrefix: string;
+  label: string;
+}
+
 export class SessionBusyError extends Error {
   constructor(sessionId: string) {
     super(
@@ -406,8 +426,8 @@ export class SessionEngine {
   >();
   /** Once-per-process cache for the A/B snapshot backfill (see abSnapshot). */
   private restoredAbSnapshot: Promise<ABSnapshot | undefined> | undefined;
-  /** In-flight skills → Agent Store sync (see ensureCloudSkillsSynced). */
-  private cloudSkillsSync: Promise<boolean> | undefined;
+  /** In-flight authored files → Agent Store syncs (see syncToCloudStore). */
+  private readonly cloudSyncs = new Map<CloudSyncSurface, Promise<boolean>>();
 
   private readonly runner: AgentRunner;
   private readonly logger: (line: string) => void;
@@ -678,9 +698,9 @@ export class SessionEngine {
   }
 
   /**
-   * Host services with `files` bound to one session, so a relative path in a
-   * tool or hook resolves to that session's scope and can never be read as
-   * another session's. Unbound (no session) keeps `host.files` usable for
+   * Host services with `files` and `otel` bound to one session, so a relative
+   * path resolves to that session's scope and can never read another
+   * session's. Unbound (no session) keeps `host.files` usable for
    * `{ scope: "deployment" }` and fails loudly on session-scoped calls.
    */
   private hostForSession(sessionId: string | undefined): HostContext {
@@ -2006,7 +2026,9 @@ export class SessionEngine {
         this.activeToolContexts.set(sessionId, { record, turnId, emit });
         this.stubbedCallIds.set(sessionId, stubbed);
         try {
-          outcome = await this.runner.runTurn(request);
+          outcome = await this.runTurnExecute(record, turnId, () =>
+            this.runner.runTurn(request)
+          );
         } finally {
           this.activeToolContexts.delete(sessionId);
           this.stubbedCallIds.delete(sessionId);
@@ -2049,14 +2071,39 @@ export class SessionEngine {
       outcome = { ...outcome, cost: finalCost };
     }
 
+    const authored = this.project.result;
+    if (outcome.status === "finished" && authored !== undefined) {
+      const settled = await applyAuthoredResult({
+        definition: authored,
+        text: finalResult,
+        dryRun: record.dryRun === true,
+        ctx: {
+          session: this.sessionInfo(record),
+          host: this.hostForSession(sessionId),
+          artifacts: this.artifactsApi({ sessionId, turnId }),
+          stateRoot: this.stateRoot,
+          workspaceDir: harnessCwd,
+        },
+      });
+      if (!settled.ok) {
+        outcome = {
+          status: "error",
+          result: finalResult,
+          errorMessage: `turn output failed: ${settled.message}`,
+          usage: finalUsage,
+          cost: finalCost,
+        };
+      }
+    }
+
     if (outcome.status === "finished") {
       await this.appendEvent(sessionId, {
         type: "turn.completed",
         turnId,
         data: {
-          ...(finalResult === undefined ? {} : { result: finalResult }),
-          ...(finalUsage === undefined ? {} : { usage: finalUsage }),
-          ...(finalCost === undefined ? {} : { cost: finalCost }),
+          result: finalResult,
+          usage: finalUsage,
+          cost: finalCost,
         },
       });
     } else {
@@ -2098,8 +2145,8 @@ export class SessionEngine {
 
     return {
       ...outcome,
-      ...(finalResult === undefined ? {} : { result: finalResult }),
-      ...(finalUsage === undefined ? {} : { usage: finalUsage }),
+      result: finalResult,
+      usage: finalUsage,
     };
   }
 
@@ -2110,48 +2157,75 @@ export class SessionEngine {
    * first-turn S3 scan can discover them. False when the sync fails: the
    * turn then runs without store skills rather than pointing discovery at
    * paths that do not exist.
-   *
-   * With skills authored, every first cloud turn re-copies the authored
+   */
+  private ensureCloudSkillsSynced(store: CloudStoreTarget): Promise<boolean> {
+    const skills = this.project.agent.skills;
+    return this.syncToCloudStore("skills", store, skills.length > 0, () =>
+      syncSkillsToStore({
+        sink: store.sink,
+        agentName: this.project.name,
+        skills,
+        skillsPrefix: store.skillsPrefix,
+      })
+    );
+  }
+
+  /**
+   * Sync `agent/sandbox/workspace/**` seeds onto the Agent Store at
+   * `workspace/…` (hosted) or `agent-serve/<agent>/workspace/…`
+   * (personal-key local+cloud) before the first cloud prompt, which names
+   * the mounted directory (see buildCloudWorkspaceSection).
+   */
+  private ensureCloudWorkspaceSynced(
+    store: CloudStoreTarget
+  ): Promise<boolean> {
+    const seedFiles = this.project.agent.seedFiles;
+    return this.syncToCloudStore("workspace", store, seedFiles.length > 0, () =>
+      syncWorkspaceToStore({
+        sink: store.sink,
+        seedFiles,
+        workspacePrefix: store.workspacePrefix,
+      })
+    );
+  }
+
+  /**
+   * With files authored, every first cloud turn re-copies the authored
    * bytes and the memo only dedupes concurrent first turns. The mount is
    * writable from cloud sessions, so a once-per-process copy would let one
    * session's edits masquerade as agent definition for every later session
    * until the engine restarts; re-syncing keeps the store true to discovery
    * the same way local materialization always rewrites skills. Without
-   * skills the sync is best-effort stale cleanup and one attempt per
-   * process is enough, success or not — a deployment without the files
+   * authored files the sync is best-effort stale cleanup and one attempt
+   * per process is enough, success or not — a deployment without the files
    * surface must not fail and log on every new session for a feature it
    * does not use.
    */
-  private ensureCloudSkillsSynced(): Promise<boolean> {
-    if (this.cloudSkillsSync !== undefined) {
-      return this.cloudSkillsSync;
-    }
-    const target = this.cloudSkillsStore();
-    if (target === undefined) {
-      this.cloudSkillsSync = Promise.resolve(false);
-      return this.cloudSkillsSync;
+  private syncToCloudStore(
+    surface: CloudSyncSurface,
+    store: CloudStoreTarget,
+    authored: boolean,
+    run: () => Promise<void>
+  ): Promise<boolean> {
+    const inFlight = this.cloudSyncs.get(surface);
+    if (inFlight !== undefined) {
+      return inFlight;
     }
-    const skills = this.project.agent.skills;
-    let sync = syncSkillsToStore({
-      sink: target.sink,
-      agentName: this.project.name,
-      skills,
-      skillsPrefix: target.skillsPrefix,
-    }).then(
+    let sync = run().then(
       () => true,
       (error) => {
         this.logger(
-          `[skills] ${target.label} sync failed: ${error instanceof Error ? error.message : String(error)}`
+          `[${surface}] ${store.label} sync failed: ${error instanceof Error ? error.message : String(error)}`
         );
         return false;
       }
     );
-    if (skills.length > 0) {
+    if (authored) {
       sync = sync.finally(() => {
-        this.cloudSkillsSync = undefined;
+        this.cloudSyncs.delete(surface);
       });
     }
-    this.cloudSkillsSync = sync;
+    this.cloudSyncs.set(surface, sync);
     return sync;
   }
 
@@ -2159,39 +2233,36 @@ export class SessionEngine {
    * Hosted deployments own the deployment store. Local `serve`/`run` with
    * a personal API key writes into the USER store under `agent-serve/`.
    */
-  private cloudSkillsStore():
-    | {
-        sink: ReturnType<typeof cursorHostedFiles>;
-        skillsPrefix: string;
-        label: string;
-      }
-    | undefined {
+  private cloudStore(): CloudStoreTarget | undefined {
     const v2Hosting = resolveAgentV2Hosting({
       architecture: this.project.agent.architecture,
     });
+    const deployment = {
+      mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
+      skillsPrefix: agentStoreKeys.skillsPrefix(),
+      workspacePrefix: agentStoreKeys.workspacePrefix(),
+      label: "deployment store",
+    };
     if (v2Hosting.kind === "cursor-managed") {
       return {
         sink: cursorHostedFiles({
           resolveStoreSourceId: () =>
             v2Hosting.resolveStoreIds().deploymentStoreSourceId,
         }),
-        skillsPrefix: agentStoreKeys.skillsPrefix(),
-        label: "deployment store",
+        ...deployment,
       };
     }
     if (v2Hosting.kind === "not-v2" && isCursorHostedFilesAvailable()) {
-      return {
-        sink: cursorHostedFiles(),
-        skillsPrefix: agentStoreKeys.skillsPrefix(),
-        label: "deployment store",
-      };
+      return { sink: cursorHostedFiles(), ...deployment };
     }
     if (isCursorUserStoreFilesAvailable()) {
       return {
         sink: cursorHostedFiles({
           storeSourceId: AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
         }),
+        mountPath: USER_STORE_MOUNT_PATH,
         skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
+        workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
         label: "user store",
       };
     }
@@ -2263,13 +2334,14 @@ export class SessionEngine {
     if (isFirstTurn) {
       if (runtime === "cloud") {
         // Cloud VMs have no materialized workspace: ship the full context,
-        // including agent tool script bodies. On hosted deployments authored
-        // skills land on the store mount for native discovery, and the
-        // shared memory journal is on that mount too — say where. When the
-        // turn carries the session-bound server-tool MCP endpoint, the
-        // preamble catalogs server tools under that MCP server name *before*
-        // the agent-tool "write the script if missing" recipe, so a model
-        // told to "use <server tool>" calls MCP instead of inventing a .sh.
+        // including agent tool script bodies. Authored skills and workspace
+        // seeds land on the store mount (skills for native discovery, seeds
+        // for the model's file tools), and on hosted deployments the shared
+        // memory journal is on that mount too — say where. When the turn
+        // carries the session-bound server-tool MCP endpoint, the preamble
+        // catalogs server tools under that MCP server name *before* the
+        // agent-tool "write the script if missing" recipe, so a model told
+        // to "use <server tool>" calls MCP instead of inventing a .sh.
         const preamble = buildAgentsMdContent(agent, {
           includeScripts: true,
           serverToolsMcpName:
@@ -2278,17 +2350,30 @@ export class SessionEngine {
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
         const hosted = isCursorHostedFilesAvailable();
-        // Synced whenever a store is reachable, not just when skills exist:
-        // removing the last skill has to delete its store copies too.
-        // Discovery is native (`--agent-store-skills-dir`); this only has
-        // to land the bytes.
-        if (hosted || isCursorUserStoreFilesAvailable()) {
-          await this.ensureCloudSkillsSynced();
+        // Synced whenever a store is reachable, not just when skills or
+        // seeds exist: removing the last one has to delete its store copies
+        // too.
+        const store =
+          hosted || isCursorUserStoreFilesAvailable()
+            ? this.cloudStore()
+            : undefined;
+        let sections = "";
+        if (store !== undefined) {
+          const [, seedsSynced] = await Promise.all([
+            this.ensureCloudSkillsSynced(store),
+            this.ensureCloudWorkspaceSynced(store),
+          ]);
+          // Only name the mount when the bytes landed; a failed sync must
+          // not send the model looking for files that are not there.
+          if (seedsSynced && agent.seedFiles.length > 0) {
+            const dir = `${store.mountPath}/${store.workspacePrefix}`;
+            sections += `\n\n${buildCloudWorkspaceSection(dir)}`;
+          }
         }
-        const memorySection = hosted
-          ? `\n\n${buildCloudMemorySection(this.project.name)}`
-          : "";
-        turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
+        if (hosted) {
+          sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
+        }
+        turnPrompt = `${preamble}${sections}\n\n${turnPrompt}`;
       } else if (runtime === "local" && instructionsInvisibleToHarness) {
         // Local workspace whose AGENTS.md the harness will not load. With a
         // borrowed harness cwd, agent tool scripts live only in the durable
@@ -2880,6 +2965,31 @@ export class SessionEngine {
     }
   }
 
+  /**
+   * Bind outbound inject (Factory / Cursor API `traceparent`) to the
+   * turn span for the whole harness run. Host files / VFS RPCs happen
+   * here, not under `runInCall`. No-op when OTel is off.
+   */
+  private runTurnExecute<T>(
+    record: SessionRecord,
+    turnId: string,
+    fn: () => T | Promise<T>
+  ): Promise<T> {
+    const otel = this.otel;
+    const run = (): Promise<T> => Promise.resolve(fn());
+    if (otel === undefined) {
+      return run();
+    }
+    return otel.runInTurn(
+      {
+        sessionId: record.sessionId,
+        session: this.sessionInfo(record),
+        turnId,
+      },
+      run
+    );
+  }
+
   /**
    * Bind outbound inject (Factory / Cursor API `traceparent`) to the
    * tool span. No-op when OTel is off.
@@ -4011,7 +4121,10 @@ export class SessionEngine {
       return;
     }
 
-    const sessionCtx = { session: this.sessionInfo(record) };
+    const sessionCtx: SessionContext = {
+      session: this.sessionInfo(record),
+      host: this.hostForSession(record.sessionId),
+    };
     const channelEvents = this.channelEventHandlersFor(record.channelId);
     if (channelEvents !== undefined) {
       // Handlers are declared against the narrowed event for their key; the
@@ -4054,14 +4167,13 @@ export class SessionEngine {
         }
         try {
           await handler(event, {
+            ...sessionCtx,
             agent: { name: this.project.name },
             channel: {
               id: record.channelId,
               continuationToken: record.continuationKey,
             },
-            session: this.sessionInfo(record),
             stateRoot: this.stateRoot,
-            host: this.hostForSession(record.sessionId),
             artifacts: this.artifactsApi({
               sessionId: record.sessionId,
               turnId: event.turnId,
@@ -4078,12 +4190,12 @@ export class SessionEngine {
     if (this.abCollector.enabled) {
       await this.abCollector.onEvent(
         event,
-        this.sessionInfo(record),
+        sessionCtx.session,
         this.project.name
       );
     }
 
-    this.otel?.onEvent(event, this.sessionInfo(record));
+    this.otel?.onEvent(event, sessionCtx.session);
   }
 
   private channelEventHandlersFor(
@@ -5191,10 +5303,6 @@ function buildRunnerSubagents(agent: ResolvedAgent): RunnerSubagent[] {
   }));
 }
 
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function toolErrorResult(message: string): SDKCustomToolResult {
   return {
     content: [{ type: "text", text: message }],

package/src/internal/session-run-log.ts

@@ -26,6 +26,7 @@ import type { AgentProject } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { describeError } from "./describe-error.js";
 import type { HostedExecutionDiagAbortReason } from "./hosted-execution-diag.js";
+import { isRecord } from "./is-record.js";
 import type { LogRingEntry } from "./log-ring.js";
 import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
@@ -193,10 +194,6 @@ export function snapshotSessionRunLogs(
   }));
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function decodeSinkBody(body: Uint8Array | { body: Uint8Array }): Uint8Array {
   return body instanceof Uint8Array ? body : body.body;
 }

package/src/internal/skills-sync.ts

@@ -7,10 +7,10 @@
  */
 
 import { readFile } from "node:fs/promises";
-import { posix } from "node:path";
-import { agentStoreKeys, FileConflictError, type FileSink } from "../files.js";
+import { agentStoreKeys, type FileSink } from "../files.js";
 import { STORAGE_KEY_ROOT } from "../storage.js";
 import type { DiscoveredSkill, SkillFileSource } from "../types.js";
+import { mirrorToStore, storeRelPath } from "./store-mirror.js";
 import { buildSkillMd } from "./workspace.js";
 
 /** Pre-native layout. Deleted on every sync so a rolled-forward deploy does not leave undiscoverable copies. */
@@ -22,10 +22,7 @@ function legacySkillsPrefix(agent: string): string {
  * Mirror the agent's skills onto the store: write every SKILL.md (with the
  * same generated frontmatter local materialization uses) plus sibling files,
  * and delete keys no authored skill claims so redeploys drop removed skills.
- *
- * Everything loads and validates before the store is touched, and writes
- * land before stale deletes, so a failed sync never leaves a gap a
- * concurrent cloud reader could see.
+ * Everything loads and validates before the store is touched.
  */
 export async function syncSkillsToStore(args: {
   sink: FileSink;
@@ -42,65 +39,18 @@ export async function syncSkillsToStore(args: {
       agentStoreKeys.skillFile(skill.name, relPath, skillsPrefix);
     desired.set(key("SKILL.md"), Buffer.from(buildSkillMd(skill), "utf8"));
     for (const [relPath, source] of Object.entries(skill.files)) {
-      desired.set(key(storeRelPath(relPath)), await sourceBytes(source));
+      desired.set(
+        key(storeRelPath(relPath, "skill file")),
+        await sourceBytes(source)
+      );
     }
   }
-  await Promise.all(
-    [...desired].map(([key, body]) => putLastWriterWins(args.sink, key, body))
-  );
-  const [existing, leftover] = await Promise.all([
-    args.sink.list(skillsPrefix),
-    args.sink.list(legacySkillsPrefix(args.agentName)),
-  ]);
-  await Promise.all(
-    [...existing.filter((entry) => !desired.has(entry.key)), ...leftover].map(
-      (entry) => args.sink.delete(entry.key)
-    )
-  );
-}
-
-/**
- * Same refusals as local materialization's `resolveInside`: a rel that
- * escapes the skill directory or would not round-trip through the FUSE
- * mount (`..`, `.`, `//`, absolute) fails the sync, exactly as it fails a
- * local turn's workspace write. Backslashes are refused too — the store
- * normalizes `\` to `/` on write, so the stored key would differ from the
- * desired one and the stale pass would delete the file it just wrote.
- */
-function storeRelPath(relPath: string): string {
-  if (
-    relPath.includes("\0") ||
-    relPath.includes("\\") ||
-    posix.isAbsolute(relPath) ||
-    relPath.endsWith("/") ||
-    relPath.split("/").some((seg) => seg === ".." || seg === ".") ||
-    posix.normalize(relPath) !== relPath
-  ) {
-    throw new Error(
-      `Refusing skill file path "${relPath}" (must be a normalized relative path)`
-    );
-  }
-  return relPath;
-}
-
-/**
- * Last writer wins. A raced conditional put (dual engine pods during a
- * deploy rollover) clears the sink's cached etag, so one retry re-learns
- * the current version and lands.
- */
-async function putLastWriterWins(
-  sink: FileSink,
-  key: string,
-  body: Uint8Array
-): Promise<void> {
-  try {
-    await sink.put(key, body);
-  } catch (error) {
-    if (!(error instanceof FileConflictError)) {
-      throw error;
-    }
-    await sink.put(key, body);
-  }
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: skillsPrefix,
+    desired,
+    legacyPrefixes: [legacySkillsPrefix(args.agentName)],
+  });
 }
 
 async function sourceBytes(source: SkillFileSource): Promise<Uint8Array> {

package/src/internal/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/internal/store-mirror.ts

@@ -0,0 +1,86 @@
+/**
+ * Mirror an authored file tree onto an Agent Store prefix. Shared by the
+ * skills and workspace seed syncs so both keep the same write-then-sweep
+ * discipline and the same path refusals.
+ */
+
+import { posix } from "node:path";
+import { FileConflictError, type FileSink } from "../files.js";
+
+/**
+ * Write every `desired` key, then delete keys under `prefix` (and the
+ * `legacyPrefixes`) that nothing claims, so a redeploy drops removed files.
+ * Writes land before stale deletes, so a failed sync never leaves a gap a
+ * concurrent cloud reader could see.
+ */
+export async function mirrorToStore(args: {
+  sink: FileSink;
+  prefix: string;
+  desired: ReadonlyMap<string, Uint8Array>;
+  /** Pre-native layouts emptied on every sync so a rolled-forward deploy does not leave undiscoverable copies. */
+  legacyPrefixes?: readonly string[];
+}): Promise<void> {
+  await Promise.all(
+    [...args.desired].map(([key, body]) =>
+      putLastWriterWins(args.sink, key, body)
+    )
+  );
+  const listed = await Promise.all(
+    [args.prefix, ...(args.legacyPrefixes ?? [])].map((prefix) =>
+      args.sink.list(prefix)
+    )
+  );
+  await Promise.all(
+    listed
+      .flat()
+      .filter((entry) => !args.desired.has(entry.key))
+      .map((entry) => args.sink.delete(entry.key))
+  );
+}
+
+/**
+ * Same refusals as local materialization's `resolveInside`: a rel that
+ * escapes its directory or would not round-trip through the FUSE mount
+ * (`..`, `.`, `//`, absolute) fails the sync, exactly as it fails a local
+ * turn's workspace write. Backslashes are refused too — the store
+ * normalizes `\` to `/` on write, so the stored key would differ from the
+ * desired one and the stale pass would delete the file it just wrote.
+ */
+export function storeRelPath(
+  relPath: string,
+  what: "skill file" | "workspace file"
+): string {
+  if (
+    relPath.includes("\0") ||
+    relPath.includes("\\") ||
+    posix.isAbsolute(relPath) ||
+    relPath.endsWith("/") ||
+    relPath.split("/").some((seg) => seg === ".." || seg === ".") ||
+    posix.normalize(relPath) !== relPath
+  ) {
+    throw new Error(
+      `Refusing ${what} path "${relPath}" (must be a normalized relative path)`
+    );
+  }
+  return relPath;
+}
+
+/**
+ * Last writer wins. A raced conditional put (dual engine pods during a
+ * deploy rollover) clears the sink's cached etag, so one retry re-learns
+ * the current version and lands.
+ */
+async function putLastWriterWins(
+  sink: FileSink,
+  key: string,
+  body: Uint8Array
+): Promise<void> {
+  try {
+    await sink.put(key, body);
+  } catch (error) {
+    if (!(error instanceof FileConflictError)) {
+      throw error;
+    }
+    await sink.put(key, body);
+  }
+}