nolo-cli 0.148.0-alpha.1 → 0.151.0-alpha.2

package/chunk-YVPQATSC.js

@@ -0,0 +1,709 @@
+// packages/agent-runtime/dockerQuotaStore.ts
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from "node:fs";
+var InMemoryDockerQuotaKvStore = class {
+  store = /* @__PURE__ */ new Map();
+  async get(key) {
+    const val = this.store.get(key);
+    return val ? JSON.parse(JSON.stringify(val)) : null;
+  }
+  async put(key, record) {
+    this.store.set(key, JSON.parse(JSON.stringify(record)));
+  }
+};
+var FileDockerQuotaKvStore = class {
+  filePath;
+  constructor(filePath) {
+    this.filePath = filePath ?? join(process.env.NOLO_HOME || resolve(homedir(), ".nolo"), "docker-quota.json");
+  }
+  async get(key) {
+    try {
+      if (!existsSync(this.filePath)) {
+        return null;
+      }
+      const raw = readFileSync(this.filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object") {
+        return null;
+      }
+      if (parsed.key === key) {
+        return parsed;
+      }
+      if (key in parsed) {
+        return parsed[key] ?? null;
+      }
+      return null;
+    } catch (err) {
+      console.warn(`[FileDockerQuotaKvStore] Warning: failed to parse quota file at ${this.filePath}:`, err);
+      return null;
+    }
+  }
+  async put(key, record) {
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    let data = {};
+    try {
+      if (existsSync(this.filePath)) {
+        const raw = readFileSync(this.filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          if (parsed.key && typeof parsed.key === "string" && !parsed[parsed.key]) {
+            data[parsed.key] = parsed;
+          } else {
+            data = parsed;
+          }
+        }
+      }
+    } catch (err) {
+      console.warn(`[FileDockerQuotaKvStore] Warning: corrupted quota file at ${this.filePath}, resetting content:`, err);
+      data = {};
+    }
+    data[key] = record;
+    const tmpPath = `${this.filePath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+    try {
+      writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+      renameSync(tmpPath, this.filePath);
+    } catch (err) {
+      try {
+        if (existsSync(tmpPath)) {
+          unlinkSync(tmpPath);
+        }
+      } catch {
+      }
+      throw err;
+    }
+  }
+};
+function buildDockerQuotaKey(owner, dockerAccount) {
+  if (!owner || !dockerAccount) {
+    throw new Error("Both owner and dockerAccount must be non-empty to build quota key");
+  }
+  return `docker-quota:${owner}:${dockerAccount}`;
+}
+
+// packages/agent-runtime/dockerBudgetAdmission.ts
+var DEFAULT_MAX_STALENESS_MS = 5 * 60 * 1e3;
+function calculateEstimatedBudget(ttlSeconds, rateNanoUsd) {
+  if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+    throw new Error("Invalid ttlSeconds: must be positive finite number");
+  }
+  if (rateNanoUsd <= 0n) {
+    throw new Error("Invalid rateNanoUsd: must be positive non-zero bigint");
+  }
+  const ceilSeconds = BigInt(Math.ceil(ttlSeconds));
+  return ceilSeconds * rateNanoUsd;
+}
+
+// packages/agent-runtime/dockerSandboxCloudSpec.ts
+var SANDBOX_BILLABLE_SHAPES = [
+  { id: "micro1/2G", cpus: 1, memory: "2g" },
+  { id: "small2/4G", cpus: 2, memory: "4g" },
+  { id: "medium4/8G", cpus: 4, memory: "8g" },
+  { id: "large8/16G", cpus: 8, memory: "16g" },
+  { id: "xl16/32G", cpus: 16, memory: "32g" }
+];
+var SANDBOX_DEFAULT_SHAPE = "medium4/8G";
+function billableSandboxShape(id) {
+  const found = SANDBOX_BILLABLE_SHAPES.find((x) => x.id === id);
+  if (!found) throw Error(`Non-billable sandbox shape: ${id}`);
+  return found;
+}
+function pinnedBunSandboxImage(pinnedBun) {
+  return `docker.io/oven/bun:${pinnedBun}`;
+}
+var SANDBOX_DEFAULT_PLATFORM = "linux/amd64";
+function buildSbxCloudCreateArgv(spec) {
+  const shape = billableSandboxShape(spec.shapeId ?? SANDBOX_DEFAULT_SHAPE);
+  const args = ["--cloud", "create", "--name", spec.name];
+  if (spec.template !== void 0) {
+    args.push("--template", spec.template);
+  } else {
+    args.push(
+      "--image-ref",
+      spec.image ?? pinnedBunSandboxImage(Bun.version),
+      "--cpus",
+      String(shape.cpus),
+      "--memory",
+      shape.memory
+    );
+  }
+  args.push(
+    "--platform",
+    SANDBOX_DEFAULT_PLATFORM,
+    "--ttl",
+    `${spec.ttlMinutes}m`,
+    "--on-timeout",
+    spec.onTimeout ?? "stop"
+  );
+  return args;
+}
+
+// packages/agent-runtime/dockerSandboxExecutionBackend.ts
+var DOCKER_SANDBOX_BACKEND_ID = "docker-sandbox-cloud";
+var SAFE_MESSAGE = {
+  "invalid-ticket": "Rejected: execution ticket cannot be satisfied by the docker sandbox backend",
+  "quota-unverifiable": "Rejected before any sandbox side effect: docker quota could not be verified",
+  "quota-insufficient": "Rejected before any sandbox side effect: docker quota is below the estimated budget",
+  "concurrency-rejected": "Rejected: this docker account already holds the maximum number of active sandboxes",
+  "create-failed": "Sandbox create failed",
+  "lease-not-found": "Unknown execution lease",
+  "lease-mismatch": "Lease does not match this backend or ticket",
+  "lease-released": "Lease was already released",
+  "unsupported-request": "Request kind is not supported by the docker sandbox backend",
+  "exec-timeout": "Sandbox exec exceeded the backend execution bound and was killed",
+  "exec-failed": "Sandbox exec could not be completed",
+  "quota-record-failed": "Sandbox run aborted: docker quota bookkeeping could not be persisted",
+  "stop-unverified": "Sandbox stop could not be confirmed; cleanup is pending"
+};
+var DockerSandboxBackendError = class extends Error {
+  code;
+  /** true = 云端可能仍有存活沙盒，调用方不得当作已清理。 */
+  cleanupPending;
+  constructor(code, detail, cleanupPending = false) {
+    super(detail ? `${SAFE_MESSAGE[code]} (${detail})` : SAFE_MESSAGE[code]);
+    this.name = "DockerSandboxBackendError";
+    this.code = code;
+    this.cleanupPending = cleanupPending;
+  }
+};
+var DEFAULT_TTL_MINUTES = 15;
+var DEFAULT_MAX_OUTPUT_CHARS = 8e3;
+var DEFAULT_EXEC_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_ACTIVE_SANDBOXES_PER_ACCOUNT = 3;
+function resolveMaxActiveSandboxesFromEnv(env = process.env) {
+  const raw = (env.NOLO_DOCKER_MAX_ACTIVE_SANDBOXES ?? "").trim();
+  if (!raw) return null;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(
+      `NOLO_DOCKER_MAX_ACTIVE_SANDBOXES \u5FC5\u987B\u662F\u6B63\u6574\u6570\uFF0C\u6536\u5230 "${raw}"\uFF1B\u62D2\u7EDD\u9759\u9ED8\u56DE\u843D\u9ED8\u8BA4\u503C`
+    );
+  }
+  return parsed;
+}
+var UNVERIFIED_QUOTA_RATE_NANO_USD = 77780n;
+var SHELL_EXECUTABLES = /* @__PURE__ */ new Set([
+  "bash",
+  "sh",
+  "zsh",
+  "dash",
+  "ksh",
+  "mksh",
+  "ash",
+  "fish"
+]);
+var EXEC_TIMEOUT_KILL_GRACE_MS = 2e3;
+var STALE_RUNNING_SLACK_MS = 6e4;
+var SANDBOX_NAME_PATTERN = /^agent-sbx-[A-Za-z0-9][A-Za-z0-9_-]{0,47}-[a-z0-9]{1,13}$/;
+var SATISFIABLE_ISOLATION = /* @__PURE__ */ new Set(["none", "os-sandbox", "container"]);
+function buildDockerSandboxName(ticketId, ts) {
+  const safeId = ticketId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 48) || "run";
+  const name = `agent-sbx-${safeId}-${ts.toString(36)}`;
+  if (!SANDBOX_NAME_PATTERN.test(name)) {
+    throw new DockerSandboxBackendError("invalid-ticket", "sandbox name rejected");
+  }
+  return name;
+}
+function argvToShellScript(argv) {
+  const quote = (token) => `'${token.replaceAll("'", `'\\''`)}'`;
+  if (argv.length === 3 && argv[0] === "bash" && argv[1] === "-lc") return argv[2];
+  return argv.map(quote).join(" ");
+}
+function truncateOutput(value, limitChars) {
+  if (value.length <= limitChars) return value;
+  return `${value.slice(0, limitChars)}\u2026[truncated ${value.length - limitChars} chars]`;
+}
+async function defaultRunSbx(args, options = {}) {
+  const { spawn } = await import("node:child_process");
+  const timeoutMs = typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : void 0;
+  return await new Promise((resolve2) => {
+    const child = spawn("sbx", [...args], {
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let timeoutTimer;
+    let killGraceTimer;
+    const settle = (exitCode) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killGraceTimer) clearTimeout(killGraceTimer);
+      resolve2({ exitCode, stdout, stderr, ...timedOut ? { timedOut: true } : {} });
+    };
+    child.stdout?.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", () => settle(null));
+    child.on("close", (code) => settle(code ?? null));
+    if (timeoutMs !== void 0) {
+      timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+        killGraceTimer = setTimeout(() => settle(null), EXEC_TIMEOUT_KILL_GRACE_MS);
+      }, timeoutMs);
+    }
+  });
+}
+function buildSandboxSlotKey(quotaKey, slot) {
+  return slot === 1 ? quotaKey : `${quotaKey}#slot:${slot}`;
+}
+function isShellArgv(argv) {
+  const head = argv[0];
+  if (typeof head !== "string" || !head) return false;
+  const base = head.split(/[\\/]/).pop()?.toLowerCase().replace(/\.exe$/, "") ?? "";
+  return SHELL_EXECUTABLES.has(base);
+}
+function staleRunningReason(record, nowMs, staleRunningAfterMs) {
+  const observedAt = record.observedAt;
+  if (typeof observedAt !== "number" || !Number.isFinite(observedAt)) return null;
+  const age = nowMs - observedAt;
+  if (!Number.isFinite(age) || age <= staleRunningAfterMs) return null;
+  return "observed-at-beyond-lifetime";
+}
+function buildStaleAuditKey(quotaKey, sandboxName) {
+  const safeSandbox = typeof sandboxName === "string" ? sandboxName.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 64) || "unknown" : "unknown";
+  return `${quotaKey}#stale:${safeSandbox}`;
+}
+function deriveStaleRunningMs(ttlMinutes, execTimeoutMs) {
+  return ttlMinutes * 6e4 + execTimeoutMs + STALE_RUNNING_SLACK_MS;
+}
+function warnBookkeeping(phase, extra = {}) {
+  console.warn(
+    `[dockerSandboxExecutionBackend] ${JSON.stringify({
+      event: "quota-bookkeeping-failed",
+      phase,
+      ...extra
+    })}`
+  );
+}
+var accountLockTails = /* @__PURE__ */ new Map();
+function createDockerSandboxExecutionBackend(deps = {}) {
+  const runSbx = deps.runSbx ?? defaultRunSbx;
+  const kvStore = deps.kvStore ?? new InMemoryDockerQuotaKvStore();
+  const now = deps.now ?? (() => Date.now());
+  const owner = deps.owner ?? "local-owner";
+  const dockerAccount = deps.dockerAccount ?? "default-account";
+  const shapeId = deps.shapeId ?? SANDBOX_DEFAULT_SHAPE;
+  const ttlMinutes = deps.ttlMinutes ?? DEFAULT_TTL_MINUTES;
+  const maxOutputChars = deps.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+  const leases = /* @__PURE__ */ new Map();
+  const descriptor = {
+    id: DOCKER_SANDBOX_BACKEND_ID,
+    kind: "cloud",
+    capabilities: {
+      executionClasses: ["oneshot"],
+      streamingExec: false,
+      filesystem: true,
+      persistentFilesystem: false,
+      processSignals: false,
+      inboundPorts: false,
+      networkPolicy: false,
+      snapshots: false,
+      gpu: false,
+      isolationModes: ["container"]
+    }
+  };
+  const writeQuotaRecord = async (key, patch, before) => {
+    const previous = await kvStore.get(key).catch(() => null);
+    await kvStore.put(key, {
+      key,
+      owner,
+      dockerAccount,
+      remainingNanoUsd: patch.remainingNanoUsd ?? previous?.remainingNanoUsd ?? "0",
+      observedAt: patch.observedAt ?? previous?.observedAt ?? now(),
+      pendingEstimateNanoUsd: patch.pendingEstimateNanoUsd ?? "0",
+      estimatedSpendNanoUsd: patch.estimatedSpendNanoUsd ?? previous?.estimatedSpendNanoUsd ?? "0",
+      taskId: patch.taskId ?? previous?.taskId ?? "",
+      sandbox: patch.sandbox ?? previous?.sandbox ?? "",
+      status: patch.status ?? previous?.status ?? "idle",
+      // stale 必须能表达「显式清掉」：只有调用方完全不表态（undefined）才继承上一条
+      // 记录。否则一次 stale:true 会沿 running→终态→running 永久连锁继承，把并发
+      // 闸门的年龄判定打穿（C1）。new running 写入一律显式传 stale:false。
+      ...patch.stale === void 0 ? previous?.stale === void 0 ? {} : { stale: previous.stale } : { stale: patch.stale },
+      beforeAfter: {
+        ...before ? { before } : previous?.beforeAfter?.before ? { before: previous.beforeAfter.before } : {},
+        ...previous?.beforeAfter?.after ? { after: previous.beforeAfter.after } : {}
+      }
+    });
+  };
+  const positiveMs = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+  const baseExecTimeoutMs = positiveMs(deps.execTimeoutMs) ?? DEFAULT_EXEC_TIMEOUT_MS;
+  const defaultExecTimeoutMs = positiveMs(deps.execTimeouts?.defaultMs) ?? baseExecTimeoutMs;
+  const shellExecTimeoutMs = positiveMs(deps.execTimeouts?.shellMs) ?? baseExecTimeoutMs;
+  const maxExecTimeoutMs = Math.max(defaultExecTimeoutMs, shellExecTimeoutMs);
+  const maxActiveSandboxes = typeof deps.maxActiveSandboxesPerAccount === "number" && Number.isInteger(deps.maxActiveSandboxesPerAccount) && deps.maxActiveSandboxesPerAccount > 0 ? deps.maxActiveSandboxesPerAccount : resolveMaxActiveSandboxesFromEnv() ?? DEFAULT_MAX_ACTIVE_SANDBOXES_PER_ACCOUNT;
+  const staleRunningAfterMs = typeof deps.staleRunningAfterMs === "number" && Number.isFinite(deps.staleRunningAfterMs) && deps.staleRunningAfterMs > 0 ? deps.staleRunningAfterMs : deriveStaleRunningMs(ttlMinutes, maxExecTimeoutMs);
+  const controlTimeoutMs = maxExecTimeoutMs;
+  const persistQuotaRecord = async (phase, key, patch, before) => {
+    try {
+      await writeQuotaRecord(key, patch, before);
+      return true;
+    } catch (error) {
+      warnBookkeeping(phase, {
+        sandbox: patch.sandbox ?? "",
+        reason: error instanceof Error ? error.name : typeof error
+      });
+      return false;
+    }
+  };
+  const readConcurrencyGate = async (key) => {
+    try {
+      return await kvStore.get(key);
+    } catch {
+      throw new DockerSandboxBackendError("quota-unverifiable", "quota store read failed");
+    }
+  };
+  const runningRecordPersisted = async (key, sandboxName) => {
+    try {
+      const record = await kvStore.get(key);
+      return record?.status === "running" && record.sandbox === sandboxName;
+    } catch (error) {
+      warnBookkeeping("running-verify", {
+        sandbox: sandboxName,
+        reason: error instanceof Error ? error.name : typeof error
+      });
+      return false;
+    }
+  };
+  const runWithAccountLock = async (key, fn) => {
+    const previous = accountLockTails.get(key) ?? Promise.resolve();
+    const run = previous.catch(() => void 0).then(fn);
+    const tail = run.catch(() => void 0);
+    accountLockTails.set(key, tail);
+    try {
+      return await run;
+    } finally {
+      if (accountLockTails.get(key) === tail) accountLockTails.delete(key);
+    }
+  };
+  const archiveStaleSlotRecord = async (slotKey, record) => {
+    await persistQuotaRecord(
+      "stale-running-archive",
+      buildStaleAuditKey(slotKey, record.sandbox),
+      // 归档记的是「可能仍在计费的泄漏沙盒」：金额与归属必须从被回收的那条
+      // 记录原样带入。改用 0/空串顶替（本函数对缺省字段的回落行为）会把敞口
+      // 与责任归属一起抹掉，事后无法对账、无法定位泄漏来源（M-2）。
+      {
+        status: "running",
+        stale: true,
+        sandbox: record.sandbox ?? "",
+        observedAt: record.observedAt,
+        remainingNanoUsd: record.remainingNanoUsd,
+        pendingEstimateNanoUsd: record.pendingEstimateNanoUsd,
+        estimatedSpendNanoUsd: record.estimatedSpendNanoUsd,
+        taskId: record.taskId
+      }
+    );
+  };
+  const reserveActiveSlot = async (quotaKey) => {
+    let cloudPresence = null;
+    const cloudSandboxPresence = () => {
+      cloudPresence ??= probeCloudSandboxPresence(runSbx, controlTimeoutMs);
+      return cloudPresence;
+    };
+    for (let slot = 1; slot <= maxActiveSandboxes; slot += 1) {
+      const slotKey = buildSandboxSlotKey(quotaKey, slot);
+      const record = await readConcurrencyGate(slotKey);
+      if (record?.status !== "running") return slotKey;
+      const staleReason = staleRunningReason(record, now(), staleRunningAfterMs);
+      if (staleReason) {
+        warnBookkeeping("stale-running-reclaimed", {
+          sandbox: record.sandbox ?? "",
+          reason: staleReason
+        });
+        await archiveStaleSlotRecord(slotKey, record);
+        return slotKey;
+      }
+      const sandboxName = typeof record.sandbox === "string" ? record.sandbox : "";
+      if (!sandboxName) {
+        warnBookkeeping("sandbox-presence-unverifiable", { reason: "no-sandbox-reference" });
+        throw new DockerSandboxBackendError(
+          "quota-unverifiable",
+          "active sandbox record carries no sandbox reference"
+        );
+      }
+      const presence = await cloudSandboxPresence();
+      if (!presence.ok) {
+        warnBookkeeping("sandbox-presence-unverifiable", {
+          sandbox: sandboxName,
+          reason: presence.reason
+        });
+        throw new DockerSandboxBackendError(
+          "quota-unverifiable",
+          "active sandbox presence could not be verified against the cloud listing"
+        );
+      }
+      if (presence.names.has(sandboxName)) continue;
+      warnBookkeeping("stale-running-reclaimed", {
+        sandbox: sandboxName,
+        reason: "absent-from-cloud-listing"
+      });
+      await archiveStaleSlotRecord(slotKey, record);
+      return slotKey;
+    }
+    throw new DockerSandboxBackendError(
+      "concurrency-rejected",
+      `active sandbox limit ${maxActiveSandboxes} reached`
+    );
+  };
+  return {
+    describe() {
+      return descriptor;
+    },
+    async prepare(ticket) {
+      if (ticket.version !== 1 || !ticket.ticketId || !ticket.grantId || ticket.shellAllowed !== true || !SATISFIABLE_ISOLATION.has(ticket.requestedIsolation)) {
+        throw new DockerSandboxBackendError("invalid-ticket");
+      }
+      if (ticket.target.kind !== "server" || ticket.executionClass !== "oneshot") {
+        throw new DockerSandboxBackendError("invalid-ticket", "target/class unsupported");
+      }
+      const quotaVerifyEnabled = deps.quotaVerify !== false;
+      const quota = quotaVerifyEnabled && deps.quotaProvider ? await deps.quotaProvider() : { ok: false, reason: "verification-disabled" };
+      if (quotaVerifyEnabled && !quota.ok) {
+        throw new DockerSandboxBackendError("quota-unverifiable");
+      }
+      const quotaRateNanoUsd = quota.ok ? quota.rateNanoUsd : UNVERIFIED_QUOTA_RATE_NANO_USD;
+      const estimatedNanoUsd = calculateEstimatedBudget(ttlMinutes * 60, quotaRateNanoUsd);
+      if (quota.ok && quota.availableNanoUsd < estimatedNanoUsd) {
+        throw new DockerSandboxBackendError("quota-insufficient");
+      }
+      const quotaKey = buildDockerQuotaKey(owner, dockerAccount);
+      return await runWithAccountLock(quotaKey, async () => {
+        const slotKey = await reserveActiveSlot(quotaKey);
+        const startedAt = now();
+        const sandboxName = deps.sandboxName ?? buildDockerSandboxName(ticket.ticketId, startedAt);
+        const reservedRecorded = await persistQuotaRecord(
+          "running",
+          slotKey,
+          {
+            // 未核实时没有 availableNanoUsd：记账写 "unverified" 而不是崩溃（RV-FATAL）
+            remainingNanoUsd: quota.ok ? quota.availableNanoUsd.toString() : "unverified",
+            // 槽位记录的年龄必须从「这条记录落盘的时刻」起算，沿用配额快照的
+            // observedAt 会让陈旧阈值被偷偷缩短（M-1）。配额观察时间没丢，仍在
+            // beforeAfter.before 里。
+            observedAt: now(),
+            pendingEstimateNanoUsd: estimatedNanoUsd.toString(),
+            estimatedSpendNanoUsd: "0",
+            taskId: ticket.ticketId,
+            sandbox: sandboxName,
+            status: "running",
+            // 显式清 stale：这条槽位记录代表**占位中的沙盒**，绝不能继承上一条终态
+            // 记录残留的 stale:true（否则它会被年龄之外的捷径判成可回收）。
+            stale: false
+          },
+          {
+            // 未核实时没有 availableNanoUsd：记账写 "unverified" 而不是崩溃（RV-FATAL）
+            remainingNanoUsd: quota.ok ? quota.availableNanoUsd.toString() : "unverified",
+            observedAt: quota.ok ? quota.observedAt : now()
+          }
+        );
+        if (!reservedRecorded || !await runningRecordPersisted(slotKey, sandboxName)) {
+          throw new DockerSandboxBackendError("quota-record-failed");
+        }
+        const create = await runSbx(
+          buildSbxCloudCreateArgv({ name: sandboxName, shapeId, ttlMinutes }),
+          { timeoutMs: controlTimeoutMs }
+        );
+        if (create.exitCode !== 0) {
+          await persistQuotaRecord("create-failed", slotKey, {
+            status: "failed",
+            sandbox: sandboxName,
+            taskId: ticket.ticketId
+          });
+          throw new DockerSandboxBackendError("create-failed");
+        }
+        const lease = {
+          leaseId: sandboxName,
+          backendId: descriptor.id,
+          ticketId: ticket.ticketId,
+          grantId: ticket.grantId,
+          createdAt: startedAt,
+          readableRoots: [],
+          writableRoots: [],
+          metadata: {
+            sandboxName,
+            estimatedNanoUsd: estimatedNanoUsd.toString(),
+            quotaKey,
+            slotKey,
+            /**
+             * release() 只 stop 不删除：沙盒在云端以 stopped 状态保留，
+             * 本后端从不发 `sbx rm`。调用方据此判断是否需要另行清理。
+             */
+            sandboxRetainedOnRelease: true
+          }
+        };
+        leases.set(lease.leaseId, {
+          ticketId: ticket.ticketId,
+          grantId: ticket.grantId,
+          sandboxName,
+          quotaKey,
+          slotKey,
+          estimatedNanoUsd,
+          startedAt,
+          released: false
+        });
+        return lease;
+      });
+    },
+    async execute(lease, request, onEvent) {
+      const entry = leases.get(lease.leaseId);
+      if (!entry) throw new DockerSandboxBackendError("lease-not-found");
+      if (lease.backendId !== descriptor.id || lease.ticketId !== entry.ticketId) {
+        throw new DockerSandboxBackendError("lease-mismatch");
+      }
+      if (entry.released) throw new DockerSandboxBackendError("lease-released");
+      if (request.kind !== "command") {
+        throw new DockerSandboxBackendError("unsupported-request");
+      }
+      if (request.env !== void 0 || request.stdin !== void 0 || request.cwd !== void 0) {
+        throw new DockerSandboxBackendError("unsupported-request", "request options not honored");
+      }
+      const tierExecTimeoutMs = isShellArgv(request.argv) ? shellExecTimeoutMs : defaultExecTimeoutMs;
+      const requestedTimeoutMs = request.timeoutMs;
+      if (requestedTimeoutMs !== void 0) {
+        if (!Number.isFinite(requestedTimeoutMs) || requestedTimeoutMs <= 0) {
+          throw new DockerSandboxBackendError(
+            "unsupported-request",
+            "timeoutMs must be a positive finite number"
+          );
+        }
+        if (requestedTimeoutMs > tierExecTimeoutMs) {
+          throw new DockerSandboxBackendError(
+            "unsupported-request",
+            "timeoutMs exceeds the backend execution bound"
+          );
+        }
+      }
+      const execBoundMs = requestedTimeoutMs ?? tierExecTimeoutMs;
+      const executionId = `${entry.sandboxName}:${now().toString(36)}`;
+      const startedAt = now();
+      onEvent?.({ type: "started", executionId, at: startedAt });
+      const script = argvToShellScript(request.argv);
+      const outcome = await runSbx(
+        ["--cloud", "exec", entry.sandboxName, "bash", "-lc", script],
+        { timeoutMs: execBoundMs }
+      );
+      if (outcome.timedOut) {
+        throw new DockerSandboxBackendError("exec-timeout");
+      }
+      if (outcome.exitCode === null) {
+        throw new DockerSandboxBackendError("exec-failed");
+      }
+      const stdout = truncateOutput(outcome.stdout, maxOutputChars);
+      const stderr = truncateOutput(outcome.stderr, maxOutputChars);
+      if (stdout) onEvent?.({ type: "stdout", executionId, chunk: stdout, seq: 1 });
+      if (stderr) onEvent?.({ type: "stderr", executionId, chunk: stderr, seq: 1 });
+      onEvent?.({
+        type: "usage",
+        executionId,
+        usage: { wallMs: Math.max(0, now() - startedAt) }
+      });
+      onEvent?.({ type: "exited", executionId, exitCode: outcome.exitCode });
+      return {
+        executionId,
+        ok: outcome.exitCode === 0,
+        exitCode: outcome.exitCode,
+        output: { stdout, stderr }
+      };
+    },
+    async release(lease, reason) {
+      const entry = leases.get(lease.leaseId);
+      if (!entry || entry.released) return;
+      if (lease.backendId !== descriptor.id || lease.ticketId !== entry.ticketId) {
+        throw new DockerSandboxBackendError("lease-mismatch");
+      }
+      const stop = await runSbx(["--cloud", "stop", entry.sandboxName], {
+        timeoutMs: controlTimeoutMs
+      });
+      if (stop.exitCode !== 0 || !await confirmDockerSandboxStopped(runSbx, entry.sandboxName, controlTimeoutMs)) {
+        throw new DockerSandboxBackendError("stop-unverified", void 0, true);
+      }
+      entry.released = true;
+      await persistQuotaRecord("release-final-state", entry.slotKey, {
+        status: reason === "failed" ? "failed" : "stopped",
+        pendingEstimateNanoUsd: "0",
+        estimatedSpendNanoUsd: entry.estimatedNanoUsd.toString(),
+        sandbox: entry.sandboxName
+      });
+    }
+  };
+}
+function parseSbxListingJson(stdout) {
+  const text = stdout ?? "";
+  let start = -1;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === "[" || ch === "{") {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return void 0;
+  return JSON.parse(text.slice(start));
+}
+async function probeCloudSandboxPresence(runSbx, timeoutMs) {
+  try {
+    const listing = await runSbx(["--cloud", "ls", "--format", "json"], { timeoutMs });
+    if (listing.exitCode !== 0 || listing.timedOut) return { ok: false, reason: "ls-failed" };
+    const parsed = parseSbxListingJson(listing.stdout);
+    if (!Array.isArray(parsed)) return { ok: false, reason: "malformed-listing" };
+    const names = /* @__PURE__ */ new Set();
+    for (const entry of parsed) {
+      if (!entry || typeof entry !== "object") return { ok: false, reason: "malformed-listing" };
+      const name = entry.name;
+      if (typeof name !== "string" || !name) return { ok: false, reason: "malformed-listing" };
+      names.add(name);
+    }
+    return { ok: true, names };
+  } catch {
+    return { ok: false, reason: "ls-failed" };
+  }
+}
+async function confirmDockerSandboxStopped(runSbx, sandboxName, timeoutMs = 1e4, options = {}) {
+  const attempts = Math.max(1, options.attempts ?? 1);
+  const delayMs = Math.max(0, options.delayMs ?? 0);
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const verdict = await probeOnce(runSbx, sandboxName, timeoutMs);
+    if (verdict !== "pending") return verdict;
+    if (attempt < attempts - 1 && delayMs > 0) {
+      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+    }
+  }
+  return false;
+}
+async function probeOnce(runSbx, sandboxName, timeoutMs) {
+  try {
+    const listing = await runSbx(["--cloud", "ls", "--format", "json"], { timeoutMs });
+    if (listing.exitCode !== 0 || listing.timedOut) return false;
+    const parsed = parseSbxListingJson(listing.stdout);
+    if (!Array.isArray(parsed)) return false;
+    const matches = parsed.filter((x) => x && typeof x === "object" && x.name === sandboxName);
+    if (matches.length === 0) return true;
+    if (matches.length === 1 && matches[0].status === "stopped") return true;
+    return matches.length === 1 ? "pending" : false;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  FileDockerQuotaKvStore,
+  DOCKER_SANDBOX_BACKEND_ID,
+  resolveMaxActiveSandboxesFromEnv,
+  defaultRunSbx,
+  createDockerSandboxExecutionBackend,
+  confirmDockerSandboxStopped
+};