@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/sandbox/sandbox.service.d.ts

@@ -1,244 +1,457 @@
-import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLimits, type SandboxProvider, type SandboxRoots } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
+import { BackgroundTaskStore } from "../background/store.js";
 import { type KernelConfig } from "../config/schema.js";
-import type { SandboxesTable } from "../db/kernel-schema.js";
+import type { DeviceInstancesTable } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import type { KernelLogger } from "../log.js";
 import { SandboxLeases, type SandboxPathLease } from "./leases.js";
-import { type SandboxProviderEntry, SandboxProviders } from "./providers.js";
-export { SANDBOX_BUSY_PREFIX, SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
-/** `withSandbox` 回调的第三个参数。 */
+import { SandboxProviders } from "./providers.js";
+export { SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
+/** The third argument of the `withSandbox` callback. */
 export interface SandboxUseInfo {
-    /** 本次调用新建了沙箱（首次使用或重建）。 */
+    /** This call created the instance (first use, or a rebuild). */
     fresh: boolean;
-    /** 之前有过实例、但已不在（被销毁、提供方返回 gone、换了提供方），这是重建的空沙箱。 */
-    recreated: boolean;
+    /**
+     * The device had an instance before that is no longer there (destroyed after inactivity,
+     * gone at the provider, or rebuilt by another holder since this holder last used it): this is a
+     * new instance on the kept files, so earlier processes are gone.
+     */
+    restarted: boolean;
+    /**
+     * The device's files were reset since this holder last used it (on request, or after they
+     * were lost): earlier files are gone too. Set only when true; `restarted` is then false.
+     */
+    filesReset?: true;
+    /**
+     * The instance's roots ({@link rootsOf} of its handle): every model-visible path is built from
+     * them (environments spec §13.1; a connected machine's real paths).
+     */
+    roots: SandboxRoots;
+}
+/** Who uses the sandbox in {@link SandboxService.withSandbox}. */
+export interface SandboxUseContext {
+    orgId: string;
+    deviceId: string;
+    /** The agent conversation using it (a sub-agent's own for a child): what it last saw is tracked. */
+    holderConversationId: string;
+    /** Passed with every `exec` (audit and attribution). */
+    actor: SandboxActor;
 }
 export type { SandboxProviderEntry } from "./providers.js";
-type Row = Selectable<SandboxesTable>;
+type Row = Selectable<DeviceInstancesTable>;
+type ExecArgs = Parameters<SandboxProvider["exec"]>[1];
 /**
- * One instance of a conversation's sandbox: its handle and the row's `created_at`, which the
- * fenced write after every `create` sets. The handle alone is not enough: sandbox-docker's handle
- * is the instance name, the same after a rebuild (spec §10.10).
+ * One instance of a device: its handle and the row's `created_at`, which the fenced write
+ * after every `create` sets. The handle alone is not enough: sandbox-docker's handle is the
+ * instance name, the same after a rebuild (spec §10.10).
  */
 interface Instance {
     handle: SandboxHandle;
     createdAt: number;
 }
+/**
+ * The provider {@link SandboxService.withSandbox} passes to its callback: every `exec` carries the
+ * holder's tag and the caller's actor, so the callback passes neither.
+ */
+export type HeldProvider = Omit<SandboxProvider, "exec"> & {
+    exec(h: SandboxHandle, args: Omit<ExecArgs, "tag" | "actor">): Promise<ExecResult>;
+};
+/**
+ * The provider {@link SandboxService.ifRunning} passes to its callback: every `exec` carries the
+ * holder's tag; the caller names the actor.
+ */
+export type TaggedProvider = Omit<SandboxProvider, "exec"> & {
+    exec(h: SandboxHandle, args: Omit<ExecArgs, "tag">): Promise<ExecResult>;
+};
+/** What {@link SandboxService.ifRunning} did. */
+export type IfRunningResult<T> = {
+    kind: "ran";
+    value: T;
+}
+/**
+ * No instance, or it is not running: `status` is the instance row's (`none`, `suspended`,
+ * `creating`, `destroyed`, or `running` recorded with another provider), `gone` without a row.
+ */
+ | {
+    kind: "not_running";
+    status: Row["status"] | "gone";
+}
+/** The device now records another instance (a rebuild). */
+ | {
+    kind: "other_instance";
+};
+/** The provider-side name of a device's file system and instance. */
+export declare const deviceResourceName: (deviceId: string) => string;
+/** The device is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
+export declare const deviceNotFound: () => ApiError;
+/**
+ * The device's file system is gone at the provider (409); never replaced silently. On a
+ * connected machine (`local`, details `[{ source: "local" }]`) the directory is the machine
+ * owner's: `capybara-device logout`, then `login` into the device, recreates it (ruling R24).
+ */
+export declare const deviceFilesLost: (local?: boolean) => ApiError;
 /**
  * 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).
  */
 export declare const isInstance: (row: Pick<Row, "handle" | "created_at">, gone: Instance | null) => boolean;
 /**
- * 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).
- */
-export declare function sandboxConcurrency(impl: Pick<SandboxProvider, "concurrentExec" | "killTagged">, max: number): number;
-/**
- * 启动时要提醒运维的沙箱配置问题（英文日志）：
- * - `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 declare function sandboxConfigWarnings(cfg: Pick<KernelConfig, "runtime" | "sandbox" | "extensionConfig">, providerPlugin?: string, impl?: Pick<SandboxProvider, "concurrentExec" | "killTagged">): {
+export declare function sandboxConfigWarnings(cfg: Pick<KernelConfig, "runtime" | "sandbox" | "extensionConfig">, providerPlugin?: string): {
     level: "info" | "warn";
     message: string;
 }[];
-/** 没有沙箱提供方时的错误（503）。 */
+/** No sandbox provider (503). */
 export declare const sandboxUnavailable: () => ApiError;
 /**
- * 内核的沙箱服务（M5 T7）：在 `sandbox@1` 提供方之上，每个对话一个沙箱。
+ * The kernel's sandbox service over the `sandbox@2` provider, keyed by **device** (spec
+ * 2026-11-07-environments-design §4.2, §5.1): one file system kept until the device is
+ * deleted, plus one instance attached to it that comes and goes; all conversations bound to the
+ * device (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.
- * - **Suspension and destruction**: the sweeps (`SandboxSweepJobs`, crons) call {@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-device-<deviceId>`) and then the instance on it; state lives
+ *   in `device_instances`. A file system gone at the provider is never replaced silently:
+ *   `fs_status` becomes `lost` and uses fail with `device.files_lost` until
+ *   {@link resetFileSystem}.
+ * - **Leases** (phase C, spec §10, {@link SandboxLeases}), keyed by device id: using an
+ *   instance recorded `running` with the current provider takes a **shared** lease, so up to
+ *   `sandbox.maxConcurrentCommands` holders (all sessions of the device) 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
+ *   device 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 device 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 device 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 device** (environments spec §6): each call resolves the provider from
+ *   the device's `devices.provider` ({@link providerForDevice}): a `device`
+ *   device runs on the kernel-internal `@local` provider (never the cloud one), a cloud
+ *   device on the loaded `sandbox@2` extension. A `@local` instance is never suspended or
+ *   destroyed for inactivity; a deleted `@local` device (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 device unusable
+ * (`device.unavailable`) until that provider is back; deleting it still works while that
+ * provider is loaded ({@link SandboxProviders.forName}). Without the device's provider
+ * {@link availableFor} is false and uses throw `sandbox.unavailable` (503). No in-process state:
+ * replicas share it through PG and Redis.
  */
 export declare class SandboxService {
     private readonly db;
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     private readonly redis;
     private readonly leases;
-    /** The `sandbox@1` provider (read at every call: providers are ready after the extension load). */
+    /** The providers (read at every call: providers are ready after the extension load). */
     private readonly providers;
     private readonly config;
     private readonly log;
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    private readonly background;
     constructor(db: KernelDb, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis: Pick<Redis, "set">, leases: SandboxLeases, 
-    /** The `sandbox@1` provider (read at every call: providers are ready after the extension load). */
-    providers: Pick<SandboxProviders, "current" | "lookup">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">);
+    /** The providers (read at every call: providers are ready after the extension load). */
+    providers: Pick<SandboxProviders, "cloud" | "forName">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">, 
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    background: Pick<BackgroundTaskStore, "pendingKills" | "clearKill">);
     /** Poll interval while waiting for a lease (the leases' own). */
     private get pollMs();
-    /** 是否有沙箱提供方。 */
-    get available(): boolean;
-    /** Concurrent holders the provider gets ({@link sandboxConcurrency} with the current config). */
-    effectiveCap(p: SandboxProviderEntry): number;
     /**
-     * 该对话沙箱的对外状态（只读，不拿锁）：`running` / `suspended` 与最近使用时间。
-     * 还没有、已销毁、或停在 `creating`（正在创建，或创建失败等下次使用重建）的都返回 null（界面显示「未创建」）。
+     * Whether there is a cloud sandbox provider (a loaded `sandbox@2` extension). For gates that have
+     * no device yet (tool listing, skill files); a call on a device asks
+     * {@link availableFor}.
+     */
+    get cloudAvailable(): boolean;
+    /** Whether the device's provider is there (`@local` registered, or a cloud provider). */
+    availableFor(deviceId: string): Promise<boolean>;
+    /**
+     * The provider the device works with, read from its row ({@link providerForDevice});
+     * a missing row (or one of another org, with `orgId`) reads as a cloud device, whose use
+     * then fails as not found.
      */
-    status(orgId: string, conversationId: string): Promise<{
+    private providerOf;
+    /** {@link providerOf}, or `sandbox.unavailable` (503) without it. */
+    private require;
+    /** Concurrent holders of one device (`sandbox.maxConcurrentCommands`, read at every use). */
+    private get cap();
+    /**
+     * 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 devices use
+     * them unchanged.
+     */
+    orgLimits(orgId: string): Promise<SandboxLimits>;
+    /**
+     * The device'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.
+     */
+    status(orgId: string, deviceId: string): Promise<{
         status: "running" | "suspended";
         lastUsedAt: Date;
     } | null>;
     /**
-     * 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.
-     */
-    pathLease(conversationId: string, path: string, signal: AbortSignal): Promise<SandboxPathLease>;
-    /**
-     * 在该对话（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).
-     */
-    withSandbox<T>(ctx: {
-        orgId: string;
-        conversationId: string;
-        holderConversationId?: string;
-    }, fn: (h: SandboxHandle, p: SandboxProvider, info: SandboxUseInfo, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<T>;
-    /**
-     * 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.
+     * The instance the device 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.
+     */
+    currentInstance(deviceId: string): Promise<{
+        createdAt: Date;
+    } | null>;
+    /**
+     * Runs `fn` on the device'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.
+     */
+    ifRunning<T>(deviceId: string, instance: {
+        createdAt: Date;
+    }, fn: (p: TaggedProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<IfRunningResult<T>>;
+    /**
+     * A short lease on one path of the device 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(deviceId: string, path: string, signal: AbortSignal): Promise<SandboxPathLease>;
+    /**
+     * Runs `fn` on the device'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 `device.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).
+     */
+    withSandbox<T>(ctx: SandboxUseContext, fn: (h: SandboxHandle, p: HeldProvider, info: SandboxUseInfo, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<T>;
+    /**
+     * 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
+     * `device.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.
+     */
+    private filesGone;
+    /**
+     * 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 device). Best effort: a Redis error only
+     * logs.
      */
     private seenBy;
-    /** Runs `fn` as the holder `e`: its tag on every exec, its lease's signal. */
+    /** Runs `fn` as the holder `e`: its tag and the caller's actor on every exec, its lease's signal. */
     private runAs;
     /**
      * 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.
      */
     private enter;
     private clearIntent;
     private readRow;
-    /** 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. */
+    private foreign;
+    /**
+     * 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.
+     */
     private usable;
     /**
-     * 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.
      */
     private asShared;
     /**
-     * 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.
      */
     private asExclusive;
     /** Ends a holder: unregisters it before releasing its lease, then moves `last_used_at` forward. */
     private leave;
     private register;
     private unregister;
-    /**
-     * 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.
-     */
+    /** Crashed holders' tags (claimed); a Redis error counts as none. */
     private claim;
+    /** Kills the commands of crashed holders by their tags (`killTagged`); nothing without tags. */
+    private killTagged;
     /** Runs one kill call: gone and abort are thrown, other failures only warned. */
     private kill;
     /**
-     * 休眠：空闲超过 `suspendAfterIdleMinutes`、或连续运行超过 `maxRunningMinutes` 的运行中沙箱。
-     * Skips a sandbox with any holder; one past `maxRunningMinutes` gets the intent for one poll
-     * window (about a second) first. 返回本次休眠的个数。Called every minute by the `sandbox-suspend-idle` cron.
+     * Suspends running instances idle longer than `suspendAfterIdleMinutes` or running continuously
+     * longer than `maxRunningMinutes`. Skips a device 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.
      */
     suspendIdle(now: Date): Promise<number>;
     /**
-     * 销毁：超过 `destroyAfterInactiveDays` 没用过的、所属组织已删除的、对话已不存在的沙箱
-     * （对话已不存在的，销毁后删掉记录）。有 holder 的跳过。返回本次销毁的个数。Called hourly by the `sandbox-destroy-inactive` cron.
+     * 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
+     * device that was deleted, or whose org was deleted, loses its instance and its file system
+     * and its row is deleted (as {@link destroyDevice} does). Devices with any holder are
+     * skipped. Inactivity never destroys a `@local` instance; a gone `@local` device is
+     * destroyed like any other while `@local` is registered. Returns how many it destroyed. Called
+     * hourly by the `sandbox-destroy-inactive` cron.
      */
     destroyInactive(now: Date): Promise<number>;
     /**
-     * 立即销毁该对话的沙箱（对话删除、离职处理时调用）；没有沙箱或已销毁时什么也不做。
-     * Waits for the exclusive lease (with intent, so running commands finish and new ones wait) up
-     * to 10 minutes. 没有提供方时只记 warn。
+     * Destroys the device's instance, then its file system, then deletes its instance row
+     * (device 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
+     * device's provider it throws and the row stays, marked `sweep_failed_at` (the job is
+     * retried, and the destruction sweep finishes a deleted device once the provider is back).
+     * Files kept by another provider that is not loaded cannot be destroyed: it throws and the row
+     * stays.
+     */
+    destroyDevice(deviceId: string): Promise<void>;
+    /**
+     * Starts the device over with empty files (after `device.files_lost`, or on request):
+     * under the exclusive lease (waited for like {@link destroyDevice}) 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.
      */
-    destroyFor(conversationId: string): Promise<void>;
+    resetFileSystem(deviceId: string): Promise<void>;
     /**
-     * 接手前任：杀掉沙箱里遗留的全部命令（killAll）。实例已不在（SandboxGoneError）与中止照常抛出（交给 withSandbox 重建 /
-     * 结束）；其余失败只记 warn。提供方没有 `killAll` 时只记 info。
+     * 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.
      */
     private killLeftovers;
-    private require;
     /**
-     * 防护写入：lease 仍在、且记录的 generation 仍是锁内读到的值时才写（并加一）；否则抛 {@link SandboxLockLostError}。
+     * 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.
+     */
+    private killPendingTasks;
+    /**
+     * 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}.
      */
     private fenced;
-    /** 扫描的候选：上次扫描失败的排在后面，其余按最久未用在前。 */
+    /** Sweep candidates: those whose last sweep failed come last, the rest least recently used first. */
     private candidates;
     /**
      * 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 device 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.
      */
     private tryLocked;
     /**
-     * Under the exclusive lease: make the conversation's sandbox run. `gone`: the instance a holder
+     * Under the exclusive lease: make the device'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.
      */
     private ensure;
     /**
-     * 在锁内创建：先防护地重置为 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 `device.files_lost`. When the instance handle cannot be written (lease lost), the
+     * new instance is destroyed (best effort) before {@link SandboxLockLostError} is thrown.
      */
     private create;
     /**
-     * 用旧提供方销毁别的提供方创建的实例：旧提供方仍加载且销毁成功 → false；否则 warn 并返回 true（需要留着记录）。
+     * Destroys the file system another provider may have made under the device'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 device stays
+     * usable; an abort is thrown.
+     */
+    private dropUnrecordedFiles;
+    /**
+     * Destroys an instance of another provider with that provider: still loaded and destroyed →
+     * false; otherwise warns and returns true (the record must be kept).
      */
     private retire;
-    /** 在锁内：销毁实例（与遗留的旧提供方实例）；对话已不存在的删掉记录，否则标记 destroyed。 */
+    /**
+     * 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.
+     */
+    private destroyInstance;
+    /**
+     * 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).
+     */
+    private destroyFiles;
+    /**
+     * Under the lease: `instance` destroys the instance and marks the row `destroyed` (the file
+     * system stays); `device` also destroys the file system and deletes the row.
+     */
     private destroyRow;
-    /** 该休眠的：本提供方创建、运行中，且空闲到期或连续运行超时。 */
+    /** Due for suspension: made by this provider, running, and idle or running for too long. */
     private suspendDue;
-    /** 该销毁的：未销毁，且不活跃到期、组织已删除或对话已不存在。 */
-    private destroyDue;
+    /** The provider of an instance row: an internal one (`@local`) by name, else the cloud one. */
+    private rowProvider;
+    /**
+     * A row the idle sweeps may touch: not on a kernel-internal provider (`@local` instances live on
+     * people's machines and are never suspended or destroyed for inactivity).
+     */
+    private cloudRow;
+    /** The device was deleted, or its org was: the instance and the files go. */
+    private deviceGone;
+    /** Due for instance destruction: an instance (or a create in progress) unused for too long. */
+    private instanceDue;
 }