@tickernelz/wardmote-plugin-daytona 0.0.0 → 2026.1108.1

package/dist/plugin.js

@@ -0,0 +1,2930 @@
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { Daytona, DaytonaNotFoundError, DaytonaTimeoutError } from "@daytonaio/sdk";
+import { decodeChannelBytes, definePlugin, NOOP_PLUGIN_TRACER, PluginEnvironmentCreationCleanupError, readEnvironmentCreationCleanupError, withEnvironmentSyncTransferStep, preserveEnvironmentSyncErrorDiagnostic } from "@tickernelz/wardmote-plugin-sdk";
+import { performSyncIn, performSyncOut, withProviderSpan } from "./file-sync.js";
+import { DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS } from "./manifest.js";
+// The Claude `setup-token` login pseudo-terminal (PTY) session for this provider.
+// The session runs the login command on a real pseudo-terminal, streams the
+// terminal output, and delivers the delayed browser code plus the Enter byte. A
+// later phase binds the opener to `sandbox.process` and wraps it with the
+// `createLoginPtyTransport` factory from `@tickernelz/wardmote-adapter-utils` to
+// build the transport the login runner drives.
+export { createDaytonaLoginPtySessionOpener, openDaytonaLoginPtySession, createDaytonaLoginHomeFs, } from "./login-pty.js";
+import { openDaytonaLoginPtySession as openLoginPtySession, createDaytonaLoginHomeFs, } from "./login-pty.js";
+// The Daytona duplex command stream for the sandbox callback bridge. The channel
+// runs the gateway command on a raw pseudo-terminal, streams the frames, and
+// accepts host input. The worker resolves the sandbox by the provider lease id,
+// registers the channel under the host route id, and streams the data and the
+// exit through `ctx.duplexChannel`.
+export { createDaytonaDuplexChannelSessionOpener, openDaytonaDuplexChannelSession, buildDuplexChannelLaunchWrapper, } from "./duplex-command-stream.js";
+import { openDaytonaDuplexChannelSession as openDuplexChannelSession } from "./duplex-command-stream.js";
+// Injectable monotonic clock for provider-boundary timing (Open Q1). Defaults
+// to the real wall clock; `plugin.test.ts` overrides it via
+// `setDaytonaTimingClockForTest` so the measured `durationMs`/`getDurationMs`
+// are deterministic. The timing path never calls `Date.now()` directly.
+let timingNow = () => Date.now();
+// The plugin context, hoisted to a module variable in `setup(ctx)`. The
+// lifecycle hooks and the file-sync helpers have no closure over `ctx`, so they
+// read the tracer through `getPluginTracer()`. Before `setup` runs (or in a
+// test) the tracer is a no-op, so a span never throws.
+let pluginContext = null;
+// Provider deadlines and terminal close failures do not prove remote work
+// stopped. Until those paths provide complete cleanup receipts, only a worker
+// which has never contacted the provider can opt into automatic idle sleep.
+let providerUsed = false;
+/**
+ * Return the plugin tracer. It is the injected `ctx.tracer` after `setup`, or a
+ * no-op before it. A provider span opened through it records only when tracing
+ * is on and an active host trace context is present.
+ */
+export function getPluginTracer() {
+    return pluginContext?.tracer ?? NOOP_PLUGIN_TRACER;
+}
+/**
+ * Test seam: set the module-level plugin context, and return a restore function.
+ * `plugin.test.ts` uses it to inject a recording tracer without running `setup`.
+ */
+export function __setDaytonaPluginContextForTest(ctx) {
+    const previous = pluginContext;
+    pluginContext = ctx;
+    return () => {
+        pluginContext = previous;
+    };
+}
+/**
+ * Test seam: override the provider-timing clock and return a restore function.
+ * Not used in production, where the default wall clock always applies.
+ */
+export function setDaytonaTimingClockForTest(now) {
+    const previous = timingNow;
+    timingNow = now;
+    return () => {
+        timingNow = previous;
+    };
+}
+// Injectable clock for the handle cache's freshness bookkeeping, deliberately
+// kept separate from the provider-timing clock so tests can advance virtual time
+// past a lease's auto-stop interval without perturbing the `getDurationMs` /
+// `durationMs` measurements that ride on `timingNow`.
+let handleFreshnessNow = () => Date.now();
+/**
+ * Test seam: override the handle-cache freshness clock and return a restore
+ * function. Not used in production, where the default wall clock always applies.
+ */
+export function setDaytonaHandleFreshnessClockForTest(now) {
+    const previous = handleFreshnessNow;
+    handleFreshnessNow = now;
+    return () => {
+        handleFreshnessNow = previous;
+    };
+}
+const WORKSPACE_SENTINEL_RELATIVE_PATH = ".paperclip-runtime/reusable-sandbox-lease.json";
+// Quota-safety defaults (minutes). Daytona counts *stopped* sandboxes against
+// the storage quota; only *archived* sandboxes move to cold object storage and
+// stop counting. Without these, stopped/leaked sandboxes accumulate until the
+// org quota fills. We apply sane defaults so every sandbox eventually leaves the
+// quota on its own even when our own cleanup fails or never runs (crashed runs,
+// failed lease destroys, orphaned probes). All three stay overridable per
+// environment; an explicit 0/-1 in config is preserved.
+//
+// - autoStop: stop idle *running* sandboxes (frees CPU/RAM, starts the archive clock).
+// - autoArchive: archive *stopped* sandboxes so they leave the disk quota.
+// - autoDelete: backstop reaper for sandboxes nobody resumes.
+const DEFAULT_AUTO_STOP_INTERVAL_MINUTES = 15;
+const DEFAULT_AUTO_ARCHIVE_INTERVAL_MINUTES = 60;
+const DEFAULT_AUTO_DELETE_INTERVAL_MINUTES = 7 * 24 * 60; // 7 days
+// Sandboxes released with `archiveOnRelease` (test/probe runs) are archived so
+// operators can inspect them from the Daytona dashboard, then expired by
+// Daytona itself after this interval (counted from the stop that precedes the
+// archive) so debugging copies don't accumulate.
+const ARCHIVE_ON_RELEASE_AUTO_DELETE_MINUTES = 60;
+// Fail-fast cap for git network operations (push, fetch, pull, ls-remote, etc.)
+// so a stalled remote or missing credential never consumes the full 900 s adapter
+// RPC ceiling; callers always see an actionable error within this window.
+const GIT_NETWORK_TIMEOUT_MS = 120_000;
+// Per-call bound on the provider liveness read (`sandbox.refreshData()`). The
+// Daytona SDK gives this metadata read no timeout, so a silently unresponsive
+// sandbox connection leaves it pending with no error. The plugin then stalls
+// until the outer host-to-worker RPC backstop fires, which is a general ceiling,
+// not a fast, specific detector. This bound turns that silent hang into a fast,
+// clear error. It is configurable through `livenessTimeoutMs`; a value of 0 or
+// less disables the extra bound.
+const DEFAULT_LIVENESS_TIMEOUT_MS = 30_000;
+// Extra margin added to the SDK start/recover timeout when the plugin wraps
+// those lifecycle calls in its own per-call bound. The SDK call already carries
+// a `timeoutSeconds` deadline; the wrapper is a backstop for a connection-level
+// hang that the SDK deadline can miss. The margin lets the SDK deadline fire
+// first on a normal slow start, so the wrapper only fires on a true hang.
+const LIVENESS_START_TIMEOUT_MARGIN_MS = 5_000;
+// Noninteractive git credential defaults injected into every Daytona one-shot
+// command so that git operations never stall waiting for a terminal prompt.
+// Callers can override any of these via the env parameter.
+const NONINTERACTIVE_GIT_ENV = {
+    GIT_TERMINAL_PROMPT: "0",
+    GCM_INTERACTIVE: "Never",
+    GIT_ASKPASS: "echo",
+    SSH_ASKPASS: "echo",
+    SSH_ASKPASS_REQUIRE: "force",
+};
+const DEFAULT_SSH_ACCESS_MINUTES = 60;
+const DAYTONA_SSH_GATEWAY_HOST = "ssh.app.daytona.io";
+function parseOptionalString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function parseOptionalInteger(value) {
+    if (value == null || value === "")
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? Math.trunc(parsed) : null;
+}
+function parseOptionalNumber(value) {
+    if (value == null || value === "")
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function parseDriverConfig(raw) {
+    const timeoutMs = Number(raw.timeoutMs ?? DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS);
+    const livenessTimeoutMs = Number(raw.livenessTimeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS);
+    return {
+        apiKey: parseOptionalString(raw.apiKey),
+        apiUrl: parseOptionalString(raw.apiUrl),
+        target: parseOptionalString(raw.target),
+        snapshot: parseOptionalString(raw.snapshot),
+        image: parseOptionalString(raw.image),
+        language: parseOptionalString(raw.language),
+        timeoutMs: Number.isFinite(timeoutMs) ? Math.trunc(timeoutMs) : DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS,
+        livenessTimeoutMs: Number.isFinite(livenessTimeoutMs) ? Math.trunc(livenessTimeoutMs) : DEFAULT_LIVENESS_TIMEOUT_MS,
+        cpu: parseOptionalNumber(raw.cpu),
+        memory: parseOptionalNumber(raw.memory),
+        disk: parseOptionalNumber(raw.disk),
+        gpu: parseOptionalNumber(raw.gpu),
+        autoStopInterval: parseOptionalInteger(raw.autoStopInterval) ?? DEFAULT_AUTO_STOP_INTERVAL_MINUTES,
+        autoArchiveInterval: parseOptionalInteger(raw.autoArchiveInterval) ?? DEFAULT_AUTO_ARCHIVE_INTERVAL_MINUTES,
+        autoDeleteInterval: parseOptionalInteger(raw.autoDeleteInterval) ?? DEFAULT_AUTO_DELETE_INTERVAL_MINUTES,
+        reuseLease: raw.reuseLease === true,
+        archiveOnRelease: raw.archiveOnRelease === true,
+    };
+}
+function resolveApiKey(config) {
+    if (config.apiKey) {
+        return config.apiKey;
+    }
+    const envApiKey = process.env.DAYTONA_API_KEY?.trim() ?? "";
+    if (!envApiKey) {
+        throw new Error("Daytona sandbox environments require an API key in config or DAYTONA_API_KEY.");
+    }
+    return envApiKey;
+}
+function createDaytonaClient(config) {
+    providerUsed = true;
+    const clientConfig = {
+        apiKey: resolveApiKey(config),
+    };
+    if (config.apiUrl)
+        clientConfig.apiUrl = config.apiUrl;
+    if (config.target)
+        clientConfig.target = config.target;
+    return new Daytona(clientConfig);
+}
+function buildResources(config) {
+    if (config.cpu == null && config.memory == null && config.disk == null && config.gpu == null) {
+        return undefined;
+    }
+    return {
+        cpu: config.cpu ?? undefined,
+        memory: config.memory ?? undefined,
+        disk: config.disk ?? undefined,
+        gpu: config.gpu ?? undefined,
+    };
+}
+function buildCreateParams(config, labels) {
+    const base = {
+        labels,
+        language: config.language ?? undefined,
+        autoStopInterval: config.autoStopInterval ?? undefined,
+        autoArchiveInterval: config.autoArchiveInterval ?? undefined,
+        autoDeleteInterval: config.autoDeleteInterval ?? undefined,
+    };
+    if (config.image) {
+        return {
+            ...base,
+            image: config.image,
+            resources: buildResources(config),
+        };
+    }
+    return {
+        ...base,
+        snapshot: config.snapshot ?? undefined,
+    };
+}
+function hasResourceRequest(config) {
+    return config.cpu != null || config.memory != null || config.disk != null || config.gpu != null;
+}
+function validateResourceRequest(config) {
+    if (!hasResourceRequest(config) || config.image)
+        return null;
+    return "Daytona resource settings require image-backed sandbox creation; snapshot/default sandbox creation cannot override CPU, memory, disk, or GPU.";
+}
+function validateRuntimeResourceRequest(config) {
+    // A snapshot bakes in its own resource allocation, so resources are dropped at
+    // create time (see buildCreateParams) rather than failing the run when a custom
+    // image snapshot is layered over a base config that carries CPU/memory/disk/GPU.
+    if (!hasResourceRequest(config) || config.image || config.snapshot)
+        return null;
+    return "Daytona resource settings require image-backed sandbox creation; default sandbox creation cannot override CPU, memory, disk, or GPU.";
+}
+function buildSandboxLabels(input) {
+    return {
+        "paperclip-provider": "daytona",
+        "paperclip-company-id": input.companyId,
+        "paperclip-environment-id": input.environmentId,
+        "paperclip-reuse-lease": input.reuseLease ? "true" : "false",
+        ...(input.runId ? { "paperclip-run-id": input.runId } : {}),
+        ...(input.setupSessionId ? { "paperclip-setup-session-id": input.setupSessionId } : {}),
+        ...(input.purpose ? { "paperclip-purpose": input.purpose } : {}),
+    };
+}
+function toTimeoutSeconds(timeoutMs) {
+    return Math.max(1, Math.ceil(timeoutMs / 1000));
+}
+function resolveTimeoutMs(paramsTimeoutMs, config) {
+    return paramsTimeoutMs != null && Number.isFinite(paramsTimeoutMs) && paramsTimeoutMs > 0
+        ? Math.trunc(paramsTimeoutMs)
+        : config.timeoutMs;
+}
+function formatErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+    }
+    if (isRecord(value)) {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function isValidUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// A per-call liveness bound elapsed before the wrapped provider call returned.
+// The message names the operation and the bound so an operator sees at once
+// that the sandbox connection is unresponsive, not that the operation is slow.
+class SandboxLivenessTimeoutError extends Error {
+    constructor(operation, timeoutMs) {
+        super(`Daytona sandbox liveness call "${operation}" did not respond within ${timeoutMs} ms; `
+            + "the sandbox connection is unresponsive.");
+        this.name = "SandboxLivenessTimeoutError";
+    }
+}
+// Race a provider call against a per-call deadline. A value of 0 or less turns
+// the bound off and runs the call unwrapped. The timer is always cleared, so a
+// call that resolves before the deadline leaks no pending timer. A call that
+// never resolves stays pending after the deadline rejects, but it holds no
+// timer and produces no unhandled rejection.
+async function withLivenessTimeout(operation, timeoutMs, run) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return run();
+    }
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new SandboxLivenessTimeoutError(operation, timeoutMs)), timeoutMs);
+    });
+    try {
+        return await Promise.race([run(), deadline]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** A dead bridge must not prevent provider-level termination. Stop/delete is
+ * the receipt boundary; timing out this drain is never termination evidence. */
+async function drainSandboxBeforeTermination(sandbox, scope) {
+    const timeoutMs = Math.max(1, Math.min(scope.config.livenessTimeoutMs || 10_000, 10_000));
+    const steps = [
+        ["sandbox.activityDrain", () => sandboxHandleActivityGates.waitForIdle(scope)],
+        ["sandbox.sessionTeardown", () => teardownSession(sandbox, scope)],
+        ["sandbox.channelTeardown", () => closeDaytonaDuplexChannelsForLease(scope.providerLeaseId)],
+    ];
+    for (const [operation, action] of steps) {
+        try {
+            await withLivenessTimeout(operation, timeoutMs, action);
+        }
+        catch {
+            // Each cleanup is independent; one hung bridge must not retain other routes.
+            console.warn("Sandbox bridge cleanup failed; continuing provider termination.");
+        }
+    }
+}
+async function terminateAtProvider(scope, operation, action) {
+    const timeoutMs = scope.config.timeoutMs > 0 ? scope.config.timeoutMs : DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS;
+    return withLivenessTimeout(operation, timeoutMs + LIVENESS_START_TIMEOUT_MARGIN_MS, action);
+}
+async function ensureSandboxStarted(sandbox, timeoutSeconds) {
+    if (sandbox.state === "started")
+        return;
+    // Bound the lifecycle call just past its own SDK deadline. A normal slow start
+    // finishes within `timeoutSeconds`; only a connection-level hang the SDK
+    // deadline misses reaches this wrapper bound.
+    const startBoundMs = timeoutSeconds * 1_000 + LIVENESS_START_TIMEOUT_MARGIN_MS;
+    if (sandbox.state === "error") {
+        if (sandbox.recoverable) {
+            await withLivenessTimeout("sandbox.recover", startBoundMs, () => sandbox.recover(timeoutSeconds));
+            return;
+        }
+        throw new Error(`Daytona sandbox ${sandbox.id} is in an unrecoverable error state: ${sandbox.errorReason ?? "unknown error"}`);
+    }
+    await withLivenessTimeout("sandbox.start", startBoundMs, () => sandbox.start(timeoutSeconds));
+}
+function hasMissingSandboxContainer(sandbox) {
+    if (sandbox.state !== "error" || sandbox.recoverable !== false || typeof sandbox.errorReason !== "string")
+        return false;
+    if (typeof sandbox.id !== "string" || !sandbox.id)
+        return false;
+    return sandbox.errorReason ===
+        `not found: failed to inspect sandbox container ${sandbox.id}: Error response from daemon: No such container: ${sandbox.id}`;
+}
+async function resolveSandboxWorkingDirectory(sandbox, create = true) {
+    const root = (await sandbox.getWorkDir())?.trim()
+        || (await sandbox.getUserHomeDir())?.trim()
+        || "/home/daytona";
+    const remoteCwd = path.posix.join(root, "paperclip-workspace");
+    if (create)
+        await sandbox.fs.createFolder(remoteCwd, "755");
+    return remoteCwd;
+}
+async function detectSandboxShellCommand(sandbox, timeoutSeconds) {
+    try {
+        const result = await sandbox.process.executeCommand("if command -v bash >/dev/null 2>&1; then printf bash; else printf sh; fi", undefined, undefined, timeoutSeconds);
+        return result.result?.trim() === "bash" ? "bash" : "sh";
+    }
+    catch {
+        return "sh";
+    }
+}
+function parseProbeInteger(value) {
+    const trimmed = value?.trim() ?? "";
+    if (!/^\d+$/.test(trimmed)) {
+        return null;
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    return Number.isInteger(parsed) ? parsed : null;
+}
+function workspaceSentinelToken(input) {
+    if ((!input.config.reuseLease && !input.params.runId) || !input.params.agentId || (!input.params.executionWorkspaceId && !input.params.issueId)) {
+        return null;
+    }
+    return createHash("sha256")
+        .update(stableStringify({
+        provider: "daytona",
+        ...(!input.config.reuseLease ? { ephemeralRunId: input.params.runId, ephemeralProviderLeaseId: input.providerLeaseId } : {}),
+        companyId: input.params.companyId,
+        environmentId: input.params.environmentId,
+        agentId: input.params.agentId,
+        executionWorkspaceId: input.params.executionWorkspaceId,
+        ...(input.params.executionWorkspaceId ? {} : { projectlessIssueId: input.params.issueId }),
+        adapterType: input.params.adapterType ?? null,
+        image: input.config.image,
+        snapshot: input.config.snapshot,
+        target: input.config.target,
+        // Include resource-shaping inputs so changing the requested allocation
+        // expires old reusable leases and forces a fresh sandbox instead of
+        // reusing a previously provisioned (e.g. one-CPU) sandbox.
+        cpu: input.config.cpu,
+        memory: input.config.memory,
+        disk: input.config.disk,
+        gpu: input.config.gpu,
+    }))
+        .digest("hex");
+}
+function workspaceSentinelPath(remoteCwd) {
+    return path.posix.join(remoteCwd, WORKSPACE_SENTINEL_RELATIVE_PATH);
+}
+async function writeWorkspaceSentinel(input) {
+    const sentinelPath = workspaceSentinelPath(input.remoteCwd);
+    const token = workspaceSentinelToken({ params: input.params, config: input.config, providerLeaseId: input.sandbox.id });
+    if (!token) {
+        return { path: sentinelPath, token: null, result: "skipped" };
+    }
+    await input.sandbox.fs.createFolder(path.posix.dirname(sentinelPath), "755");
+    await input.sandbox.fs.uploadFile(Buffer.from(JSON.stringify({
+        version: 1,
+        token,
+        companyId: input.params.companyId,
+        environmentId: input.params.environmentId,
+        agentId: input.params.agentId,
+        executionWorkspaceId: input.params.executionWorkspaceId,
+        ...(input.params.executionWorkspaceId ? {} : { projectlessIssueId: input.params.issueId }),
+        adapterType: input.params.adapterType ?? null,
+        provider: "daytona",
+        writtenAt: new Date().toISOString(),
+    }, null, 2), "utf8"), sentinelPath, input.timeoutSeconds);
+    return { path: sentinelPath, token, result: "written",
+        ...(!input.config.reuseLease ? { runId: input.params.runId, providerLeaseId: input.sandbox.id } : {}) };
+}
+async function verifyWorkspaceSentinel(input) {
+    const metadataSentinel = isRecord(input.leaseMetadata?.workspaceSentinel)
+        ? input.leaseMetadata.workspaceSentinel
+        : null;
+    const sentinelPath = typeof metadataSentinel?.path === "string"
+        ? metadataSentinel.path
+        : workspaceSentinelPath(input.remoteCwd);
+    const binding = typeof metadataSentinel?.runId === "string" && typeof metadataSentinel?.providerLeaseId === "string"
+        ? { runId: metadataSentinel.runId, providerLeaseId: metadataSentinel.providerLeaseId } : {};
+    const expectedToken = typeof metadataSentinel?.token === "string" ? metadataSentinel.token : null;
+    if (!expectedToken) {
+        return { path: sentinelPath, token: null, result: "missing" };
+    }
+    const result = await input.sandbox.process.executeCommand(`cat ${shellQuote(sentinelPath)}`, undefined, undefined, input.timeoutSeconds);
+    if (result.exitCode !== 0) {
+        return { path: sentinelPath, token: expectedToken, result: "missing" };
+    }
+    try {
+        const parsed = JSON.parse(result.result ?? result.artifacts?.stdout ?? "");
+        const actualToken = isRecord(parsed) && typeof parsed.token === "string" ? parsed.token : null;
+        return {
+            path: sentinelPath,
+            token: expectedToken,
+            ...binding,
+            result: actualToken === expectedToken ? "matched" : "mismatch",
+        };
+    }
+    catch {
+        return { path: sentinelPath, token: expectedToken, result: "mismatch" };
+    }
+}
+function leaseMetadata(input) {
+    return {
+        provider: "daytona",
+        shellCommand: input.shellCommand,
+        sandboxId: input.sandbox.id,
+        sandboxName: input.sandbox.name,
+        sandboxState: input.sandboxState ?? input.sandbox.state ?? null,
+        image: input.config.image,
+        snapshot: input.config.snapshot,
+        target: input.sandbox.target,
+        timeoutMs: input.config.timeoutMs,
+        reuseLease: input.config.reuseLease,
+        // Persisted so the release path (which rebuilds config from lease
+        // metadata) still knows to archive instead of delete.
+        ...(input.config.archiveOnRelease ? { archiveOnRelease: true } : {}),
+        remoteCwd: input.remoteCwd,
+        resumedLease: input.resumedLease,
+        ...(input.resumedLease
+            ? { resumedFromState: input.resumedFromState ?? null }
+            : {}),
+        // Record the resources Paperclip attempted to request so future diagnosis
+        // can compare requested allocation against what Daytona provisioned.
+        ...(input.config.cpu != null ? { cpu: input.config.cpu } : {}),
+        ...(input.config.memory != null ? { memory: input.config.memory } : {}),
+        ...(input.config.disk != null ? { disk: input.config.disk } : {}),
+        ...(input.config.gpu != null ? { gpu: input.config.gpu } : {}),
+        ...(input.workspaceSentinel ? { workspaceSentinel: input.workspaceSentinel } : {}),
+    };
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function resolveConnectionExpiresInMinutes(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return DEFAULT_SSH_ACCESS_MINUTES;
+    return Math.min(24 * 60, Math.max(1, Math.trunc(value)));
+}
+function expiresAtForMinutes(minutes) {
+    return new Date(Date.now() + minutes * 60_000).toISOString();
+}
+// Configure a provider-side time-to-live so Daytona destroys the sandbox at or
+// before the caller-requested deadline, even after a Paperclip crash or outage.
+// `setTtl` counts wall-clock time regardless of the sandbox state, so the destroy
+// happens even when the sandbox is stopped, paused, or archived. The function
+// returns the real provider destroy time (`autoDestroyAt`) as evidence of the
+// provider-side bound. It returns null when the caller sets no deadline, when the
+// deadline is invalid, or when the deadline is less than one minute away (Daytona
+// TTL granularity is one minute, so a nearer deadline maps to no valid TTL). The
+// server then fails closed on a null expiry and releases the lease.
+async function configureSandboxExpiry(input) {
+    const requestedMs = input.requestedExpiresAt ? Date.parse(input.requestedExpiresAt) : Number.NaN;
+    if (!Number.isFinite(requestedMs))
+        return null;
+    // Round DOWN so the provider destroy time never lands after the deadline.
+    const ttlMinutes = Math.floor((requestedMs - input.nowMs) / 60_000);
+    if (ttlMinutes < 1)
+        return null;
+    await input.sandbox.setTtl(ttlMinutes);
+    await input.sandbox.refreshData();
+    const autoDestroyAt = input.sandbox.autoDestroyAt;
+    return typeof autoDestroyAt === "string" && autoDestroyAt.trim().length > 0
+        ? autoDestroyAt.trim()
+        : null;
+}
+function sanitizeSnapshotName(value, fallback) {
+    const cleaned = (value ?? fallback)
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 96);
+    return cleaned || fallback;
+}
+function withSetupSourceTemplate(config, params) {
+    if (!params.sourceTemplateRef)
+        return config;
+    const sourceKind = params.sourceTemplateKind ?? "snapshot";
+    if (sourceKind === "image") {
+        return {
+            ...config,
+            image: params.sourceTemplateRef,
+            snapshot: null,
+        };
+    }
+    if (sourceKind !== "snapshot") {
+        throw new Error(`Daytona interactive setup can start from image or snapshot templates only, not ${sourceKind}.`);
+    }
+    return {
+        ...config,
+        snapshot: params.sourceTemplateRef,
+        image: null,
+    };
+}
+async function createSshConnection(sandbox, expiresInMinutes) {
+    const createSshAccess = sandbox.createSshAccess;
+    if (typeof createSshAccess !== "function") {
+        throw new Error("Daytona interactive setup requires @daytonaio/sdk Sandbox.createSshAccess support.");
+    }
+    const fallbackExpiresAt = expiresAtForMinutes(expiresInMinutes);
+    const access = await createSshAccess.call(sandbox, expiresInMinutes);
+    const token = typeof access.token === "string" && access.token.trim().length > 0
+        ? access.token.trim()
+        : null;
+    const commandFromAccess = typeof access.command === "string" && access.command.trim().length > 0
+        ? access.command.trim()
+        : typeof access.sshCommand === "string" && access.sshCommand.trim().length > 0
+            ? access.sshCommand.trim()
+            : null;
+    const command = commandFromAccess ?? (token ? `ssh ${token}@${DAYTONA_SSH_GATEWAY_HOST}` : null);
+    if (!command) {
+        throw new Error("Daytona SSH access did not return a token or SSH command.");
+    }
+    const expiresAt = typeof access.expiresAt === "string" && access.expiresAt.trim().length > 0
+        ? access.expiresAt.trim()
+        : fallbackExpiresAt;
+    return {
+        connectionSummary: {
+            type: "ssh",
+            username: "token",
+            hostRedacted: true,
+            portRedacted: true,
+            commandRedacted: true,
+            expiresAt,
+            metadata: {
+                provider: "daytona",
+                expiresInMinutes,
+            },
+        },
+        connectionPayload: {
+            type: "ssh",
+            command,
+            token,
+            expiresAt,
+            metadata: {
+                provider: "daytona",
+                sensitive: true,
+            },
+        },
+    };
+}
+function interactiveSetupMetadata(input) {
+    return {
+        provider: "daytona",
+        sandboxId: input.sandbox.id,
+        sandboxState: input.sandbox.state ?? null,
+        shellCommand: input.shellCommand,
+        imageConfigured: Boolean(input.config.image),
+        snapshotConfigured: Boolean(input.config.snapshot),
+        sourceTemplateRefRedacted: Boolean(input.sourceTemplateRef),
+        target: input.sandbox.target,
+        timeoutMs: input.config.timeoutMs,
+        remoteCwd: input.remoteCwd,
+        connectionRedacted: true,
+    };
+}
+function isValidShellEnvKey(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+const GIT_NETWORK_SUBCOMMANDS = new Set(["push", "fetch", "pull", "ls-remote", "clone"]);
+function isGitNetworkCommand(command, args) {
+    if (path.basename(command) !== "git")
+        return false;
+    // Find the first positional arg (the git subcommand), skipping flags and their values.
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "-C" || arg === "-c" || arg === "--git-dir" || arg === "--work-tree") {
+            i += 2;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            i++;
+            continue;
+        }
+        if (GIT_NETWORK_SUBCOMMANDS.has(arg))
+            return true;
+        if (arg === "remote") {
+            const next = args.slice(i + 1).find(a => !a.startsWith("-"));
+            return next === "update";
+        }
+        if (arg === "submodule") {
+            const next = args.slice(i + 1).find(a => !a.startsWith("-"));
+            return next === "update";
+        }
+        return false;
+    }
+    return false;
+}
+// Build the one-shot exec command. Daytona's `executeCommand` runs the script
+// in a non-login shell, so it does not source `/etc/profile` on its own. The
+// Daytona reference image puts `node`, `claude`, and the other CLIs on the PATH
+// through `/etc/profile.d/00-restore-env.sh`, which only `/etc/profile` sources.
+// So the wrapper sources the login profiles itself; a non-login shell is then
+// enough to resolve the CLIs. The wrapper no longer sources `nvm.sh`; the
+// sandbox image supplies `node` on the PATH. See the sandbox runtime
+// requirements document.
+function buildLoginShellScript(input) {
+    const callerEnv = input.env ?? {};
+    for (const key of Object.keys(callerEnv)) {
+        if (!isValidShellEnvKey(key)) {
+            throw new Error(`Invalid sandbox environment variable key: ${key}`);
+        }
+    }
+    // Caller env takes priority over noninteractive git credential defaults
+    const env = { ...NONINTERACTIVE_GIT_ENV, ...callerEnv };
+    const envArgs = Object.entries(env)
+        .filter((entry) => typeof entry[1] === "string")
+        .map(([key, value]) => `${key}=${shellQuote(value)}`);
+    const commandParts = [shellQuote(input.command), ...input.args.map(shellQuote)].join(" ");
+    const redirectedCommand = input.stdinPath
+        ? `${commandParts} < ${shellQuote(input.stdinPath)}`
+        : commandParts;
+    // Each `executeCommand` call runs in its own shell, so we don't `exec`-
+    // replace it; running the command as the last `&&`-chained line is enough to
+    // surface the right exit code.
+    const finalLine = envArgs.length > 0
+        ? `env ${envArgs.join(" ")} ${redirectedCommand}`
+        : redirectedCommand;
+    const lines = [
+        'if [ -f /etc/profile ]; then . /etc/profile >/dev/null 2>&1 || true; fi',
+        'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',
+        // .bash_profile typically sources .bashrc itself; only source .bashrc
+        // directly when no .bash_profile exists to avoid double-running setup.
+        'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; elif [ -f "$HOME/.bashrc" ]; then . "$HOME/.bashrc" >/dev/null 2>&1 || true; fi',
+        'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',
+    ];
+    if (input.cwd) {
+        lines.push(`cd ${shellQuote(input.cwd)}`);
+    }
+    lines.push(finalLine);
+    return lines.join(" && ");
+}
+// The workspace remote dir is the confinement root for native file sync. It is
+// recorded on the lease metadata at acquire/resume time; require it so a sync can
+// never run without a concrete root to confine every sandbox path against.
+function resolveSyncRemoteDir(lease) {
+    const remoteCwd = lease.metadata?.remoteCwd;
+    if (typeof remoteCwd === "string" && remoteCwd.trim().length > 0) {
+        return remoteCwd.trim();
+    }
+    throw new Error("Daytona file sync requires a workspace remote dir on the lease metadata.");
+}
+async function createSandbox(params, config, options = {}) {
+    const resourceRequestError = validateRuntimeResourceRequest(config);
+    if (resourceRequestError) {
+        throw new Error(resourceRequestError);
+    }
+    const client = createDaytonaClient(config);
+    // The SDK can create a sandbox and then throw while waiting for it to start.
+    // Keep an attempt-specific provider name so that failure cannot lose ownership.
+    const attemptId = randomUUID();
+    const name = `paperclip-create-${attemptId}`;
+    const labels = { ...buildSandboxLabels({
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            runId: "runId" in params ? params.runId : undefined,
+            setupSessionId: "sessionId" in params ? params.sessionId : undefined,
+            purpose: options.purpose,
+            reuseLease: config.reuseLease,
+        }), "paperclip-create-attempt": attemptId };
+    // The SDK mutates params.labels (for example, code-toolbox-language).
+    // Preserve our immutable ownership snapshot for validation and retry.
+    const createParams = { ...buildCreateParams(config, { ...labels }), name };
+    const cleanup = {
+        providerLeaseId: name, companyId: params.companyId, environmentId: params.environmentId,
+        ...("runId" in params ? { runId: params.runId } : {}),
+        attemptId, labels, accountFingerprint: sandboxAccountDiscriminator(config),
+    };
+    options.onCreateAttempt?.(cleanup);
+    try {
+        return await client.create(createParams, {
+            timeout: toTimeoutSeconds(config.timeoutMs),
+        });
+    }
+    catch (createError) {
+        // Observe the create failure before compensating deletion can stall or fail.
+        const diagnostic = options.onCreateFailure?.();
+        try {
+            // A not-found lookup after an uncertain create is not a deletion receipt:
+            // the provider may still materialize the request. Keep the name in the
+            // error so cleanup can be reconciled rather than declaring success.
+            await destroyFailedCreation(config, cleanup);
+        }
+        catch (cleanupError) {
+            throw new PluginEnvironmentCreationCleanupError([createError, cleanupError], `Daytona sandbox creation failed; cleanup could not be confirmed for ${name}`, cleanup, diagnostic);
+        }
+        throw createError;
+    }
+}
+// Resolve by the immutable creation name, not through the admitted-lease cache:
+// the SDK's returned sandbox ID differs from this provisional name. Persist a
+// verified provider ID before host-driven deletion. Its later absence is then
+// conclusive, even if the deletion receipt or database update was lost.
+async function destroyFailedCreation(config, cleanup, requireDurableObservation = false) {
+    if (cleanup.providerLeaseId !== `paperclip-create-${cleanup.attemptId}` ||
+        cleanup.accountFingerprint !== sandboxAccountDiscriminator(config) ||
+        cleanup.labels["paperclip-provider"] !== "daytona" ||
+        cleanup.labels["paperclip-create-attempt"] !== cleanup.attemptId ||
+        cleanup.labels["paperclip-company-id"] !== cleanup.companyId ||
+        cleanup.labels["paperclip-environment-id"] !== cleanup.environmentId ||
+        (cleanup.runId !== undefined && cleanup.labels["paperclip-run-id"] !== cleanup.runId)) {
+        throw new Error("Failed-create sandbox ownership does not match");
+    }
+    const client = createDaytonaClient(config);
+    let orphan;
+    try {
+        orphan = await withLivenessTimeout("sandbox.failedCreateLookup", 10_000, () => client.get(cleanup.observedProviderLeaseId ?? cleanup.providerLeaseId));
+    }
+    catch (error) {
+        // A name that has never been observed may still materialize. An ID already
+        // observed with exact ownership cannot materialize as a new allocation.
+        if (cleanup.observedProviderLeaseId && error instanceof DaytonaNotFoundError)
+            return;
+        throw error;
+    }
+    if ((cleanup.observedProviderLeaseId && orphan.id !== cleanup.observedProviderLeaseId) ||
+        orphan.name !== cleanup.providerLeaseId || Object.entries(cleanup.labels).some(([key, value]) => orphan.labels?.[key] !== value)) {
+        throw new Error("Failed-create sandbox ownership does not match");
+    }
+    if (!cleanup.observedProviderLeaseId) {
+        cleanup.observedProviderLeaseId = orphan.id;
+        if (requireDurableObservation) {
+            // No destructive call yet: the host journals the observation and retries.
+            throw new PluginEnvironmentCreationCleanupError([], "Persist observed sandbox identity before cleanup", cleanup);
+        }
+    }
+    await withLivenessTimeout("sandbox.failedCreateDelete", 15_000, () => orphan.delete(10, true));
+}
+// Non-secret provider/account fingerprint. Uses the *resolved* key (config or
+// DAYTONA_API_KEY env fallback) so an env-provided credential is still scoped,
+// but only its sha256 digest — never the key itself — enters the cache key (C1/C6).
+function sandboxAccountDiscriminator(config) {
+    const resolvedApiKey = config.apiKey ?? process.env.DAYTONA_API_KEY?.trim() ?? null;
+    return createHash("sha256")
+        .update(stableStringify({
+        apiUrl: config.apiUrl,
+        // Target is a creation placement hint, not account identity: the SDK
+        // resolves existing sandboxes by ID. Lease metadata fills an omitted
+        // target with the actual region, which must not split admission state.
+        apiKey: resolvedApiKey,
+    }))
+        .digest("hex");
+}
+function sandboxHandleCacheKey(scope) {
+    return stableStringify({
+        driverKey: scope.driverKey,
+        companyId: scope.companyId,
+        environmentId: scope.environmentId,
+        providerLeaseId: scope.providerLeaseId,
+        account: sandboxAccountDiscriminator(scope.config),
+    });
+}
+function assertHandleMatchesLease(sandbox, providerLeaseId) {
+    // C2: a handle must never stand in for a different sandbox than the lease
+    // asked for. Belt-and-suspenders against a provider that returns a renamed or
+    // substituted sandbox, and against any future key collision.
+    if (sandbox.id !== providerLeaseId) {
+        throw new Error(`Daytona sandbox handle mismatch: handle ${sandbox.id} does not belong to lease ${providerLeaseId}.`);
+    }
+}
+// A cached `Sandbox` carries the provider state captured when it was last
+// fetched/refreshed. Daytona auto-stops an idle sandbox after `autoStopInterval`
+// minutes, at which point that snapshot ("started") no longer matches reality
+// and `ensureSandboxStarted` would wrongly skip the restart, sending every
+// subsequent exec/sync at a stopped sandbox. Before reusing a handle that has
+// gone untouched for this fraction of the auto-stop interval we re-read the live
+// state so the restart decision is made against the truth. Reusing a handle for
+// an operation resets Daytona's idle clock, so an actively-used lease stays well
+// inside the window and never pays the refresh — only a lease resumed after an
+// idle gap does.
+const STALE_HANDLE_REFRESH_SAFETY_FRACTION = 0.5;
+function staleHandleRefreshThresholdMs(autoStopIntervalMinutes) {
+    // Auto-stop disabled (0 / null): the provider never stops the sandbox out from
+    // under a live handle, so the started snapshot stays valid until we evict it
+    // and no refresh is warranted.
+    if (autoStopIntervalMinutes == null || autoStopIntervalMinutes <= 0)
+        return null;
+    return Math.floor(autoStopIntervalMinutes * 60_000 * STALE_HANDLE_REFRESH_SAFETY_FRACTION);
+}
+const sandboxHandleTeardownGates = (() => {
+    const gates = new Map();
+    function begin(scope) {
+        const key = sandboxHandleCacheKey(scope);
+        const existing = gates.get(key);
+        if (existing) {
+            existing.refCount += 1;
+            return existing;
+        }
+        let release;
+        const gate = {
+            promise: new Promise((resolve) => {
+                release = resolve;
+            }),
+            release: () => release(),
+            refCount: 1,
+        };
+        gates.set(key, gate);
+        return gate;
+    }
+    function current(scope) {
+        return gates.get(sandboxHandleCacheKey(scope)) ?? null;
+    }
+    function end(scope, gate) {
+        const key = sandboxHandleCacheKey(scope);
+        gate.refCount -= 1;
+        if (gate.refCount > 0)
+            return;
+        if (gates.get(key) === gate) {
+            gates.delete(key);
+        }
+        gate.release();
+    }
+    function reset() {
+        gates.clear();
+    }
+    return { begin, current, end, reset };
+})();
+const sandboxHandleActivityGates = (() => {
+    const gates = new Map();
+    async function begin(scope) {
+        const key = sandboxHandleCacheKey(scope);
+        const existing = gates.get(key);
+        if (existing) {
+            existing.refCount += 1;
+            return existing;
+        }
+        let release;
+        const gate = {
+            promise: new Promise((resolve) => {
+                release = resolve;
+            }),
+            release: () => release(),
+            refCount: 1,
+        };
+        gates.set(key, gate);
+        return gate;
+    }
+    async function waitForIdle(scope) {
+        const gate = gates.get(sandboxHandleCacheKey(scope));
+        if (!gate)
+            return;
+        await gate.promise;
+    }
+    function end(scope, gate) {
+        const key = sandboxHandleCacheKey(scope);
+        gate.refCount -= 1;
+        if (gate.refCount > 0)
+            return;
+        if (gates.get(key) === gate) {
+            gates.delete(key);
+        }
+        gate.release();
+    }
+    function reset() {
+        gates.clear();
+    }
+    function isActive(scope) {
+        return gates.has(sandboxHandleCacheKey(scope));
+    }
+    return { begin, waitForIdle, isActive, end, reset };
+})();
+const sandboxHandleLeaseAdmissionStates = (() => {
+    const states = new Map();
+    function key(scope) {
+        return sandboxHandleCacheKey(scope);
+    }
+    function open(scope) {
+        states.set(key(scope), false);
+    }
+    function close(scope) {
+        states.set(key(scope), true);
+    }
+    function isClosed(scope) {
+        return states.get(key(scope)) === true;
+    }
+    function reset() {
+        states.clear();
+    }
+    return { open, close, isClosed, reset };
+})();
+async function withSandboxActivityGate(scope, fn, options = {}) {
+    while (true) {
+        if (!options.allowClosed && sandboxHandleLeaseAdmissionStates.isClosed(scope)) {
+            throw new Error(`Daytona sandbox lease ${scope.providerLeaseId} is no longer active.`);
+        }
+        const teardownGate = sandboxHandleTeardownGates.current(scope);
+        if (teardownGate) {
+            await teardownGate.promise;
+            if (!options.allowClosed && sandboxHandleLeaseAdmissionStates.isClosed(scope)) {
+                throw new Error(`Daytona sandbox lease ${scope.providerLeaseId} is no longer active.`);
+            }
+            continue;
+        }
+        const activityGate = await sandboxHandleActivityGates.begin(scope);
+        try {
+            // A teardown can still begin between the initial check above and the
+            // activity-gate admission. If that happens, back out and wait for the
+            // teardown to finish instead of proceeding into a race with cleanup.
+            if (sandboxHandleTeardownGates.current(scope)) {
+                continue;
+            }
+            if (!options.allowClosed && sandboxHandleLeaseAdmissionStates.isClosed(scope)) {
+                throw new Error(`Daytona sandbox lease ${scope.providerLeaseId} is no longer active.`);
+            }
+            return await fn();
+        }
+        finally {
+            sandboxHandleActivityGates.end(scope, activityGate);
+        }
+    }
+}
+const sandboxHandleCache = (() => {
+    const entries = new Map();
+    function markFresh(scope) {
+        const entry = entries.get(sandboxHandleCacheKey(scope));
+        if (entry) {
+            entry.verifiedAtMs = handleFreshnessNow();
+        }
+    }
+    async function get(scope, options = {}) {
+        const key = sandboxHandleCacheKey(scope);
+        const entry = entries.get(key);
+        if (entry) {
+            // The warm handle cache holds an entry, so this lookup serves the handle
+            // without a `client.get` round trip. Report the cache decision now.
+            options.onCacheDecision?.(true);
+            const sandbox = await entry.sandbox;
+            // Re-assert on every hit; evict + fail closed on any mismatch (C2).
+            try {
+                assertHandleMatchesLease(sandbox, scope.providerLeaseId);
+            }
+            catch (error) {
+                entries.delete(key);
+                throw error;
+            }
+            // Refresh the live provider state if the handle may have been auto-stopped
+            // since we last confirmed it, so the cached `state` snapshot can't hide a
+            // provider-initiated stop from `ensureSandboxStarted`. A failed refresh
+            // means the handle is no longer trustworthy — evict and fail closed.
+            const thresholdMs = staleHandleRefreshThresholdMs(scope.config.autoStopInterval);
+            if (thresholdMs != null && handleFreshnessNow() - entry.verifiedAtMs >= thresholdMs) {
+                try {
+                    await withLivenessTimeout("sandbox.refreshData", scope.config.livenessTimeoutMs, () => sandbox.refreshData());
+                }
+                catch (error) {
+                    entries.delete(key);
+                    throw error;
+                }
+            }
+            return sandbox;
+        }
+        // The warm handle cache holds no entry, so this lookup calls `client.get`.
+        // Report the cache decision now, before the single-flight populate.
+        options.onCacheDecision?.(false);
+        // Single-flight: the first miss stores the in-flight promise under the
+        // composite key so concurrent misses on the same lease share one `client.get`
+        // instead of double-fetching. The promise lives only under this key (C5).
+        const populate = (async () => {
+            const client = createDaytonaClient(scope.config);
+            const sandbox = await client.get(scope.providerLeaseId);
+            assertHandleMatchesLease(sandbox, scope.providerLeaseId);
+            return sandbox;
+        })();
+        const populated = { sandbox: populate, verifiedAtMs: handleFreshnessNow() };
+        entries.set(key, populated);
+        try {
+            const sandbox = await populate;
+            return sandbox;
+        }
+        catch (error) {
+            // A rejected populate (NotFound, network, id mismatch) must never remain
+            // cached (C4/C5). Guard against clobbering a newer entry under the key.
+            if (entries.get(key) === populated) {
+                entries.delete(key);
+            }
+            throw error;
+        }
+    }
+    // Seed the cache with a handle the caller already holds (e.g. the fresh handle
+    // from `createSandbox` on a cold acquire), so the next `get` under the same
+    // scope reuses it instead of paying a real `client.get`. The seed must land
+    // under the exact composite key the reader uses, or the reader misses and the
+    // saved round trip is lost. Assert the handle belongs to the lease so a caller
+    // that builds a wrong scope fails loudly here instead of caching a foreign
+    // handle.
+    function seed(scope, sandbox) {
+        assertHandleMatchesLease(sandbox, scope.providerLeaseId);
+        entries.set(sandboxHandleCacheKey(scope), {
+            sandbox: Promise.resolve(sandbox),
+            verifiedAtMs: handleFreshnessNow(),
+        });
+    }
+    function clear(scope) {
+        entries.delete(sandboxHandleCacheKey(scope));
+    }
+    function reset() {
+        entries.clear();
+    }
+    // Resolve a cached sandbox by its provider lease id alone. The
+    // login pseudo-terminal open carries only the provider lease id, not the full
+    // scope, so this scans the cached handles for the one whose `sandbox.id`
+    // matches. The lease was cached on acquire in the same worker, so the scan is
+    // a hit for a live login lease. It returns null when no cached handle matches,
+    // so the caller fails closed.
+    async function findByProviderLeaseId(providerLeaseId) {
+        if (!providerLeaseId)
+            return null;
+        for (const entry of entries.values()) {
+            let sandbox;
+            try {
+                sandbox = await entry.sandbox;
+            }
+            catch {
+                continue;
+            }
+            if (sandbox.id === providerLeaseId)
+                return sandbox;
+        }
+        return null;
+    }
+    return { get, seed, clear, reset, markFresh, findByProviderLeaseId };
+})();
+// Preview credentials can rotate without a sandbox restart, so they must not
+// define endpoint generation. Daytona's lifecycle revision does: refreshData
+// updates `updatedAt` after stop/start. When Daytona does not expose a
+// lifecycle revision, the in-memory generation remains stable for the worker.
+const runnerIngressGenerationStore = (() => {
+    const entries = new Map();
+    function get(sandbox) {
+        const revision = sandbox.updatedAt ?? sandbox.createdAt ?? null;
+        const current = entries.get(sandbox.id);
+        if (current && current.revision === revision)
+            return current.generation;
+        const generation = createHash("sha256")
+            .update(`${sandbox.id}\0${revision ?? randomUUID()}`)
+            .digest("hex");
+        entries.set(sandbox.id, { revision, generation });
+        return generation;
+    }
+    function reset() {
+        entries.clear();
+    }
+    return { get, reset };
+})();
+// Advisory writable-set store. It holds, per lease scope, the sandbox
+// directories that a sync operation declared read-write (`access: "rw"`). The
+// store is advisory and best-effort in-memory state: it adds no security (the
+// ephemeral sandbox stays the only boundary). The store is keyed the same way
+// as `sandboxHandleCache`, by `sandboxHandleCacheKey(scope)`.
+//
+// The command path no longer reads this set. The provider dropped the advisory
+// `bwrap` wrapper that once bound these directories read-write for real-time
+// feedback (see `DIRECTORY-CONSTRAINT-FINDINGS.md`). The store still records the
+// read-write set, so a future isolation wrapper for the session can consume it
+// without a new sync change.
+const sandboxHandleWritableDirs = (() => {
+    const dirsByKey = new Map();
+    // Record the read-write destination directory of every `access: "rw"`
+    // mapping. Skip read-only mappings (`access` absent or `"ro"`). Read-only is
+    // the safe default for an advisory signal.
+    //
+    // A workspace, git-history, or asset mapping uploads a tar archive, so its
+    // `targetPath` is the staging archive under the runtime root, not the directory
+    // that the post-upload extract command fills. For those mappings the author
+    // sets `writablePath` to the final destination directory, so this records the
+    // real read-write destination, not the staging parent. When `writablePath` is
+    // absent the mapping writes `targetPath` in place, so the parent directory of
+    // `targetPath` is the destination.
+    function recordWritableTargets(scope, operations) {
+        const key = sandboxHandleCacheKey(scope);
+        for (const operation of operations) {
+            for (const mapping of operation.files) {
+                if (mapping.access !== "rw")
+                    continue;
+                let dirs = dirsByKey.get(key);
+                if (!dirs) {
+                    dirs = new Set();
+                    dirsByKey.set(key, dirs);
+                }
+                dirs.add(mapping.writablePath ?? path.posix.dirname(mapping.targetPath));
+            }
+        }
+    }
+    function get(scope) {
+        return dirsByKey.get(sandboxHandleCacheKey(scope)) ?? new Set();
+    }
+    function reset() {
+        dirsByKey.clear();
+    }
+    return { recordWritableTargets, get, reset };
+})();
+// Per-lease Daytona session-id store. It holds, per lease scope, the id of the
+// one persistent session the exec hook opened for that lease. The store is
+// keyed the same way as `sandboxHandleCache`, by `sandboxHandleCacheKey(scope)`.
+// The exec hook creates one session on a cache miss and records its id here. The
+// teardown hooks delete the session and clear the id. A resume clears the id,
+// because a restarted sandbox loses its session shell, so the next exec must
+// open a fresh session. The store is process-memory only; it holds an id string,
+// never a handle, a credential, or a command.
+const sandboxHandleSessionStore = (() => {
+    const idByKey = new Map();
+    // In-flight session creates, keyed the same way as `idByKey`. A create records
+    // its promise here for the time it runs, then removes it. The map lets two
+    // overlapping first commands for one lease share one create. See `runSingle`.
+    const pendingByKey = new Map();
+    function get(scope) {
+        return idByKey.get(sandboxHandleCacheKey(scope));
+    }
+    function set(scope, sessionId) {
+        idByKey.set(sandboxHandleCacheKey(scope), sessionId);
+    }
+    function clear(scope) {
+        idByKey.delete(sandboxHandleCacheKey(scope));
+    }
+    // Single-flight guard for the first-command session create. Two overlapping
+    // first commands for one lease must open at most one live session. The first
+    // caller runs `create` and records its in-flight promise; every concurrent
+    // caller awaits the same promise instead of a second `create`. The store keeps
+    // the promise only while `create` runs, then removes it, so a later command
+    // (for example, after a resume clears the id) can open a fresh session. A
+    // failed `create` removes the promise too, so the next command retries.
+    function runSingle(scope, create) {
+        const key = sandboxHandleCacheKey(scope);
+        const inFlight = pendingByKey.get(key);
+        if (inFlight)
+            return inFlight;
+        const promise = create();
+        pendingByKey.set(key, promise);
+        const settle = () => {
+            pendingByKey.delete(key);
+        };
+        promise.then(settle, settle);
+        return promise;
+    }
+    function reset() {
+        idByKey.clear();
+        pendingByKey.clear();
+    }
+    return { get, set, clear, runSingle, reset };
+})();
+/**
+ * Test seam: clear the process-scoped handle cache between tests so a handle
+ * memoized under a reused composite key in one test never leaks into the next.
+ * Not used in production.
+ */
+export function __resetDaytonaSandboxHandleCacheForTest() {
+    providerUsed = false;
+    sandboxHandleCache.reset();
+    sandboxHandleTeardownGates.reset();
+    sandboxHandleActivityGates.reset();
+    sandboxHandleLeaseAdmissionStates.reset();
+    sandboxHandleWritableDirs.reset();
+    sandboxHandleSessionStore.reset();
+    runnerIngressGenerationStore.reset();
+}
+/**
+ * Test seam: read the advisory writable directories recorded for a sync scope.
+ * The caller passes the same `onEnvironmentSyncIn` inputs, so this rebuilds the
+ * exact scope key the hook used. Not used in production.
+ */
+export function __getDaytonaWritableDirsForTest(input) {
+    const scope = {
+        driverKey: input.driverKey,
+        companyId: input.companyId,
+        environmentId: input.environmentId,
+        providerLeaseId: input.lease.providerLeaseId ?? "",
+        config: parseDriverConfig(input.config),
+    };
+    return [...sandboxHandleWritableDirs.get(scope)];
+}
+async function getSandbox(scope, options = {}) {
+    return await sandboxHandleCache.get(scope, options);
+}
+async function getSandboxOrNull(scope, options = {}) {
+    try {
+        return await getSandbox(scope, options);
+    }
+    catch (error) {
+        if (error instanceof DaytonaNotFoundError) {
+            return null;
+        }
+        throw error;
+    }
+}
+function evictSandboxHandle(scope) {
+    sandboxHandleCache.clear(scope);
+}
+// Return the persistent session id for a lease, and open one session on a cache
+// miss. The exec hook calls this once per command. The first call opens the
+// session through `createSession` and records its id; every later call returns
+// the stored id, so one lease runs every command in one persistent shell. The
+// provider never falls back to a one-shot command to open a session.
+//
+// Leak bound: the Daytona SDK exposes NO per-session TTL. `createSession` takes
+// only a session id, and there is no session update or expiry field. Two
+// backstops bound the session against a leak. First, `teardownSession` runs a
+// guaranteed `deleteSession` in every teardown hook's `try/finally`. Second, the
+// sandbox-level `autoStopInterval` (15 minutes idle by default) stops the
+// sandbox and, with it, every session; the `autoArchiveInterval` and
+// `autoDeleteInterval` intervals then reap the sandbox. A session is a shell
+// inside its sandbox and cannot outlive it.
+async function getOrCreateSession(sandbox, scope) {
+    const existing = sandboxHandleSessionStore.get(scope);
+    if (existing)
+        return existing;
+    // Single-flight the first-command create. Two overlapping first commands for
+    // one lease share one create promise, so the lease opens at most one live
+    // session. The guard checks and starts the create in one synchronous step, so
+    // no second command can slip in between the store read and the create start.
+    return sandboxHandleSessionStore.runSingle(scope, async () => {
+        const sessionId = `paperclip-${randomUUID()}`;
+        // Wrap the session create in a short `session.open` provider span. The span
+        // carries no session id and no command text, only the provider family. The
+        // host maps the name to `sandbox.daytona.session.open`.
+        // `session.open` span: create the one persistent Daytona session for a lease,
+        // on the first in-run command — `sandbox.process.createSession`.
+        await withProviderSpan({
+            name: "session.open",
+            run: () => sandbox.process.createSession(sessionId),
+        });
+        sandboxHandleSessionStore.set(scope, sessionId);
+        return sessionId;
+    });
+}
+// Delete the persistent session for a lease and clear its stored id. Each
+// teardown hook calls this inside its `try/finally`, so a failed delete never
+// skips the rest of teardown. A failed delete logs the session id and the error
+// loudly and does not throw past teardown; the sandbox stop or delete that
+// follows removes the session shell anyway, and the sandbox-level
+// `autoStopInterval` / `autoDeleteInterval` / `autoArchiveInterval` backstops
+// bound any residual state (the session API exposes no per-session TTL). The
+// store id is always cleared, so no orphan id survives.
+async function teardownSession(sandbox, scope) {
+    const sessionId = sandboxHandleSessionStore.get(scope);
+    if (!sessionId)
+        return;
+    // Retire the captured identity before awaiting the provider. A late response
+    // must not clear a new session created after this lease is resumed.
+    sandboxHandleSessionStore.clear(scope);
+    try {
+        // Wrap the session delete in a short `session.close` provider span. The
+        // host maps the name to `sandbox.daytona.session.close`.
+        // `session.close` span: delete that persistent session on lease release —
+        // `sandbox.process.deleteSession`.
+        await withProviderSpan({
+            name: "session.close",
+            run: () => sandbox.process.deleteSession(sessionId),
+        });
+    }
+    catch (error) {
+        console.error(`Failed to delete Daytona session ${sessionId} during teardown: ${formatErrorMessage(error)}`);
+    }
+}
+// One-shot command execution via Daytona's `process.executeCommand`. This is the
+// fallback path the exec hook uses when the session model is off. The command
+// runs plain as the unprivileged sandbox user; the provider no longer wraps a
+// user command with the advisory `bwrap` wrapper on any path.
+//
+// `executeCommand` returns combined stdout+stderr in `result`. We surface that
+// as `stdout` and leave `stderr` empty; callers that grep for error messages
+// still see them in `stdout`.
+async function executeOneShot(sandbox, params, config) {
+    const gitNet = isGitNetworkCommand(params.command, params.args ?? []);
+    const timeoutMs = resolveTimeoutMs(params.timeoutMs, config);
+    const effectiveTimeoutMs = gitNet ? Math.min(timeoutMs, GIT_NETWORK_TIMEOUT_MS) : timeoutMs;
+    const timeoutSeconds = toTimeoutSeconds(effectiveTimeoutMs);
+    const stdinPath = params.stdin != null ? `/tmp/paperclip-stdin-${randomUUID()}` : null;
+    // Marks the start of the `executeCommand` REST round-trip. Hoisted out of the
+    // try so the timeout path below can still attribute the exec wall-time it spent
+    // before the SDK aborted — a slow failed exec is exactly what we want to
+    // measure. Stays null until we are about to call `executeCommand`, so a timeout
+    // during the earlier `uploadFile` step honestly reports no `durationMs`.
+    let execStart = null;
+    try {
+        if (stdinPath) {
+            await sandbox.fs.uploadFile(Buffer.from(params.stdin ?? "", "utf8"), stdinPath, timeoutSeconds);
+        }
+        // Run the plain login-shell script as the unprivileged sandbox user. The
+        // provider no longer wraps a user command with the advisory `bwrap` wrapper.
+        const command = buildLoginShellScript({
+            command: params.command,
+            args: params.args ?? [],
+            cwd: params.cwd,
+            env: params.env,
+            stdinPath: stdinPath ?? undefined,
+        });
+        // Pass cwd undefined: `buildLoginShellScript` already injects the `cd` after
+        // it sources the login profiles, when params.cwd is set. The Daytona
+        // executor's own cwd argument runs before that profile sourcing, which is
+        // the wrong order (a profile could reset the caller env).
+        // Time only the `executeCommand` REST round-trip so the caller can
+        // attribute a step's exec time to the provider boundary through the
+        // free-form `metadata.durationMs`.
+        execStart = timingNow();
+        const result = await sandbox.process.executeCommand(command, undefined, undefined, timeoutSeconds);
+        const durationMs = timingNow() - execStart;
+        return {
+            exitCode: typeof result.exitCode === "number" ? result.exitCode : 1,
+            timedOut: false,
+            stdout: result.result ?? result.artifacts?.stdout ?? "",
+            stderr: "",
+            metadata: { durationMs },
+        };
+    }
+    catch (error) {
+        if (error instanceof DaytonaTimeoutError) {
+            const timeoutMessage = gitNet
+                ? `Git network operation timed out after ${Math.round(effectiveTimeoutMs / 1000)} s — the remote may be unreachable or noninteractive credentials are not configured.`
+                : error.message.trim();
+            // Preserve provider-boundary exec attribution on the timeout path: if the
+            // SDK aborted the `executeCommand` call itself, report how long it ran
+            // before timing out so slow failed startup exec is attributed to the
+            // provider, not silently dropped.
+            const durationMs = execStart != null ? timingNow() - execStart : undefined;
+            return {
+                exitCode: null,
+                timedOut: true,
+                stdout: "",
+                stderr: `${timeoutMessage}\n`,
+                ...(durationMs != null ? { metadata: { durationMs } } : {}),
+            };
+        }
+        throw error;
+    }
+    finally {
+        if (stdinPath) {
+            await sandbox.fs.deleteFile(stdinPath).catch(() => undefined);
+        }
+    }
+}
+// Fallback reads full log snapshots as well as status. Limit the heavier
+// polling path while keeping output available to interactive commands.
+const SESSION_LOG_POLL_INTERVAL_MS = 1000;
+// A socket can stay open after it stops delivering output. Switch to saved
+// logs after this much silence; silence never proves that the command exited.
+const SESSION_LOG_STREAM_IDLE_MS = 15_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Backoff delays for the exit-code read after the log stream ends. The live
+// spike measured the exit code available within one poll (91-202 ms), so the
+// first read almost always holds the code. These delays cover the rare case
+// where the first read has no code yet.
+const SESSION_EXIT_CODE_RETRY_DELAYS_MS = [50, 100, 200];
+// A bounded reconnect for the log stream. The SDK resolves on WebSocket close,
+// which does not prove that the command exited. A reconnect replays the log
+// from byte 0; the stream buffer drops the replayed prefix by byte offset.
+// After this many reconnects the dispatch falls back to
+// the poll path.
+const MAX_SESSION_STREAM_RECONNECTS = 1;
+// Buffers the stdout and stderr of one session command from the callback log
+// stream, and drops a replayed prefix by byte offset.
+//
+// The Daytona callback stream replays the whole log from byte 0 after a
+// reconnect (it does not resume from an offset and does not omit earlier
+// bytes). So the buffer tracks the byte count it already holds per stream and
+// drops any replayed bytes that fall before that count. The dedupe runs at the
+// byte level, because Daytona replays the log byte-for-byte. The SDK keeps each
+// multibyte UTF-8 character whole per chunk and per stream, so the delivered
+// byte count always lands on a character boundary and the byte-offset split is
+// safe.
+//
+// The buffer stores each new tail as a separate chunk and joins the chunks one
+// time at read. It does not copy the earlier output on each append, so total
+// buffering work stays linear in the output size, not quadratic.
+function createSessionStreamBuffer(onNewTail) {
+    const createStream = () => ({
+        chunks: [], length: 0, connectionBytes: 0, pendingReplacement: "", previousReplacement: null,
+    });
+    const streams = {
+        stdout: createStream(),
+        stderr: createStream(),
+    };
+    function append(streamName, stream, chunk, final = false, publish = true) {
+        // The SDK flushes an incomplete UTF-8 character as U+FFFD on socket close.
+        // Do not publish that suffix or count its replacement bytes until a replay
+        // confirms it. A real final U+FFFD is flushed at confirmed command exit.
+        const text = stream.pendingReplacement + chunk;
+        stream.pendingReplacement = final ? "" : (text.match(/\uFFFD+$/u)?.[0] ?? "");
+        const buf = Buffer.from(text.slice(0, text.length - stream.pendingReplacement.length), "utf8");
+        const start = stream.connectionBytes;
+        stream.connectionBytes = start + buf.length;
+        if (stream.previousReplacement && stream.connectionBytes > stream.previousReplacement.offset) {
+            stream.previousReplacement = null;
+        }
+        // The whole chunk falls before the delivered byte count, so it is a replay.
+        if (start + buf.length <= stream.length) {
+            return;
+        }
+        // Keep only the new tail. When the whole chunk is new, `start >=
+        // stream.length` and the tail is the whole chunk. When the chunk straddles
+        // the delivered byte count, the tail starts after the replayed prefix.
+        const tail = start >= stream.length ? buf : buf.subarray(stream.length - start);
+        stream.chunks.push(tail);
+        stream.length += tail.length;
+        // Deliver only the genuinely new tail to the live sink, so a replayed
+        // prefix on a reconnect never reaches the host twice.
+        if (publish && onNewTail && tail.length > 0) {
+            onNewTail(streamName, tail.toString("utf8"));
+        }
+    }
+    return {
+        onStdout: (chunk) => append("stdout", streams.stdout, chunk),
+        onStderr: (chunk) => append("stderr", streams.stderr, chunk),
+        // Reset the per-connection read cursors after a reconnect, so the replayed
+        // prefix drops against the already-delivered byte count.
+        resetConnectionCursors() {
+            for (const stream of Object.values(streams)) {
+                if (stream.pendingReplacement &&
+                    (!stream.previousReplacement || stream.connectionBytes > stream.previousReplacement.offset ||
+                        (stream.connectionBytes === stream.previousReplacement.offset &&
+                            stream.pendingReplacement.length > stream.previousReplacement.text.length))) {
+                    stream.previousReplacement = { offset: stream.connectionBytes, text: stream.pendingReplacement };
+                }
+                stream.pendingReplacement = "";
+                stream.connectionBytes = 0;
+            }
+        },
+        finish(publish = true) {
+            for (const name of ["stdout", "stderr"]) {
+                const stream = streams[name];
+                if (stream.previousReplacement?.offset === stream.connectionBytes &&
+                    stream.previousReplacement.text.length > stream.pendingReplacement.length) {
+                    stream.pendingReplacement = stream.previousReplacement.text;
+                }
+                append(name, stream, "", true, publish);
+                // A short terminal snapshot must not discard a genuine trailing
+                // replacement character already received from a longer stream.
+                const previous = stream.previousReplacement;
+                if (previous && previous.offset >= stream.length) {
+                    stream.connectionBytes = previous.offset;
+                    append(name, stream, previous.text, true, publish);
+                }
+                stream.previousReplacement = null;
+            }
+        },
+        get stdout() {
+            return Buffer.concat(streams.stdout.chunks).toString("utf8");
+        },
+        get stderr() {
+            return Buffer.concat(streams.stderr.chunks).toString("utf8");
+        },
+    };
+}
+class SessionCommandDeadlineError extends Error {
+}
+class SessionObservationTimeoutError extends Error {
+}
+async function beforeSessionDeadline(deadlineMs, action) {
+    const remainingMs = deadlineMs - Date.now();
+    if (remainingMs <= 0)
+        throw new SessionCommandDeadlineError();
+    let timer;
+    try {
+        return await Promise.race([
+            action(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new SessionCommandDeadlineError()), remainingMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+// A provider operation timeout bounds one observation, not a healthy stream's
+// lifetime. The caller's RPC/run guard and session teardown own that lifetime.
+async function observeSessionCommand(timeoutMs, action) {
+    try {
+        return await beforeSessionDeadline(Date.now() + timeoutMs, action);
+    }
+    catch (error) {
+        if (error instanceof SessionCommandDeadlineError || error instanceof DaytonaTimeoutError) {
+            throw new SessionObservationTimeoutError();
+        }
+        throw error;
+    }
+}
+// Stream stdout and stderr of one session command from the callback log form.
+// The stream buffer drops a replayed prefix by byte offset on a reconnect.
+// Rejected streams and clean closes use bounded reconnects, then polling.
+// An idle socket goes directly to polling, including one that never settles.
+async function runSessionLogStream(sandbox, sessionId, commandId, timeoutMs, buffer) {
+    let reconnects = 0;
+    let pollUntilExit = false;
+    while (true) {
+        let streamClosed = false;
+        let acceptingOutput = true;
+        let idleTimer;
+        let signalIdle;
+        const idle = new Promise((resolve) => { signalIdle = () => resolve("idle"); });
+        const armIdleTimer = () => {
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(signalIdle, SESSION_LOG_STREAM_IDLE_MS);
+        };
+        const receive = (stream, chunk) => {
+            if (!acceptingOutput || !chunk)
+                return;
+            armIdleTimer();
+            if (stream === "stdout")
+                buffer.onStdout(chunk);
+            else
+                buffer.onStderr(chunk);
+        };
+        try {
+            armIdleTimer();
+            const outcome = await Promise.race([
+                sandbox.process.getSessionCommandLogs(sessionId, commandId, (chunk) => receive("stdout", chunk), (chunk) => receive("stderr", chunk)).then(() => "closed"),
+                idle,
+            ]);
+            if (outcome === "idle") {
+                // Do not wait for the abandoned socket or open another one. The SDK
+                // exposes no cancellation handle. Fence its callbacks before the
+                // snapshot path resets the buffer's byte cursors.
+                return { exitCode: null, pollUntilExit: true, buffer };
+            }
+            streamClosed = true;
+            pollUntilExit = true;
+        }
+        catch {
+            // The command can still be running after a log transport failure.
+        }
+        finally {
+            // The SDK exposes no cancellation handle for this socket. Session
+            // teardown owns closing it; late data cannot change a settled execution.
+            acceptingOutput = false;
+            clearTimeout(idleTimer);
+        }
+        if (streamClosed) {
+            const exitCode = await readSessionExitCode(sandbox, sessionId, commandId, timeoutMs);
+            if (exitCode !== null)
+                return { exitCode, pollUntilExit, buffer };
+        }
+        if (reconnects >= MAX_SESSION_STREAM_RECONNECTS) {
+            return { exitCode: null, pollUntilExit, buffer };
+        }
+        reconnects += 1;
+        buffer.resetConnectionCursors();
+    }
+}
+// Read the exit code one time after the log stream ends. The exit code is
+// available within one poll, so the first read almost always holds it. Add a
+// small bounded retry with backoff only for the rare case where the first read
+// has no code yet. Return null when no read holds a numeric code.
+async function readSessionExitCode(sandbox, sessionId, commandId, timeoutMs) {
+    const first = await observeSessionCommand(timeoutMs, () => sandbox.process.getSessionCommand(sessionId, commandId));
+    if (typeof first.exitCode === "number") {
+        return first.exitCode;
+    }
+    for (const delayMs of SESSION_EXIT_CODE_RETRY_DELAYS_MS) {
+        await sleep(delayMs);
+        const status = await observeSessionCommand(timeoutMs, () => sandbox.process.getSessionCommand(sessionId, commandId));
+        if (typeof status.exitCode === "number") {
+            return status.exitCode;
+        }
+    }
+    return null;
+}
+// Dispatch one user command into the persistent session and return its true
+// stdout and stderr.
+//
+// The Daytona session is one persistent shell. A top-level `exit N` inside a
+// session command ends that shell, so the next command then fails with "session
+// process has exited". To stop a user `exit` from reaching the session shell,
+// the dispatch wraps the whole login-shell script in a subshell `( ... )`. A
+// user `exit` then ends only the subshell and reports its exit code, and the
+// session shell stays alive. The provider passes the caller cwd and env inside
+// the login-shell script on every command, so it never relies on implicit state
+// that leaks between commands.
+//
+// The SDK exposes no built-in wait for a session command, so the dispatch runs
+// the command with `runAsync: true` and polls `getSessionCommand` until the exit
+// code is set. It then reads true `stdout` and `stderr` from
+// `getSessionCommandLogs`, because the synchronous response fields are optional.
+// The `runAsync: true` path also avoids the known `runAsync: false` login-shell
+// hang.
+async function executeInSession(sandbox, sessionId, params, config) {
+    const gitNet = isGitNetworkCommand(params.command, params.args ?? []);
+    const timeoutMs = resolveTimeoutMs(params.timeoutMs, config);
+    const effectiveTimeoutMs = gitNet ? Math.min(timeoutMs, GIT_NETWORK_TIMEOUT_MS) : timeoutMs;
+    const timeoutSeconds = toTimeoutSeconds(effectiveTimeoutMs);
+    const stdinPath = params.stdin != null ? `/tmp/paperclip-stdin-${randomUUID()}` : null;
+    // Marks the start of the session dispatch and poll. The timeout paths report
+    // the exec wall-time spent before the abort, so a slow command is still
+    // attributed to the provider boundary.
+    let execStart = null;
+    let confirmedExitCode = null;
+    const streamBuffer = createSessionStreamBuffer((stream, text) => pluginContext?.execution.log(stream, text));
+    try {
+        if (stdinPath) {
+            await sandbox.fs.uploadFile(Buffer.from(params.stdin ?? "", "utf8"), stdinPath, timeoutSeconds);
+        }
+        const loginScript = buildLoginShellScript({
+            command: params.command,
+            args: params.args ?? [],
+            cwd: params.cwd,
+            env: params.env,
+            stdinPath: stdinPath ?? undefined,
+        });
+        // Subshell wrap: a top-level `exit` in the user command exits only the
+        // subshell, not the persistent session shell.
+        const command = `( ${loginScript} )`;
+        execStart = timingNow();
+        const dispatched = await sandbox.process.executeSessionCommand(sessionId, { command, runAsync: true }, timeoutSeconds);
+        const commandId = dispatched.cmdId;
+        // Log-stream path. A session command always tries the stream first: it
+        // streams stdout and stderr from the callback log form, then reads the exit
+        // code. A log socket closing without a recorded exit leaves the command
+        // running, so reconnect and then poll the same command without replaying it.
+        //
+        // Emit each genuinely new output chunk to the host during the active execute
+        // call. The host routes it to the runner log sink by the host-issued
+        // invocation id. This is a no-op when no plugin context is set (a direct
+        // test call) or when the host has no active execute route.
+        const streamResult = await runSessionLogStream(sandbox, sessionId, commandId, effectiveTimeoutMs, streamBuffer);
+        if (streamResult.exitCode !== null) {
+            confirmedExitCode = streamResult.exitCode;
+            // A log socket can close before the process emits its final bytes. Even
+            // a now-visible exit code does not prove the streamed prefix is complete.
+            const logs = await observeSessionCommand(effectiveTimeoutMs, () => sandbox.process.getSessionCommandLogs(sessionId, commandId));
+            streamBuffer.resetConnectionCursors();
+            streamBuffer.onStdout(logs?.stdout ?? "");
+            streamBuffer.onStderr(logs?.stderr ?? "");
+            streamBuffer.finish();
+            const durationMs = timingNow() - execStart;
+            return {
+                exitCode: streamResult.exitCode,
+                timedOut: false,
+                stdout: streamResult.buffer.stdout,
+                stderr: streamResult.buffer.stderr,
+                metadata: { durationMs },
+            };
+        }
+        // Keep forwarding output while waiting for the actual command exit. ACP
+        // peers may need a tool response before they can finish the command. Waiting
+        // for exit before reading logs would strand those peers after a stream loss.
+        // A closed or idle log socket does not end the command's lifetime. Bound
+        // each recovery read independently; the caller still owns stop/teardown.
+        // Preserve the legacy budget starting at fallback entry when both stream
+        // attempts fail, including a stream that fails after running for hours.
+        const deadlineMs = Date.now() + effectiveTimeoutMs;
+        const observe = async (action) => {
+            try {
+                return await (streamResult.pollUntilExit
+                    ? observeSessionCommand(effectiveTimeoutMs, action)
+                    : beforeSessionDeadline(deadlineMs, action));
+            }
+            catch (error) {
+                if (error instanceof DaytonaTimeoutError)
+                    throw new SessionObservationTimeoutError();
+                throw error;
+            }
+        };
+        while (true) {
+            const status = await observe(() => sandbox.process.getSessionCommand(sessionId, commandId));
+            if (typeof status.exitCode === "number")
+                confirmedExitCode = status.exitCode;
+            const logs = await observe(() => sandbox.process.getSessionCommandLogs(sessionId, commandId));
+            streamResult.buffer.resetConnectionCursors();
+            streamResult.buffer.onStdout(logs.stdout ?? "");
+            streamResult.buffer.onStderr(logs.stderr ?? "");
+            if (confirmedExitCode !== null) {
+                streamResult.buffer.finish();
+                const durationMs = timingNow() - execStart;
+                return {
+                    exitCode: confirmedExitCode,
+                    timedOut: false,
+                    stdout: streamResult.buffer.stdout,
+                    stderr: streamResult.buffer.stderr,
+                    metadata: { durationMs },
+                };
+            }
+            // Full log snapshots are heavier than a status read. Limit fallback
+            // traffic to one snapshot per second. Failed-stream fallback retains
+            // its original deadline, including the time spent waiting between reads.
+            await sleep(streamResult.pollUntilExit ? SESSION_LOG_POLL_INTERVAL_MS
+                : Math.max(0, Math.min(SESSION_LOG_POLL_INTERVAL_MS, deadlineMs - Date.now())));
+        }
+    }
+    catch (error) {
+        if (error instanceof SessionObservationTimeoutError) {
+            // Preserve undecided decoder suffixes in the partial result, without
+            // injecting a possibly incomplete character into the live protocol.
+            streamBuffer.finish(false);
+            return {
+                exitCode: null,
+                timedOut: true,
+                stdout: streamBuffer.stdout,
+                stderr: `${streamBuffer.stderr}Session log observation timed out after ${Math.round(effectiveTimeoutMs / 1000)} s; ${confirmedExitCode === null ? "command exit remains unconfirmed" : "final output may be incomplete"}.\n`,
+                metadata: {
+                    ...(execStart != null ? { durationMs: timingNow() - execStart } : {}),
+                    timeoutScope: "session_log_observation",
+                    commandExitConfirmed: confirmedExitCode !== null,
+                    ...(confirmedExitCode !== null ? { observedExitCode: confirmedExitCode } : {}),
+                },
+            };
+        }
+        if (error instanceof DaytonaTimeoutError || error instanceof SessionCommandDeadlineError) {
+            streamBuffer.finish(false);
+            const timeoutMessage = gitNet
+                ? `Git network operation timed out after ${Math.round(effectiveTimeoutMs / 1000)} s — the remote may be unreachable or noninteractive credentials are not configured.`
+                : error instanceof SessionCommandDeadlineError
+                    ? `Command timed out after ${Math.round(effectiveTimeoutMs / 1000)} s.`
+                    : error.message.trim();
+            const durationMs = execStart != null ? timingNow() - execStart : undefined;
+            return {
+                exitCode: null,
+                timedOut: true,
+                stdout: streamBuffer.stdout,
+                stderr: `${streamBuffer.stderr}${timeoutMessage}\n`,
+                ...(durationMs != null ? { metadata: { durationMs } } : {}),
+            };
+        }
+        throw error;
+    }
+    finally {
+        if (stdinPath) {
+            await sandbox.fs.deleteFile(stdinPath).catch(() => undefined);
+        }
+    }
+}
+const daytonaLoginPtyByRoute = new Map();
+const daytonaLoginPtyBySession = new Map();
+function forgetDaytonaLoginPty(entry) {
+    daytonaLoginPtyByRoute.delete(entry.hostRouteId);
+    daytonaLoginPtyBySession.delete(entry.workerSessionId);
+}
+const daytonaDuplexChannelByRoute = new Map();
+const daytonaDuplexChannelBySession = new Map();
+function forgetDaytonaDuplexChannel(entry) {
+    daytonaDuplexChannelByRoute.delete(entry.hostRouteId);
+    daytonaDuplexChannelBySession.delete(entry.workerSessionId);
+}
+// Close every open duplex channel that belongs to one provider lease and drop its
+// entry. The lease teardown hooks (release, destroy, resume) call this, so a
+// channel never outlives the sandbox that carries it. The close kills the child
+// and releases the pseudo-terminal socket, so no live channel survives the
+// teardown. The stored identifiers are always cleared, so no orphan id survives.
+async function closeDaytonaDuplexChannelsForLease(providerLeaseId) {
+    const matches = [...daytonaDuplexChannelByRoute.values()].filter((entry) => entry.providerLeaseId === providerLeaseId);
+    for (const entry of matches)
+        forgetDaytonaDuplexChannel(entry);
+    await Promise.allSettled(matches.map(entry => entry.session.close()));
+}
+const plugin = definePlugin({
+    async setup(ctx) {
+        // Hoist the context to a module variable so the lifecycle hooks and the
+        // file-sync helpers can read `ctx.tracer` — they have no closure over `ctx`.
+        pluginContext = ctx;
+        ctx.logger.info("Daytona sandbox provider plugin ready");
+    },
+    async onHealth() {
+        return { status: "ok", message: "Daytona sandbox provider plugin healthy" };
+    },
+    async onIdleDrain() {
+        return providerUsed || daytonaLoginPtyByRoute.size > 0 || daytonaDuplexChannelByRoute.size > 0
+            ? "present" : "none";
+    },
+    async onEnvironmentValidateConfig(params) {
+        const config = parseDriverConfig(params.config);
+        const errors = [];
+        if (typeof params.config.image === "string" && params.config.image.trim().length === 0) {
+            errors.push("Daytona image cannot be empty.");
+        }
+        if (typeof params.config.snapshot === "string" && params.config.snapshot.trim().length === 0) {
+            errors.push("Daytona snapshot cannot be empty.");
+        }
+        if (config.image && config.snapshot) {
+            errors.push("Daytona sandbox environments must set either image or snapshot, not both.");
+        }
+        if (config.apiUrl && !isValidUrl(config.apiUrl)) {
+            errors.push("apiUrl must be a valid URL.");
+        }
+        if (config.timeoutMs < 1 || config.timeoutMs > 86_400_000) {
+            errors.push("timeoutMs must be between 1 and 86400000.");
+        }
+        // A value of 0 or less disables the extra bound on purpose; reject only a
+        // value above the outer RPC ceiling, which would make the bound useless.
+        if (config.livenessTimeoutMs > 86_400_000) {
+            errors.push("livenessTimeoutMs must be less than or equal to 86400000.");
+        }
+        if (config.autoStopInterval != null && config.autoStopInterval < 0) {
+            errors.push("autoStopInterval must be greater than or equal to 0.");
+        }
+        if (config.autoArchiveInterval != null && config.autoArchiveInterval < 0) {
+            errors.push("autoArchiveInterval must be greater than or equal to 0.");
+        }
+        if (config.autoDeleteInterval != null && config.autoDeleteInterval < -1) {
+            errors.push("autoDeleteInterval must be greater than or equal to -1.");
+        }
+        if (!config.apiKey && !(process.env.DAYTONA_API_KEY?.trim())) {
+            errors.push("Daytona sandbox environments require an API key in config or DAYTONA_API_KEY.");
+        }
+        const resourceRequestError = validateResourceRequest(config);
+        if (resourceRequestError) {
+            errors.push(resourceRequestError);
+        }
+        for (const [key, value] of Object.entries({
+            cpu: config.cpu,
+            memory: config.memory,
+            disk: config.disk,
+            gpu: config.gpu,
+        })) {
+            if (value != null && value <= 0) {
+                errors.push(`${key} must be greater than 0 when provided.`);
+            }
+        }
+        if (errors.length > 0) {
+            return { ok: false, errors };
+        }
+        return {
+            ok: true,
+            normalizedConfig: { ...config },
+        };
+    },
+    async onEnvironmentProbe(params) {
+        const config = parseDriverConfig(params.config);
+        try {
+            const sandbox = await createSandbox(params, config);
+            try {
+                const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
+                const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
+                return {
+                    ok: true,
+                    summary: `Connected to Daytona sandbox ${sandbox.name}.`,
+                    metadata: {
+                        provider: "daytona",
+                        shellCommand,
+                        sandboxId: sandbox.id,
+                        sandboxName: sandbox.name,
+                        target: sandbox.target,
+                        image: config.image,
+                        snapshot: config.snapshot,
+                        timeoutMs: config.timeoutMs,
+                        reuseLease: config.reuseLease,
+                        remoteCwd,
+                    },
+                };
+            }
+            finally {
+                await sandbox.delete(toTimeoutSeconds(config.timeoutMs)).catch(() => undefined);
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                summary: "Daytona sandbox probe failed.",
+                metadata: {
+                    provider: "daytona",
+                    image: config.image,
+                    snapshot: config.snapshot,
+                    timeoutMs: config.timeoutMs,
+                    reuseLease: config.reuseLease,
+                    error: formatErrorMessage(error),
+                },
+            };
+        }
+    },
+    async onEnvironmentAcquireLease(params) {
+        const config = parseDriverConfig(params.config);
+        // One budget covers creation, setup, and inline cleanup. The host leaves
+        // 30 seconds beyond this deadline to receive/journal the cleanup record.
+        const budgetMs = config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS;
+        const startedAt = Date.now();
+        const deadline = startedAt + budgetMs;
+        let expired = false;
+        let phase = "create";
+        let cleanupInProgress = false;
+        let firstFailure;
+        const observeFailure = () => {
+            // Cleanup may consume the rest of the budget. Keep the original failed
+            // step and time, rather than attributing that failure to its cleanup.
+            return firstFailure ??= {
+                phase,
+                elapsedMs: Math.max(0, Math.min(604_800_000, Date.now() - startedAt)),
+                budgetMs,
+            };
+        };
+        let cleanup;
+        const timeoutFailure = () => {
+            const diagnostic = observeFailure();
+            expired = true;
+            const cause = new Error(`Daytona lease acquisition exceeded ${budgetMs} ms during ${cleanupInProgress ? "cleanup" : phase}`);
+            return cleanup
+                ? new PluginEnvironmentCreationCleanupError([cause], "Daytona lease acquisition timed out; allocation cleanup is pending", { ...cleanup, labels: { ...cleanup.labels } }, diagnostic)
+                : cause;
+        };
+        const assertActive = () => {
+            if (expired || Date.now() >= deadline)
+                throw timeoutFailure();
+        };
+        const acquire = async () => {
+            const sandbox = await createSandbox(params, config, {
+                onCreateAttempt: (attempt) => { cleanup = attempt; },
+                onCreateFailure: observeFailure,
+            });
+            try {
+                assertActive();
+                if (cleanup)
+                    cleanup.observedProviderLeaseId = sandbox.id;
+                phase = "workspace";
+                const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
+                assertActive();
+                phase = "shell";
+                const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(Math.max(1, deadline - Date.now())));
+                assertActive();
+                // Configure a provider-side destroy time at or before a caller deadline, so
+                // an abandoned sandbox self-destroys even if Paperclip is down. The lease
+                // carries the real provider expiry (or none) as evidence of the bound.
+                phase = "expiry";
+                const expiresAt = await configureSandboxExpiry({
+                    sandbox,
+                    requestedExpiresAt: params.requestedExpiresAt,
+                    nowMs: Date.now(),
+                });
+                assertActive();
+                phase = "sentinel";
+                const workspaceSentinel = await writeWorkspaceSentinel({
+                    sandbox,
+                    remoteCwd,
+                    params,
+                    config,
+                    timeoutSeconds: toTimeoutSeconds(Math.max(1, deadline - Date.now())),
+                });
+                assertActive();
+                sandboxHandleLeaseAdmissionStates.open({
+                    driverKey: params.driverKey,
+                    companyId: params.companyId,
+                    environmentId: params.environmentId,
+                    providerLeaseId: sandbox.id,
+                    config,
+                });
+                // Seed the handle cache with the fresh handle under the exact scope that
+                // `onEnvironmentRealizeWorkspace` reads (providerLeaseId === sandbox.id).
+                // Realize then reuses this handle instead of paying a real `client.get`.
+                sandboxHandleCache.seed({
+                    driverKey: params.driverKey,
+                    companyId: params.companyId,
+                    environmentId: params.environmentId,
+                    providerLeaseId: sandbox.id,
+                    config,
+                }, sandbox);
+                return {
+                    providerLeaseId: sandbox.id,
+                    expiresAt,
+                    metadata: leaseMetadata({
+                        config,
+                        sandbox,
+                        shellCommand,
+                        remoteCwd,
+                        resumedLease: false,
+                        workspaceSentinel,
+                    }),
+                };
+            }
+            catch (error) {
+                const diagnostic = observeFailure();
+                // After timeout the host owns the durable cleanup record. A late SDK
+                // completion must not admit this lease or start another setup phase.
+                if (!expired) {
+                    cleanupInProgress = true;
+                    try {
+                        await sandbox.delete(toTimeoutSeconds(Math.max(1, deadline - Date.now())));
+                    }
+                    catch (cleanupError) {
+                        if (cleanup) {
+                            throw new PluginEnvironmentCreationCleanupError([error, cleanupError], "Daytona lease setup failed; allocation cleanup is pending", { ...cleanup, labels: { ...cleanup.labels } }, diagnostic);
+                        }
+                        throw error;
+                    }
+                }
+                throw error;
+            }
+        };
+        let timer;
+        try {
+            return await Promise.race([
+                acquire(),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(timeoutFailure()), budgetMs);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+    async onEnvironmentResumeLease(params) {
+        const config = parseDriverConfig(params.config);
+        if (params.leaseMetadata?.reuseLease === false) {
+            const sentinel = isRecord(params.leaseMetadata.workspaceSentinel) ? params.leaseMetadata.workspaceSentinel : null;
+            const intent = isRecord(params.leaseMetadata.nativeWorkspaceExportResume) ? params.leaseMetadata.nativeWorkspaceExportResume : null;
+            // Ephemeral recovery is bound at acquisition. Never mint proof during
+            // resume, accept a copied sentinel for a replacement, or waive legacy proof.
+            if (typeof sentinel?.token !== "string" || !sentinel.token || typeof sentinel.runId !== "string" || !sentinel.runId
+                || sentinel.providerLeaseId !== params.providerLeaseId || params.leaseMetadata.sandboxId !== params.providerLeaseId
+                || (intent && intent.runId !== sentinel.runId)) {
+                return { providerLeaseId: null, metadata: { expired: true, workspaceSentinel: { result: "mismatch" } } };
+            }
+        }
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.providerLeaseId,
+            config,
+        };
+        // A confirmed stop may precede completion of an old SDK request. Do not
+        // restart its sandbox under that request; it could still write or execute.
+        if (sandboxHandleLeaseAdmissionStates.isClosed(scope) && sandboxHandleActivityGates.isActive(scope)) {
+            throw new Error("The stopped Daytona sandbox is still settling cancelled work. Retry shortly.");
+        }
+        return await withSandboxActivityGate(scope, async () => {
+            const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
+            if (!sandbox) {
+                return { providerLeaseId: null, metadata: { expired: true } };
+            }
+            // Daytona can retain the API record after losing its container. Confirm
+            // the exact provider report again before allowing the host's existing
+            // backup-guarded replacement path. Unknown errors preserve the lease.
+            if (hasMissingSandboxContainer(sandbox)) {
+                try {
+                    await withLivenessTimeout("sandbox.refreshData", config.livenessTimeoutMs, () => sandbox.refreshData());
+                    assertHandleMatchesLease(sandbox, params.providerLeaseId);
+                }
+                catch (error) {
+                    evictSandboxHandle(scope);
+                    if (error instanceof DaytonaNotFoundError) {
+                        return { providerLeaseId: null, metadata: { expired: true } };
+                    }
+                    throw error;
+                }
+                if (hasMissingSandboxContainer(sandbox)) {
+                    evictSandboxHandle(scope);
+                    return { providerLeaseId: null, metadata: { expired: true } };
+                }
+            }
+            // A stopped sandbox loses its session shell, so the stored session id is
+            // stale after a real restart. Clear the id only when the sandbox is not
+            // already running, and clear it before the restart. A stopped sandbox has
+            // no live session, so the clear drops a dead id and a later command opens
+            // a fresh session. A running sandbox keeps its live session, so the resume
+            // leaves the id in place; a concurrent command still finds it and teardown
+            // deletes one session. An unconditional clear would drop the id of a live
+            // session and leak its shell until sandbox reaping.
+            if (sandbox.state !== "started") {
+                sandboxHandleSessionStore.clear(scope);
+                // A stopped sandbox loses its pseudo-terminals, so a stored duplex channel
+                // is dead after a real restart. Close and drop every channel on this lease
+                // before the restart, so no stale channel id survives the resume.
+                await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);
+            }
+            const resumedFromState = sandbox.state ?? null;
+            await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
+            try {
+                const remoteCwd = await resolveSandboxWorkingDirectory(sandbox, false);
+                // C3: a resumed lease must clear the workspace sentinel before it is
+                // trusted, even when the handle came from the cache. On any non-match we
+                // evict the cached handle and expire the lease so a stale/foreign sandbox
+                // is never reused on the subsequent (sentinel-skipping) exec path.
+                const workspaceSentinel = await verifyWorkspaceSentinel({
+                    sandbox,
+                    remoteCwd,
+                    leaseMetadata: params.leaseMetadata,
+                    timeoutSeconds: toTimeoutSeconds(config.timeoutMs),
+                });
+                if (workspaceSentinel.result !== "matched") {
+                    evictSandboxHandle(scope);
+                    return {
+                        providerLeaseId: null,
+                        metadata: { expired: true, workspaceSentinel },
+                    };
+                }
+                const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
+                sandboxHandleCache.markFresh(scope);
+                sandboxHandleLeaseAdmissionStates.open(scope);
+                return {
+                    providerLeaseId: sandbox.id,
+                    metadata: leaseMetadata({
+                        config,
+                        sandbox,
+                        shellCommand,
+                        remoteCwd,
+                        resumedLease: true,
+                        resumedFromState,
+                        sandboxState: "started",
+                        workspaceSentinel,
+                    }),
+                };
+            }
+            catch (error) {
+                evictSandboxHandle(scope);
+                // A timeout, rate limit, or provider 5xx does not prove this sandbox is
+                // lost. Preserve the exact resource and let the host retry its recorded
+                // lease; replacement is permitted only after an explicit not-found or
+                // an immutable workspace identity mismatch.
+                throw error;
+            }
+        }, { allowClosed: true });
+    },
+    async onEnvironmentStopLease(params) {
+        if (!params.providerLeaseId)
+            throw new Error("Daytona stop requires an exact sandbox identity");
+        const config = parseDriverConfig(params.config);
+        const scope = { driverKey: params.driverKey, companyId: params.companyId,
+            environmentId: params.environmentId, providerLeaseId: params.providerLeaseId, config };
+        const teardownGate = sandboxHandleTeardownGates.begin(scope);
+        sandboxHandleLeaseAdmissionStates.close(scope);
+        try {
+            const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
+            if (!sandbox)
+                throw new Error("Daytona retained sandbox is unavailable");
+            evictSandboxHandle(scope);
+            // Provider auto-delete can destroy a stopped sandbox without an explicit
+            // delete call. Confirm the provider disabled it before stopping saved work;
+            // the SDK setter also updates a local field, which is not sufficient proof.
+            const deadline = Math.min(config.livenessTimeoutMs, 30_000);
+            await withLivenessTimeout("sandbox.setAutoDeleteInterval", deadline, () => sandbox.setAutoDeleteInterval(-1));
+            await withLivenessTimeout("sandbox.refreshData", deadline, () => sandbox.refreshData());
+            if (sandbox.autoDeleteInterval !== -1)
+                throw new Error("Daytona retention policy was not confirmed");
+            if (sandbox.state !== "stopped") {
+                await terminateAtProvider(scope, "sandbox.stop", () => sandbox.stop(Math.min(toTimeoutSeconds(config.timeoutMs), 30)));
+            }
+            sandboxHandleSessionStore.clear(scope);
+            await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);
+            return { providerLeaseId: params.providerLeaseId, state: "stopped" };
+        }
+        finally {
+            sandboxHandleTeardownGates.end(scope, teardownGate);
+            evictSandboxHandle(scope);
+        }
+    },
+    async onEnvironmentReleaseLease(params) {
+        if (!params.providerLeaseId)
+            return;
+        if (params.resourceDisposition === "stop_and_retain")
+            return plugin.definition.onEnvironmentStopLease(params);
+        const config = parseDriverConfig(params.config);
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.providerLeaseId,
+            config,
+        };
+        // C4: the lease's handle must not outlive its teardown. A teardown gate
+        // blocks fresh cache reads while cleanup is in flight so overlapping
+        // exec/sync calls cannot reacquire the same sandbox mid-stop/delete.
+        const teardownGate = sandboxHandleTeardownGates.begin(scope);
+        sandboxHandleLeaseAdmissionStates.close(scope);
+        try {
+            const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
+            if (!sandbox)
+                return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
+            evictSandboxHandle(scope);
+            if (params.cancelActiveWork) {
+                // Graceful release waits for activity below. Stop must not wait on the
+                // command it is cancelling. Admission is already closed for this lease.
+                const timeoutSeconds = Math.min(toTimeoutSeconds(config.timeoutMs), 30);
+                await withLivenessTimeout("sandbox.refreshData", Math.min(config.livenessTimeoutMs, 30_000), () => sandbox.refreshData());
+                if (sandbox.state !== "stopped")
+                    await sandbox.stop(timeoutSeconds);
+                sandboxHandleSessionStore.clear(scope);
+                await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);
+                return { providerLeaseId: params.providerLeaseId, state: "stopped" };
+            }
+            await drainSandboxBeforeTermination(sandbox, scope);
+            // A cached stopped state is not a receipt: the resource could have been
+            // resumed since the handle was cached. Read provider state at this boundary.
+            await withLivenessTimeout("sandbox.refreshData", config.livenessTimeoutMs, () => sandbox.refreshData());
+            if (config.reuseLease) {
+                if (sandbox.state !== "stopped") {
+                    try {
+                        await terminateAtProvider(scope, "sandbox.stop", () => sandbox.stop(toTimeoutSeconds(config.timeoutMs)));
+                    }
+                    catch (error) {
+                        console.warn(`Failed to stop Daytona sandbox during lease release: ${formatErrorMessage(error)}. Attempting delete instead.`);
+                        await terminateAtProvider(scope, "sandbox.delete", () => sandbox.delete(toTimeoutSeconds(config.timeoutMs), true));
+                        return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
+                    }
+                }
+                return { providerLeaseId: params.providerLeaseId, state: "stopped" };
+            }
+            if (config.archiveOnRelease) {
+                try {
+                    if (sandbox.state !== "stopped") {
+                        await terminateAtProvider(scope, "sandbox.stop", () => sandbox.stop(toTimeoutSeconds(config.timeoutMs)));
+                    }
+                    await sandbox.setAutoDeleteInterval(ARCHIVE_ON_RELEASE_AUTO_DELETE_MINUTES);
+                    await sandbox.archive();
+                    return { providerLeaseId: params.providerLeaseId, state: "stopped" };
+                }
+                catch (error) {
+                    console.warn(`Failed to archive Daytona sandbox during lease release: ${formatErrorMessage(error)}. Falling back to delete.`);
+                }
+            }
+            await terminateAtProvider(scope, "sandbox.delete", () => sandbox.delete(toTimeoutSeconds(config.timeoutMs), true));
+            return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
+        }
+        finally {
+            sandboxHandleTeardownGates.end(scope, teardownGate);
+            evictSandboxHandle(scope);
+        }
+    },
+    async onEnvironmentDestroyLease(params) {
+        if (!params.providerLeaseId)
+            return;
+        const config = parseDriverConfig(params.config);
+        if (params.leaseMetadata?.failedCreateCleanup !== undefined) {
+            const cleanup = readEnvironmentCreationCleanupError({ data: {
+                    schema: "paperclip/environment-creation-cleanup/v1", cleanup: params.leaseMetadata.failedCreateCleanup,
+                } });
+            if (!cleanup || cleanup.companyId !== params.companyId || cleanup.environmentId !== params.environmentId ||
+                cleanup.providerLeaseId !== params.providerLeaseId) {
+                throw new Error("Failed-create sandbox cleanup scope does not match");
+            }
+            await destroyFailedCreation(config, cleanup, true);
+            return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
+        }
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.providerLeaseId,
+            config,
+        };
+        // C4: the teardown gate blocks fresh cache reads while delete is in flight
+        // so overlapping exec/sync calls cannot reacquire the same sandbox mid-teardown.
+        const teardownGate = sandboxHandleTeardownGates.begin(scope);
+        sandboxHandleLeaseAdmissionStates.close(scope);
+        try {
+            const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
+            if (!sandbox)
+                return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
+            evictSandboxHandle(scope);
+            await drainSandboxBeforeTermination(sandbox, scope);
+            await terminateAtProvider(scope, "sandbox.delete", () => sandbox.delete(toTimeoutSeconds(config.timeoutMs), true));
+            return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
+        }
+        finally {
+            sandboxHandleTeardownGates.end(scope, teardownGate);
+            evictSandboxHandle(scope);
+        }
+    },
+    async onEnvironmentRealizeWorkspace(params) {
+        const config = parseDriverConfig(params.config);
+        const remoteCwd = typeof params.lease.metadata?.remoteCwd === "string" &&
+            params.lease.metadata.remoteCwd.trim().length > 0
+            ? params.lease.metadata.remoteCwd.trim()
+            : params.workspace.remotePath ?? params.workspace.localPath ?? "/paperclip-workspace";
+        if (params.lease.providerLeaseId) {
+            const scope = {
+                driverKey: params.driverKey,
+                companyId: params.companyId,
+                environmentId: params.environmentId,
+                providerLeaseId: params.lease.providerLeaseId,
+                config,
+            };
+            await withSandboxActivityGate(scope, async () => {
+                const sandbox = await getSandbox(scope, { bypassTeardownGate: true });
+                await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
+                await sandbox.fs.createFolder(remoteCwd, "755");
+            });
+        }
+        return {
+            cwd: remoteCwd,
+            metadata: {
+                provider: "daytona",
+                remoteCwd,
+            },
+        };
+    },
+    async onEnvironmentStartInteractiveSetup(params) {
+        const baseConfig = parseDriverConfig(params.config);
+        const config = withSetupSourceTemplate(baseConfig, params);
+        const sandbox = await createSandbox(params, config, { purpose: "interactive_setup" });
+        try {
+            const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
+            const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
+            const connection = await createSshConnection(sandbox, resolveConnectionExpiresInMinutes(params.connectionExpiresInMinutes));
+            sandboxHandleLeaseAdmissionStates.open({
+                driverKey: params.driverKey,
+                companyId: params.companyId,
+                environmentId: params.environmentId,
+                providerLeaseId: sandbox.id,
+                config,
+            });
+            return {
+                providerLeaseId: sandbox.id,
+                status: "waiting_for_user",
+                expiresAt: params.expiresAt ?? connection.connectionPayload?.expiresAt ?? null,
+                ...connection,
+                metadata: interactiveSetupMetadata({
+                    config,
+                    sandbox,
+                    shellCommand,
+                    remoteCwd,
+                    sourceTemplateRef: params.sourceTemplateRef,
+                }),
+            };
+        }
+        catch (error) {
+            await sandbox.delete(toTimeoutSeconds(config.timeoutMs)).catch(() => undefined);
+            throw error;
+        }
+    },
+    async onEnvironmentGetInteractiveSetup(params) {
+        const config = parseDriverConfig(params.config);
+        if (!params.providerLeaseId) {
+            return {
+                providerLeaseId: null,
+                status: "missing",
+                connectionSummary: null,
+                connectionPayload: null,
+                metadata: {
+                    provider: "daytona",
+                    missing: true,
+                },
+            };
+        }
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.providerLeaseId,
+            config,
+        };
+        return await withSandboxActivityGate(scope, async () => {
+            const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
+            if (!sandbox) {
+                return {
+                    providerLeaseId: null,
+                    status: "missing",
+                    connectionSummary: null,
+                    connectionPayload: null,
+                    metadata: {
+                        provider: "daytona",
+                        missing: true,
+                    },
+                };
+            }
+            await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
+            const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
+            const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
+            const connection = params.includeConnectionPayload === true
+                ? await createSshConnection(sandbox, resolveConnectionExpiresInMinutes(params.connectionExpiresInMinutes))
+                : {
+                    connectionSummary: {
+                        type: "ssh",
+                        username: "token",
+                        hostRedacted: true,
+                        portRedacted: true,
+                        commandRedacted: true,
+                        metadata: {
+                            provider: "daytona",
+                        },
+                    },
+                    connectionPayload: null,
+                };
+            return {
+                providerLeaseId: sandbox.id,
+                status: "waiting_for_user",
+                ...connection,
+                metadata: interactiveSetupMetadata({
+                    config,
+                    sandbox,
+                    shellCommand,
+                    remoteCwd,
+                }),
+            };
+        });
+    },
+    async onEnvironmentCaptureTemplate(params) {
+        const config = parseDriverConfig(params.config);
+        if (!params.providerLeaseId) {
+            throw new Error("Cannot capture a Daytona template without a setup sandbox lease.");
+        }
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.providerLeaseId,
+            config,
+        };
+        return await withSandboxActivityGate(scope, async () => {
+            const sandbox = await getSandbox(scope, { bypassTeardownGate: true });
+            const createSnapshot = sandbox._experimental_createSnapshot;
+            if (typeof createSnapshot !== "function") {
+                throw new Error("Daytona template capture requires @daytonaio/sdk Sandbox._experimental_createSnapshot support.");
+            }
+            const templateRef = sanitizeSnapshotName(params.templateLabel, `paperclip-${params.environmentId}-${randomUUID().slice(0, 8)}`);
+            const timeoutMs = typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0
+                ? Math.trunc(params.timeoutMs)
+                : config.timeoutMs;
+            await createSnapshot.call(sandbox, templateRef, toTimeoutSeconds(timeoutMs));
+            return {
+                templateKind: "snapshot",
+                templateRef,
+                metadata: {
+                    provider: "daytona",
+                    sandboxId: sandbox.id,
+                    capturedAt: new Date().toISOString(),
+                    sourceTemplateRefRedacted: Boolean(params.sourceTemplateRef),
+                    previousTemplateRefRedacted: Boolean(params.previousTemplateRef),
+                    timeoutMs,
+                },
+            };
+        });
+    },
+    async onEnvironmentCancelInteractiveSetup(params) {
+        const config = parseDriverConfig(params.config);
+        if (!params.providerLeaseId) {
+            return {
+                status: "missing",
+                metadata: {
+                    provider: "daytona",
+                    missing: true,
+                    reason: params.reason ?? null,
+                },
+            };
+        }
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.providerLeaseId,
+            config,
+        };
+        // C4: cancelling an interactive-setup lease deletes the sandbox, so the
+        // teardown gate blocks fresh cache reads while delete is in flight.
+        const teardownGate = sandboxHandleTeardownGates.begin(scope);
+        sandboxHandleLeaseAdmissionStates.close(scope);
+        try {
+            const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
+            if (!sandbox) {
+                return {
+                    status: "missing",
+                    metadata: {
+                        provider: "daytona",
+                        missing: true,
+                        reason: params.reason ?? null,
+                    },
+                };
+            }
+            evictSandboxHandle(scope);
+            await sandboxHandleActivityGates.waitForIdle(scope);
+            await teardownSession(sandbox, scope);
+            await sandbox.delete(toTimeoutSeconds(config.timeoutMs));
+            return {
+                status: params.reason === "timed_out" ? "timed_out" : "cancelled",
+                metadata: {
+                    provider: "daytona",
+                    sandboxId: sandbox.id,
+                    reason: params.reason ?? null,
+                },
+            };
+        }
+        finally {
+            sandboxHandleTeardownGates.end(scope, teardownGate);
+            evictSandboxHandle(scope);
+        }
+    },
+    async onEnvironmentDeleteTemplate(params) {
+        const templateKind = params.templateKind ?? "snapshot";
+        if (templateKind !== "snapshot") {
+            throw new Error(`Daytona can delete snapshot templates only, not ${templateKind}.`);
+        }
+        const config = parseDriverConfig(params.config);
+        const client = createDaytonaClient(config);
+        const snapshotService = client.snapshot;
+        if (typeof snapshotService?.get !== "function" || typeof snapshotService.delete !== "function") {
+            throw new Error("Daytona template deletion requires @daytonaio/sdk snapshot.get/delete support.");
+        }
+        const snapshot = await snapshotService.get(params.templateRef);
+        await snapshotService.delete(snapshot);
+        return {
+            deleted: true,
+            metadata: {
+                provider: "daytona",
+                templateKind: "snapshot",
+                templateRefRedacted: true,
+                reason: params.reason ?? null,
+            },
+        };
+    },
+    async onEnvironmentExecute(params) {
+        if (!params.lease.providerLeaseId) {
+            return {
+                exitCode: 1,
+                timedOut: false,
+                stdout: "",
+                stderr: "No provider lease ID available for execution.",
+            };
+        }
+        const config = parseDriverConfig(params.config);
+        const providerLeaseId = params.lease.providerLeaseId;
+        return await withSandboxActivityGate({
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId,
+            config,
+        }, async () => {
+            // Time the sandbox handle lookup (Open Q1) separately from the
+            // `executeCommand` round-trip so telemetry can split the per-call get cost
+            // from the exec cost. With the per-lease handle cache this collapses to ~0
+            // on a hit (no `client.get` REST round-trip), but the field stays present so
+            // `providerGetMs` remains observable — and still captures the occasional
+            // freshness refresh the cache issues after an idle gap. `ensureSandboxStarted`
+            // is a no-op for an already-started sandbox, so it is excluded from the get
+            // measurement.
+            const getStart = timingNow();
+            // Decide the explicit `cache_hit` flag at the true cache decision: the
+            // handle lookup reports whether the warm cache served the handle or the
+            // lookup called `client.get`. This replaces the old `providerGetMs == 0`
+            // proxy. The default `false` covers the theoretical case where the lookup
+            // reports nothing.
+            let cacheHit = false;
+            const sandbox = await getSandbox({
+                driverKey: params.driverKey,
+                companyId: params.companyId,
+                environmentId: params.environmentId,
+                providerLeaseId,
+                config,
+            }, {
+                bypassTeardownGate: true,
+                onCacheDecision: (hit) => {
+                    cacheHit = hit;
+                },
+            });
+            const getDurationMs = timingNow() - getStart;
+            const scope = {
+                driverKey: params.driverKey,
+                companyId: params.companyId,
+                environmentId: params.environmentId,
+                providerLeaseId,
+                config,
+            };
+            if (sandbox.state !== "started") {
+                // A provider restart destroys Daytona process sessions. Drop the stale
+                // session id before starting the sandbox so runnerd recovery opens a
+                // new session instead of retrying a dead one for its whole grace.
+                sandboxHandleSessionStore.clear(scope);
+            }
+            await ensureSandboxStarted(sandbox, toTimeoutSeconds(resolveTimeoutMs(params.timeoutMs, config)));
+            // Dispatch the command. A normal command runs in the persistent session:
+            // the provider opens the one session on a cache miss and runs every command
+            // in it. The provider never falls back to a one-shot command to open a
+            // session; a cache miss creates one.
+            //
+            // A `bypassSession` command runs one-shot and does NOT open the session.
+            // The host sets this flag on a pre-run command (the workspace provision
+            // command) that runs before the run opens its trace root. Opening the
+            // session there would emit a `session.open` span with no run parent, and
+            // the span backend would drop it. With the bypass the session opens on the
+            // first in-run command, whose open span parents to the run trace.
+            let result;
+            if (!params.bypassSession) {
+                const sessionId = await getOrCreateSession(sandbox, scope);
+                result = await executeInSession(sandbox, sessionId, params, config);
+            }
+            else {
+                result = await executeOneShot(sandbox, params, config);
+            }
+            if (!result.timedOut) {
+                sandboxHandleCache.markFresh(scope);
+            }
+            return {
+                ...result,
+                metadata: { ...(result.metadata ?? {}), getDurationMs, cacheHit },
+            };
+        });
+    },
+    async onEnvironmentRunnerIngressEndpoint(params) {
+        if (params.port !== 43_127) {
+            throw new Error("Daytona runner ingress must use fixed port 43127.");
+        }
+        if (!/^\/api\/runner\/v1\/connect\/[^/?#]+$/.test(params.path)) {
+            throw new Error("Daytona runner ingress path is invalid.");
+        }
+        const providerLeaseId = params.lease.providerLeaseId;
+        if (!providerLeaseId) {
+            throw new Error("Daytona runner ingress requires a provider lease id.");
+        }
+        const config = parseDriverConfig(params.config);
+        return await withSandboxActivityGate({
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId,
+            config,
+        }, async () => {
+            const sandbox = await getSandbox({
+                driverKey: params.driverKey,
+                companyId: params.companyId,
+                environmentId: params.environmentId,
+                providerLeaseId,
+                config,
+            });
+            await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
+            await withLivenessTimeout("sandbox.refreshData", config.livenessTimeoutMs, () => sandbox.refreshData());
+            const preview = await sandbox.getPreviewLink(params.port);
+            if (typeof preview.url !== "string" || typeof preview.token !== "string") {
+                throw new Error("Daytona returned an incomplete private preview endpoint.");
+            }
+            const url = new URL(preview.url);
+            if (url.protocol !== "https:" ||
+                url.username ||
+                url.password ||
+                url.search ||
+                url.hash) {
+                throw new Error("Daytona returned an invalid private preview URL.");
+            }
+            url.protocol = "wss:";
+            url.pathname = `${url.pathname.replace(/\/$/, "")}${params.path}`;
+            return {
+                kind: "authenticated_websocket",
+                websocketUrl: url.toString(),
+                secretHeaders: [
+                    { name: "X-Daytona-Preview-Token", value: preview.token },
+                ],
+                generation: runnerIngressGenerationStore.get(sandbox),
+            };
+        });
+    },
+    // Opt-in native inbound transfer. Defining this hook (with onEnvironmentSyncOut)
+    // makes the worker advertise `environmentSyncIn`/`environmentSyncOut`, so the
+    // host runner routes Daytona workspace/asset transfers through the SDK's batch
+    // `uploadFiles` (plus host-side tarballs for directories) instead of the
+    // base64-over-exec fallback. Providers that do not define these keep the
+    // byte-identical fallback.
+    async onEnvironmentSyncIn(params) {
+        if (!params.lease.providerLeaseId) {
+            throw new Error("Daytona syncIn requires a provider lease ID.");
+        }
+        const config = parseDriverConfig(params.config);
+        const remoteDir = resolveSyncRemoteDir(params.lease);
+        const timeoutSeconds = toTimeoutSeconds(config.timeoutMs);
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.lease.providerLeaseId,
+            config,
+        };
+        // Collect the advisory read-write destinations for this scope. This records
+        // intent only; it does not change the transfer below.
+        sandboxHandleWritableDirs.recordWritableTargets(scope, params.operations);
+        return await withSandboxActivityGate(scope, async () => {
+            const sandbox = await getSandbox(scope, { bypassTeardownGate: true });
+            await ensureSandboxStarted(sandbox, timeoutSeconds);
+            const result = await performSyncIn({
+                sandbox,
+                operations: params.operations,
+                remoteDir,
+                timeoutSeconds,
+            });
+            sandboxHandleCache.markFresh(scope);
+            return result;
+        });
+    },
+    // Opt-in native outbound transfer. See onEnvironmentSyncIn.
+    async onEnvironmentSyncOut(params) {
+        if (!params.lease.providerLeaseId) {
+            throw new Error("Daytona syncOut requires a provider lease ID.");
+        }
+        const config = parseDriverConfig(params.config);
+        const remoteDir = resolveSyncRemoteDir(params.lease);
+        const timeoutSeconds = toTimeoutSeconds(config.timeoutMs);
+        const scope = {
+            driverKey: params.driverKey,
+            companyId: params.companyId,
+            environmentId: params.environmentId,
+            providerLeaseId: params.lease.providerLeaseId,
+            config,
+        };
+        try {
+            return await withSandboxActivityGate(scope, async () => {
+                const sandbox = await withEnvironmentSyncTransferStep("sandbox_access", async () => {
+                    const resolved = await getSandbox(scope, { bypassTeardownGate: true });
+                    await ensureSandboxStarted(resolved, timeoutSeconds);
+                    return resolved;
+                });
+                const result = await performSyncOut({
+                    sandbox,
+                    operations: params.operations,
+                    remoteDir,
+                    timeoutSeconds,
+                    onArchiveRecovery: () => pluginContext?.logger.info("Workspace export omitted unsafe links; retrying with confined entries."),
+                });
+                sandboxHandleCache.markFresh(scope);
+                return result;
+            });
+        }
+        catch (error) {
+            // A deleted Daytona sandbox is the one provider failure that proves its
+            // unexported workspace bytes no longer exist. Convert the SDK class to a
+            // stable cross-worker message; every other error remains retryable.
+            if (error instanceof DaytonaNotFoundError) {
+                throw preserveEnvironmentSyncErrorDiagnostic(new Error("daytona_sandbox_not_found"), error);
+            }
+            throw error;
+        }
+    },
+    // Open one live login pseudo-terminal. Resolve the cached sandbox by the
+    // provider lease id, revalidate the host launch descriptor, create the session
+    // home with one `mkdir -p` command, run the fixed login command on a real
+    // pseudo-terminal, and register the session under the host route id. Stream the
+    // raw output and the exit through `ctx.loginPty`, bound to the returned worker
+    // session id. Fail closed when no cached sandbox matches the lease.
+    async onLoginPtyOpen(params) {
+        const sandbox = await sandboxHandleCache.findByProviderLeaseId(params.providerLeaseId);
+        if (!sandbox) {
+            throw new Error("Daytona login pseudo-terminal: no cached sandbox resolves the provider lease.");
+        }
+        const homeFs = createDaytonaLoginHomeFs(sandbox.process);
+        const session = await openLoginPtySession(sandbox.process, homeFs, { loginCommandKey: params.loginCommandKey, sessionHome: params.sessionHome });
+        const workerSessionId = `pty-${randomUUID()}`;
+        const entry = {
+            hostRouteId: params.hostRouteId,
+            workerSessionId,
+            session,
+        };
+        daytonaLoginPtyByRoute.set(params.hostRouteId, entry);
+        daytonaLoginPtyBySession.set(workerSessionId, entry);
+        // Register the output listener before the first input, so no early output
+        // chunk is lost. The client stamps the host route identifier and the worker
+        // session identifier, so the host can hold more than one concurrent login
+        // pseudo-terminal on this worker and binds the output to its own route.
+        session.onData((chunk) => {
+            pluginContext?.loginPty.output(params.hostRouteId, workerSessionId, chunk);
+        });
+        // Forward the child exit one time. The host resolves the login run on it.
+        void session.wait().then((result) => pluginContext?.loginPty.exit(params.hostRouteId, workerSessionId, result.exitCode), () => pluginContext?.loginPty.exit(params.hostRouteId, workerSessionId, null));
+        return { workerSessionId };
+    },
+    // Write delayed input to an open login pseudo-terminal, keyed by the worker
+    // session id. Drop the input for an unknown session.
+    async onLoginPtyInput(params) {
+        const entry = daytonaLoginPtyBySession.get(params.workerSessionId);
+        if (!entry)
+            return;
+        entry.session.write(params.data);
+    },
+    // Stop an open login pseudo-terminal child, keyed by the worker session id.
+    async onLoginPtyStop(params) {
+        const entry = daytonaLoginPtyBySession.get(params.workerSessionId);
+        if (!entry)
+            return;
+        entry.session.kill();
+    },
+    // Close an open login pseudo-terminal by the host route id and acknowledge the
+    // close with the same identifier. The close is idempotent: it returns the
+    // acknowledgement even when the entry is already gone, so the host confirms the
+    // terminal is closed. The worker never keys the close on the worker session id.
+    async onLoginPtyClose(params) {
+        const entry = daytonaLoginPtyByRoute.get(params.hostRouteId);
+        if (entry) {
+            forgetDaytonaLoginPty(entry);
+            await entry.session.close().catch(() => undefined);
+        }
+        return { hostRouteId: params.hostRouteId };
+    },
+    // Open one persistent duplex channel. Resolve the cached sandbox by the provider
+    // lease id, run the gateway command on a raw pseudo-terminal, and register the
+    // channel under the host route id. Stream the raw data and the exit through
+    // `ctx.duplexChannel`, bound to the returned worker session id. Fail closed when
+    // no cached sandbox matches the lease.
+    async onDuplexChannelOpen(params) {
+        const sandbox = await sandboxHandleCache.findByProviderLeaseId(params.providerLeaseId);
+        if (!sandbox) {
+            throw new Error("Daytona duplex channel: no cached sandbox resolves the provider lease.");
+        }
+        const session = await openDuplexChannelSession(sandbox.process, params.command);
+        const workerSessionId = `duplex-${randomUUID()}`;
+        const entry = {
+            hostRouteId: params.hostRouteId,
+            workerSessionId,
+            providerLeaseId: params.providerLeaseId,
+            session,
+        };
+        daytonaDuplexChannelByRoute.set(params.hostRouteId, entry);
+        daytonaDuplexChannelBySession.set(workerSessionId, entry);
+        // Register the data listener before the first write, so no early data chunk is
+        // lost. The client echoes the host route id and the worker session id, so the
+        // host routes the data to the exact live pair.
+        session.onData((chunk) => {
+            pluginContext?.duplexChannel.data(entry.hostRouteId, workerSessionId, chunk);
+        });
+        // Forward the child exit one time. The host resolves the open route on it. A
+        // numeric exit code is a real process exit; a resolved transport close carries
+        // `transportClosed`, so the host keeps the two apart in the loss taxonomy. A
+        // rejected wait is not a resolved transport close, so it reports no code and no
+        // transport-close mark.
+        void session.wait().then((result) => pluginContext?.duplexChannel.exit(entry.hostRouteId, workerSessionId, result.exitCode, result.transportClosed), () => pluginContext?.duplexChannel.exit(entry.hostRouteId, workerSessionId, null));
+        // Echo the host route id on the reply, so the host binds the exact pair.
+        return { hostRouteId: params.hostRouteId, workerSessionId };
+    },
+    // Write host input to an open duplex channel. Act only on the exact live pair.
+    // A write whose pair does not match the bound entry applies no bytes.
+    //
+    // `params.data` arrives in the wire-safe base64 form (JSON carries no binary
+    // type; see `ChannelBytesWireValue` in the plugin SDK's protocol.ts). Decode it
+    // back to raw bytes before it reaches the pseudo-terminal. A malformed value
+    // decodes to `null`; the worker applies no bytes rather than sending an empty
+    // write to the sandbox.
+    async onDuplexChannelWrite(params) {
+        const entry = daytonaDuplexChannelBySession.get(params.workerSessionId);
+        if (!entry || entry.hostRouteId !== params.hostRouteId)
+            return;
+        const data = decodeChannelBytes(params.data);
+        if (data === null)
+            return;
+        entry.session.write(data);
+    },
+    // Stop an open duplex channel child. Act only on the exact live pair. A stop
+    // whose pair does not match the bound entry stops nothing.
+    async onDuplexChannelStop(params) {
+        const entry = daytonaDuplexChannelBySession.get(params.workerSessionId);
+        if (!entry || entry.hostRouteId !== params.hostRouteId)
+            return;
+        entry.session.kill();
+    },
+    // Close an open duplex channel by the host route id and acknowledge the close.
+    // The host route id is the authoritative close key, so a pre-bind close with a
+    // lost open reply still closes the channel. On a bound close the acknowledgement
+    // echoes the worker session id too, so the host verifies the exact pair. The
+    // close is idempotent: it returns the acknowledgement even when the entry is
+    // already gone, so the host confirms the channel is closed.
+    async onDuplexChannelClose(params) {
+        const entry = daytonaDuplexChannelByRoute.get(params.hostRouteId);
+        if (entry) {
+            const boundWorkerSessionId = entry.workerSessionId;
+            forgetDaytonaDuplexChannel(entry);
+            await entry.session.close().catch(() => undefined);
+            return { hostRouteId: params.hostRouteId, workerSessionId: boundWorkerSessionId };
+        }
+        return { hostRouteId: params.hostRouteId };
+    },
+    // Close every open login pseudo-terminal and every open duplex channel on an
+    // orderly shutdown, then drain the sandbox handle cache, so a graceful shutdown
+    // holds no live terminal and no live channel.
+    async onShutdown() {
+        const openSessions = [...daytonaLoginPtyByRoute.values()];
+        daytonaLoginPtyByRoute.clear();
+        daytonaLoginPtyBySession.clear();
+        for (const entry of openSessions) {
+            await entry.session.close().catch(() => undefined);
+        }
+        const openChannels = [...daytonaDuplexChannelByRoute.values()];
+        daytonaDuplexChannelByRoute.clear();
+        daytonaDuplexChannelBySession.clear();
+        for (const entry of openChannels) {
+            await entry.session.close().catch(() => undefined);
+        }
+        sandboxHandleCache.reset();
+        runnerIngressGenerationStore.reset();
+    },
+});
+export default plugin;
+//# sourceMappingURL=plugin.js.map