@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.13

package/dist/sandbox/leases.d.ts

@@ -4,11 +4,11 @@ import { LockService } from "../infra/lock/lock.service.js";
 import type { KernelLogger } from "../log.js";
 /**
  * Shared and exclusive sandbox leases (sub-agents spec §10.3; environments spec §4.2): the Redis
- * protocol that lets several holders (every conversation bound to the environment, and their
- * sub-agents) use one environment's running instance concurrently (shared leases: commands, file
+ * protocol that lets several holders (every conversation bound to the device, and their
+ * sub-agents) use one device's running instance concurrently (shared leases: commands, file
  * reads and writes) while lifecycle changes (create, resume, rebuild, suspend, destroy, reset) stay
  * alone (exclusive leases). Every `sandbox@2` provider runs commands concurrently and kills by tag,
- * so there is no single-holder mode. Keys, env = the environment id:
+ * so there is no single-holder mode. Keys, env = the device id:
  *
  * - `capk:sandbox:<env>`: the lock key: an exclusive holder's token, or `shared` while shared
  *   leases exist.
@@ -28,17 +28,17 @@ import type { KernelLogger } from "../log.js";
  * the renewal deadline (send time of the last successful renewal + 2/3 TTL): its `signal` aborts
  * with {@link SandboxLockLostError}.
  */
-/** Prefix of the lock key `capk:sandbox:<environmentId>`. */
+/** Prefix of the lock key `capk:sandbox:<deviceId>`. */
 export declare const SANDBOX_LOCK_PREFIX = "capk:sandbox:";
 /** TTL of a lease (ms): renewed every TTL / 3 while held. */
 export declare const SANDBOX_LOCK_TTL_MS = 60000;
-/** The environment's sandbox is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
+/** The device's sandbox is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
 export declare const sandboxBusy: () => ApiError;
 /** A lease was lost while held, or the record changed under it (generation mismatch). */
 export declare class SandboxLockLostError extends Error {
     /** `lock`: the lease was lost (renewal failed or none succeeded in time); `generation`: the record's fence changed. */
     readonly reason: "lock" | "generation";
-    constructor(environmentId: string, reason?: "lock" | "generation");
+    constructor(deviceId: string, reason?: "lock" | "generation");
 }
 /** Another holder kept writing the same file longer than the path lease wait (model-visible text). */
 export declare class SandboxPathBusyError extends Error {
@@ -49,7 +49,7 @@ export type LeaseKind = "shared" | "exclusive";
 export interface SandboxLease {
     readonly kind: LeaseKind;
     readonly token: string;
-    readonly environmentId: string;
+    readonly deviceId: string;
     /** Aborts with {@link SandboxLockLostError} when the lease is lost. */
     readonly signal: AbortSignal;
     /** Renews once now; false when the lease is lost (the signal then aborts). */
@@ -131,9 +131,9 @@ export declare class SandboxLeases {
      * (it should then {@link clearIntent}).
      */
     tryShared(env: string, cap: number, token?: string): Promise<SandboxLease | null>;
-    /** Deletes the environment's intent when it is `token`'s. */
+    /** Deletes the device's intent when it is `token`'s. */
     clearIntent(env: string, token: string): Promise<void>;
-    /** Live shared leases of the environment. */
+    /** Live shared leases of the device. */
     sharedCount(env: string): Promise<number>;
     /**
      * Records (or refreshes) a holder that may run commands (before its provider calls); `ttlMs`

package/dist/sandbox/leases.js

@@ -15,11 +15,11 @@ import { redisClockScript, sharedLeaseReadScript, } from "../infra/lock/shared-l
 import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 /**
  * Shared and exclusive sandbox leases (sub-agents spec §10.3; environments spec §4.2): the Redis
- * protocol that lets several holders (every conversation bound to the environment, and their
- * sub-agents) use one environment's running instance concurrently (shared leases: commands, file
+ * protocol that lets several holders (every conversation bound to the device, and their
+ * sub-agents) use one device's running instance concurrently (shared leases: commands, file
  * reads and writes) while lifecycle changes (create, resume, rebuild, suspend, destroy, reset) stay
  * alone (exclusive leases). Every `sandbox@2` provider runs commands concurrently and kills by tag,
- * so there is no single-holder mode. Keys, env = the environment id:
+ * so there is no single-holder mode. Keys, env = the device id:
  *
  * - `capk:sandbox:<env>`: the lock key: an exclusive holder's token, or `shared` while shared
  *   leases exist.
@@ -39,7 +39,7 @@ import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
  * the renewal deadline (send time of the last successful renewal + 2/3 TTL): its `signal` aborts
  * with {@link SandboxLockLostError}.
  */
-/** Prefix of the lock key `capk:sandbox:<environmentId>`. */
+/** Prefix of the lock key `capk:sandbox:<deviceId>`. */
 export const SANDBOX_LOCK_PREFIX = "capk:sandbox:";
 /** TTL of a lease (ms): renewed every TTL / 3 while held. */
 export const SANDBOX_LOCK_TTL_MS = 60_000;
@@ -51,16 +51,16 @@ const PATH_PREFIX = "capk:sandbox-path:";
 const PATH_LEASE_TTL_MS = 30_000;
 /** Shortest life of an exclusive waiter's intent (ms): outlasts event-loop lag between polls. */
 const INTENT_TTL_FLOOR_MS = 2000;
-/** The environment's sandbox is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
-export const sandboxBusy = () => new ApiError("sandbox.busy", "The sandbox of this environment is busy with other commands; wait for them to finish and try again");
+/** The device's sandbox is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
+export const sandboxBusy = () => new ApiError("sandbox.busy", "The sandbox of this device is busy with other commands; wait for them to finish and try again");
 /** A lease was lost while held, or the record changed under it (generation mismatch). */
 export class SandboxLockLostError extends Error {
     /** `lock`: the lease was lost (renewal failed or none succeeded in time); `generation`: the record's fence changed. */
     reason;
-    constructor(environmentId, reason = "lock") {
+    constructor(deviceId, reason = "lock") {
         super(reason === "lock"
-            ? `sandbox lock lost for environment ${environmentId}`
-            : `sandbox state of environment ${environmentId} changed concurrently (generation mismatch)`);
+            ? `sandbox lock lost for device ${deviceId}`
+            : `sandbox state of device ${deviceId} changed concurrently (generation mismatch)`);
         this.name = "SandboxLockLostError";
         this.reason = reason;
     }
@@ -208,7 +208,7 @@ let SandboxLeases = class SandboxLeases {
         }
         catch (e) {
             if (o.intent) {
-                await this.clearIntent(env, token).catch((err) => this.log.warn("cannot clear sandbox intent", { environmentId: env, err }));
+                await this.clearIntent(env, token).catch((err) => this.log.warn("cannot clear sandbox intent", { deviceId: env, err }));
             }
             throw e;
         }
@@ -231,11 +231,11 @@ let SandboxLeases = class SandboxLeases {
         const h = await this.locks.tryShared(this.keys(env), token, cap, this.ttlMs);
         return h ? this.held(env, h) : null;
     }
-    /** Deletes the environment's intent when it is `token`'s. */
+    /** Deletes the device's intent when it is `token`'s. */
     async clearIntent(env, token) {
         await this.locks.releaseIf(this.keys(env).intent, token);
     }
-    /** Live shared leases of the environment. */
+    /** Live shared leases of the device. */
     sharedCount(env) {
         return this.locks.sharedCount(this.keys(env));
     }
@@ -291,7 +291,7 @@ let SandboxLeases = class SandboxLeases {
         return {
             kind,
             token: h.token,
-            environmentId: env,
+            deviceId: env,
             signal,
             // a Redis error is warned, not thrown: the deadline decides whether the lease is lost
             renew: async () => {
@@ -301,7 +301,7 @@ let SandboxLeases = class SandboxLeases {
                     return await h.renew();
                 }
                 catch (err) {
-                    this.log.warn("sandbox lease renew failed", { environmentId: env, err });
+                    this.log.warn("sandbox lease renew failed", { deviceId: env, err });
                     return !signal.aborted;
                 }
             },

package/dist/sandbox/providers.d.ts

@@ -1,7 +1,7 @@
 import { type SandboxProvider } from "@capybara-hq/plugin-sdk";
 import { ExtensionRegistry } from "../extensions/registry.js";
-/** The kernel-internal provider of connected machines (`device` environments). */
-export declare const DEVICE_PROVIDER = "@device";
+/** The kernel-internal provider of connected machines (local devices). */
+export declare const LOCAL_PROVIDER = "@local";
 /**
  * A kernel-internal provider name: it starts with `@`, which no extension name can
  * (`EXTENSION_NAME_RE`), so it never collides with a loaded `sandbox@2` plugin.
@@ -15,7 +15,7 @@ export interface SandboxProviderEntry {
 /**
  * The sandbox providers of this process. The cloud provider is the loaded `sandbox@2` extension,
  * read from the {@link ExtensionRegistry} at every call (providers are ready only after the
- * extension load, and change with installs). Kernel-internal providers (`@device`) are registered
+ * extension load, and change with installs). Kernel-internal providers (`@local`) are registered
  * by their module on init, in every replica: they are code, not shared state.
  *
  * Every `sandbox@2` extension is handed out guarded: a network-level failure to reach it is
@@ -38,9 +38,9 @@ export declare class SandboxProviders {
     forName(name: string): SandboxProviderEntry | undefined;
 }
 /**
- * The provider an environment works with, from its `environments.provider`: an internal one
- * (`@device`) by that name only, never falling back to the cloud provider; any other environment
- * is a cloud environment and uses the current cloud provider (files kept by another provider are
- * refused by the sandbox service, `environment.unavailable`).
+ * The provider a device works with, from its `devices.provider`: an internal one
+ * (`@local`) by that name only, never falling back to the cloud provider; any other device
+ * is a cloud device and uses the current cloud provider (files kept by another provider are
+ * refused by the sandbox service, `device.unavailable`).
  */
-export declare function providerForEnvironment(providers: Pick<SandboxProviders, "cloud" | "forName">, provider: string | null): SandboxProviderEntry | undefined;
+export declare function providerForDevice(providers: Pick<SandboxProviders, "cloud" | "forName">, provider: string | null): SandboxProviderEntry | undefined;

package/dist/sandbox/providers.js

@@ -11,8 +11,8 @@ import { SANDBOX_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { guardProviderConnection } from "./unreachable.js";
-/** The kernel-internal provider of connected machines (`device` environments). */
-export const DEVICE_PROVIDER = "@device";
+/** The kernel-internal provider of connected machines (local devices). */
+export const LOCAL_PROVIDER = "@local";
 /**
  * A kernel-internal provider name: it starts with `@`, which no extension name can
  * (`EXTENSION_NAME_RE`), so it never collides with a loaded `sandbox@2` plugin.
@@ -21,7 +21,7 @@ export const isInternalProvider = (name) => name.startsWith("@");
 /**
  * The sandbox providers of this process. The cloud provider is the loaded `sandbox@2` extension,
  * read from the {@link ExtensionRegistry} at every call (providers are ready only after the
- * extension load, and change with installs). Kernel-internal providers (`@device`) are registered
+ * extension load, and change with installs). Kernel-internal providers (`@local`) are registered
  * by their module on init, in every replica: they are code, not shared state.
  *
  * Every `sandbox@2` extension is handed out guarded: a network-level failure to reach it is
@@ -71,12 +71,12 @@ SandboxProviders = __decorate([
 ], SandboxProviders);
 export { SandboxProviders };
 /**
- * The provider an environment works with, from its `environments.provider`: an internal one
- * (`@device`) by that name only, never falling back to the cloud provider; any other environment
- * is a cloud environment and uses the current cloud provider (files kept by another provider are
- * refused by the sandbox service, `environment.unavailable`).
+ * The provider a device works with, from its `devices.provider`: an internal one
+ * (`@local`) by that name only, never falling back to the cloud provider; any other device
+ * is a cloud device and uses the current cloud provider (files kept by another provider are
+ * refused by the sandbox service, `device.unavailable`).
  */
-export function providerForEnvironment(providers, provider) {
+export function providerForDevice(providers, provider) {
     if (provider !== null && isInternalProvider(provider))
         return providers.forName(provider);
     return providers.cloud();

package/dist/sandbox/sandbox.module.d.ts

@@ -1,5 +1,5 @@
 /**
- * Sandboxes: the one {@link SandboxService} (an environment's file system and instance over the
+ * Sandboxes: the one {@link SandboxService} (a device's file system and instance over the
  * `sandbox@2` provider, with the shared / exclusive leases of {@link SandboxLeases}) and the
  * producer of the
  * one-off `sandbox-destroy-for` jobs (`MaintenanceProcessor` consumes them). The sweeps

package/dist/sandbox/sandbox.module.js

@@ -14,7 +14,7 @@ import { SandboxLeases } from "./leases.js";
 import { SandboxProviders } from "./providers.js";
 import { SandboxService } from "./sandbox.service.js";
 /**
- * Sandboxes: the one {@link SandboxService} (an environment's file system and instance over the
+ * Sandboxes: the one {@link SandboxService} (a device's file system and instance over the
  * `sandbox@2` provider, with the shared / exclusive leases of {@link SandboxLeases}) and the
  * producer of the
  * one-off `sandbox-destroy-for` jobs (`MaintenanceProcessor` consumes them). The sweeps

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

@@ -3,7 +3,7 @@ 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 { EnvironmentInstancesTable } 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";
@@ -16,13 +16,13 @@ export interface SandboxUseInfo {
     /** This call created the instance (first use, or a rebuild). */
     fresh: boolean;
     /**
-     * The environment had an instance before that is no longer there (destroyed after inactivity,
+     * 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 environment's files were reset since this holder last used it (on request, or after they
+     * 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;
@@ -35,17 +35,17 @@ export interface SandboxUseInfo {
 /** Who uses the sandbox in {@link SandboxService.withSandbox}. */
 export interface SandboxUseContext {
     orgId: string;
-    environmentId: 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<EnvironmentInstancesTable>;
+type Row = Selectable<DeviceInstancesTable>;
 type ExecArgs = Parameters<SandboxProvider["exec"]>[1];
 /**
- * One instance of an environment: its handle and the row's `created_at`, which the fenced write
+ * 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).
  */
@@ -80,20 +80,20 @@ export type IfRunningResult<T> = {
     kind: "not_running";
     status: Row["status"] | "gone";
 }
-/** The environment now records another instance (a rebuild). */
+/** The device now records another instance (a rebuild). */
  | {
     kind: "other_instance";
 };
-/** The provider-side name of an environment's file system and instance. */
-export declare const environmentResourceName: (environmentId: string) => string;
-/** The environment is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
-export declare const environmentNotFound: () => ApiError;
+/** 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 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).
+ * 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 environmentFilesLost: (device?: boolean) => ApiError;
+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).
@@ -115,19 +115,19 @@ export declare function sandboxConfigWarnings(cfg: Pick<KernelConfig, "runtime"
 /** No sandbox provider (503). */
 export declare const sandboxUnavailable: () => ApiError;
 /**
- * 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
+ * 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
- * environment (and their sub-agents) share both.
+ * device (and their sub-agents) share both.
  *
  * - **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
+ *   (`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 environment id: using an
+ * - **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 environment) run at once. Every
+ *   `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.
@@ -140,9 +140,9 @@ export declare const sandboxUnavailable: () => ApiError;
  *   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
+ *   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 environment or org loses its files too.
+ *   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`
@@ -150,7 +150,7 @@ export declare const sandboxUnavailable: () => ApiError;
  * - **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
+ *   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,
@@ -160,16 +160,16 @@ export declare const sandboxUnavailable: () => ApiError;
  *   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).
  *
- * - **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
+ * - **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 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
+ * 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.
  */
@@ -195,48 +195,48 @@ export declare class SandboxService {
     private get pollMs();
     /**
      * 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
+     * no device yet (tool listing, skill files); a call on a device asks
      * {@link availableFor}.
      */
     get cloudAvailable(): boolean;
-    /** Whether the environment's provider is there (`@device` registered, or a cloud provider). */
-    availableFor(environmentId: string): Promise<boolean>;
+    /** Whether the device's provider is there (`@local` registered, or a cloud provider). */
+    availableFor(deviceId: string): Promise<boolean>;
     /**
-     * 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
+     * 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.
      */
     private providerOf;
     /** {@link providerOf}, or `sandbox.unavailable` (503) without it. */
     private require;
-    /** Concurrent holders of one environment (`sandbox.maxConcurrentCommands`, read at every use). */
+    /** 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 environments use
+     * org override (C19 / Ruling M16). Instances are created with them; phase 1 devices use
      * them unchanged.
      */
     orgLimits(orgId: string): Promise<SandboxLimits>;
     /**
-     * The environment's instance state as shown to people (read only, no lease): `running` /
+     * 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, environmentId: string): Promise<{
+    status(orgId: string, deviceId: string): Promise<{
         status: "running" | "suspended";
         lastUsedAt: Date;
     } | null>;
     /**
-     * The instance the environment records now (its `created_at`), while it has one that runs or is
+     * 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(environmentId: string): Promise<{
+    currentInstance(deviceId: string): Promise<{
         createdAt: Date;
     } | null>;
     /**
-     * Runs `fn` on the environment's instance only while it runs the instance created at
+     * 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
@@ -247,17 +247,17 @@ export declare class SandboxService {
      * to `fn` aborts with `signal` or when the lease is lost. Errors of `fn` (`SandboxGoneError`
      * too) are thrown as they are.
      */
-    ifRunning<T>(environmentId: string, instance: {
+    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 environment around the kernel's own read-modify-write of
+     * 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(environmentId: string, path: string, signal: AbortSignal): Promise<SandboxPathLease>;
+    pathLease(deviceId: string, path: string, signal: AbortSignal): Promise<SandboxPathLease>;
     /**
-     * Runs `fn` on the environment's instance: take a lease → make sure the instance runs (file
+     * 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
@@ -268,7 +268,7 @@ export declare class SandboxService {
      * - 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
+     * - 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).
@@ -278,7 +278,7 @@ export declare class SandboxService {
      * 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
+     * `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;
@@ -288,7 +288,7 @@ export declare class SandboxService {
      * 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
+     * (sandbox-docker's volumes are named after the device). Best effort: a Redis error only
      * logs.
      */
     private seenBy;
@@ -335,7 +335,7 @@ export declare class SandboxService {
     private kill;
     /**
      * Suspends running instances idle longer than `suspendAfterIdleMinutes` or running continuously
-     * longer than `maxRunningMinutes`. Skips an environment with any holder; one past
+     * 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.
      */
@@ -343,30 +343,30 @@ export declare class SandboxService {
     /**
      * 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
+     * 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>;
     /**
-     * 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
+     * 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
-     * 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).
+     * 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.
      */
-    destroyEnvironment(environmentId: string): Promise<void>;
+    destroyDevice(deviceId: string): Promise<void>;
     /**
-     * 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
+     * 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.
      */
-    resetFileSystem(environmentId: string): Promise<void>;
+    resetFileSystem(deviceId: string): Promise<void>;
     /**
      * 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
@@ -392,13 +392,13 @@ export declare class SandboxService {
     private candidates;
     /**
      * One try at the exclusive lease: null → false; else runs `fn`. With `overdue` (past
-     * `maxRunningMinutes`) a busy environment gets the intent for about a second, so new commands
+     * `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 environment's instance 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.
      */
@@ -407,14 +407,14 @@ export declare class SandboxService {
      * 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
+     * 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;
     /**
-     * Destroys the file system another provider may have made under the environment's name without
+     * 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 environment stays
+     * loaded, or a failure, is only warned (the files may leak there) so the device stays
      * usable; an abort is thrown.
      */
     private dropUnrecordedFiles;
@@ -438,20 +438,20 @@ export declare class SandboxService {
     private destroyFiles;
     /**
      * 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.
+     * 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;
-    /** The provider of an instance row: an internal one (`@device`) by name, else the cloud one. */
+    /** 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 (`@device` instances live on
+     * 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 environment was deleted, or its org was: the instance and the files go. */
-    private environmentGone;
+    /** 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;
 }