merge: reconcile measured sandbox qualification with Claude platforms

Co-Authored-By: Paperclip <noreply@paperclip.ing>

server/src/services/agent-runner-selection.test.ts

@@ -1,10 +1,11 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { agentHarnessType, agentRunner, paperclipRunnerProfileForHarness, paperclipRunnerSupportsPlatform, PAPERCLIP_RUNNER_MINIMUM_GLIBC_VERSION, createAgentSchema, updateAgentSchema, testAdapterEnvironmentSchema } from "@paperclipai/shared";
-const state = vi.hoisted(() => ({ disabled: [] as string[], overridden: new Set<string>(), settings: {} as Record<string, unknown>, getEnvironment: vi.fn(), bindings: vi.fn(), managedEnvironment: vi.fn(), ssh: vi.fn(), resolveEnvironment: vi.fn() }));
+const state = vi.hoisted(() => ({ disabled: [] as string[], overridden: new Set<string>(), settings: {} as Record<string, unknown>, getEnvironment: vi.fn(), bindings: vi.fn(), managedEnvironment: vi.fn(), ssh: vi.fn(), resolveEnvironment: vi.fn(), sandboxQualification: vi.fn() }));
 vi.mock("../adapters/registry.js", () => ({ findActiveServerAdapter: (type: string) => ({ type }), hasActiveAdapterOverride: (type: string) => state.overridden.has(type), waitForExternalAdapters: async () => {} }));
 vi.mock("./adapter-plugin-store.js", () => ({ getDisabledAdapterTypes: () => state.disabled }));
 vi.mock("./instance-settings.js", () => ({ instanceSettingsService: () => ({ get: async () => state.settings }) }));
 vi.mock("./environments.js", () => ({ environmentService: () => ({ getById: state.getEnvironment, listBoundCompanyIds: state.bindings, findManagedSandboxEnvironment: state.managedEnvironment, findKubernetesEnvironment: state.managedEnvironment }) }));
+vi.mock("./environment-probe.js", () => ({ readSandboxPlatformQualification: state.sandboxQualification }));
 vi.mock("./environment-config.js", () => ({ resolveEnvironmentDriverConfigForRuntime: state.resolveEnvironment }));
 vi.mock("@paperclipai/adapter-utils/ssh", () => ({ runSshCommand: state.ssh }));
 import { AGENT_RUNNER_SSH_PLATFORM_COMMAND, agentRunnerAvailability, resolveAgentRunnerTargetForCompany, resolveNewAgentRunner, resolveNewAgentRunnerForCompany } from "./agent-runner-selection.js";
@@ -16,7 +17,7 @@ const originalArchitecture = Object.getOwnPropertyDescriptor(process, "arch")!;
 afterEach(() => { vi.restoreAllMocks(); Object.defineProperty(process, "platform", originalPlatform); Object.defineProperty(process, "arch", originalArchitecture); });
 
 describe("server-owned Codex runner selection", () => {
-  beforeEach(() => { state.disabled = []; state.overridden.clear(); state.settings = {}; state.getEnvironment.mockReset(); state.bindings.mockReset().mockResolvedValue([]); state.managedEnvironment.mockReset(); state.ssh.mockReset().mockResolvedValue({ stdout: "Linux\nx86_64\n" }); state.resolveEnvironment.mockReset().mockResolvedValue({ driver: "ssh", config: {} }); });
+  beforeEach(() => { state.disabled = []; state.overridden.clear(); state.settings = {}; state.getEnvironment.mockReset(); state.bindings.mockReset().mockResolvedValue([]); state.managedEnvironment.mockReset(); state.ssh.mockReset().mockResolvedValue({ stdout: "Linux\nx86_64\n" }); state.sandboxQualification.mockReset().mockResolvedValue(null); state.resolveEnvironment.mockReset().mockResolvedValue({ driver: "ssh", config: {} }); });
   it.each(["x64", "arm64"])("keeps detected musl/unknown Linux %s legacy and preserves saved execution", architecture => {
     for (const libc of ["musl", "unknown"] as const) {
       const target = { driver: "local", platform: "linux", architecture, libc };
@@ -166,10 +167,30 @@ describe("server-owned Codex runner selection", () => {
     expect(state.getEnvironment).not.toHaveBeenCalled();
     expect(state.ssh).not.toHaveBeenCalled();
   });
+  it.each([
+    [{ platform: "linux", architecture: "x64", libc: "glibc", glibcVersion: "2.39" }, "paperclip_runner"],
+    [{ platform: "linux", architecture: "arm64", libc: "glibc", glibcVersion: "3.0" }, "paperclip_runner"],
+    [{ platform: "linux", architecture: "arm64", libc: "glibc", glibcVersion: "2.38" }, "codex_local"],
+    [{ platform: "linux", architecture: "x64", libc: "glibc" }, "codex_local"],
+    [{ platform: "linux", architecture: "arm64", libc: "musl" }, "codex_local"],
+    [{ platform: "linux", architecture: "unknown", libc: "glibc", glibcVersion: "2.39" }, "codex_local"],
+  ])("uses cached selected-image measurements for sandbox creation/discovery (%j)", async (facts, expected) => {
+    state.getEnvironment.mockResolvedValue({ id: "sandbox", driver: "sandbox", status: "active", config: { provider: "daytona" } });
+    state.sandboxQualification.mockResolvedValue(facts);
+    const selectedTarget = await resolveAgentRunnerTargetForCompany({} as never, "company", "sandbox");
+    expect(agentRunnerAvailability("codex_local", selectedTarget).defaultRunner).toBe(expected === "paperclip_runner" ? "paperclip" : "legacy");
+    const result = await resolveNewAgentRunnerForCompany({} as never, "company", { adapterType: "codex_local", defaultEnvironmentId: "sandbox" });
+    expect(result.adapterType).toBe(expected);
+    expect(state.ssh).not.toHaveBeenCalled();
+    expect(state.resolveEnvironment).not.toHaveBeenCalled();
+    if (expected === "codex_local") await expect(resolveNewAgentRunnerForCompany({} as never, "company", { adapterType: "codex_local", runner: "paperclip", defaultEnvironmentId: "sandbox" })).rejects.toMatchObject({ status: 422 });
+  });
   it("does not infer a sandbox image architecture from its driver", async () => {
     state.getEnvironment.mockResolvedValue({ id: "sandbox", driver: "sandbox", status: "active", config: { provider: "daytona" } });
     const result = await resolveNewAgentRunnerForCompany({} as never, "company", { adapterType: "codex_local", defaultEnvironmentId: "sandbox" });
-    expect(result.adapterType).toBe("paperclip_runner"); expect(state.ssh).not.toHaveBeenCalled();
+    expect(result.adapterType).toBe("codex_local"); expect(state.ssh).not.toHaveBeenCalled();
+    expect(state.sandboxQualification).toHaveBeenCalledWith({}, expect.objectContaining({ id: "sandbox" }), "company");
+    await expect(resolveNewAgentRunnerForCompany({} as never, "company", { adapterType: "codex_local", runner: "paperclip", defaultEnvironmentId: "sandbox" })).rejects.toMatchObject({ status: 422, details: { code: "agent_runner_unavailable" } });
   });
 });
 

server/src/services/agent-runner-selection.ts

@@ -30,6 +30,8 @@ function runnerAdaptersAvailable(harness: string, driver: string): boolean {
 
 export function agentRunnerAvailability(harness: string, target: RunnerTarget = localAgentRunnerTarget()): AgentRunnerAvailability {
   const supported = runnerAdaptersAvailable(harness, target.driver)
+    && (target.driver !== "sandbox" || Boolean(target.platform && target.architecture
+      && (target.platform !== "linux" || (target.libc === "glibc" && target.glibcVersion))))
     && (harness === "claude_local"
       ? !!target.platform && paperclipRunnerSupportsPlatform(harness, target.platform, target.architecture ?? "", target.libc, target.glibcVersion)
       : !target.platform || paperclipRunnerSupportsPlatform(harness, target.platform, target.architecture ?? "", target.libc, target.glibcVersion));
@@ -108,7 +110,9 @@ export function resolveNewAgentRunner(input: AgentRunnerSelection): { adapterTyp
     return { adapterType: "codex_local", adapterConfig: { ...config, dangerouslyBypassApprovalsAndSandbox: config.dangerouslyBypassApprovalsAndSandbox ?? true } };
   }
   if (native && harness !== "codex_local" && choice === "paperclip") return { adapterType, adapterConfig: normalizeLegacyRunnerProvider(config) };
-  if (!availability.supportedRunners.includes("paperclip")) throw unprocessable("Paperclip Runner is unavailable for this harness and environment. Select Legacy runner in Advanced.", { code: "agent_runner_unavailable" });
+  if (!availability.supportedRunners.includes("paperclip")) throw unprocessable(input.target?.driver === "sandbox"
+    ? "Paperclip Runner is unavailable for this sandbox. Choose an immutable OCI image digest and run its environment connection probe to qualify the OS, architecture and libc, or select Legacy runner in Advanced."
+    : "Paperclip Runner is unavailable for this harness and environment. Select Legacy runner in Advanced.", { code: "agent_runner_unavailable" });
   if (native) return { adapterType, adapterConfig: normalizeLegacyRunnerProvider(config) };
   if (harness === "claude_local") {
     config = resolveClaudeRunnerConfig(config);
@@ -174,7 +178,12 @@ export async function resolveAgentRunnerTargetForCompany(db: Db, companyId: stri
   }
   const driver = environment?.driver ?? "local";
   let target: RunnerTarget = driver === "local" ? localAgentRunnerTarget()
-    : { driver }; // Sandbox platform/artifact identity is verified by selected-runtime setup; do not guess an image's architecture.
+    : { driver };
+  if (driver === "sandbox" && environment) {
+    const { readSandboxPlatformQualification } = await import("./environment-probe.js");
+    const qualified = await readSandboxPlatformQualification(db, environment, companyId);
+    if (qualified) target = { driver, ...qualified };
+  }
   if (driver === "ssh" && environment && ["codex_local", "claude_local"].some(harness => runnerAdaptersAvailable(harness, driver))) {
     const parsed = await resolveEnvironmentDriverConfigForRuntime(db, companyId, environment);
     if (parsed.driver !== "ssh") throw unprocessable("The selected SSH environment is unavailable.");

server/src/services/environment-config.ts

@@ -660,6 +660,8 @@ export async function resolveEnvironmentDriverConfigForRuntime(
     // but must still resolve the active custom image as prepared runtime
     // configuration and tooling so the test reflects what real agent runs use.
     applyCustomImageTemplate?: boolean;
+    readOnlyCustomImageTemplate?: boolean;
+    onResolvedCustomImageTemplate?: (identity: { id: string; capturedAt: string | null; templateKind: string; bindingField: string }) => void;
   },
 ): Promise<ParsedEnvironmentConfig> {
   const parsed = parseEnvironmentDriverConfig(environment);
@@ -729,6 +731,8 @@ export async function resolveEnvironmentDriverConfigForRuntime(
             // are excluded when the template's source fingerprint is computed,
             // so they must be excluded when re-checking it here.
             secretRefExcludePaths: collectSecretRefPaths(schema),
+            readOnly: context?.readOnlyCustomImageTemplate,
+            onResolvedTemplate: context?.onResolvedCustomImageTemplate,
           })
         : runtimeConfig,
     };

server/src/services/environment-custom-image-runtime.ts

@@ -13,6 +13,8 @@ import { readConfigValueAtPath, writeConfigValueAtPath } from "./json-schema-sec
 type TemplateRow = typeof environmentCustomImageTemplates.$inferSelect;
 
 export const ENVIRONMENT_CUSTOM_IMAGE_RUNTIME_CONFIG_BINDING_METADATA_KEY = "runtimeConfigBinding";
+/** Measured platform evidence is reserved to explicit server-side environment probes. */
+export const SANDBOX_PLATFORM_PROBE_METADATA_KEY = "paperclipSandboxPlatformProbes";
 export const ENVIRONMENT_CUSTOM_IMAGE_CONFIG_FINGERPRINT_EXCLUDED_PATHS = [
   "timeoutMs",
   "reuseLease",
@@ -557,6 +559,8 @@ export async function resolveActiveEnvironmentCustomImageTemplateForRuntime(
     runtimeConfig: SandboxEnvironmentConfig;
     secretRefExcludePaths?: Iterable<string>;
     now?: Date;
+    readOnly?: boolean;
+    onResolvedTemplate?: (identity: { id: string; capturedAt: string | null; templateKind: string; bindingField: string }) => void;
   },
 ): Promise<SandboxEnvironmentConfig> {
   const row = await db
@@ -587,7 +591,9 @@ export async function resolveActiveEnvironmentCustomImageTemplateForRuntime(
   // match. Runtime-only knobs such as lease reuse, timeouts, and resource hints
   // are excluded from the fingerprint so those edits do not discard the capture.
   const now = input.now ?? new Date();
-  await db
+  input.onResolvedTemplate?.({ id: row.id, capturedAt: row.capturedAt?.toISOString() ?? null,
+    templateKind: row.templateKind ?? "unknown", bindingField: resolveEnvironmentCustomImageRuntimeConfigBinding(row).field });
+  if (!input.readOnly) await db
     .update(environmentCustomImageTemplates)
     .set({ lastUsedAt: now, updatedAt: now })
     .where(eq(environmentCustomImageTemplates.id, active.id));

server/src/services/environment-probe.ts

@@ -11,6 +11,56 @@ import { isBuiltinSandboxProvider, probeSandboxProvider } from "./sandbox-provid
 import { probePluginEnvironmentDriver, probePluginSandboxProviderDriver } from "./plugin-environment-driver.js";
 import type { PluginWorkerManager } from "./plugin-worker-manager.js";
 import { environmentRuntimeService } from "./environment-runtime.js";
+import { environmentService } from "./environments.js";
+import { fingerprintEnvironmentSandboxProviderConfig, SANDBOX_PLATFORM_PROBE_METADATA_KEY } from "./environment-custom-image-runtime.js";
+import type { SandboxEnvironmentConfig } from "@paperclipai/shared";
+
+export const SANDBOX_PLATFORM_PROBE_COMMAND = "uname -s; uname -m; if version=$(getconf GNU_LIBC_VERSION 2>/dev/null) && [ -n \"$version\" ]; then printf 'glibc\\n%s\\n' \"$version\"; else case \"$(ldd --version 2>&1)\" in *musl*) printf 'musl\\n' ;; *) printf 'unknown\\n' ;; esac; fi";
+type PlatformFacts = { platform: string; architecture: string; libc: "glibc" | "musl" | "unknown"; glibcVersion?: string };
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+function fingerprint(config: Record<string, unknown>): string {
+  return fingerprintEnvironmentSandboxProviderConfig(config as SandboxEnvironmentConfig);
+}
+function isImmutableImage(value: unknown): value is string {
+  return typeof value === "string" && /^[^\s@]+@sha256:[a-f0-9]{64}$/.test(value);
+}
+export function parseSandboxPlatformFacts(output: string): PlatformFacts {
+  const [os, arch, libc, version] = output.trim().split(/\r?\n/);
+  return { platform: os === "Linux" ? "linux" : os === "Darwin" ? "darwin" : "unknown",
+    architecture: arch === "x86_64" ? "x64" : arch === "aarch64" || arch === "arm64" ? "arm64" : "unknown",
+    libc: libc === "glibc" || libc === "musl" ? libc : "unknown",
+    ...(libc === "glibc" ? { glibcVersion: version?.trim() ?? "unknown" } : {}) };
+}
+async function sandboxBinding(db: Db, environment: Environment, companyId: string) {
+  const selectedTemplate: { value: { id: string; capturedAt: string | null; templateKind: string; bindingField: string } | null } = { value: null };
+  const parsed = await resolveEnvironmentDriverConfigForRuntime(db, companyId, environment, {
+    applyCustomImageTemplate: true, readOnlyCustomImageTemplate: true,
+    onResolvedCustomImageTemplate: identity => { selectedTemplate.value = identity; },
+  });
+  if (parsed.driver !== "sandbox") return null;
+  const image = parsed.config.image;
+  // Names, mutable tags, provider defaults and snapshot names are not immutable identities.
+  const template = selectedTemplate.value;
+  if (!isImmutableImage(image) || ["snapshot", "template", "templateRef"].some(key => record(parsed.config)[key])
+    || (template && (template.templateKind !== "image" || template.bindingField !== "image"))) return null;
+  return { baseConfigFingerprint: fingerprint(environment.config), runtimeConfigFingerprint: fingerprint(parsed.config as unknown as Record<string, unknown>), image, template };
+}
+
+/** Read measured, company-scoped image evidence without leasing or contacting a provider. */
+export async function readSandboxPlatformQualification(db: Db, environment: Environment, companyId: string): Promise<PlatformFacts | null> {
+  const proof = record(record(environment.metadata?.[SANDBOX_PLATFORM_PROBE_METADATA_KEY])[companyId]);
+  if (proof.v !== 1 || proof.companyId !== companyId || proof.baseConfigFingerprint !== fingerprint(environment.config)) return null;
+  const binding = await sandboxBinding(db, environment, companyId);
+  if (!binding || proof.runtimeConfigFingerprint !== binding.runtimeConfigFingerprint || proof.image !== binding.image
+    || JSON.stringify(proof.template) !== JSON.stringify(binding.template)) return null;
+  const facts = record(proof.facts);
+  if (typeof facts.platform !== "string" || typeof facts.architecture !== "string"
+    || !["glibc", "musl", "unknown"].includes(String(facts.libc))) return null;
+  return { platform: facts.platform, architecture: facts.architecture, libc: facts.libc as PlatformFacts["libc"],
+    ...(typeof facts.glibcVersion === "string" ? { glibcVersion: facts.glibcVersion } : {}) };
+}
 
 export async function probeEnvironment(
   db: Db,
@@ -24,6 +74,10 @@ export async function probeEnvironment(
   } = {},
 ): Promise<EnvironmentProbeResult> {
   const resolvedCompanyId = options.companyId ?? null;
+  const savedSandboxProbe = environment.driver === "sandbox" && options.acquireSandboxRuntimeLease === true && resolvedCompanyId;
+  const environments = environmentService(db);
+  if (savedSandboxProbe) await environments.recordSandboxPlatformProbe({ environmentId: environment.id,
+    companyId: savedSandboxProbe, config: environment.config, proof: null });
   const parsed = options.resolvedConfig ?? (
     options.acquireSandboxRuntimeLease === true
       ? parseEnvironmentDriverConfig(environment)
@@ -77,6 +131,8 @@ export async function probeEnvironment(
       };
       let leaseRecord: Awaited<ReturnType<typeof runtime.acquireRunLease>> | null = null;
       let releaseStatus: "released" | "failed" = "released";
+      let qualification: Record<string, unknown> | null = null;
+      let details: Record<string, unknown> | null = null;
       try {
         leaseRecord = await runtime.acquireRunLease({
           companyId: resolvedCompanyId,
@@ -93,19 +149,37 @@ export async function probeEnvironment(
         const sandboxName = typeof metadata.sandboxName === "string" && metadata.sandboxName.trim().length > 0
           ? metadata.sandboxName.trim()
           : null;
+        details = { provider, providerLeaseId: leaseRecord.lease.providerLeaseId, leaseId: leaseRecord.lease.id,
+          leasePolicy: leaseRecord.lease.leasePolicy, metadata, platformQualificationRecorded: false,
+          platformQualificationDiagnostic: "An immutable OCI image digest is required; this connection probe does not qualify a mutable image or snapshot name." };
+        if (isImmutableImage(metadata.image) && !metadata.snapshot) {
+          try {
+            const binding = await sandboxBinding(db, environment, resolvedCompanyId);
+            if (binding && metadata.image === binding.image) {
+              const platform = await runtime.execute({ environment: probeEnvironmentConfig, lease: leaseRecord.lease,
+                command: "sh", args: ["-c", SANDBOX_PLATFORM_PROBE_COMMAND],
+                bypassSession: true, timeoutMs: 10_000, commandTimeoutMs: 10_000 });
+              if (platform.exitCode !== 0) throw new Error("platform_probe_failed");
+              const facts = parseSandboxPlatformFacts(platform.stdout);
+              details.platform = facts;
+              if (facts.platform !== "unknown" && facts.architecture !== "unknown"
+                && (facts.platform !== "linux" || facts.libc !== "unknown")
+                && (facts.libc !== "glibc" || /^(?:glibc\s+)?\d+\.\d+(?:\.\d+)?$/.test(facts.glibcVersion ?? ""))) {
+                qualification = { v: 1, companyId: resolvedCompanyId, ...binding, facts, probedAt: new Date().toISOString() };
+                delete details.platformQualificationDiagnostic;
+              } else details.platformQualificationDiagnostic = "The image's OS, architecture or libc could not be identified. Legacy remains the creation default.";
+            } else details.platformQualificationDiagnostic = "The live lease does not match the selected immutable image configuration. Probe again.";
+          } catch {
+            details.platformQualificationDiagnostic = "Platform qualification could not complete; connection readiness does not establish native compatibility. Check the image and probe again.";
+          }
+        }
         return {
           ok: true,
           driver: "sandbox",
           summary: sandboxName
             ? `Connected to ${provider} sandbox ${sandboxName}.`
             : `Connected to ${provider} sandbox environment.`,
-          details: {
-            provider,
-            providerLeaseId: leaseRecord.lease.providerLeaseId,
-            leaseId: leaseRecord.lease.id,
-            leasePolicy: leaseRecord.lease.leasePolicy,
-            metadata,
-          },
+          details,
         };
       } catch (error) {
         releaseStatus = "failed";
@@ -122,11 +196,25 @@ export async function probeEnvironment(
         if (leaseRecord) {
           const driver = runtime.getDriver(environment.driver);
           try {
-            await driver?.releaseRunLease({
+            const releasedLease = await driver?.releaseRunLease({
               environment: probeEnvironmentConfig,
               lease: leaseRecord.lease,
               status: releaseStatus,
             });
+            if (qualification && driver && savedSandboxProbe
+              && releasedLease?.id === leaseRecord.lease.id
+              && releasedLease.companyId === resolvedCompanyId
+              && releasedLease.environmentId === environment.id
+              && releasedLease.status === "released" && releasedLease.cleanupStatus === "success") {
+              const recorded = await environments.recordSandboxPlatformProbe({ environmentId: environment.id, companyId: savedSandboxProbe,
+                config: environment.config, proof: qualification });
+              if (details) {
+                details.platformQualificationRecorded = recorded;
+                if (!recorded) details.platformQualificationDiagnostic = "The environment changed during the probe. Probe its current configuration again.";
+              }
+            } else if (qualification && details) {
+              details.platformQualificationDiagnostic = "The probe lease cleanup could not be verified. Resolve pending cleanup and probe again.";
+            }
           } catch (releaseError) {
             // Cleanup failures must not mask the connection result shown to
             // the operator, but a leaked sandbox should still be traceable.

server/src/services/environments.ts

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { and, desc, eq, inArray, isNull, ne, sql } from "drizzle-orm";
+
+import { SANDBOX_PLATFORM_PROBE_METADATA_KEY } from "./environment-custom-image-runtime.js";
+import { and, desc, eq, inArray, isNull, ne, sql, type SQL } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
   agents,
@@ -859,6 +861,21 @@ export function environmentService(db: Db) {
   };
 
   return {
+    recordSandboxPlatformProbe: async (input: {
+      environmentId: string;
+      companyId: string;
+      config: Record<string, unknown>;
+      proof: Record<string, unknown> | null;
+    }): Promise<boolean> => {
+      const existing = sql`coalesce(${environments.metadata}->${SANDBOX_PLATFORM_PROBE_METADATA_KEY}, '{}'::jsonb)`;
+      const probes = input.proof === null
+        ? sql`${existing} - ${input.companyId}`
+        : sql`${existing} || ${JSON.stringify({ [input.companyId]: input.proof })}::jsonb`;
+      const rows = await db.update(environments).set({
+        metadata: sql`jsonb_set(coalesce(${environments.metadata}, '{}'::jsonb), ARRAY[${SANDBOX_PLATFORM_PROBE_METADATA_KEY}]::text[], ${probes}, true)`,
+      }).where(and(eq(environments.id, input.environmentId), eq(environments.driver, "sandbox"), eq(environments.config, input.config))).returning({ id: environments.id });
+      return rows.length > 0;
+    },
     list: async (
       companyIdOrFilters?: string | EnvironmentListFilters,
       maybeFilters?: EnvironmentListFilters,
@@ -1118,20 +1135,30 @@ export function environmentService(db: Db) {
       if ("envVars" in patch && patch.envVars !== undefined) {
         values.envVars = (patch.envVars ?? {}) as Record<string, unknown>;
       }
+      const changesTarget = patch.config !== undefined || patch.driver !== undefined;
+      let metadataUpdate: SQL | undefined;
       if (patch.metadata !== undefined) {
-        values.metadata = withoutManagedEnvironmentArchiveToken(patch.metadata ?? null);
-      } else if (patch.status !== undefined) {
-        const existingMetadata = await writeDb
-          .select({ metadata: environments.metadata })
-          .from(environments)
-          .where(eq(environments.id, id))
-          .then((rows) => rows[0]?.metadata ?? null);
-        values.metadata = withoutManagedEnvironmentArchiveToken(existingMetadata);
+        const userMetadata = withoutManagedEnvironmentArchiveToken(patch.metadata ?? null);
+        if (userMetadata) delete userMetadata[SANDBOX_PLATFORM_PROBE_METADATA_KEY];
+        if (changesTarget) {
+          values.metadata = userMetadata;
+        } else {
+          const replacement = userMetadata === null ? sql`null::jsonb` : sql`${JSON.stringify(userMetadata)}::jsonb`;
+          // Preserve the current private subtree in the same statement. A route's
+          // earlier read must never replace a newer concurrent probe receipt.
+          metadataUpdate = sql`case when ${environments.metadata} ? ${SANDBOX_PLATFORM_PROBE_METADATA_KEY}
+            then coalesce(${replacement}, '{}'::jsonb) || jsonb_build_object(
+              ${SANDBOX_PLATFORM_PROBE_METADATA_KEY}::text, ${environments.metadata}->${SANDBOX_PLATFORM_PROBE_METADATA_KEY})
+            else ${replacement} end`;
+        }
+      } else if (changesTarget || patch.status !== undefined) {
+        metadataUpdate = sql`${environments.metadata} - ${MANAGED_ENVIRONMENT_ARCHIVE_TOKEN_METADATA_KEY}`;
+        if (changesTarget) metadataUpdate = sql`${metadataUpdate} - ${SANDBOX_PLATFORM_PROBE_METADATA_KEY}`;
       }
 
       const row = await writeDb
         .update(environments)
-        .set(values)
+        .set({ ...values, ...(metadataUpdate ? { metadata: metadataUpdate } : {}) })
         .where(eq(environments.id, id))
         .returning()
         .then((rows) => rows[0] ?? null)