@paperclipai/server 2026.824.0 → 2026.825.0-beta.1

package/dist/services/environment-runtime.js

@@ -1,10 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
-import { and, eq, inArray } from "drizzle-orm";
-import { companySecrets, companySecretVersions, environmentLeases } from "@paperclipai/db";
+import { and, eq, inArray, sql } from "drizzle-orm";
+import { companySecrets, companySecretVersions, environmentLeases, heartbeatRuns } from "@paperclipai/db";
 import { resolveDeclaredSandboxCapabilities } from "@paperclipai/shared";
 import { ensureSshWorkspaceReady } from "@paperclipai/adapter-utils/ssh";
 import { getActiveStepContext, runWithRuntimeParent, } from "@paperclipai/adapter-utils/acpx-engine/startup-timing";
 import { environmentService } from "./environments.js";
+import { instanceSettingsService } from "./instance-settings.js";
 import { collectEnvironmentSecretRefs, parseEnvironmentDriverConfig, resolveEnvironmentDriverConfigForRuntime, resolveSandboxCleanupConfigSecrets, stripSandboxProviderEnvelope, } from "./environment-config.js";
 import { createEffectiveRunConfigFingerprints, } from "./effective-run-config-fingerprints.js";
 import { acquireSandboxProviderLease, destroySandboxProviderLease, findReusableSandboxProviderLeaseId, getSandboxProvider as getBuiltinSandboxProvider, isBuiltinSandboxProvider, releaseSandboxProviderLease, sandboxConfigFromLeaseMetadata, sandboxConfigFromLeaseMetadataLoose, } from "./sandbox-provider-runtime.js";
@@ -19,6 +20,10 @@ import { logger } from "../middleware/logger.js";
 // credential in its name, code, message, cause, or stack. So the log records
 // this constant and the plain provider identifiers only.
 const SANDBOX_ORPHAN_CLEANUP_WRITE_ERROR_KIND = "sandbox_orphan_cleanup_write_failed";
+// The fixed non-secret refusal a duplex channel open returns when the lease does
+// not grant the opt-in `duplexCommandStream` capability. The service resolves the
+// exact lease capability snapshot and throws this before it reaches any driver.
+const DUPLEX_CHANNEL_CAPABILITY_DENIED = "Sandbox lease does not grant the duplex command stream capability.";
 // ---------------------------------------------------------------------------
 // Sandbox capability contract — one normalizer for both branches
 // ---------------------------------------------------------------------------
@@ -29,6 +34,8 @@ export const SANDBOX_CAPABILITY_KEYS = [
     "persistentProcessSessions",
     "independentControlCommands",
     "incrementalSessionOutput",
+    "concurrentSyncOperations",
+    "duplexCommandStream",
 ];
 /**
  * Opt-in capability keys. Most capabilities are a worker property: an absent
@@ -41,6 +48,8 @@ export const SANDBOX_CAPABILITY_KEYS = [
  */
 const SANDBOX_CAPABILITY_OPT_IN_KEYS = new Set([
     "incrementalSessionOutput",
+    "concurrentSyncOperations",
+    "duplexCommandStream",
 ]);
 /**
  * Verified prerequisite mapping: the worker methods each capability requires.
@@ -70,6 +79,17 @@ const SANDBOX_CAPABILITY_OPT_IN_KEYS = new Set([
  *   provider tails the session log through it. The verified verb is necessary
  *   but not sufficient: this key is opt-in, so the declaration is the real gate
  *   (see {@link SANDBOX_CAPABILITY_OPT_IN_KEYS}).
+ * - `concurrentSyncOperations` requires BOTH sync verbs, because parallel
+ *   bidirectional transfer runs an inbound and an outbound transfer at the same
+ *   time. The two verbs are separate required groups, so a provider that
+ *   verifies only one direction cannot get the capability. The verbs are
+ *   necessary but not sufficient: this key is opt-in, so the declaration is the
+ *   real gate (see {@link SANDBOX_CAPABILITY_OPT_IN_KEYS}).
+ * - `duplexCommandStream` requires `duplexChannelOpen`, the worker verb that
+ *   opens the persistent duplex channel. The verified verb is necessary but not
+ *   sufficient: this key is opt-in, so the declaration is the real gate. A
+ *   provider that does not implement the duplex open verb resolves `false` and
+ *   keeps the file bridge.
  */
 const SANDBOX_CAPABILITY_PREREQUISITE_METHODS = {
     // Reusable leases require ALL reuse verbs. Each verb is its own required
@@ -83,6 +103,8 @@ const SANDBOX_CAPABILITY_PREREQUISITE_METHODS = {
     persistentProcessSessions: [["environmentExecute"]],
     independentControlCommands: [["environmentExecute"]],
     incrementalSessionOutput: [["environmentExecute"]],
+    concurrentSyncOperations: [["environmentSyncIn"], ["environmentSyncOut"]],
+    duplexCommandStream: [["duplexChannelOpen"]],
 };
 function capabilityIsVerified(key, verifiedMethods) {
     return SANDBOX_CAPABILITY_PREREQUISITE_METHODS[key].every((group) => group.some((verb) => verifiedMethods.has(verb)));
@@ -108,28 +130,49 @@ export function builtinSandboxProviderVerifiedMethods(provider) {
     }
     return methods;
 }
+// `EnvironmentDriverCapabilitySupport` and `ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT`
+// now live in the dependency-leaf module `environment-driver-traits.ts`, next to
+// the other static per-driver traits. Re-export both names here so an existing
+// import of this module keeps resolving.
+export { ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT, } from "./environment-driver-traits.js";
+import { ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT } from "./environment-driver-traits.js";
 /**
- * The one normalizer for the sandbox capability contract. It resolves the
- * effective capability as verified ∩ declared ∩ narrowing.
+ * The one general capability classifier. It resolves each of the eight effective
+ * capabilities as static support ∩ verified ∩ declared ∩ narrowing, and returns
+ * the read-only eight-field snapshot. Every driver reads the same classifier, so
+ * the runtime no longer branches on the driver name.
  *
+ * - `supportedCapabilities` is the driver's static support definition (see
+ *   {@link ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT}). A capability not in the set
+ *   resolves `false` regardless of the other inputs. An absent set applies no
+ *   static gate, so the classifier behaves as the pure declaration ∩ verified ∩
+ *   narrowing normalizer.
  * - `verifiedMethods` is the runtime's verified worker verb list (the plug-in
  *   worker's `supportedMethods`, or a built-in provider mapped through
  *   {@link builtinSandboxProviderVerifiedMethods}). A missing or empty list
  *   verifies nothing, so every capability resolves `false` (fail closed).
  * - `declared` is the provider's declaration. An absent flag defers to the
- *   verified discovery baseline; it never grants a capability. A present flag
- *   can only remove a verified capability, never add one.
- * - `narrowing` is the per-target restriction from the config or lease. An
- *   absent key applies no restriction; a `false` value removes the capability.
+ *   verified discovery baseline for a worker-property capability; it never grants
+ *   an opt-in capability. A present flag can only remove a capability.
+ * - `narrowing` is the per-target restriction from the config or lease. An absent
+ *   key applies no restriction; a `false` value removes the capability.
  *
- * A declaration never grants a capability the runtime did not verify, so a
- * declared capability whose worker lacks a prerequisite verb resolves `false`.
+ * The two default rules stay intact. An absent declaration defers to the
+ * verified baseline for a worker-property capability. The three opt-in
+ * capabilities deny by default (see {@link SANDBOX_CAPABILITY_OPT_IN_KEYS}). A
+ * declaration never grants a capability the runtime did not verify.
  */
-export function resolveEffectiveSandboxCapabilities(input) {
+export function classifyEnvironmentCapabilities(input) {
     const verifiedMethods = new Set(input.verifiedMethods ?? []);
     const declared = input.declared ?? {};
     const narrowing = input.narrowing ?? {};
+    const supportedCapabilities = input.supportedCapabilities ?? null;
     const resolve = (key) => {
+        // The static support definition is the first gate. A capability the driver
+        // family cannot support resolves false, whatever the other inputs say. An
+        // absent set applies no static gate.
+        if (supportedCapabilities && !supportedCapabilities.has(key))
+            return false;
         const verified = capabilityIsVerified(key, verifiedMethods);
         // An absent declaration defers to the verified baseline for a worker-property
         // capability (true = no extra restriction), but denies an opt-in capability
@@ -147,6 +190,8 @@ export function resolveEffectiveSandboxCapabilities(input) {
         persistentProcessSessions: resolve("persistentProcessSessions"),
         independentControlCommands: resolve("independentControlCommands"),
         incrementalSessionOutput: resolve("incrementalSessionOutput"),
+        concurrentSyncOperations: resolve("concurrentSyncOperations"),
+        duplexCommandStream: resolve("duplexCommandStream"),
     };
 }
 /**
@@ -160,9 +205,9 @@ export function resolveEffectiveSandboxCapabilities(input) {
  *   which falls back for a `job` backend or a `nativeFileSyncUnsupported` lease).
  * - `configResolutionFailed` marks that the runtime could not resolve the
  *   provider config. A provider whose config cannot be resolved is untrusted, so
- *   the runtime fails closed and narrows `persistentProcessSessions` and
- *   `incrementalSessionOutput` to false. An empty config alone does not fail
- *   closed; only a resolution error does.
+ *   the runtime fails closed and narrows `persistentProcessSessions`,
+ *   `incrementalSessionOutput`, and `duplexCommandStream` to false. An empty
+ *   config alone does not fail closed; only a resolution error does.
  */
 export function buildSandboxCapabilityNarrowing(input) {
     const narrowing = {};
@@ -174,11 +219,15 @@ export function buildSandboxCapabilityNarrowing(input) {
     }
     if (input.configResolutionFailed === true) {
         // The runtime could not resolve the provider config, so it fails closed and
-        // denies persistent process sessions and incremental session output. The
-        // session-output streaming gate reads `incrementalSessionOutput`, so it must
-        // narrow with the persistent-session gate to keep the fail-closed behavior.
+        // denies persistent process sessions, incremental session output, and the
+        // duplex command stream. The session-output streaming gate reads
+        // `incrementalSessionOutput`, so it must narrow with the persistent-session
+        // gate to keep the fail-closed behavior. The duplex command stream opens a
+        // host-owned bidirectional channel, so an untrusted provider must not keep
+        // it either.
         narrowing.persistentProcessSessions = false;
         narrowing.incrementalSessionOutput = false;
+        narrowing.duplexCommandStream = false;
     }
     return narrowing;
 }
@@ -188,6 +237,14 @@ export function buildEnvironmentLeaseContext(input) {
         executionWorkspaceMode: input.persistedExecutionWorkspace?.mode ?? null,
     };
 }
+/**
+ * Map the experimental instance setting `enableSandboxDuplexBridge` into the
+ * per-run duplex bridge input. The setting is the kill switch. It defaults off,
+ * so an absent or false setting keeps the file bridge.
+ */
+export function resolveSandboxDuplexBridgeInput(experimental) {
+    return { enableDuplexBridge: experimental.enableSandboxDuplexBridge === true };
+}
 function stripSecretRefValuesFromPluginLeaseMetadata(input) {
     const sanitized = structuredClone(input.metadata ?? {});
     for (const path of collectSecretRefPaths(input.schema)) {
@@ -537,6 +594,15 @@ function createLocalEnvironmentDriver(db) {
                 },
             };
         },
+        async resolveCapabilities() {
+            // The local driver runs commands on the host file system with no
+            // provider capability model, so its static support definition names
+            // none of the eight capabilities. The classifier resolves every field
+            // `false` regardless of the other inputs, so this method needs none.
+            return classifyEnvironmentCapabilities({
+                supportedCapabilities: ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT.local.supportedCapabilities,
+            });
+        },
     };
 }
 function createSshEnvironmentDriver(db) {
@@ -593,6 +659,45 @@ function createSshEnvironmentDriver(db) {
                 },
             };
         },
+        async resolveCapabilities() {
+            // The SSH driver runs commands on a remote host through the SSH
+            // transport with no provider capability model, so it supports none of
+            // the eight capabilities either.
+            return classifyEnvironmentCapabilities({
+                supportedCapabilities: ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT.ssh.supportedCapabilities,
+            });
+        },
+    };
+}
+/**
+ * Adapt the worker manager's duplex host session to the cross-layer channel. The
+ * two shapes differ in the exit and stop members: the host session resolves the
+ * exit one time from `wait()`, so the channel bridges it to a one-time `onExit`
+ * listener; `kill()` maps to `stop()`. The `write`, `onData`, and `close`
+ * members map one to one.
+ */
+function adaptDuplexChannelHostSession(session) {
+    return {
+        write(data) {
+            session.write(data);
+        },
+        onData(listener) {
+            session.onData(listener);
+        },
+        onExit(listener) {
+            // `wait()` resolves one time with the exit and never rejects, so a single
+            // `then` bridges it to the one-time exit listener. The exit carries
+            // `transportClosed`, so the broker tells a real exit from a transport close.
+            void session.wait().then((exit) => {
+                listener(exit);
+            });
+        },
+        stop() {
+            session.kill();
+        },
+        close() {
+            return session.close();
+        },
     };
 }
 function createSandboxEnvironmentDriver(db, options = {}) {
@@ -1794,80 +1899,36 @@ function createSandboxEnvironmentDriver(db, options = {}) {
         async syncOut(input) {
             return await callPluginEnvironmentSync("environmentSyncOut", input);
         },
-        async effectiveSandboxCapabilities(input) {
-            const metadata = input.lease.metadata ?? {};
-            const providerKey = readString(metadata.provider) ??
-                (input.environment.driver === "sandbox"
-                    ? readString(parseEnvironmentDriverConfig(input.environment).config.provider)
-                    : null);
-            if (!providerKey) {
-                return resolveEffectiveSandboxCapabilities({ verifiedMethods: [], declared: null, narrowing: null });
-            }
-            let declared = null;
-            let verifiedMethods = [];
-            let configResolutionFailed = false;
-            if (metadata.sandboxProviderPlugin) {
-                const pluginId = readString(metadata.pluginId);
-                // Read the declaration from the exact plugin that acquired the lease,
-                // not the first installed plugin with this driver key. A driver key is
-                // only unique inside one manifest, so two plugins can share it. The
-                // by-key resolver could intersect this lease's verified methods with a
-                // different plugin's declaration. This resolver fails closed: it returns
-                // null when the pinned plugin id is absent, or when that exact plugin no
-                // longer declares this provider key with the `sandbox_provider` kind.
-                const resolvedDriver = pluginId
-                    ? await resolvePluginSandboxProviderDriverById({
-                        db,
-                        pluginId,
-                        driverKey: providerKey,
-                    })
-                    : null;
-                if (!pluginId || !resolvedDriver) {
-                    // Exact-plugin identity failure. The lease pins a plugin id, but the
-                    // id is missing, that plugin is absent, or it no longer declares this
-                    // provider key. Fail closed: resolve every effective capability to
-                    // false, no matter what methods a stale or running worker still
-                    // advertises. Do not read the worker methods here; passing them would
-                    // let an identity-less lease keep a verified baseline. This differs
-                    // from a valid plugin whose manifest merely omits
-                    // `sandboxCapabilities`: that case keeps `declared` null below and
-                    // defers to verified worker discovery.
-                    return resolveEffectiveSandboxCapabilities({
-                        verifiedMethods: [],
-                        declared: null,
-                        narrowing: null,
-                    });
-                }
-                verifiedMethods = pluginWorkerManager?.getWorker(pluginId)?.supportedMethods ?? [];
-                declared = resolveDeclaredSandboxCapabilities(resolvedDriver.driver);
-                try {
-                    // Resolve the provider config to confirm it is readable. A provider
-                    // whose config cannot be resolved is untrusted, so a resolution error
-                    // fails closed on persistent process sessions below. The resolved
-                    // value itself is no longer read for the narrowing decision.
-                    await resolvePluginSandboxRuntimeConfig({
-                        environment: input.environment,
-                        lease: input.lease,
-                        provider: providerKey,
-                    });
-                }
-                catch {
-                    configResolutionFailed = true;
-                }
+        async openDuplexChannel(input) {
+            // Plugin-backed sandbox providers only: open the host-owned duplex route on
+            // the plugin worker. The lease scope mirrors the sandbox execute path — the
+            // provider driver key, the company, the environment, and the provider lease
+            // id — so the route binds to the same worker session the runner streams.
+            if (!input.lease.metadata?.sandboxProviderPlugin || !pluginWorkerManager) {
+                throw new Error("Sandbox driver does not support duplex channels for this lease.");
             }
-            else {
-                const builtin = getBuiltinSandboxProvider(providerKey);
-                verifiedMethods = builtinSandboxProviderVerifiedMethods(builtin);
-                declared = resolveDeclaredSandboxCapabilities({
-                    supportsReusableLeases: builtin?.supportsReusableLeases,
-                });
+            const pluginId = readString(input.lease.metadata?.pluginId);
+            const providerKey = readString(input.lease.metadata?.provider);
+            const providerLeaseId = readString(input.lease.providerLeaseId);
+            if (!pluginId || !providerKey || !providerLeaseId) {
+                throw new Error("Sandbox duplex channel needs a plugin id, a provider key, and a provider lease id on the lease.");
             }
-            const narrowing = buildSandboxCapabilityNarrowing({
-                leasePolicy: input.lease.leasePolicy,
-                leaseMetadata: metadata,
-                configResolutionFailed,
-            });
-            return resolveEffectiveSandboxCapabilities({ verifiedMethods, declared, narrowing });
+            const worker = pluginWorkerManager.getWorker(pluginId);
+            if (!worker) {
+                throw new Error(`Plugin worker "${pluginId}" is not running for the duplex channel.`);
+            }
+            const managerInput = {
+                driverKey: providerKey,
+                companyId: input.lease.companyId,
+                environmentId: input.environment.id,
+                providerLeaseId,
+                command: input.command,
+            };
+            const session = await worker.openDuplexChannel(managerInput);
+            return adaptDuplexChannelHostSession(session);
+        },
+        async resolveCapabilities(input) {
+            return await resolveSandboxCapabilitiesForLease(input);
         },
         async destroyRunLease(input) {
             return await destroyReusableSandboxLease({
@@ -1877,6 +1938,102 @@ function createSandboxEnvironmentDriver(db, options = {}) {
             });
         },
     };
+    /**
+     * Resolve the effective capability snapshot for one sandbox lease. This is
+     * the sandbox driver's implementation of the general capability-resolution
+     * method: it gates through {@link ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT}'s
+     * `sandbox` support (the whole set, so this gate adds no restriction beyond
+     * declaration, verification, and narrowing), then reads the per-lease
+     * declaration, the live verified worker methods, and the per-lease
+     * narrowing, exactly as the runtime resolved them before this method
+     * existed.
+     */
+    async function resolveSandboxCapabilitiesForLease(input) {
+        const metadata = input.lease.metadata ?? {};
+        const providerKey = readString(metadata.provider) ??
+            (input.environment.driver === "sandbox"
+                ? readString(parseEnvironmentDriverConfig(input.environment).config.provider)
+                : null);
+        if (!providerKey) {
+            return classifyEnvironmentCapabilities({
+                verifiedMethods: [],
+                declared: null,
+                narrowing: null,
+                supportedCapabilities: ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT.sandbox.supportedCapabilities,
+            });
+        }
+        let declared = null;
+        let verifiedMethods = [];
+        let configResolutionFailed = false;
+        if (metadata.sandboxProviderPlugin) {
+            const pluginId = readString(metadata.pluginId);
+            // Read the declaration from the exact plugin that acquired the lease,
+            // not the first installed plugin with this driver key. A driver key is
+            // only unique inside one manifest, so two plugins can share it. The
+            // by-key resolver could intersect this lease's verified methods with a
+            // different plugin's declaration. This resolver fails closed: it returns
+            // null when the pinned plugin id is absent, or when that exact plugin no
+            // longer declares this provider key with the `sandbox_provider` kind.
+            const resolvedDriver = pluginId
+                ? await resolvePluginSandboxProviderDriverById({
+                    db,
+                    pluginId,
+                    driverKey: providerKey,
+                })
+                : null;
+            if (!pluginId || !resolvedDriver) {
+                // Exact-plugin identity failure. The lease pins a plugin id, but the
+                // id is missing, that plugin is absent, or it no longer declares this
+                // provider key. Fail closed: resolve every effective capability to
+                // false, no matter what methods a stale or running worker still
+                // advertises. Do not read the worker methods here; passing them would
+                // let an identity-less lease keep a verified baseline. This differs
+                // from a valid plugin whose manifest merely omits
+                // `sandboxCapabilities`: that case keeps `declared` null below and
+                // defers to verified worker discovery.
+                return classifyEnvironmentCapabilities({
+                    verifiedMethods: [],
+                    declared: null,
+                    narrowing: null,
+                    supportedCapabilities: ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT.sandbox.supportedCapabilities,
+                });
+            }
+            verifiedMethods = pluginWorkerManager?.getWorker(pluginId)?.supportedMethods ?? [];
+            declared = resolveDeclaredSandboxCapabilities(resolvedDriver.driver);
+            try {
+                // Resolve the provider config to confirm it is readable. A provider
+                // whose config cannot be resolved is untrusted, so a resolution error
+                // fails closed on persistent process sessions below. The resolved
+                // value itself is no longer read for the narrowing decision.
+                await resolvePluginSandboxRuntimeConfig({
+                    environment: input.environment,
+                    lease: input.lease,
+                    provider: providerKey,
+                });
+            }
+            catch {
+                configResolutionFailed = true;
+            }
+        }
+        else {
+            const builtin = getBuiltinSandboxProvider(providerKey);
+            verifiedMethods = builtinSandboxProviderVerifiedMethods(builtin);
+            declared = resolveDeclaredSandboxCapabilities({
+                supportsReusableLeases: builtin?.supportsReusableLeases,
+            });
+        }
+        const narrowing = buildSandboxCapabilityNarrowing({
+            leasePolicy: input.lease.leasePolicy,
+            leaseMetadata: metadata,
+            configResolutionFailed,
+        });
+        return classifyEnvironmentCapabilities({
+            verifiedMethods,
+            declared,
+            narrowing,
+            supportedCapabilities: ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT.sandbox.supportedCapabilities,
+        });
+    }
     /**
      * Verify that the live plugin worker still advertises a reusable-lease
      * lifecycle method before the runtime dispatches that RPC. The worker reports
@@ -2326,6 +2483,50 @@ function createPluginEnvironmentDriver(db, workerManager) {
                 },
             });
         },
+        async resolveCapabilities(input) {
+            const metadata = input.lease.metadata ?? {};
+            const pluginId = readString(metadata.pluginId);
+            const driverKey = readString(metadata.driverKey);
+            const noCapabilities = () => classifyEnvironmentCapabilities({
+                verifiedMethods: [],
+                declared: null,
+                narrowing: null,
+                supportedCapabilities: ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT.plugin.supportedCapabilities,
+            });
+            if (!pluginId || !driverKey) {
+                // The lease carries no plugin pin, so there is no exact plugin to read
+                // the declaration or the live worker methods from. Fail closed: resolve
+                // every capability false.
+                return noCapabilities();
+            }
+            // Read the declaration from the exact plugin that acquired the lease, not
+            // the plugin the environment's current config names. A plugin uninstall,
+            // a manifest change, or a config edit between the acquire and this call
+            // must not let a stale declaration or a different plugin's worker grant a
+            // capability this lease never verified.
+            const plugin = await pluginRegistry.getById(pluginId);
+            const declaredDriver = plugin && plugin.status === "ready"
+                ? plugin.manifestJson.environmentDrivers?.find((candidate) => candidate.driverKey === driverKey)
+                : undefined;
+            if (!plugin || plugin.status !== "ready" || !declaredDriver) {
+                return noCapabilities();
+            }
+            // Read the live worker method list fresh on every call. A worker restart
+            // can drop or add a method between the acquire and this call, so the
+            // runtime never trusts a cached method list for a capability grant.
+            const verifiedMethods = workerManager.getWorker(plugin.id)?.supportedMethods ?? [];
+            const declared = resolveDeclaredSandboxCapabilities(declaredDriver);
+            const narrowing = buildSandboxCapabilityNarrowing({
+                leasePolicy: input.lease.leasePolicy,
+                leaseMetadata: metadata,
+            });
+            return classifyEnvironmentCapabilities({
+                verifiedMethods,
+                declared,
+                narrowing,
+                supportedCapabilities: ENVIRONMENT_DRIVER_CAPABILITY_SUPPORT.plugin.supportedCapabilities,
+            });
+        },
     };
 }
 export function environmentRuntimeService(db, options = {}) {
@@ -2370,6 +2571,16 @@ export function environmentRuntimeService(db, options = {}) {
     }
     return {
         getDriver,
+        /**
+         * Read the sandbox duplex bridge kill switch for a new run. The host calls it
+         * per run before it selects the callback bridge transport. It reads the
+         * experimental instance setting `enableSandboxDuplexBridge` and maps it into
+         * the resolved bridge input. The default-off setting keeps the file bridge.
+         */
+        async readSandboxDuplexBridgeInput() {
+            const experimental = await instanceSettingsService(db).getExperimental();
+            return resolveSandboxDuplexBridgeInput(experimental);
+        },
         async acquireRunLease(input) {
             if (input.environment.status !== "active") {
                 throw new Error(`Environment "${input.environment.name}" is not active.`);
@@ -2530,6 +2741,113 @@ export function environmentRuntimeService(db, options = {}) {
             }
             return destroyed;
         },
+        /**
+         * Destroy every reusable sandbox lease still owned by one environment, so a
+         * consented environment delete can proceed. This must run while the
+         * environment row still exists: the driver resolves provider credentials
+         * from the environment config, and after the delete the normal destroy path
+         * has no context left. A per-lease failure is contained — the driver routes
+         * a failed teardown to `pending_cleanup` for the sweep, and an unexpected
+         * throw leaves the lease in place — so the caller re-checks the blast
+         * radius instead of trusting these counts for the delete decision.
+         */
+        async destroyReusableSandboxLeasesForEnvironment(input) {
+            const environment = await environmentsSvc.getById(input.environmentId);
+            if (!environment)
+                return { destroyed: 0, failed: 0, skippedLiveRun: 0 };
+            const leaseRows = await db
+                .select()
+                .from(environmentLeases)
+                .where(and(eq(environmentLeases.environmentId, input.environmentId), eq(environmentLeases.leasePolicy, "reuse_by_environment"), inArray(environmentLeases.status, ["active", "released", "retained"])));
+            // A lease whose holding run is still in flight keeps its sandbox: the
+            // consented delete must not tear a live run's environment out from under
+            // it. The skipped lease keeps blocking the delete, so the caller's
+            // blast-radius re-check rejects and the operator retries after the run
+            // finishes. A lease pointing at a finished run — or at no run — is a
+            // stale reservation and destroys normally.
+            const holdingRunIds = leaseRows
+                .map((row) => row.heartbeatRunId)
+                .filter((runId) => Boolean(runId));
+            const liveRunIds = new Set();
+            if (holdingRunIds.length > 0) {
+                const liveRuns = await db
+                    .select({ id: heartbeatRuns.id })
+                    .from(heartbeatRuns)
+                    .where(and(inArray(heartbeatRuns.id, holdingRunIds), inArray(heartbeatRuns.status, ["queued", "scheduled_retry", "running"])));
+                for (const run of liveRuns)
+                    liveRunIds.add(run.id);
+            }
+            let destroyed = 0;
+            let failed = 0;
+            let skippedLiveRun = 0;
+            const failureReason = input.failureReason ?? "environment_delete_requested";
+            const now = new Date();
+            for (const leaseRow of leaseRows) {
+                if (leaseRow.heartbeatRunId && liveRunIds.has(leaseRow.heartbeatRunId)) {
+                    skippedLiveRun += 1;
+                    continue;
+                }
+                // Claim the row BEFORE the provider call, mirroring the inline-teardown
+                // invariant used elsewhere in this file: no provider destroy without a
+                // durable `pending_cleanup` reference already on disk. The claim is one
+                // conditional UPDATE, so it is the fence against a racing resume: a
+                // resume that re-activates the lease first makes the status predicate
+                // (or the run-liveness predicate) fail and the claim loses — the live
+                // run keeps its sandbox. A claim that wins parks the lease where the
+                // cleanup sweep owns it, so a crash or thrown destroy after this point
+                // is recovered by the sweep's idempotent teardown, and a double write
+                // failure cannot strand the lease in a reusable status.
+                const claimedRow = await db
+                    .update(environmentLeases)
+                    .set({
+                    status: "pending_cleanup",
+                    failureReason,
+                    cleanupStatus: "failed",
+                    releasedAt: now,
+                    lastUsedAt: now,
+                    updatedAt: now,
+                })
+                    .where(and(eq(environmentLeases.id, leaseRow.id), inArray(environmentLeases.status, ["active", "released", "retained"]), sql `NOT EXISTS (
+                SELECT 1 FROM ${heartbeatRuns}
+                WHERE ${heartbeatRuns.id} = ${environmentLeases.heartbeatRunId}
+                  AND ${heartbeatRuns.status} IN ('queued', 'scheduled_retry', 'running')
+              )`))
+                    .returning()
+                    .then((rows) => rows[0] ?? null);
+                if (!claimedRow) {
+                    // Lost to a racing resume or a concurrent terminal transition — the
+                    // lease is no longer ours to destroy.
+                    skippedLiveRun += 1;
+                    continue;
+                }
+                const leaseSnapshot = toEnvironmentLeaseSnapshot(claimedRow);
+                try {
+                    const driver = getDriver(getLeaseDriverKey(leaseSnapshot, environment));
+                    if (!driver?.destroyRunLease) {
+                        // No driver available: the claim already parked the lease for the
+                        // sweep, which retries once the driver's plugin is back.
+                        failed += 1;
+                        continue;
+                    }
+                    const lease = await driver.destroyRunLease({
+                        environment,
+                        lease: leaseSnapshot,
+                        failureReason,
+                    });
+                    if (lease && lease.status !== "pending_cleanup")
+                        destroyed += 1;
+                    else
+                        failed += 1;
+                }
+                catch {
+                    // The claim above already parked the lease in `pending_cleanup`, so
+                    // the sweep owns the retry; its teardown is idempotent, so a destroy
+                    // that reached the provider before the throw resolves as success.
+                    failed += 1;
+                }
+            }
+            return { destroyed, failed, skippedLiveRun };
+        },
         async resumeRunLease(input) {
             const driver = requireDriverKey(getLeaseDriverKey(input.lease, input.environment));
             if (!driver.resumeRunLease) {
@@ -2562,9 +2880,18 @@ export function environmentRuntimeService(db, options = {}) {
             const driver = getDriver(getLeaseDriverKey(input.lease, input.environment));
             return driver?.supportsSync?.(input) ?? false;
         },
-        async effectiveSandboxCapabilities(input) {
+        /**
+         * Resolve the general per-lease capability snapshot through the driver's
+         * {@link EnvironmentRuntimeDriver.resolveCapabilities}. Every registered
+         * driver implements this method, so it returns a full snapshot for any
+         * registered driver. It returns `null` only when the lease's driver is
+         * not registered — never as a stand-in for "every capability denied".
+         */
+        async resolveCapabilities(input) {
             const driver = getDriver(getLeaseDriverKey(input.lease, input.environment));
-            return (await driver?.effectiveSandboxCapabilities?.(input)) ?? null;
+            if (!driver)
+                return null;
+            return await driver.resolveCapabilities(input);
         },
         async syncIn(input) {
             const driver = requireDriverKey(getLeaseDriverKey(input.lease, input.environment));
@@ -2580,6 +2907,24 @@ export function environmentRuntimeService(db, options = {}) {
             }
             return await driver.syncOut(input);
         },
+        async openDuplexChannel(input) {
+            const driver = requireDriverKey(getLeaseDriverKey(input.lease, input.environment));
+            if (!driver.openDuplexChannel) {
+                throw new Error(`Environment driver "${driver.driver}" does not support duplex channels.`);
+            }
+            // Centralize the duplex channel authorization here. Resolve the exact lease
+            // capability snapshot through the general resolver and refuse unless the
+            // effective snapshot grants the opt-in `duplexCommandStream` capability.
+            // This gate runs before the driver call, so an unauthorized lease never
+            // reaches the worker. The execution-target member gate stays as defense
+            // in depth. A driver that cannot resolve the snapshot fails closed with
+            // the fixed refusal.
+            const effective = await driver.resolveCapabilities(input);
+            if (effective.duplexCommandStream !== true) {
+                throw new Error(DUPLEX_CHANNEL_CAPABILITY_DENIED);
+            }
+            return await driver.openDuplexChannel(input);
+        },
     };
 }
 //# sourceMappingURL=environment-runtime.js.map