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

package/dist/sandbox/job-ids.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the sandbox sweeps had before they became `@LockedCron` jobs
+ * an upgraded deployment still has them in Redis, so the worker removes
+ * them at start (`RETIRED_SCHEDULER_IDS`). A leaf module: the maintenance worker imports it without
+ * the sandbox providers.
+ */
+/** The idle suspension sweep's old scheduler (every minute). */
+export declare const SANDBOX_SUSPEND_SCHEDULER_ID = "sandbox-suspend-idle-every-minute";
+/** The inactivity destruction sweep's old scheduler (hourly). */
+export declare const SANDBOX_DESTROY_SCHEDULER_ID = "sandbox-destroy-inactive-hourly";

package/dist/sandbox/job-ids.js

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the sandbox sweeps had before they became `@LockedCron` jobs
+ * an upgraded deployment still has them in Redis, so the worker removes
+ * them at start (`RETIRED_SCHEDULER_IDS`). A leaf module: the maintenance worker imports it without
+ * the sandbox providers.
+ */
+/** The idle suspension sweep's old scheduler (every minute). */
+export const SANDBOX_SUSPEND_SCHEDULER_ID = "sandbox-suspend-idle-every-minute";
+/** The inactivity destruction sweep's old scheduler (hourly). */
+export const SANDBOX_DESTROY_SCHEDULER_ID = "sandbox-destroy-inactive-hourly";

package/dist/sandbox/jobs.d.ts

@@ -0,0 +1,68 @@
+import type { Job, Queue } from "bullmq";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { SandboxService } from "./sandbox.service.js";
+/** The idle suspension sweep (every minute, once per tick across replicas). */
+export declare const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
+/** The inactivity destruction sweep (hourly, once per tick across replicas). */
+export declare const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
+/**
+ * One-off job: destroy a batch of environments now, instance and file system (environment
+ * deletion, offboarding; data `{ environmentIds }`).
+ */
+export declare const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/**
+ * One-off job: start an environment over with empty files (`resetFileSystem`; data
+ * `{ environmentId }`, job id {@link resetFilesJobId}).
+ */
+export declare const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
+/**
+ * The deterministic id of an environment's reset job: a second request while one is waiting or
+ * running joins it (that reset still empties the files); once it ended, a new request is a new job.
+ */
+export declare const resetFilesJobId: (environmentId: string) => string;
+/**
+ * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
+ * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
+ * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
+ */
+export declare class SandboxJobs {
+    private readonly queue;
+    constructor(queue: Pick<Queue, "add">);
+    /**
+     * Enqueues the destruction of these environments: a failed batch is retried whole (destroying
+     * one already destroyed does nothing).
+     */
+    destroy(environmentIds: string[]): Promise<void>;
+    /**
+     * Enqueues the reset of an environment's files (see {@link resetFilesJobId}): retried on failure
+     * (the exclusive lease not obtained in time, the provider failing); a job that failed all its
+     * attempts is removed, so the id never blocks a later request.
+     */
+    resetFiles(environmentId: string): Promise<void>;
+}
+/**
+ * The worker side of {@link SANDBOX_RESET_FILES_JOB}: `resetFileSystem` under the exclusive lease;
+ * a failure fails the job (retried).
+ */
+export declare function runSandboxResetFiles(sandbox: Pick<SandboxService, "resetFileSystem">, job: Pick<Job, "data">): Promise<void>;
+/**
+ * The worker side of {@link SANDBOX_DESTROY_FOR_JOB}: `destroyEnvironment` one by one; a failure is
+ * warned and fails the job (the whole batch is retried) after the others were destroyed.
+ */
+export declare function runSandboxDestroyFor(sandbox: Pick<SandboxService, "destroyEnvironment">, log: Pick<KernelLogger, "warn">, job: Pick<Job, "data">): Promise<void>;
+/**
+ * The sandbox sweeps (exactly once per tick across replicas): every minute the idle and overdue
+ * running instances are suspended, every hour the inactive instances are destroyed (files kept)
+ * and deleted environments, or those of deleted orgs, are destroyed with their files. Both do nothing without a sandbox provider. They replace the
+ * maintenance schedulers `sandbox-suspend-idle-every-minute` and `sandbox-destroy-inactive-hourly`
+ * (retired at worker start).
+ */
+export declare class SandboxSweepJobs {
+    private readonly sandbox;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(sandbox: Pick<SandboxService, "suspendIdle" | "destroyInactive">, lockService: LockService, log: KernelLogger);
+    suspendIdle(): Promise<void>;
+    destroyInactive(): Promise<void>;
+}

package/dist/sandbox/jobs.js

@@ -0,0 +1,150 @@
+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 { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { SandboxService } from "./sandbox.service.js";
+/** The idle suspension sweep (every minute, once per tick across replicas). */
+export const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
+/** The inactivity destruction sweep (hourly, once per tick across replicas). */
+export const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
+/**
+ * One-off job: destroy a batch of environments now, instance and file system (environment
+ * deletion, offboarding; data `{ environmentIds }`).
+ */
+export const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/**
+ * One-off job: start an environment over with empty files (`resetFileSystem`; data
+ * `{ environmentId }`, job id {@link resetFilesJobId}).
+ */
+export const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
+/**
+ * The deterministic id of an environment's reset job: a second request while one is waiting or
+ * running joins it (that reset still empties the files); once it ended, a new request is a new job.
+ */
+export const resetFilesJobId = (environmentId) => `${SANDBOX_RESET_FILES_JOB}-${environmentId}`;
+/**
+ * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
+ * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
+ * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
+ */
+let SandboxJobs = class SandboxJobs {
+    queue;
+    constructor(queue) {
+        this.queue = queue;
+    }
+    /**
+     * Enqueues the destruction of these environments: a failed batch is retried whole (destroying
+     * one already destroyed does nothing).
+     */
+    async destroy(environmentIds) {
+        await this.queue.add(SANDBOX_DESTROY_FOR_JOB, { environmentIds }, {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 30_000 },
+            removeOnComplete: true,
+            removeOnFail: 100,
+        });
+    }
+    /**
+     * Enqueues the reset of an environment's files (see {@link resetFilesJobId}): retried on failure
+     * (the exclusive lease not obtained in time, the provider failing); a job that failed all its
+     * attempts is removed, so the id never blocks a later request.
+     */
+    async resetFiles(environmentId) {
+        await this.queue.add(SANDBOX_RESET_FILES_JOB, { environmentId }, {
+            jobId: resetFilesJobId(environmentId),
+            attempts: 5,
+            backoff: { type: "exponential", delay: 30_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        });
+    }
+};
+SandboxJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+], SandboxJobs);
+export { SandboxJobs };
+/**
+ * The worker side of {@link SANDBOX_RESET_FILES_JOB}: `resetFileSystem` under the exclusive lease;
+ * a failure fails the job (retried).
+ */
+export async function runSandboxResetFiles(sandbox, job) {
+    const id = job.data.environmentId;
+    if (typeof id !== "string")
+        return;
+    await sandbox.resetFileSystem(id);
+}
+/**
+ * The worker side of {@link SANDBOX_DESTROY_FOR_JOB}: `destroyEnvironment` one by one; a failure is
+ * warned and fails the job (the whole batch is retried) after the others were destroyed.
+ */
+export async function runSandboxDestroyFor(sandbox, log, job) {
+    const ids = job.data.environmentIds;
+    if (!Array.isArray(ids))
+        return;
+    let failed = 0;
+    for (const id of ids) {
+        if (typeof id !== "string")
+            continue;
+        try {
+            await sandbox.destroyEnvironment(id);
+        }
+        catch (err) {
+            failed++;
+            log.warn("cannot destroy environment; will retry", { environmentId: id, err });
+        }
+    }
+    if (failed > 0)
+        throw new Error(`${failed} of ${ids.length} environments could not be destroyed`);
+}
+/**
+ * The sandbox sweeps (exactly once per tick across replicas): every minute the idle and overdue
+ * running instances are suspended, every hour the inactive instances are destroyed (files kept)
+ * and deleted environments, or those of deleted orgs, are destroyed with their files. Both do nothing without a sandbox provider. They replace the
+ * maintenance schedulers `sandbox-suspend-idle-every-minute` and `sandbox-destroy-inactive-hourly`
+ * (retired at worker start).
+ */
+let SandboxSweepJobs = class SandboxSweepJobs {
+    sandbox;
+    lockService;
+    log;
+    constructor(sandbox, lockService, log) {
+        this.sandbox = sandbox;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async suspendIdle() {
+        const n = await this.sandbox.suspendIdle(new Date());
+        if (n > 0)
+            this.log.info("idle sandboxes suspended", { count: n });
+    }
+    async destroyInactive() {
+        const n = await this.sandbox.destroyInactive(new Date());
+        if (n > 0)
+            this.log.info("inactive sandboxes destroyed", { count: n });
+    }
+};
+__decorate([
+    LockedCron("* * * * *", { name: SANDBOX_SUSPEND_JOB })
+], SandboxSweepJobs.prototype, "suspendIdle", null);
+__decorate([
+    LockedCron("0 * * * *", { name: SANDBOX_DESTROY_JOB })
+], SandboxSweepJobs.prototype, "destroyInactive", null);
+SandboxSweepJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(SandboxService)),
+    __param(1, Inject(LockService)),
+    __param(2, Inject(KERNEL_LOGGER))
+], SandboxSweepJobs);
+export { SandboxSweepJobs };

package/dist/sandbox/leases.d.ts

@@ -1,52 +1,44 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { ApiError } from "../errors.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
 /**
- * Shared and exclusive sandbox leases (sub-agents spec §10.3): the Redis protocol that lets several
- * holders use one conversation's running sandbox concurrently (shared leases: commands, file reads
- * and writes) while lifecycle changes (create, resume, rebuild, suspend, destroy) stay alone
- * (exclusive leases). Keys, conversation = the sandbox conversation:
+ * 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
+ * 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:
  *
- * - `capk:sandbox:<conv>`: the lock key kept from before (rollout, §10.8): an exclusive holder's
- *   token, or `shared` while shared leases exist. An older replica's `SET NX` therefore never gets
- *   in while shared leases live, and its token blocks new shared leases.
- * - `capk:sandbox-users:<conv>`: sorted set of shared lease tokens scored by their expiry (ms, Redis
+ * - `capk:sandbox:<env>`: the lock key: an exclusive holder's token, or `shared` while shared
+ *   leases exist.
+ * - `capk:sandbox-users:<env>`: sorted set of shared lease tokens scored by their expiry (ms, Redis
  *   server clock).
- * - `capk:sandbox-intent:<conv>`: an exclusive waiter's token (writer preference); while it exists
+ * - `capk:sandbox-intent:<env>`: an exclusive waiter's token (writer preference); while it exists
  *   no new shared lease is granted.
- * - `capk:sandbox-holders:<conv>`: hash token → expiry of holders that may have commands running
- *   (the per-holder replacement of the single busy marker `capk:sandbox-busy:<conv>`, still read).
- * - `capk:sandbox-path:<conv>:<sha256hex(path)>`: a short per-path lease around the kernel's own
+ * - `capk:sandbox-holders:<env>`: hash token → expiry of holders that may have commands running;
+ *   a record without a live lease is a crashed holder whose commands (tagged with its token) are
+ *   killed by the next acquirer.
+ * - `capk:sandbox-path:<env>:<sha256hex(path)>`: a short per-path lease around the kernel's own
  *   read-modify-write of one file.
  *
- * Every script purges expired shared leases first, and every key carries a TTL. A holder renews
- * every TTL / 3 (a timer for a lease this process holds) and treats "no successful renewal for
- * 2/3 TTL" as lost: its `signal` aborts with {@link SandboxLockLostError}.
+ * The first three keys are a {@link LockService} shared lease (`tryShared` / `tryExclusive`,
+ * infra/lock/shared-lease.ts); the holder records and the path leases are this file's. Every key
+ * carries a TTL. A holder renews every TTL / 3 (LockService's watchdog) and loses the lease at
+ * 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:<conversationId>`. */
+/** Prefix of the lock key `capk:sandbox:<environmentId>`. */
 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;
-/**
- * Prefix of the single "sandbox in use" marker of kernels before phase C,
- * `capk:sandbox-busy:<conversationId>`: present while such a holder ran commands. Found by an
- * exclusive acquirer, it means that holder crashed and its commands may still run.
- *
- * Holders of this kernel write it too, with the value {@link BUSY_V2}, while any holder record
- * exists (spec §10.8): this kernel ignores that value, and a replica from before phase C that
- * takes the lock after a new holder crashed sees a marker and kills everything, which is safe
- * because it only gets the lock when no shared lease is live.
- */
-export declare const SANDBOX_BUSY_PREFIX = "capk:sandbox-busy:";
-/** Value of the busy marker written by holders of this kernel (ignored by it). */
-export declare const BUSY_V2 = "v2";
-/** The sandbox of this conversation is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
+/** The environment'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(conversationId: string, reason?: "lock" | "generation");
+    constructor(environmentId: 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 {
@@ -57,7 +49,7 @@ export type LeaseKind = "shared" | "exclusive";
 export interface SandboxLease {
     readonly kind: LeaseKind;
     readonly token: string;
-    readonly conversationId: string;
+    readonly environmentId: 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). */
@@ -67,30 +59,41 @@ export interface SandboxLease {
     /** exclusive → shared in one Lua step (same token, same signal); throws if not exclusive. */
     downgrade(): Promise<SandboxLease>;
 }
-export interface SandboxLeasesDeps {
-    redis: Redis;
-    log: Pick<Logger, "warn">;
-    /** Lease TTL (ms), default {@link SANDBOX_LOCK_TTL_MS}. */
-    ttlMs?: number;
-    /** Poll interval while waiting (ms, jittered up to 2×), default 100. */
-    pollMs?: number;
-    /** Path lease TTL (ms), default 30 s; tests make it shorter. */
-    pathTtlMs?: number;
-}
 /** A path lease this process holds. */
 export interface SandboxPathLease {
-    /** Aborts with {@link SandboxLockLostError} when a renewal finds the lease gone. */
+    /** Aborts with {@link SandboxLockLostError} when the lease is lost. */
     readonly signal: AbortSignal;
     release(): Promise<void>;
 }
-/** The lease protocol; no state in process beyond the leases this process holds. */
+/** The timings of {@link SandboxLeases} (each defaults as documented). */
+export interface SandboxLeaseTimings {
+    /** Lease TTL (ms), default {@link SANDBOX_LOCK_TTL_MS}. */
+    ttlMs: number;
+    /** Poll interval while waiting (ms, jittered up to 2×), default 100. */
+    pollMs: number;
+    /** Path lease TTL (ms), default {@link PATH_LEASE_TTL_MS}. */
+    pathTtlMs: number;
+}
+/** Optional provider: {@link SandboxLeaseTimings} that replace some defaults (tests make them shorter). */
+export declare const SANDBOX_LEASE_TIMINGS: unique symbol;
+/**
+ * The lease protocol over {@link LockService}'s shared leases; no state in process beyond the
+ * leases this process holds.
+ */
 export declare class SandboxLeases {
+    private readonly locks;
+    /** The holder records (scripts of this file). */
     private readonly redis;
     private readonly log;
-    private readonly ttlMs;
-    private readonly pollMs;
-    private readonly pathTtlMs;
-    constructor(d: SandboxLeasesDeps);
+    /** Lease TTL (ms). */
+    readonly ttlMs: number;
+    /** Poll interval while waiting (ms, jittered up to 2×). */
+    readonly pollMs: number;
+    /** Path lease TTL (ms). */
+    readonly pathTtlMs: number;
+    constructor(locks: LockService, 
+    /** The holder records (scripts of this file). */
+    redis: Pick<Redis, "eval" | "hdel">, log: Pick<KernelLogger, "warn">, timings?: Partial<SandboxLeaseTimings>);
     /**
      * TTL of an intent (ms): 4 × the poll interval (a jittered wait is up to 2 × the interval plus
      * round trips), at least {@link INTENT_TTL_FLOOR_MS} so event-loop lag cannot let it lapse.
@@ -103,14 +106,14 @@ export declare class SandboxLeases {
      * `capMs`, the signal's reason when it aborts. Not granted while an exclusive lease, an older
      * replica's lock token or another caller's intent exists.
      */
-    acquireShared(conv: string, cap: number, signal: AbortSignal, capMs: number): Promise<SandboxLease>;
+    acquireShared(env: string, cap: number, signal: AbortSignal, capMs: number): Promise<SandboxLease>;
     /**
      * An exclusive lease, polling until no other lease exists; `sandbox.busy` after `capMs` (no cap
      * when omitted), the signal's reason when it aborts. With `intent` the waiter sets the intent
      * (refreshed while it waits) so new shared leases stop being granted; it is cleared on success
      * and when the wait ends otherwise.
      */
-    acquireExclusive(conv: string, signal: AbortSignal, capMs?: number, o?: {
+    acquireExclusive(env: string, signal: AbortSignal, capMs?: number, o?: {
         intent?: boolean;
     }): Promise<SandboxLease>;
     /**
@@ -118,7 +121,7 @@ export declare class SandboxLeases {
      * intent. With `o.token` the lease (and, when `o.intent`, the intent set on failure) carries that
      * token, so one waiter can alternate between this and {@link tryShared} with the same token.
      */
-    tryExclusive(conv: string, o?: {
+    tryExclusive(env: string, o?: {
         token?: string;
         intent?: boolean;
     }): Promise<SandboxLease | null>;
@@ -127,43 +130,31 @@ export declare class SandboxLeases {
      * lease token; a waiter that set an intent with the same token is let through its own intent
      * (it should then {@link clearIntent}).
      */
-    tryShared(conv: string, cap: number, token?: string): Promise<SandboxLease | null>;
-    /** Deletes the conversation's intent when it is `token`'s. */
-    clearIntent(conv: string, token: string): Promise<void>;
-    /** Whether the single busy marker of a kernel before phase C is present (v2 does not count). */
-    legacyMarker(conv: string): Promise<boolean>;
-    /** Live shared leases of the conversation. */
-    sharedCount(conv: string): Promise<number>;
+    tryShared(env: string, cap: number, token?: string): Promise<SandboxLease | null>;
+    /** Deletes the environment's intent when it is `token`'s. */
+    clearIntent(env: string, token: string): Promise<void>;
+    /** Live shared leases of the environment. */
+    sharedCount(env: string): Promise<number>;
     /**
      * Records (or refreshes) a holder that may run commands (before its provider calls); `ttlMs`
-     * bounds the record. Also keeps the v2 busy marker for older replicas ({@link BUSY_V2}).
+     * bounds the record.
      */
-    registerHolder(conv: string, token: string, ttlMs: number): Promise<void>;
-    /** Deletes a holder record (after its provider calls); the v2 marker goes with the last one. */
-    unregisterHolder(conv: string, token: string): Promise<void>;
+    registerHolder(env: string, token: string, ttlMs: number): Promise<void>;
+    /** Deletes a holder record (after its provider calls). */
+    unregisterHolder(env: string, token: string): Promise<void>;
     /**
-     * Tags of holders without a live lease, plus whether an older kernel's single busy marker was
-     * present. Atomically claims them (removes the fields) so only one caller kills. That marker is
-     * claimed only when `exclusiveToken` is the caller's exclusive lease (no shared lease live).
+     * Tags of holders without a live lease, atomically claimed (their fields removed) so only one
+     * caller kills them.
      */
-    claimDeadHolders(conv: string, exclusiveToken?: string): Promise<{
-        tags: string[];
-        legacyMarker: boolean;
-    }>;
+    claimDeadHolders(env: string): Promise<string[]>;
     /**
      * A short lease on one path of the sandbox (the kernel's own read-modify-write of a file); waits
-     * up to `capMs`, then throws {@link SandboxPathBusyError}. Renewed while held; a renewal that
-     * finds it gone warns and aborts its `signal`.
-     */
-    pathLease(conv: string, path: string, signal: AbortSignal, capMs: number): Promise<SandboxPathLease>;
-    /**
-     * Wraps a just-acquired lease: renews every TTL / 3 and remembers the last successful renewal;
-     * the lease is lost when a renewal reports it gone or none succeeded for 2/3 TTL (leaving margin
-     * so the abort takes effect before the key expires).
+     * up to `capMs`, then throws {@link SandboxPathBusyError}. A {@link LockService.hold} lease
+     * (renewed every TTL / 3): when it is lost its `signal` aborts.
      */
-    private hold;
-    private lose;
-    private renew;
-    /** A lease view of `s` as `kind`; a view stops working once the lease changes kind. */
+    pathLease(env: string, path: string, signal: AbortSignal, capMs: number): Promise<SandboxPathLease>;
+    /** A sandbox lease over a held {@link SharedLeaseHandle}, as its current kind. */
+    private held;
+    /** A lease view of `h` as `kind`; a view stops working once the lease changes kind. */
     private view;
 }