@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/sandbox/sandbox.service.js

@@ -1,29 +1,60 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { randomUUID } from "node:crypto";
-import { isSandboxGoneError, } from "@capybara-hq/plugin-sdk";
+import { isFileSystemGoneError, isSandboxGoneError, rootsOf, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql, } from "kysely";
+import { BackgroundTaskStore } from "../background/store.js";
 import { DEFAULT_MAX_COMMAND_SECONDS, DEFAULT_MAX_RUN_SECONDS, } from "../config/schema.js";
 import { ApiError } from "../errors.js";
 import { readSandboxLimitOverride } from "../identity/settings.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 import { effectiveSandboxEgress, effectiveSandboxLimits, readOrgSettings, } from "../orgs/settings.service.js";
-import { canonicalJson } from "../tools/registry.js";
-import { SANDBOX_LOCK_TTL_MS, SandboxLeases, SandboxLockLostError, sandboxBusy, } from "./leases.js";
+import { canonicalJson } from "../tools/canonical-json.js";
+import { SandboxLeases, SandboxLockLostError, sandboxBusy, } from "./leases.js";
+import { DEVICE_PROVIDER, providerForEnvironment, SandboxProviders, } from "./providers.js";
 // Moved to leases.ts (phase C); re-exported for existing importers
-export { SANDBOX_BUSY_PREFIX, SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
+export { SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
 /** Margin (ms) of a holder record's TTL beyond the longest command: by then the in-sandbox limit has ended its commands. */
 const HOLDER_TTL_MARGIN_MS = 10 * 60_000;
 /** How long the kernel's own read-modify-write of one file waits for another holder's (ms, spec §10.4). */
 const PATH_LEASE_WAIT_MS = 30_000;
-/** 维护扫描里单个提供方操作（休眠 / 销毁）的超时。 */
+/** Time limit of one provider call in maintenance (suspend, destroy). */
 const SWEEP_OP_TIMEOUT_MS = 120_000;
 /** How long the suspension sweep holds the intent on a sandbox past `maxRunningMinutes` (ms). */
 const SWEEP_INTENT_WAIT_MS = 1000;
-/** 每次扫描最多处理的沙箱数，与同时进行的提供方操作数。 */
+/** Rows one sweep handles at most, and the provider calls it runs at once. */
 const SWEEP_BATCH = 200;
 const SWEEP_CONCURRENCY = 4;
-/** destroyFor 等锁的上限：持有者在跑命令时最多等这么久。 */
-const DESTROY_FOR_WAIT_MS = 10 * 60_000;
-/** 维护里一次提供方操作的 signal：超时或锁丢失时中止。 */
+/** How long `destroyEnvironment` / `resetFileSystem` wait for the exclusive lease (running commands). */
+const EXCLUSIVE_WAIT_MS = 10 * 60_000;
+/** The time limit of the exec that kills lost background tasks after a resume (ms). */
+const PENDING_KILL_TIMEOUT_MS = 30_000;
+/** A background task's session id as `echo $!` printed it; anything else is never put in a command. */
+const SID_RE = /^[1-9][0-9]{0,9}$/;
+/** The signal of one provider call in maintenance: aborted on timeout or when the lease is lost. */
 const opSignal = (lease) => AbortSignal.any([lease.signal, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS)]);
+/** The provider-side name of an environment's file system and instance. */
+export const environmentResourceName = (environmentId) => `cap-env-${environmentId}`;
+/** The environment is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
+export const environmentNotFound = () => new ApiError("environment.not_found", "This environment does not exist or was deleted.");
+/**
+ * The environment's file system is gone at the provider (409); never replaced silently. On a
+ * connected machine (`device`, details `[{ source: "device" }]`) the directory is the machine
+ * owner's: `capybara-device logout`, then `login` into the environment, recreates it (ruling R24).
+ */
+export const environmentFilesLost = (device = false) => device
+    ? new ApiError("environment.files_lost", "The environment's directory is gone from its connected machine; run capybara-device logout, then capybara-device login into this environment, on that machine to recreate it.", [{ source: "device" }])
+    : new ApiError("environment.files_lost", "The environment's files are gone; reset its files from the environments page to start with an empty workspace.");
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -33,42 +64,31 @@ export const isInstance = (row, gone) => gone !== null &&
     canonicalJson(row.handle) === canonicalJson(gone.handle) &&
     row.created_at.getTime() === gone.createdAt;
 /**
- * Concurrent commands a provider gets (spec §10.7): `max` when it declares both `concurrentExec`
- * and `killTagged`, else 1 (one call at a time, the behavior before phase C).
+ * `impl` with every `exec` labelled with the holder's tag (and `actor` when given); `before` runs
+ * first (it refreshes the holder's record, so a callback that runs several long commands in a row
+ * stays recorded).
  */
-export function sandboxConcurrency(impl, max) {
-    return impl.concurrentExec === true && typeof impl.killTagged === "function" ? max : 1;
-}
-/**
- * `impl` with every `exec` labelled with the holder's tag; `before` runs first (it refreshes the
- * holder's record, so a callback that runs several long commands in a row stays recorded).
- */
-function tagged(impl, tag, before) {
+function tagged(impl, tag, actor, before) {
     const wrapped = Object.create(impl);
     Object.defineProperty(wrapped, "exec", {
         value: async (h, args) => {
             await before();
-            return impl.exec(h, { ...args, tag });
+            return impl.exec(h, { ...args, tag, ...(actor !== undefined && { actor }) });
         },
     });
     return wrapped;
 }
 /**
- * 启动时要提醒运维的沙箱配置问题（英文日志）：
- * - `runtime.maxRunSeconds` 小于 `sandbox.limits.maxCommandSeconds`：长命令会被运行时限截断（Ruling M20）；
- * - `sandbox.limits.egress` 为 open、但当前提供方插件没打开 `allowOpenEgress`：每次创建沙箱都会被拒。
- * 两个时限都是默认值（900 < 7200，已知的取舍）时只记 info；运维改过其中一个却仍不一致时才 warn。
- * - the provider declares only one of `concurrentExec` and `killTagged`: it is used one call at a
- *   time (spec §10.7).
+ * Sandbox config problems to tell operators at startup (English log lines):
+ * - `runtime.maxRunSeconds` below `sandbox.limits.maxCommandSeconds`: long commands are cut by the
+ *   run time limit (Ruling M20);
+ * - `sandbox.limits.egress` is open but the current provider plugin has no `allowOpenEgress`: every
+ *   instance creation is refused.
+ * With both time limits at their defaults (900 < 7200, a known trade-off) it is only info; warn
+ * when an operator changed one and they still disagree.
  */
-export function sandboxConfigWarnings(cfg, providerPlugin, impl) {
+export function sandboxConfigWarnings(cfg, providerPlugin) {
     const out = [];
-    if (impl && (impl.concurrentExec === true) !== (typeof impl.killTagged === "function")) {
-        out.push({
-            level: "warn",
-            message: `the sandbox plugin ${providerPlugin ?? ""} declares only one of concurrentExec and killTagged; concurrent commands need both, so its sandboxes run one command at a time`,
-        });
-    }
     if (cfg.sandbox.limits.egress === "open" && providerPlugin !== undefined) {
         const pc = cfg.extensionConfig[providerPlugin];
         if (pc?.allowOpenEgress !== true) {
@@ -89,8 +109,13 @@ export function sandboxConfigWarnings(cfg, providerPlugin, impl) {
     }
     return out;
 }
-/** 没有沙箱提供方时的错误（503）。 */
+/** No sandbox provider (503). */
 export const sandboxUnavailable = () => new ApiError("sandbox.unavailable", "Sandbox is not available in this deployment; install a sandbox plugin");
+/**
+ * The environment's files are kept by a provider that is not the current one (503); its files are
+ * not migrated, so it stays unusable until that provider is back (spec §4.2 item 13).
+ */
+const otherProvider = (provider) => new ApiError("environment.unavailable", `This environment's files are kept by the sandbox provider ${provider}, which is not the current provider; it can be used again once ${provider} is the deployment's sandbox provider`);
 const abortReason = (signal) => signal.reason ?? new DOMException("This operation was aborted", "AbortError");
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -109,7 +134,7 @@ function sleep(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
-/** 按 `limit` 个一组并发执行。 */
+/** Runs `fn` on `items`, `limit` at a time. */
 async function inPool(items, limit, fn) {
     let next = 0;
     const worker = async () => {
@@ -121,77 +146,156 @@ async function inPool(items, limit, fn) {
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
 }
 /**
- * 内核的沙箱服务（M5 T7）：在 `sandbox@1` 提供方之上，每个对话一个沙箱。
+ * The kernel's sandbox service over the `sandbox@2` provider, keyed by **environment** (spec
+ * 2026-11-07-environments-design §4.2, §5.1): one file system kept until the environment is
+ * deleted, plus one instance attached to it that comes and goes; all conversations bound to the
+ * environment (and their sub-agents) share both.
  *
- * - **懒创建**：第一次 {@link withSandbox} 才创建；状态在 PG 表 `sandboxes`。
- * - **Leases** (phase C, spec §10, {@link SandboxLeases}): using a sandbox recorded `running` with
- *   the current provider takes a **shared** lease, so up to `sandbox.maxConcurrentCommands` holders
- *   (commands of parallel sub-agents) run at once ({@link sandboxConcurrency}: 1 for a provider
- *   without `concurrentExec` + `killTagged`). Every lifecycle change (create, resume, rebuild,
- *   suspend, destroy) takes the **exclusive** lease, alone; a caller that needs one on the use path
- *   sets the intent so new shared leases wait for it, and downgrades to a shared lease to run its
- *   own command once the sandbox is running. Waiting is capped at `sandbox.lockWaitSeconds`
- *   (`sandbox.busy`); two replicas using it for the first time at once still build only one.
- * - **防护**：exclusive holders read `generation` and compare-and-increment it with every write of
- *   status / handle ({@link SandboxLockLostError}); every acquisition (shared ones too) bumps it
- *   first, so a stale exclusive holder's later writes fail. Shared holders write nothing else but
- *   `last_used_at` (monotonic). A lost
- *   lease aborts the signal passed to `fn` and to maintenance provider calls.
- * - **休眠与销毁**由维护队列定期调用 {@link suspendIdle} / {@link destroyInactive}；它们只试一次 exclusive
- *   lease and skip a sandbox with any holder; a sandbox past `maxRunningMinutes` gets the intent for
- *   a short window (about a second) so the suspension can get in when its commands end.
- * - **透明恢复**：已休眠的在下次使用时恢复；恢复返回 `gone`、已销毁、记录的提供方不是当前提供方、
- *   或 `fn` 抛 `SandboxGoneError`（重试一次）时重建空沙箱，`recreated` 为 true（工具层告诉模型「之前的文件已不在」）。
- *   Several holders hitting `gone` together rebuild once: the others find the new instance.
- * - **Takeover** (spec §10.5): every holder records itself in `capk:sandbox-holders:<conv>` (again
- *   before each `exec`) and its commands carry its lease token as `tag`. An acquirer that finds a
- *   record without a live lease (a crashed holder) kills its commands: `killTagged` on the shared
- *   path whenever the provider has it (else `killAll` only while it is the one shared holder),
- *   `killAll` under the exclusive lease (no live sibling can exist). The single marker
- *   `capk:sandbox-busy:<conv>` of kernels before phase C sends the next use down the exclusive
- *   path, which `killAll`s; holders of this kernel write it as `v2` for older replicas (§10.8),
- *   which this kernel ignores. A sandbox just resumed from `suspended` is `killAll`ed too. Failures
- *   are only warned (the in-sandbox time limit is the backstop).
+ * - **Lazy creation**: the first {@link withSandbox} creates the file system
+ *   (`createFileSystem`, name `cap-env-<environmentId>`) and then the instance on it; state lives
+ *   in `environment_instances`. A file system gone at the provider is never replaced silently:
+ *   `fs_status` becomes `lost` and uses fail with `environment.files_lost` until
+ *   {@link resetFileSystem}.
+ * - **Leases** (phase C, spec §10, {@link SandboxLeases}), keyed by environment id: using an
+ *   instance recorded `running` with the current provider takes a **shared** lease, so up to
+ *   `sandbox.maxConcurrentCommands` holders (all sessions of the environment) run at once. Every
+ *   lifecycle change (create, resume, rebuild, suspend, destroy, reset) takes the **exclusive**
+ *   lease, alone; a caller that needs one on the use path sets the intent so new shared leases wait
+ *   for it, and downgrades to a shared lease to run its own command once the instance runs.
+ *   Waiting is capped at `sandbox.lockWaitSeconds` (`sandbox.busy`); two replicas using it for the
+ *   first time at once still build only one.
+ * - **Fencing**: exclusive holders read `generation` and compare-and-increment it with every state
+ *   write ({@link SandboxLockLostError}); every acquisition (shared ones too) bumps it first, so a
+ *   stale exclusive holder's later writes fail. Shared holders write nothing else but
+ *   `last_used_at` (monotonic). A lost lease aborts the signal passed to `fn` and to maintenance
+ *   provider calls.
+ * - **Suspension and destruction**: the sweeps (`SandboxSweepJobs`, crons) call
+ *   {@link suspendIdle} / {@link destroyInactive}; they try the exclusive lease once and skip an
+ *   environment with any holder; one past `maxRunningMinutes` gets the intent for a short window
+ *   (about a second) so the suspension can get in when its commands end. Inactivity destroys only
+ *   the instance (files kept); a deleted environment or org loses its files too.
+ * - **Transparent recovery**: a suspended instance is resumed on next use; when `resume` returns
+ *   `gone`, the instance was destroyed, or `fn` throws `SandboxGoneError` (retried once), a new
+ *   instance is created on the kept files and `restarted` is true. Several holders hitting `gone`
+ *   together rebuild once: the others find the new instance.
+ * - **Takeover** (spec §10.5; environments spec §4.2): every holder records itself in
+ *   `capk:sandbox-holders:<env>` (again before each `exec`) and its commands carry its lease token
+ *   as `tag`. An acquirer that finds a record without a live lease (a crashed holder) kills only
+ *   that holder's commands (`killTagged`): other conversations of the environment may be running
+ *   commands. `killAll` runs only under the exclusive lease, before the downgrade, on an instance
+ *   this holder just resumed from `suspended` (nobody else can hold it; a provider that keeps
+ *   memory across a pause brings old commands back); it also covers crashed holders' records,
+ *   which it claims. A freshly created instance has nothing to kill. Failures are only warned (the
+ *   in-sandbox time limit is the backstop).
  * - **Instance identity**: a holder that hits `gone` names the instance by its handle and the
  *   row's `created_at` (set by the fenced write after each `create`); the handle alone is the same
  *   after a rebuild on providers whose handle is the instance name (sandbox-docker).
  *
- * 换提供方会泄漏旧实例：新提供方销毁不了旧提供方的实例，只有旧提供方仍加载时才能清理（记在 `prev_*` 列）。
- * 没有提供方时 {@link available} 为 false，使用时抛 `sandbox.unavailable`（503）。本身无进程内状态，可多副本共用。
+ * - **Provider per environment** (environments spec §6): each call resolves the provider from
+ *   the environment's `environments.provider` ({@link providerForEnvironment}): a `device`
+ *   environment runs on the kernel-internal `@device` provider (never the cloud one), a cloud
+ *   environment on the loaded `sandbox@2` extension. A `@device` instance is never suspended or
+ *   destroyed for inactivity; a deleted `@device` environment (or one of a deleted org) is
+ *   destroyed by the sweep like any other.
+ *
+ * Files kept by another provider than the current one make the environment unusable
+ * (`environment.unavailable`) until that provider is back; deleting it still works while that
+ * provider is loaded ({@link SandboxProviders.forName}). Without the environment's provider
+ * {@link availableFor} is false and uses throw `sandbox.unavailable` (503). No in-process state:
+ * replicas share it through PG and Redis.
  */
-export class SandboxService {
-    d;
+let SandboxService = class SandboxService {
+    db;
+    redis;
     leases;
-    pollMs;
-    constructor(d) {
-        this.d = d;
-        this.pollMs = d.lockPollMs ?? 100;
-        this.leases =
-            d.leases ??
-                new SandboxLeases({
-                    redis: d.redis,
-                    log: d.log,
-                    ttlMs: d.lockTtlMs ?? SANDBOX_LOCK_TTL_MS,
-                    pollMs: this.pollMs,
-                });
+    providers;
+    config;
+    log;
+    background;
+    constructor(db, 
+    /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
+    redis, leases, 
+    /** The providers (read at every call: providers are ready after the extension load). */
+    providers, config, log, 
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    background) {
+        this.db = db;
+        this.redis = redis;
+        this.leases = leases;
+        this.providers = providers;
+        this.config = config;
+        this.log = log;
+        this.background = background;
+    }
+    /** Poll interval while waiting for a lease (the leases' own). */
+    get pollMs() {
+        return this.leases.pollMs;
     }
-    /** 是否有沙箱提供方。 */
-    get available() {
-        return this.d.provider() !== undefined;
+    /**
+     * Whether there is a cloud sandbox provider (a loaded `sandbox@2` extension). For gates that have
+     * no environment yet (tool listing, skill files); a call on an environment asks
+     * {@link availableFor}.
+     */
+    get cloudAvailable() {
+        return this.providers.cloud() !== undefined;
     }
-    /** Concurrent holders the provider gets ({@link sandboxConcurrency} with the current config). */
-    effectiveCap(p) {
-        return sandboxConcurrency(p.impl, this.d.config().sandbox.maxConcurrentCommands);
+    /** Whether the environment's provider is there (`@device` registered, or a cloud provider). */
+    async availableFor(environmentId) {
+        return (await this.providerOf(environmentId)) !== undefined;
     }
     /**
-     * 该对话沙箱的对外状态（只读，不拿锁）：`running` / `suspended` 与最近使用时间。
-     * 还没有、已销毁、或停在 `creating`（正在创建，或创建失败等下次使用重建）的都返回 null（界面显示「未创建」）。
+     * The provider the environment works with, read from its row ({@link providerForEnvironment});
+     * a missing row (or one of another org, with `orgId`) reads as a cloud environment, whose use
+     * then fails as not found.
      */
-    async status(orgId, conversationId) {
-        const row = await this.d.db
-            .selectFrom("sandboxes")
+    async providerOf(environmentId, orgId) {
+        const row = await this.db
+            .selectFrom("environments")
+            .select("provider")
+            .where("id", "=", environmentId)
+            .$if(orgId !== undefined, (q) => q.where("org_id", "=", orgId))
+            .executeTakeFirst();
+        return providerForEnvironment(this.providers, row?.provider ?? null);
+    }
+    /** {@link providerOf}, or `sandbox.unavailable` (503) without it. */
+    async require(environmentId, orgId) {
+        const p = await this.providerOf(environmentId, orgId);
+        if (!p)
+            throw sandboxUnavailable();
+        return p;
+    }
+    /** Concurrent holders of one environment (`sandbox.maxConcurrentCommands`, read at every use). */
+    get cap() {
+        return this.config.get().sandbox.maxConcurrentCommands;
+    }
+    /**
+     * The org's effective sandbox limits (spec §8.4): the deployment's `sandbox.limits`, egress
+     * narrowed by the org setting `sandboxEgress` (Ruling M19), cpu / memory per the super admin's
+     * org override (C19 / Ruling M16). Instances are created with them; phase 1 environments use
+     * them unchanged.
+     */
+    async orgLimits(orgId) {
+        const cfg = this.config.get().sandbox;
+        const egress = effectiveSandboxEgress(cfg.limits, (await readOrgSettings(this.db.db, orgId)).sandboxEgress);
+        const sized = effectiveSandboxLimits({ ...cfg.limits, ...egress }, await readSandboxLimitOverride(this.db.db, orgId));
+        return {
+            cpu: sized.cpu,
+            memoryMb: sized.memoryMb,
+            diskMb: sized.diskMb,
+            egress: sized.egress,
+            allowHosts: sized.allowHosts,
+        };
+    }
+    /**
+     * The environment's instance state as shown to people (read only, no lease): `running` /
+     * `suspended` and the last use. No instance, a destroyed one, or one stuck in `creating` (being
+     * created, or a failed create the next use retries) is null.
+     */
+    async status(orgId, environmentId) {
+        const row = await this.db
+            .selectFrom("environment_instances")
             .select(["status", "last_used_at"])
-            .where("conversation_id", "=", conversationId)
+            .where("environment_id", "=", environmentId)
             .where("org_id", "=", orgId)
             .executeTakeFirst();
         if (!row || (row.status !== "running" && row.status !== "suspended"))
@@ -199,91 +303,224 @@ export class SandboxService {
         return { status: row.status, lastUsedAt: row.last_used_at };
     }
     /**
-     * A short lease on one path of the conversation's sandbox around the kernel's own
-     * read-modify-write of that file (spec §10.4); waits up to 30 s, then throws
-     * `SandboxPathBusyError`. Its `signal` aborts when a renewal finds it lost.
+     * The instance the environment records now (its `created_at`), while it has one that runs or is
+     * suspended; null otherwise. Read without a lease: a caller inside `withSandbox` reads the
+     * instance its own lease keeps.
+     */
+    async currentInstance(environmentId) {
+        const row = await this.db
+            .selectFrom("environment_instances")
+            .select(["status", "handle", "created_at"])
+            .where("environment_id", "=", environmentId)
+            .executeTakeFirst();
+        if (!row || row.handle === null)
+            return null;
+        if (row.status !== "running" && row.status !== "suspended")
+            return null;
+        return { createdAt: row.created_at };
+    }
+    /**
+     * Runs `fn` on the environment's instance only while it runs the instance created at
+     * `instance.createdAt` (background tasks, spec 2026-11-05-background-bash-design §4.3). It never
+     * creates, resumes or rebuilds one: an instance that is missing, suspended, being created or
+     * destroyed (or recorded with another provider) is `not_running`, one that records another
+     * instance is `other_instance`. Otherwise `fn` runs under a shared lease, as a `withSandbox`
+     * holder does (its tag on every exec, crashed holders' commands killed), and `last_used_at`
+     * moves forward when it ends. Waits for the lease up to `sandbox.lockWaitSeconds`
+     * (`sandbox.busy`); `signal` (optional) ends the wait with its abort reason. The signal passed
+     * to `fn` aborts with `signal` or when the lease is lost. Errors of `fn` (`SandboxGoneError`
+     * too) are thrown as they are.
+     */
+    async ifRunning(environmentId, instance, fn, signal = new AbortController().signal) {
+        const p = await this.require(environmentId);
+        const env = environmentId;
+        const deadline = Date.now() + this.config.get().sandbox.lockWaitSeconds * 1000;
+        const token = randomUUID();
+        for (;;) {
+            if (signal.aborted)
+                throw abortReason(signal);
+            const row = await this.db
+                .selectFrom("environment_instances")
+                .selectAll()
+                .where("environment_id", "=", env)
+                .executeTakeFirst();
+            if (!row)
+                return { kind: "not_running", status: "gone" };
+            if (row.created_at.getTime() !== instance.createdAt.getTime()) {
+                return { kind: "other_instance" };
+            }
+            if (!this.usable(row, p, null))
+                return { kind: "not_running", status: row.status };
+            // the instance this check saw: its handle plus `created_at` (never `generation`, which
+            // every lease bumps)
+            const want = { handle: row.handle, createdAt: row.created_at.getTime() };
+            const lease = await this.leases.tryShared(env, this.cap, token);
+            if (lease) {
+                const e = await this.asShared({ orgId: row.org_id, environmentId: env }, p, lease, (r) => this.usable(r, p, null) && isInstance(r, want), signal);
+                if (e) {
+                    try {
+                        const impl = tagged(p.impl, lease.token, undefined, () => this.register(env, lease.token));
+                        const sig = AbortSignal.any([signal, lease.signal]);
+                        try {
+                            return { kind: "ran", value: await fn(impl, e.handle, sig) };
+                        }
+                        catch (err) {
+                            if (isFileSystemGoneError(err))
+                                throw await this.filesGone(env, p, e);
+                            throw err;
+                        }
+                    }
+                    finally {
+                        await this.leave(env, e);
+                    }
+                }
+                // the row changed between the check and the lease: classify it again
+                continue;
+            }
+            if (Date.now() + this.pollMs > deadline)
+                throw sandboxBusy();
+            await sleep(this.pollMs + Math.floor(Math.random() * this.pollMs), signal);
+        }
+    }
+    /**
+     * A short lease on one path of the environment around the kernel's own read-modify-write of
+     * that file (spec §10.4); waits up to 30 s, then throws `SandboxPathBusyError`. Its `signal`
+     * aborts when a renewal finds it lost.
      */
-    pathLease(conversationId, path, signal) {
-        return this.leases.pathLease(conversationId, path, signal, PATH_LEASE_WAIT_MS);
+    pathLease(environmentId, path, signal) {
+        return this.leases.pathLease(environmentId, path, signal, PATH_LEASE_WAIT_MS);
     }
     /**
-     * 在该对话（the sandbox conversation）的沙箱上执行 `fn`: take a lease → make sure the sandbox runs
-     * (create / resume / rebuild, under the exclusive lease) → `fn` under a shared lease → update
-     * `last_used_at` → release.
-     * - 等待超过 `sandbox.lockWaitSeconds` 抛 `sandbox.busy`（409）；`signal` 中止等待与创建 / 恢复。
-     * - `fn` 的第四个参数是 `signal` 与「lease 已丢失」的合并：执行命令时用它，lease 丢失就中止。
-     * - The provider passed to `fn` labels every `exec` with this holder's tag.
-     * - `fn` 抛 `SandboxGoneError`（实例已不在）时重建（or take the instance another holder rebuilt）、
-     *   以 `recreated: true` 再调用一次；再次 gone 则抛出。其余错误原样抛出。
-     * - `holderConversationId` (default `conversationId`): the agent conversation using it, a
-     *   sub-agent's own for a child. When that holder last used another instance (another holder
-     *   rebuilt it meanwhile), `info.recreated` is true, so it learns its files are gone (final
-     *   review m5).
+     * Runs `fn` on the environment's instance: take a lease → make sure the instance runs (file
+     * system, create / resume / rebuild, under the exclusive lease) → `fn` under a shared lease →
+     * update `last_used_at` → release.
+     * - Waiting longer than `sandbox.lockWaitSeconds` throws `sandbox.busy` (409); `signal` aborts
+     *   the wait and the creation / resume.
+     * - The fourth argument of `fn` combines `signal` with the lease's: use it for commands, so they
+     *   stop when the lease is lost.
+     * - The provider passed to `fn` labels every `exec` with this holder's tag and `ctx.actor`.
+     * - When `fn` throws `SandboxGoneError` (the instance is gone) the instance is rebuilt on the
+     *   kept files (or the one another holder rebuilt is taken) and `fn` runs once more with
+     *   `restarted: true`; a second `gone` is thrown. Other errors are thrown as they are.
+     * - Lost files throw `environment.files_lost` (409), also when `fn` throws
+     *   `FileSystemGoneError` (the files are then recorded lost, ruling R24).
+     * - When `ctx.holderConversationId` last used another instance (another holder rebuilt it
+     *   meanwhile), `info.restarted` is true, so it learns its processes are gone (final review m5).
      */
     async withSandbox(ctx, fn, signal) {
-        const p = this.require();
-        const holder = ctx.holderConversationId ?? ctx.conversationId;
-        let e = await this.seenBy(ctx.conversationId, holder, await this.enter(ctx, p, signal, null));
+        const p = await this.require(ctx.environmentId, ctx.orgId);
+        const env = ctx.environmentId;
+        const holder = ctx.holderConversationId;
+        let e = await this.seenBy(env, holder, await this.enter(ctx, p, signal, null));
         try {
             try {
-                return await this.runAs(e, p, fn, signal);
+                return await this.runAs(e, ctx, p, fn, signal);
             }
             catch (err) {
+                if (isFileSystemGoneError(err))
+                    throw await this.filesGone(env, p, e);
                 if (!isSandboxGoneError(err))
                     throw err;
-                this.d.log.info("sandbox instance is gone during use; recreating", {
-                    conversationId: ctx.conversationId,
-                });
+                this.log.info("sandbox instance is gone during use; recreating", { environmentId: env });
                 const gone = { handle: e.handle, createdAt: e.createdAt };
                 const prev = e;
-                await this.leave(ctx.conversationId, prev);
-                e = await this.seenBy(ctx.conversationId, holder, await this.enter(ctx, p, signal, gone));
-                return await this.runAs({ ...e, info: { fresh: true, recreated: true } }, p, fn, signal);
+                await this.leave(env, prev);
+                e = await this.seenBy(env, holder, await this.enter(ctx, p, signal, gone));
+                // a reset seen on the first try still has to be told (it covers the restart)
+                const info = prev.info.filesReset
+                    ? { fresh: true, restarted: false, filesReset: true }
+                    : { fresh: true, restarted: true };
+                try {
+                    return await this.runAs({ ...e, info }, ctx, p, fn, signal);
+                }
+                catch (err2) {
+                    if (isFileSystemGoneError(err2))
+                        throw await this.filesGone(env, p, e);
+                    throw err2;
+                }
             }
         }
         finally {
-            await this.leave(ctx.conversationId, e);
+            await this.leave(env, e);
+        }
+    }
+    /**
+     * Ruling R24: an operation on the held instance `e` found its file system gone. Records
+     * `fs_status = 'lost'` while the row still records that instance on its file system (the
+     * instance handle stays, so a reset still destroys it), moving the fence on, and returns
+     * `environment.files_lost` to throw. Uses then fail until the files are reset (a connected
+     * machine: until a new login, which resets the row). A failed write only logs.
+     */
+    async filesGone(env, p, e) {
+        this.log.warn("environment file system is gone at the provider; its files are lost", {
+            environmentId: env,
+            provider: p.plugin,
+        });
+        try {
+            await this.db
+                .updateTable("environment_instances")
+                .set((eb) => ({ fs_status: "lost", generation: eb("generation", "+", 1) }))
+                .where("environment_id", "=", env)
+                .where("fs_status", "=", "ready")
+                // `createdAt` is the row's value read back in milliseconds
+                .where(sql `date_trunc('milliseconds', created_at)`, "=", new Date(e.createdAt))
+                .execute();
+        }
+        catch (err) {
+            this.log.warn("cannot record lost environment files", { environmentId: env, err });
         }
+        return environmentFilesLost(p.plugin === DEVICE_PROVIDER);
     }
     /**
-     * Records that `holder` uses the instance of `e` (`capk:sandbox-seen:<conv>:<holder>`, its
-     * `created_at`, with a TTL of the inactivity destruction plus a day) and marks `e` recreated
-     * when the holder last used another instance. Best effort: a Redis error only logs.
+     * Records that `holder` uses the instance of `e` (`capk:sandbox-seen:<env>:<holder>` =
+     * `<created_at>:<fs_resets>`, with a TTL of the inactivity destruction plus a day). When the
+     * holder last used another instance under the same reset count `e` is marked restarted (files
+     * kept); under another count it is marked `filesReset` instead. The count, not the provider's
+     * file system id, tells them apart: a provider may give the new file system the old id
+     * (sandbox-docker's volumes are named after the environment). Best effort: a Redis error only
+     * logs.
      */
-    async seenBy(conversationId, holder, e) {
+    async seenBy(environmentId, holder, e) {
         try {
-            const ttl = (this.d.config().sandbox.limits.destroyAfterInactiveDays + 1) * 86_400;
-            const prev = await this.d.redis.set(`capk:sandbox-seen:${conversationId}:${holder}`, String(e.createdAt), "EX", ttl, "GET");
-            if (prev !== null && prev !== String(e.createdAt) && !e.info.recreated) {
-                return { ...e, info: { fresh: e.info.fresh, recreated: true } };
+            const ttl = (this.config.get().sandbox.limits.destroyAfterInactiveDays + 1) * 86_400;
+            const seen = `${e.createdAt}:${e.fsResets}`;
+            const prev = await this.redis.set(`capk:sandbox-seen:${environmentId}:${holder}`, seen, "EX", ttl, "GET");
+            if (prev !== null && prev !== seen) {
+                // `<createdAt>:<fsResets>`: another reset count means the files were reset since; another
+                // instance under the same count is a restart on kept files
+                const sameFiles = prev.slice(prev.indexOf(":") + 1) === String(e.fsResets);
+                if (!sameFiles) {
+                    return { ...e, info: { fresh: e.info.fresh, restarted: false, filesReset: true } };
+                }
+                if (!e.info.restarted)
+                    return { ...e, info: { fresh: e.info.fresh, restarted: true } };
             }
         }
         catch (err) {
-            this.d.log.warn("cannot record the sandbox instance a holder uses", {
-                conversationId,
+            this.log.warn("cannot record the sandbox instance a holder uses", {
+                environmentId,
                 holder,
                 err,
             });
         }
         return e;
     }
-    /** Runs `fn` as the holder `e`: its tag on every exec, its lease's signal. */
-    runAs(e, p, fn, signal) {
+    /** Runs `fn` as the holder `e`: its tag and the caller's actor on every exec, its lease's signal. */
+    runAs(e, ctx, p, fn, signal) {
         const sig = AbortSignal.any([signal, e.lease.signal]);
-        const conv = e.lease.conversationId;
-        const impl = tagged(p.impl, e.lease.token, () => this.register(conv, e.lease.token));
-        return fn(e.handle, impl, e.info, sig);
+        const env = ctx.environmentId;
+        const impl = tagged(p.impl, e.lease.token, ctx.actor, () => this.register(env, e.lease.token));
+        return fn(e.handle, impl, { ...e.info, roots: rootsOf(e.handle) }, sig);
     }
     /**
      * Becomes a holder: loops until it has a shared lease on a running instance, or `sandbox.busy`.
-     * A sandbox recorded `running` (with the current provider, not the `gone` instance, and no legacy
-     * busy marker) is used under a shared lease; otherwise the exclusive lease (with intent) makes it
-     * run and is downgraded. One token serves both, so the waiter passes its own intent.
+     * An instance recorded `running` (with the current provider, not the `gone` instance) is used
+     * under a shared lease; otherwise the exclusive lease (with intent) makes it run and is
+     * downgraded. One token serves both, so the waiter passes its own intent.
      */
     async enter(ctx, p, signal, gone) {
-        const conv = ctx.conversationId;
-        const cap = this.effectiveCap(p);
-        const deadline = Date.now() + this.d.config().sandbox.lockWaitSeconds * 1000;
+        const env = ctx.environmentId;
+        const deadline = Date.now() + this.config.get().sandbox.lockWaitSeconds * 1000;
         const token = randomUUID();
         let intent = false;
         try {
@@ -291,19 +528,19 @@ export class SandboxService {
                 if (signal.aborted)
                     throw abortReason(signal);
                 const row = await this.readRow(ctx);
-                if (this.usable(row, p, gone) && !(await this.leases.legacyMarker(conv))) {
-                    const lease = await this.leases.tryShared(conv, cap, token);
+                if (this.usable(row, p, gone)) {
+                    const lease = await this.leases.tryShared(env, this.cap, token);
                     if (lease) {
                         if (intent)
-                            await this.clearIntent(conv, token);
+                            await this.clearIntent(env, token);
                         intent = false;
-                        const e = await this.asShared(ctx, p, lease, gone, signal);
+                        const e = await this.asShared(ctx, p, lease, (r) => this.usable(r, p, gone), signal);
                         if (e)
                             return e;
                     }
                 }
                 else {
-                    const lease = await this.leases.tryExclusive(conv, { token, intent: true });
+                    const lease = await this.leases.tryExclusive(env, { token, intent: true });
                     intent = lease === null;
                     if (lease)
                         return await this.asExclusive(ctx, p, lease, gone, signal);
@@ -315,181 +552,193 @@ export class SandboxService {
         }
         catch (err) {
             if (intent)
-                await this.clearIntent(conv, token);
+                await this.clearIntent(env, token);
             throw err;
         }
     }
-    async clearIntent(conv, token) {
+    async clearIntent(env, token) {
         await this.leases
-            .clearIntent(conv, token)
-            .catch((err) => this.d.log.warn("cannot clear sandbox intent", { conversationId: conv, err }));
+            .clearIntent(env, token)
+            .catch((err) => this.log.warn("cannot clear sandbox intent", { environmentId: env, err }));
     }
     async readRow(ctx) {
-        const row = await this.d.db
-            .selectFrom("sandboxes")
+        const row = await this.db
+            .selectFrom("environment_instances")
             .selectAll()
-            .where("conversation_id", "=", ctx.conversationId)
+            .where("environment_id", "=", ctx.environmentId)
             .executeTakeFirst();
-        if (row && row.org_id !== ctx.orgId) {
-            throw new ApiError("forbidden", `The sandbox of conversation ${ctx.conversationId} does not belong to organization ${ctx.orgId}`);
-        }
+        if (row && row.org_id !== ctx.orgId)
+            throw this.foreign(ctx);
         return row;
     }
-    /** Recorded running with the current provider, and not the instance found gone. */
+    /** The instance row belongs to another org: reported as not found, so ids cannot be probed. */
+    foreign(_ctx) {
+        return environmentNotFound();
+    }
+    /**
+     * Recorded running with the current provider on files not lost (lost ones go through the
+     * exclusive path, which refuses them), and not the instance found gone.
+     */
     usable(row, p, gone) {
         return (row !== undefined &&
             row.status === "running" &&
+            row.fs_status !== "lost" &&
             row.provider === p.plugin &&
             row.handle !== null &&
             !isInstance(row, gone));
     }
     /**
-     * Under a just-taken shared lease: confirms the row is still usable (else releases and returns
-     * null), records the holder and kills crashed holders' commands.
+     * Under a just-taken shared lease: confirms the row is still `accept`ed (else releases and
+     * returns null), records the holder and kills crashed holders' commands.
      */
-    async asShared(ctx, p, lease, gone, signal) {
-        const conv = ctx.conversationId;
+    async asShared(ctx, p, lease, accept, signal) {
+        const env = ctx.environmentId;
         try {
             const row = await this.readRow(ctx);
-            if (!this.usable(row, p, gone)) {
+            if (!accept(row)) {
                 await lease.release();
                 return null;
             }
             // Bump the fence as every acquisition did before phase C: an exclusive holder whose lease
             // expired unnoticed (a stalled sweep) then fails its next write instead of suspending or
             // destroying the instance under this holder. Shared holders never compare it.
-            await this.d.db
-                .updateTable("sandboxes")
+            await this.db
+                .updateTable("environment_instances")
                 .set((eb) => ({ generation: eb("generation", "+", 1) }))
-                .where("conversation_id", "=", conv)
+                .where("environment_id", "=", env)
                 .execute();
-            await this.register(conv, lease.token);
-            // a shared caller never claims an older kernel's busy marker (it holds no exclusive lease)
-            const dead = await this.claim(conv);
-            if (dead.tags.length > 0) {
-                const sig = AbortSignal.any([signal, lease.signal]);
-                const impl = p.impl;
-                if (impl.killTagged) {
-                    // by tag whenever the provider can, even with cap 1: while a hot change of
-                    // maxConcurrentCommands spreads, a replica on a larger cap may have let a sibling in
-                    await this.kill(conv, "takeover", async () => impl.killTagged?.(row.handle, dead.tags, sig), sig);
-                }
-                else if ((await this.leases.sharedCount(conv)) <= 1) {
-                    // cap 1 and this holder is alone: killing everything cannot hit a sibling
-                    await this.killLeftovers(conv, row.handle, p, sig, "takeover");
-                }
-                else {
-                    this.d.log.warn("cannot kill leftover sandbox commands: the provider has no killTagged and another holder is live; the in-sandbox time limit ends them", { conversationId: conv });
-                }
-            }
+            await this.register(env, lease.token);
+            // other holders (any conversation of the environment) may be running: only the dead
+            // holders' own commands are killed
+            await this.killTagged(env, row.handle, p, await this.claim(env), signal, lease);
             return {
                 lease,
                 handle: row.handle,
                 createdAt: row.created_at.getTime(),
-                info: { fresh: false, recreated: false },
+                fsResets: row.fs_resets,
+                info: { fresh: false, restarted: false },
             };
         }
         catch (err) {
-            await this.unregister(conv, lease.token);
+            await this.unregister(env, lease.token);
             await lease.release();
             throw err;
         }
     }
     /**
-     * Under a just-taken exclusive lease: makes the sandbox run (create / resume / rebuild when the
-     * recorded instance is the one found gone), kills leftovers, then downgrades to a shared lease.
+     * Under a just-taken exclusive lease: makes the instance run (file system, create / resume /
+     * rebuild when the recorded instance is the one found gone), kills leftovers, then downgrades to
+     * a shared lease. Crashed holders' records are claimed here: on an instance just resumed from
+     * `suspended` one `killAll` covers them and anything else left (nobody else holds the instance),
+     * on a new instance there is nothing to kill, and on one that already ran their tags are killed.
      */
     async asExclusive(ctx, p, lease, gone, signal) {
-        const conv = ctx.conversationId;
+        const env = ctx.environmentId;
         const sig = AbortSignal.any([signal, lease.signal]);
         try {
             const s = await this.ensure(ctx, p, lease, sig, gone);
-            const dead = await this.claim(conv, lease.token);
-            if (!s.info.fresh && (s.resumed || dead.legacyMarker || dead.tags.length > 0)) {
-                await this.killLeftovers(conv, s.handle, p, sig, s.resumed && !dead.legacyMarker && dead.tags.length === 0 ? "resume" : "takeover");
+            const dead = await this.claim(env);
+            if (s.resumed)
+                await this.killLeftovers(env, s.handle, p, sig, dead);
+            else if (!s.info.fresh)
+                await this.killTagged(env, s.handle, p, dead, signal, lease);
+            if (s.resumed || s.info.fresh) {
+                await this.killPendingTasks(env, s.handle, s.createdAt, p, lease.token, ctx.actor, sig);
             }
             const shared = await lease.downgrade();
-            await this.register(conv, shared.token);
-            return { lease: shared, handle: s.handle, createdAt: s.createdAt, info: s.info };
+            await this.register(env, shared.token);
+            return {
+                lease: shared,
+                handle: s.handle,
+                createdAt: s.createdAt,
+                fsResets: s.fsResets,
+                info: s.info,
+            };
         }
         catch (err) {
-            await this.unregister(conv, lease.token);
+            await this.unregister(env, lease.token);
             // releases the lease in whatever kind it has now (also after a downgrade)
             await lease.release();
             throw err;
         }
     }
     /** Ends a holder: unregisters it before releasing its lease, then moves `last_used_at` forward. */
-    async leave(conv, e) {
-        await this.unregister(conv, e.lease.token);
+    async leave(env, e) {
+        await this.unregister(env, e.lease.token);
         await e.lease.release();
-        await this.d.db
-            .updateTable("sandboxes")
+        await this.db
+            .updateTable("environment_instances")
             .set({ last_used_at: sql `GREATEST(last_used_at, now())` })
-            .where("conversation_id", "=", conv)
+            .where("environment_id", "=", env)
             .where("status", "=", "running")
             .execute()
-            .catch((err) => this.d.log.warn("cannot update sandbox last_used_at", { conversationId: conv, err }));
+            .catch((err) => this.log.warn("cannot update sandbox last_used_at", { environmentId: env, err }));
     }
-    async register(conv, token) {
-        const ttl = this.d.config().sandbox.limits.maxCommandSeconds * 1000 + HOLDER_TTL_MARGIN_MS;
+    async register(env, token) {
+        const ttl = this.config.get().sandbox.limits.maxCommandSeconds * 1000 + HOLDER_TTL_MARGIN_MS;
         await this.leases
-            .registerHolder(conv, token, ttl)
-            .catch((err) => this.d.log.warn("cannot record sandbox holder", { conversationId: conv, err }));
+            .registerHolder(env, token, ttl)
+            .catch((err) => this.log.warn("cannot record sandbox holder", { environmentId: env, err }));
     }
-    async unregister(conv, token) {
+    async unregister(env, token) {
         await this.leases
-            .unregisterHolder(conv, token)
-            .catch((err) => this.d.log.warn("cannot clear sandbox holder record", { conversationId: conv, err }));
+            .unregisterHolder(env, token)
+            .catch((err) => this.log.warn("cannot clear sandbox holder record", { environmentId: env, err }));
     }
-    /**
-     * Crashed holders' tags (claimed), and an older kernel's busy marker when `exclusiveToken` is
-     * the caller's exclusive lease; a Redis error counts as none.
-     */
-    async claim(conv, exclusiveToken) {
+    /** Crashed holders' tags (claimed); a Redis error counts as none. */
+    async claim(env) {
         try {
-            return await this.leases.claimDeadHolders(conv, exclusiveToken);
+            return await this.leases.claimDeadHolders(env);
         }
         catch (err) {
-            this.d.log.warn("cannot read sandbox holder records", { conversationId: conv, err });
-            return { tags: [], legacyMarker: false };
+            this.log.warn("cannot read sandbox holder records", { environmentId: env, err });
+            return [];
         }
     }
+    /** Kills the commands of crashed holders by their tags (`killTagged`); nothing without tags. */
+    async killTagged(env, handle, p, tags, signal, lease) {
+        if (tags.length === 0)
+            return;
+        const sig = AbortSignal.any([signal, lease.signal]);
+        await this.kill(env, "takeover", () => p.impl.killTagged(handle, tags, sig), sig);
+    }
     /** Runs one kill call: gone and abort are thrown, other failures only warned. */
-    async kill(conversationId, why, call, signal) {
+    async kill(environmentId, why, call, signal) {
         try {
             await call();
             if (why === "takeover") {
-                this.d.log.info("sandbox taken over from a holder that did not finish; leftover commands killed", { conversationId });
+                this.log.info("sandbox taken over from a holder that did not finish; leftover commands killed", { environmentId });
             }
         }
         catch (err) {
             if (signal?.aborted || isSandboxGoneError(err))
                 throw err;
-            this.d.log.warn("cannot kill leftover sandbox commands", { conversationId, err });
+            this.log.warn("cannot kill leftover sandbox commands", { environmentId, err });
         }
     }
     /**
-     * 休眠：空闲超过 `suspendAfterIdleMinutes`、或连续运行超过 `maxRunningMinutes` 的运行中沙箱。
-     * Skips a sandbox with any holder; one past `maxRunningMinutes` gets the intent for one poll
-     * window (about a second) first. 返回本次休眠的个数。由维护队列每分钟调用。
+     * Suspends running instances idle longer than `suspendAfterIdleMinutes` or running continuously
+     * longer than `maxRunningMinutes`. Skips an environment with any holder; one past
+     * `maxRunningMinutes` gets the intent for one poll window (about a second) first. Returns how
+     * many it suspended. Called every minute by the `sandbox-suspend-idle` cron.
      */
     async suspendIdle(now) {
-        const p = this.d.provider();
+        // cloud only: suspendDue keeps to this provider's rows, so `@device` is never suspended here
+        const p = this.providers.cloud();
         if (!p)
             return 0;
         const due = this.suspendDue(now, p.plugin);
-        const runningBefore = new Date(now.getTime() - this.d.config().sandbox.limits.maxRunningMinutes * 60_000);
+        const runningBefore = new Date(now.getTime() - this.config.get().sandbox.limits.maxRunningMinutes * 60_000);
         const rows = await this.candidates(due);
         let n = 0;
         await inPool(rows, SWEEP_CONCURRENCY, async (c) => {
             const overdue = c.running_since !== null && c.running_since < runningBefore;
-            const done = await this.tryLocked(c.conversation_id, async (lease) => {
-                const id = c.conversation_id;
-                const row = await this.d.db
-                    .selectFrom("sandboxes")
+            const done = await this.tryLocked(c.environment_id, async (lease) => {
+                const id = c.environment_id;
+                const row = await this.db
+                    .selectFrom("environment_instances")
                     .selectAll()
-                    .where("conversation_id", "=", id)
+                    .where("environment_id", "=", id)
                     .where(due)
                     .executeTakeFirst();
                 if (!row?.handle)
@@ -504,7 +753,7 @@ export class SandboxService {
                     running_since: null,
                     sweep_failed_at: null,
                 });
-                this.d.log.info("sandbox suspended", { conversationId: id });
+                this.log.info("sandbox suspended", { environmentId: id });
                 return true;
             }, overdue);
             if (done)
@@ -513,106 +762,217 @@ export class SandboxService {
         return n;
     }
     /**
-     * 销毁：超过 `destroyAfterInactiveDays` 没用过的、所属组织已删除的、对话已不存在的沙箱
-     * （对话已不存在的，销毁后删掉记录）。有 holder 的跳过。返回本次销毁的个数。由维护队列每小时调用。
+     * Destruction sweep: an instance unused for longer than `destroyAfterInactiveDays` is destroyed
+     * (the instance only; the file system is kept and the next use builds a new instance on it); an
+     * environment that was deleted, or whose org was deleted, loses its instance and its file system
+     * and its row is deleted (as {@link destroyEnvironment} does). Environments with any holder are
+     * skipped. Inactivity never destroys a `@device` instance; a gone `@device` environment is
+     * destroyed like any other while `@device` is registered. Returns how many it destroyed. Called
+     * hourly by the `sandbox-destroy-inactive` cron.
      */
     async destroyInactive(now) {
-        const p = this.d.provider();
-        if (!p)
-            return 0;
-        const due = this.destroyDue(now);
-        const rows = await this.candidates(due);
+        const p = this.providers.cloud();
+        const device = this.providers.forName(DEVICE_PROVIDER) !== undefined;
         let n = 0;
-        await inPool(rows, SWEEP_CONCURRENCY, async ({ conversation_id: id }) => {
+        // Gone environments (deleted, or of a deleted org) on every provider that is here, `@device`
+        // too (its destroy calls never need the machine online); rows whose provider is missing wait.
+        const here = (eb) => eb.or([
+            ...(p ? [this.cloudRow(eb)] : []),
+            ...(device ? [eb("provider", "=", DEVICE_PROVIDER)] : []),
+        ]);
+        const gone = (eb) => eb.and([here(eb), this.environmentGone(eb)]);
+        if (p || device) {
+            await inPool(await this.candidates(gone), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
+                const done = await this.tryLocked(id, async (lease) => {
+                    const row = await this.db
+                        .selectFrom("environment_instances")
+                        .selectAll()
+                        .where("environment_id", "=", id)
+                        .where(gone)
+                        .executeTakeFirst();
+                    const owner = row && this.rowProvider(row);
+                    if (!row || !owner)
+                        return false;
+                    await this.destroyRow(row, owner, lease, "environment");
+                    return true;
+                });
+                if (done)
+                    n++;
+            });
+        }
+        // inactivity destroys cloud instances only: `@device` instances are never swept
+        if (!p)
+            return n;
+        const due = this.instanceDue(now);
+        const idle = (eb) => eb.and([this.cloudRow(eb), due(eb)]);
+        await inPool(await this.candidates(idle), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
             const done = await this.tryLocked(id, async (lease) => {
-                const row = await this.d.db
-                    .selectFrom("sandboxes")
+                const row = await this.db
+                    .selectFrom("environment_instances")
                     .selectAll()
-                    .where("conversation_id", "=", id)
-                    .where(due)
+                    .where("environment_id", "=", id)
+                    .where(idle)
                     .executeTakeFirst();
                 if (!row)
                     return false;
-                await this.destroyRow(row, p, lease);
+                await this.destroyRow(row, p, lease, "instance");
                 return true;
             });
             if (done)
                 n++;
         });
-        // 早先已销毁、对话后来才删除、且没有遗留旧实例的记录
-        await this.d.db
-            .deleteFrom("sandboxes")
-            .where("status", "=", "destroyed")
-            .where("prev_handle", "is", null)
-            .where(({ not, exists, selectFrom }) => not(exists(selectFrom("conversations")
-            .select("conversations.id")
-            .whereRef("conversations.id", "=", "sandboxes.conversation_id"))))
-            .execute();
         return n;
     }
     /**
-     * 立即销毁该对话的沙箱（对话删除、离职处理时调用）；没有沙箱或已销毁时什么也不做。
-     * Waits for the exclusive lease (with intent, so running commands finish and new ones wait) up
-     * to 10 minutes. 没有提供方时只记 warn。
+     * Destroys the environment's instance, then its file system, then deletes its instance row
+     * (environment deletion, offboarding); nothing to do without a row. Waits for the exclusive lease
+     * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without the
+     * environment's provider it throws and the row stays, marked `sweep_failed_at` (the job is
+     * retried, and the destruction sweep finishes a deleted environment once the provider is back).
+     * Files kept by another provider that is not loaded cannot be destroyed: it throws and the row
+     * stays.
      */
-    async destroyFor(conversationId) {
-        const row = await this.d.db
-            .selectFrom("sandboxes")
-            .select("status")
-            .where("conversation_id", "=", conversationId)
+    async destroyEnvironment(environmentId) {
+        const row = await this.db
+            .selectFrom("environment_instances")
+            .select("environment_id")
+            .where("environment_id", "=", environmentId)
             .executeTakeFirst();
-        if (!row || row.status === "destroyed")
+        if (!row)
             return;
-        const p = this.d.provider();
+        const p = await this.providerOf(environmentId);
         if (!p) {
-            this.d.log.warn("cannot destroy sandbox: no sandbox provider", { conversationId });
-            return;
+            await this.db
+                .updateTable("environment_instances")
+                .set({ sweep_failed_at: sql `now()` })
+                .where("environment_id", "=", environmentId)
+                .execute();
+            throw new Error(`cannot destroy environment ${environmentId}: its sandbox provider is not there; ` +
+                "the destruction sweep retries it");
         }
-        const lease = await this.leases.acquireExclusive(conversationId, AbortSignal.timeout(DESTROY_FOR_WAIT_MS), undefined, { intent: true });
+        const lease = await this.leases.acquireExclusive(environmentId, AbortSignal.timeout(EXCLUSIVE_WAIT_MS), undefined, { intent: true });
         try {
-            const current = await this.d.db
-                .selectFrom("sandboxes")
+            const current = await this.db
+                .selectFrom("environment_instances")
                 .selectAll()
-                .where("conversation_id", "=", conversationId)
-                .where("status", "<>", "destroyed")
+                .where("environment_id", "=", environmentId)
                 .executeTakeFirst();
             if (current)
-                await this.destroyRow(current, p, lease);
+                await this.destroyRow(current, p, lease, "environment");
         }
         finally {
             await lease.release();
         }
     }
     /**
-     * 接手前任：杀掉沙箱里遗留的全部命令（killAll）。实例已不在（SandboxGoneError）与中止照常抛出（交给 withSandbox 重建 /
-     * 结束）；其余失败只记 warn。提供方没有 `killAll` 时只记 info。
+     * Starts the environment over with empty files (after `environment.files_lost`, or on request):
+     * under the exclusive lease (waited for like {@link destroyEnvironment}) destroys any instance and
+     * the file system (a `lost` one is only dropped), and records no file system; the next use
+     * creates a new one. Nothing to do without a row. Throws `sandbox.unavailable` without a provider.
      */
-    async killLeftovers(conversationId, handle, p, signal, why) {
-        const killAll = p.impl.killAll;
-        if (!killAll) {
-            if (why === "takeover") {
-                this.d.log.info("sandbox taken over from a holder that did not finish; provider cannot kill its commands", { conversationId });
-            }
-            return;
+    async resetFileSystem(environmentId) {
+        const p = await this.require(environmentId);
+        const lease = await this.leases.acquireExclusive(environmentId, AbortSignal.timeout(EXCLUSIVE_WAIT_MS), undefined, { intent: true });
+        try {
+            const row = await this.db
+                .selectFrom("environment_instances")
+                .selectAll()
+                .where("environment_id", "=", environmentId)
+                .executeTakeFirst();
+            if (!row)
+                return;
+            const fence = { gen: row.generation };
+            const signal = opSignal(lease);
+            const prev = await this.destroyInstance(row, p, signal);
+            await this.destroyFiles(row, p, signal, true);
+            if (!(await lease.renew()))
+                throw new SandboxLockLostError(environmentId);
+            await this.fenced(lease, environmentId, fence, {
+                fs_handle: null,
+                fs_status: "none",
+                handle: null,
+                status: "none",
+                running_since: null,
+                suspended_at: null,
+                destroyed_at: sql `now()`,
+                sweep_failed_at: null,
+                // conversations that used the old files are told they were reset (seenBy)
+                fs_resets: sql `fs_resets + 1`,
+                ...prev,
+            });
+            this.log.info("environment files reset", { environmentId });
+        }
+        finally {
+            await lease.release();
         }
-        await this.kill(conversationId, why, () => killAll.call(p.impl, handle, signal), signal);
     }
-    require() {
-        const p = this.d.provider();
-        if (!p)
-            throw sandboxUnavailable();
-        return p;
+    /**
+     * Under the exclusive lease (before the downgrade), on an instance just resumed from
+     * `suspended`: kills every command left in it (`killAll`), crashed holders' (`dead`, already
+     * claimed) included. Never on the shared path: other holders may be running commands. A gone
+     * instance (`SandboxGoneError`) and an abort are thrown (`withSandbox` rebuilds / ends); other
+     * failures are only warned.
+     */
+    async killLeftovers(environmentId, handle, p, signal, dead) {
+        await this.kill(environmentId, dead.length > 0 ? "takeover" : "resume", () => p.impl.killAll(handle, signal), signal);
+    }
+    /**
+     * Under the exclusive lease, right after a resume or a (re)build: kills the sessions of the
+     * background tasks marked lost while their process may live on (`kill_pending`), in one exec of
+     * `pkill -KILL -s <sid>`, then clears their flags. Tasks of another instance have no process
+     * here and are only cleared. A gone instance and an abort are thrown; another failure is warned
+     * and leaves the flags of this instance's tasks for the next resume.
+     */
+    async killPendingTasks(environmentId, handle, createdAt, p, tag, actor, signal) {
+        const rows = await this.background.pendingKills(environmentId);
+        if (rows.length === 0)
+            return;
+        const mine = rows.filter((r) => r.sandboxCreatedAt?.getTime() === createdAt && r.sid !== null && SID_RE.test(r.sid));
+        let cleared = rows;
+        if (mine.length > 0) {
+            // pkill exits 1 when the session has no process left: only a higher status is a failure
+            const command = `rc=0; for sid in ${mine.map((r) => r.sid).join(" ")}; do pkill -KILL -s "$sid"; c=$?; [ "$c" -le 1 ] || rc=$c; done; exit $rc`;
+            try {
+                const r = await p.impl.exec(handle, {
+                    command,
+                    timeoutMs: PENDING_KILL_TIMEOUT_MS,
+                    maxOutputBytes: 4096,
+                    signal,
+                    tag,
+                    actor,
+                });
+                if (r.exitCode !== 0) {
+                    throw new Error(`pkill exited with ${r.exitCode === null ? "no status" : r.exitCode}: ${r.stderr.slice(0, 500)}`);
+                }
+                this.log.info("lost background tasks killed after a sandbox resume", {
+                    environmentId,
+                    tasks: mine.map((t) => t.id),
+                });
+            }
+            catch (err) {
+                if (signal.aborted || isSandboxGoneError(err))
+                    throw err;
+                this.log.warn("cannot kill lost background tasks after a sandbox resume", {
+                    environmentId,
+                    err,
+                });
+                const kept = new Set(mine.map((r) => r.id));
+                cleared = rows.filter((r) => !kept.has(r.id));
+            }
+        }
+        await this.background.clearKill(cleared.map((r) => r.id));
     }
     /**
-     * 防护写入：lease 仍在、且记录的 generation 仍是锁内读到的值时才写（并加一）；否则抛 {@link SandboxLockLostError}。
+     * A fenced write: only while the lease holds and the row's generation is still the one read
+     * under it (and incremented); otherwise {@link SandboxLockLostError}.
      */
     async fenced(lease, id, fence, set) {
         if (lease.signal.aborted)
             throw new SandboxLockLostError(id);
-        const r = await this.d.db
-            .updateTable("sandboxes")
+        const r = await this.db
+            .updateTable("environment_instances")
             .set({ ...set, generation: fence.gen + 1 })
-            .where("conversation_id", "=", id)
+            .where("environment_id", "=", id)
             .where("generation", "=", fence.gen)
             .returning("created_at")
             .executeTakeFirst();
@@ -621,11 +981,11 @@ export class SandboxService {
         fence.gen++;
         return r.created_at;
     }
-    /** 扫描的候选：上次扫描失败的排在后面，其余按最久未用在前。 */
+    /** Sweep candidates: those whose last sweep failed come last, the rest least recently used first. */
     async candidates(due) {
-        return await this.d.db
-            .selectFrom("sandboxes")
-            .select(["conversation_id", "running_since"])
+        return await this.db
+            .selectFrom("environment_instances")
+            .select(["environment_id", "running_since"])
             .where(due)
             .orderBy(sql `sweep_failed_at ASC NULLS FIRST`)
             .orderBy("last_used_at")
@@ -634,17 +994,17 @@ export class SandboxService {
     }
     /**
      * One try at the exclusive lease: null → false; else runs `fn`. With `overdue` (past
-     * `maxRunningMinutes`) a busy sandbox gets the intent for about a second, so new commands wait
-     * briefly and the sweep gets in if the running ones end. Failures are warned, recorded in
+     * `maxRunningMinutes`) a busy environment gets the intent for about a second, so new commands
+     * wait briefly and the sweep gets in if the running ones end. Failures are warned, recorded in
      * `sweep_failed_at` (sorted last next time) and return false.
      */
-    async tryLocked(conversationId, fn, overdue = false) {
+    async tryLocked(environmentId, fn, overdue = false) {
         let lease;
         try {
-            lease = await this.leases.tryExclusive(conversationId);
+            lease = await this.leases.tryExclusive(environmentId);
             if (!lease && overdue) {
                 lease = await this.leases
-                    .acquireExclusive(conversationId, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS), Math.max(this.pollMs * 2, SWEEP_INTENT_WAIT_MS), { intent: true })
+                    .acquireExclusive(environmentId, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS), Math.max(this.pollMs * 2, SWEEP_INTENT_WAIT_MS), { intent: true })
                     .catch((err) => {
                     if (err instanceof ApiError && err.code === "sandbox.busy")
                         return null;
@@ -653,7 +1013,7 @@ export class SandboxService {
             }
         }
         catch (err) {
-            this.d.log.warn("cannot take sandbox lock", { conversationId, err });
+            this.log.warn("cannot take sandbox lock", { environmentId, err });
             return false;
         }
         if (!lease)
@@ -662,11 +1022,11 @@ export class SandboxService {
             return await fn(lease);
         }
         catch (err) {
-            this.d.log.warn("sandbox maintenance failed; will retry", { conversationId, err });
-            await this.d.db
-                .updateTable("sandboxes")
+            this.log.warn("sandbox maintenance failed; will retry", { environmentId, err });
+            await this.db
+                .updateTable("environment_instances")
                 .set({ sweep_failed_at: sql `now()` })
-                .where("conversation_id", "=", conversationId)
+                .where("environment_id", "=", environmentId)
                 .execute()
                 .catch(() => { });
             return false;
@@ -676,82 +1036,121 @@ export class SandboxService {
         }
     }
     /**
-     * Under the exclusive lease: make the conversation's sandbox run. `gone`: the instance a holder
+     * Under the exclusive lease: make the environment's instance run. `gone`: the instance a holder
      * found gone; when it is still the recorded one it is rebuilt, when another holder already
      * rebuilt it the new one is used.
      */
     async ensure(ctx, p, held, signal, gone) {
-        const id = ctx.conversationId;
-        await this.d.db
-            .insertInto("sandboxes")
-            .values({ conversation_id: id, org_id: ctx.orgId, provider: p.plugin, status: "creating" })
-            .onConflict((oc) => oc.column("conversation_id").doNothing())
+        const id = ctx.environmentId;
+        // Only a live environment of the caller's org gets a row, with the environment's own org; a
+        // row made earlier (another use) keeps its file system handle.
+        await this.db
+            .insertInto("environment_instances")
+            .columns(["environment_id", "org_id", "provider", "status"])
+            .expression((eb) => eb
+            .selectFrom("environments")
+            .select((e) => [
+            "environments.id",
+            "environments.org_id",
+            e.val(p.plugin).as("provider"),
+            e.val("creating").as("status"),
+        ])
+            .where("environments.id", "=", id)
+            .where("environments.org_id", "=", ctx.orgId)
+            .where("environments.deleted_at", "is", null))
+            .onConflict((oc) => oc.column("environment_id").doNothing())
             .execute();
-        const row = await this.d.db
-            .selectFrom("sandboxes")
+        // Under the lease: a use that waited behind destroyEnvironment (or raced a deletion) must not
+        // bring the environment's provider resources back.
+        const live = await this.db
+            .selectFrom("environments")
+            .select("id")
+            .where("id", "=", id)
+            .where("org_id", "=", ctx.orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!live)
+            throw environmentNotFound();
+        const row = await this.db
+            .selectFrom("environment_instances")
             .selectAll()
-            .where("conversation_id", "=", id)
-            .executeTakeFirstOrThrow();
-        if (row.org_id !== ctx.orgId) {
-            throw new ApiError("forbidden", `The sandbox of conversation ${id} does not belong to organization ${ctx.orgId}`);
-        }
+            .where("environment_id", "=", id)
+            .executeTakeFirst();
+        if (!row)
+            throw environmentNotFound();
+        if (row.org_id !== ctx.orgId)
+            throw this.foreign(ctx);
         const fence = { gen: row.generation };
-        // 每次拿到锁先防护地加一：锁已过期、却还在跑的旧持有者（如卡住的扫描）之后的写入一定失败
+        // Every acquisition first does a fenced increment: an old holder whose lease expired while it
+        // kept running (a stalled sweep) then fails its next write.
         await this.fenced(held, id, fence, {});
+        if (row.fs_status === "lost")
+            throw environmentFilesLost(p.plugin === DEVICE_PROVIDER);
+        if (row.provider !== null &&
+            row.provider !== p.plugin &&
+            (row.fs_status !== "none" || row.handle !== null)) {
+            throw otherProvider(row.provider);
+        }
+        if (row.provider !== null &&
+            row.provider !== p.plugin &&
+            row.fs_status === "none" &&
+            row.status === "creating") {
+            // a create by the previous provider ended before its file system was recorded: that
+            // provider may have made it by name, and nothing else would ever destroy it
+            await this.dropUnrecordedFiles(id, row.provider, signal);
+        }
         const handle = row.handle;
         const createdAt = row.created_at.getTime();
-        if (handle && row.provider === p.plugin && isInstance(row, gone) && row.status === "running") {
-            const created = await this.create(ctx, p, held, fence, signal, {});
-            return { ...created, info: { fresh: true, recreated: true }, fence };
+        const fsResets = row.fs_resets;
+        if (handle && isInstance(row, gone) && row.status === "running") {
+            const created = await this.create(ctx, p, held, row, fence, signal);
+            return { ...created, fsResets, info: { fresh: true, restarted: true }, fence };
         }
-        if (handle && row.provider === p.plugin) {
-            if (row.status === "running") {
-                return { handle, createdAt, info: { fresh: false, recreated: false }, fence };
-            }
-            if (row.status === "suspended") {
-                const r = await p.impl.resume(handle, signal);
-                if (r === "resumed") {
-                    await this.fenced(held, id, fence, {
-                        status: "running",
-                        running_since: sql `now()`,
-                        suspended_at: null,
-                        sweep_failed_at: null,
-                    });
-                    return {
-                        handle,
-                        createdAt,
-                        info: { fresh: false, recreated: false },
-                        fence,
-                        resumed: true,
-                    };
-                }
-                this.d.log.info("sandbox is gone at the provider; recreating", { conversationId: id });
-            }
+        if (handle && row.status === "running") {
+            return { handle, createdAt, fsResets, info: { fresh: false, restarted: false }, fence };
         }
-        // 换了提供方且旧实例还没销毁：交给旧提供方（仍加载时）销毁，否则记进 prev_*
-        let prev = {};
-        if (handle && row.provider !== p.plugin && row.status !== "destroyed") {
-            const kept = await this.retire(id, row.provider, handle, signal);
-            if (kept) {
-                if (row.prev_handle) {
-                    this.d.log.warn("sandbox instance of an earlier provider is leaked", {
-                        conversationId: id,
-                        provider: row.prev_provider,
-                    });
-                }
-                prev = { prev_provider: row.provider, prev_handle: JSON.stringify(handle) };
+        if (handle && row.status === "suspended") {
+            const r = await p.impl.resume(handle, signal);
+            if (r === "resumed") {
+                await this.fenced(held, id, fence, {
+                    status: "running",
+                    running_since: sql `now()`,
+                    suspended_at: null,
+                    sweep_failed_at: null,
+                });
+                return {
+                    handle,
+                    createdAt,
+                    fsResets,
+                    info: { fresh: false, restarted: false },
+                    fence,
+                    resumed: true,
+                };
             }
+            this.log.info("sandbox instance is gone at the provider; recreating", {
+                environmentId: id,
+            });
         }
-        const created = await this.create(ctx, p, held, fence, signal, prev);
-        // had_instance 只会置 true：之前成功创建过（哪怕后来重建失败）都算重建
-        return { ...created, info: { fresh: true, recreated: row.had_instance }, fence };
+        const created = await this.create(ctx, p, held, row, fence, signal);
+        // had_instance only ever becomes true: any earlier instance (even if a rebuild failed since)
+        // makes this one a restart on the kept files
+        return {
+            ...created,
+            fsResets,
+            info: { fresh: true, restarted: row.had_instance && row.fs_status === "ready" },
+            fence,
+        };
     }
     /**
-     * 在锁内创建：先防护地重置为 creating，再调提供方，最后防护地写入句柄。
-     * 写句柄时发现锁已丢失：尽力销毁刚建好的实例，再抛 {@link SandboxLockLostError}。
+     * Under the lease: fenced reset to `creating`, the file system when there is none
+     * (`createFileSystem`, its handle written fenced), then the instance on it, then a fenced write
+     * of the instance handle. `FileSystemGoneError` from `create` records `fs_status = 'lost'` and
+     * throws `environment.files_lost`. When the instance handle cannot be written (lease lost), the
+     * new instance is destroyed (best effort) before {@link SandboxLockLostError} is thrown.
      */
-    async create(ctx, p, held, fence, signal, extra) {
-        const id = ctx.conversationId;
+    async create(ctx, p, held, row, fence, signal) {
+        const id = ctx.environmentId;
+        const name = environmentResourceName(id);
         await this.fenced(held, id, fence, {
             org_id: ctx.orgId,
             provider: p.plugin,
@@ -762,21 +1161,45 @@ export class SandboxService {
             suspended_at: null,
             destroyed_at: null,
             sweep_failed_at: null,
-            ...extra,
         });
-        const cfg = this.d.config().sandbox;
-        // 出站按组织设置收窄（Ruling M19）；只在创建时生效，改设置只影响之后新建的沙箱
-        const egress = effectiveSandboxEgress(cfg.limits, (await readOrgSettings(this.d.db, ctx.orgId)).sandboxEgress);
-        // cpu / 内存按企业管理员的组织覆盖（C19 / Ruling M16），同样只在创建时生效
-        const sized = effectiveSandboxLimits({ ...cfg.limits, ...egress }, await readSandboxLimitOverride(this.d.db, ctx.orgId));
-        const limits = {
-            cpu: sized.cpu,
-            memoryMb: sized.memoryMb,
-            diskMb: sized.diskMb,
-            egress: sized.egress,
-            allowHosts: sized.allowHosts,
-        };
-        const handle = await p.impl.create({ name: `cap-${id}`, image: cfg.image, limits, signal });
+        // the org's effective limits apply at creation only, so a changed setting reaches only
+        // instances created afterwards
+        const limits = await this.orgLimits(ctx.orgId);
+        const cfg = this.config.get().sandbox;
+        let fs = row.fs_status === "ready" && (row.provider === null || row.provider === p.plugin)
+            ? row.fs_handle
+            : null;
+        if (fs === null) {
+            fs = await p.impl.createFileSystem({ name, limits, signal });
+            // A lost lease fails this write and leaves the file system alone: createFileSystem returns
+            // the existing one for a name, so the new holder may already use it, files and all.
+            await this.fenced(held, id, fence, {
+                provider: p.plugin,
+                fs_handle: JSON.stringify(fs),
+                fs_status: "ready",
+            });
+            this.log.info("environment file system created", { environmentId: id, provider: p.plugin });
+        }
+        let handle;
+        try {
+            handle = await p.impl.create({
+                name,
+                ...(cfg.image !== undefined && { image: cfg.image }),
+                limits,
+                fileSystem: fs,
+                signal,
+            });
+        }
+        catch (err) {
+            if (!isFileSystemGoneError(err))
+                throw err;
+            this.log.warn("environment file system is gone at the provider; its files are lost", {
+                environmentId: id,
+                provider: p.plugin,
+            });
+            await this.fenced(held, id, fence, { fs_status: "lost", status: "none" });
+            throw environmentFilesLost(p.plugin === DEVICE_PROVIDER);
+        }
         let createdAt;
         try {
             createdAt = await this.fenced(held, id, fence, {
@@ -789,72 +1212,138 @@ export class SandboxService {
             });
         }
         catch (e) {
-            // 锁已丢失、没能记下句柄：尽力销毁刚建好的实例，免得泄漏。
-            // 提供方按名字（cap-<对话>）复用实例时（Ruling M10），这个 destroy 可能打到新持有者刚恢复 / 创建的同一个实例。
-            // 这能自愈：新持有者下一次提供方调用抛 SandboxGoneError（或 resume 返回 gone），withSandbox 原地重建并重试。
-            await p.impl.destroy(handle, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS)).catch((err) => this.d.log.warn("cannot destroy sandbox created after the lock was lost", {
-                conversationId: id,
+            // Lease lost before the handle was recorded: destroy the new instance (best effort) so it
+            // does not leak. A provider that reuses instances by name (Ruling M10) may then hit the one
+            // the new holder just resumed or created; that heals: its next provider call throws
+            // SandboxGoneError (or resume returns gone) and withSandbox rebuilds in place. The file
+            // system is never touched here.
+            await p.impl.destroy(handle, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS)).catch((err) => this.log.warn("cannot destroy sandbox created after the lock was lost", {
+                environmentId: id,
                 err,
             }));
             throw e;
         }
-        this.d.log.info("sandbox created", { conversationId: id, provider: p.plugin });
+        this.log.info("sandbox created", { environmentId: id, provider: p.plugin });
         return { handle, createdAt: createdAt.getTime() };
     }
     /**
-     * 用旧提供方销毁别的提供方创建的实例：旧提供方仍加载且销毁成功 → false；否则 warn 并返回 true（需要留着记录）。
+     * Destroys the file system another provider may have made under the environment's name without
+     * the kernel recording it (`destroyFileSystemByName`; not there is success). That provider not
+     * loaded, or a failure, is only warned (the files may leak there) so the environment stays
+     * usable; an abort is thrown.
+     */
+    async dropUnrecordedFiles(id, provider, signal) {
+        const old = this.providers.forName(provider)?.impl;
+        if (!old) {
+            this.log.warn("environment file system may have been made by a provider that is not loaded; it may leak", { environmentId: id, provider });
+            return;
+        }
+        try {
+            await old.destroyFileSystemByName(environmentResourceName(id), signal);
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw err;
+            this.log.warn("cannot destroy the file system of the previous sandbox provider", {
+                environmentId: id,
+                provider,
+                err,
+            });
+        }
+    }
+    /**
+     * Destroys an instance of another provider with that provider: still loaded and destroyed →
+     * false; otherwise warns and returns true (the record must be kept).
      */
     async retire(id, provider, handle, signal) {
-        const old = this.d.lookup?.(provider);
+        const old = this.providers.forName(provider)?.impl;
         if (old) {
             try {
                 await old.destroy(handle, AbortSignal.any([signal, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS)]));
                 return false;
             }
             catch (err) {
-                this.d.log.warn("cannot destroy sandbox instance of the previous provider", {
-                    conversationId: id,
+                this.log.warn("cannot destroy sandbox instance of the previous provider", {
+                    environmentId: id,
                     provider,
                     err,
                 });
                 return true;
             }
         }
-        this.d.log.warn("sandbox was created by another provider that is not loaded; its instance may leak", { conversationId: id, provider });
+        this.log.warn("sandbox was created by another provider that is not loaded; its instance may leak", { environmentId: id, provider });
         return true;
     }
-    /** 在锁内：销毁实例（与遗留的旧提供方实例）；对话已不存在的删掉记录，否则标记 destroyed。 */
-    async destroyRow(row, p, held) {
-        const id = row.conversation_id;
-        const fence = { gen: row.generation };
-        const signal = opSignal(held);
+    /**
+     * Under the lease: destroys the row's instance (and a leaked one of an earlier provider). An
+     * instance without a handle (a create that ended before the handle was recorded) is destroyed by
+     * name. Returns the `prev_*` patch for instances that could not be destroyed.
+     */
+    async destroyInstance(row, p, signal) {
+        const id = row.environment_id;
+        const owner = row.provider ?? p.plugin;
         let prev = {};
-        if (row.handle && row.provider === p.plugin) {
+        if (row.handle && owner === p.plugin) {
             await p.impl.destroy(row.handle, signal);
         }
         else if (row.handle && row.status !== "destroyed") {
-            if (await this.retire(id, row.provider, row.handle, signal)) {
-                prev = { prev_provider: row.provider, prev_handle: JSON.stringify(row.handle) };
+            if (await this.retire(id, owner, row.handle, signal)) {
+                prev = { prev_provider: owner, prev_handle: JSON.stringify(row.handle) };
             }
         }
-        else if (!row.handle && row.provider === p.plugin && p.impl.destroyByName) {
-            // 创建中途退出：提供方那边可能已有实例，只能按名字清理
-            await p.impl.destroyByName(`cap-${id}`, signal);
+        else if (!row.handle && row.status === "creating") {
+            // the provider may have built it already: only the name finds it
+            const impl = owner === p.plugin ? p.impl : this.providers.forName(owner)?.impl;
+            await impl?.destroyByName(environmentResourceName(id), signal);
         }
         if (row.prev_handle && row.prev_provider && !("prev_handle" in prev)) {
             if (!(await this.retire(id, row.prev_provider, row.prev_handle, signal))) {
                 prev = { prev_provider: null, prev_handle: null };
             }
         }
+        return prev;
+    }
+    /**
+     * Under the lease: destroys the row's file system with the provider that made it (by name when
+     * no handle was recorded: `createFileSystem` may have finished before the kernel stopped). With
+     * that provider not loaded it throws (the row must stay for a retry), or with `lenient` only
+     * warns (the files leak at that provider).
+     */
+    async destroyFiles(row, p, signal, lenient = false) {
+        const id = row.environment_id;
+        const owner = row.provider ?? p.plugin;
+        const impl = owner === p.plugin ? p.impl : this.providers.forName(owner)?.impl;
+        if (!impl) {
+            if (row.fs_handle === null)
+                return;
+            if (!lenient) {
+                throw new Error(`cannot destroy the file system of environment ${id}: its sandbox provider ${owner} is not loaded`);
+            }
+            this.log.warn("environment file system of a provider that is not loaded is leaked", {
+                environmentId: id,
+                provider: owner,
+            });
+            return;
+        }
+        if (row.fs_handle !== null)
+            await impl.destroyFileSystem(row.fs_handle, signal);
+        else
+            await impl.destroyFileSystemByName(environmentResourceName(id), signal);
+    }
+    /**
+     * Under the lease: `instance` destroys the instance and marks the row `destroyed` (the file
+     * system stays); `environment` also destroys the file system and deletes the row.
+     */
+    async destroyRow(row, p, held, mode) {
+        const id = row.environment_id;
+        const fence = { gen: row.generation };
+        const signal = opSignal(held);
+        const prev = await this.destroyInstance(row, p, signal);
+        if (mode === "environment")
+            await this.destroyFiles(row, p, signal);
         if (!(await held.renew()))
             throw new SandboxLockLostError(id);
-        const conversation = await this.d.db
-            .selectFrom("conversations")
-            .select("id")
-            .where("id", "=", id)
-            .executeTakeFirst();
-        const keepRow = conversation !== undefined || (prev.prev_handle ?? row.prev_handle) != null;
-        if (keepRow) {
+        if (mode === "instance") {
             await this.fenced(held, id, fence, {
                 status: "destroyed",
                 destroyed_at: sql `now()`,
@@ -862,21 +1351,21 @@ export class SandboxService {
                 sweep_failed_at: null,
                 ...prev,
             });
+            this.log.info("sandbox instance destroyed", { environmentId: id });
+            return;
         }
-        else {
-            const r = await this.d.db
-                .deleteFrom("sandboxes")
-                .where("conversation_id", "=", id)
-                .where("generation", "=", fence.gen)
-                .executeTakeFirst();
-            if (Number(r.numDeletedRows) !== 1)
-                throw new SandboxLockLostError(id, "generation");
-        }
-        this.d.log.info("sandbox destroyed", { conversationId: id });
+        const r = await this.db
+            .deleteFrom("environment_instances")
+            .where("environment_id", "=", id)
+            .where("generation", "=", fence.gen)
+            .executeTakeFirst();
+        if (Number(r.numDeletedRows) !== 1)
+            throw new SandboxLockLostError(id, "generation");
+        this.log.info("environment destroyed", { environmentId: id });
     }
-    /** 该休眠的：本提供方创建、运行中，且空闲到期或连续运行超时。 */
+    /** Due for suspension: made by this provider, running, and idle or running for too long. */
     suspendDue(now, plugin) {
-        const lim = this.d.config().sandbox.limits;
+        const lim = this.config.get().sandbox.limits;
         const idleBefore = new Date(now.getTime() - lim.suspendAfterIdleMinutes * 60_000);
         const runningBefore = new Date(now.getTime() - lim.maxRunningMinutes * 60_000);
         return (eb) => eb.and([
@@ -885,24 +1374,50 @@ export class SandboxService {
             eb.or([eb("last_used_at", "<", idleBefore), eb("running_since", "<", runningBefore)]),
         ]);
     }
-    /** 该销毁的：未销毁，且不活跃到期、组织已删除或对话已不存在。 */
-    destroyDue(now) {
-        const days = this.d.config().sandbox.limits.destroyAfterInactiveDays;
+    /** The provider of an instance row: an internal one (`@device`) by name, else the cloud one. */
+    rowProvider(row) {
+        return providerForEnvironment(this.providers, row.provider);
+    }
+    /**
+     * A row the idle sweeps may touch: not on a kernel-internal provider (`@device` instances live on
+     * people's machines and are never suspended or destroyed for inactivity).
+     */
+    cloudRow(eb) {
+        return eb.or([eb("provider", "is", null), eb("provider", "not like", "@%")]);
+    }
+    /** The environment was deleted, or its org was: the instance and the files go. */
+    environmentGone(eb) {
+        return eb.or([
+            eb.exists(eb
+                .selectFrom("environments")
+                .select("environments.id")
+                .whereRef("environments.id", "=", "environment_instances.environment_id")
+                .where("environments.deleted_at", "is not", null)),
+            eb.exists(eb
+                .selectFrom("orgs")
+                .select("orgs.id")
+                .whereRef("orgs.id", "=", "environment_instances.org_id")
+                .where("orgs.deleted_at", "is not", null)),
+        ]);
+    }
+    /** Due for instance destruction: an instance (or a create in progress) unused for too long. */
+    instanceDue(now) {
+        const days = this.config.get().sandbox.limits.destroyAfterInactiveDays;
         const before = new Date(now.getTime() - days * 24 * 3_600_000);
         return (eb) => eb.and([
-            eb("status", "<>", "destroyed"),
-            eb.or([
-                eb("last_used_at", "<", before),
-                eb.exists(eb
-                    .selectFrom("orgs")
-                    .select("orgs.id")
-                    .whereRef("orgs.id", "=", "sandboxes.org_id")
-                    .where("orgs.deleted_at", "is not", null)),
-                eb.not(eb.exists(eb
-                    .selectFrom("conversations")
-                    .select("conversations.id")
-                    .whereRef("conversations.id", "=", "sandboxes.conversation_id"))),
-            ]),
+            eb("status", "in", ["creating", "running", "suspended"]),
+            eb("last_used_at", "<", before),
         ]);
     }
-}
+};
+SandboxService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(REDIS)),
+    __param(2, Inject(SandboxLeases)),
+    __param(3, Inject(SandboxProviders)),
+    __param(4, Inject(KernelConfigService)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(BackgroundTaskStore))
+], SandboxService);
+export { SandboxService };