@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/sandbox/leases.js

@@ -1,44 +1,48 @@
+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 { createHash, randomUUID } from "node:crypto";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { LockService, } from "../infra/lock/lock.service.js";
+import { redisClockScript, sharedLeaseReadScript, } from "../infra/lock/shared-lease.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.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 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;
-/**
- * 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 const SANDBOX_BUSY_PREFIX = "capk:sandbox-busy:";
-/** Value of the busy marker written by holders of this kernel (ignored by it). */
-export const BUSY_V2 = "v2";
 const USERS_PREFIX = "capk:sandbox-users:";
 const INTENT_PREFIX = "capk:sandbox-intent:";
 const HOLDERS_PREFIX = "capk:sandbox-holders:";
@@ -47,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 sandbox of this conversation is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
-export const sandboxBusy = () => new ApiError("sandbox.busy", "The sandbox for this conversation is busy with another command; wait for it to finish and try again");
+/** 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");
 /** 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(conversationId, reason = "lock") {
+    constructor(environmentId, reason = "lock") {
         super(reason === "lock"
-            ? `sandbox lock lost for conversation ${conversationId}`
-            : `sandbox state of conversation ${conversationId} changed concurrently (generation mismatch)`);
+            ? `sandbox lock lost for environment ${environmentId}`
+            : `sandbox state of environment ${environmentId} changed concurrently (generation mismatch)`);
         this.name = "SandboxLockLostError";
         this.reason = reason;
     }
@@ -68,125 +72,18 @@ export class SandboxPathBusyError extends Error {
         this.name = "SandboxPathBusyError";
     }
 }
-const NOW = `local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)`;
-/** Drops expired shared leases; drops a `shared` lock value no live shared lease backs. */
-const PURGE = `
-redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
-local cur = redis.call('GET', KEYS[1])
-if cur == 'shared' and redis.call('ZCARD', KEYS[2]) == 0 then
-  redis.call('DEL', KEYS[1])
-  cur = false
-end`;
-/**
- * Keeps the users set and the `shared` lock value alive for at least `ttl` without shortening a
- * longer TTL another holder set (holders may use different TTLs).
- */
-const KEEP_SHARED = `
-if redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end
-local lt = redis.call('PTTL', KEYS[1])
-if redis.call('GET', KEYS[1]) ~= 'shared' or lt < ttl then
-  redis.call('SET', KEYS[1], 'shared', 'PX', math.max(ttl, lt))
-end`;
-/** KEYS lock, users, intent; ARGV token, cap, ttl. */
-const ACQUIRE_SHARED = `${NOW}
-${PURGE}
-if cur and cur ~= 'shared' then return 0 end
-local it = redis.call('GET', KEYS[3])
-if it and it ~= ARGV[1] then return 0 end
-if redis.call('ZCARD', KEYS[2]) >= tonumber(ARGV[2]) then return 0 end
-local ttl = tonumber(ARGV[3])
-redis.call('ZADD', KEYS[2], now + ttl, ARGV[1])
-${KEEP_SHARED}
-return 1`;
-/** KEYS lock, users, intent; ARGV token, ttl, setIntent (0/1), intentTtl. */
-const ACQUIRE_EXCLUSIVE = `${NOW}
-${PURGE}
-if cur or redis.call('ZCARD', KEYS[2]) > 0 then
-  if ARGV[3] == '1' then
-    local it = redis.call('GET', KEYS[3])
-    if (not it) or it == ARGV[1] then
-      redis.call('SET', KEYS[3], ARGV[1], 'PX', tonumber(ARGV[4]))
-    end
-  end
-  return 0
-end
-redis.call('SET', KEYS[1], ARGV[1], 'PX', tonumber(ARGV[2]))
-if redis.call('GET', KEYS[3]) == ARGV[1] then redis.call('DEL', KEYS[3]) end
-return 1`;
-/** KEYS lock, users; ARGV token, ttl, kind. Shared: lost when the member is gone or the lock holds a token. */
-const RENEW = `${NOW}
-local ttl = tonumber(ARGV[2])
-if ARGV[3] == 'exclusive' then
-  if redis.call('GET', KEYS[1]) == ARGV[1] then
-    redis.call('PEXPIRE', KEYS[1], ttl)
-    return 1
-  end
-  return 0
-end
-redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
-if not redis.call('ZSCORE', KEYS[2], ARGV[1]) then return 0 end
-local cur = redis.call('GET', KEYS[1])
-if cur and cur ~= 'shared' then
-  redis.call('ZREM', KEYS[2], ARGV[1])
-  return 0
-end
-redis.call('ZADD', KEYS[2], 'XX', now + ttl, ARGV[1])
-${KEEP_SHARED}
-return 1`;
-/** KEYS lock, users; ARGV token, kind. */
-const RELEASE = `${NOW}
-if ARGV[2] == 'exclusive' then
-  if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) end
-  return 1
-end
-redis.call('ZREM', KEYS[2], ARGV[1])
-${PURGE}
-return 1`;
-/** KEYS lock, users; ARGV token, ttl. */
-const DOWNGRADE = `${NOW}
-if redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end
-local ttl = tonumber(ARGV[2])
-redis.call('ZADD', KEYS[2], now + ttl, ARGV[1])
-${KEEP_SHARED}
-return 1`;
-/** KEYS lock, users; returns the live shared count. */
-const COUNT = `${NOW}
-${PURGE}
-return redis.call('ZCARD', KEYS[2])`;
-/**
- * KEYS holders, busy; ARGV token, ttl. Also writes the busy marker as v2 (kept for at least `ttl`)
- * unless an older kernel's holder owns it.
- */
-const REGISTER = `${NOW}
-local ttl = tonumber(ARGV[2])
+/** KEYS holders; ARGV token, ttl. The hash is kept for at least `ttl`. */
+const REGISTER = redisClockScript(`local ttl = tonumber(ARGV[2])
 redis.call('HSET', KEYS[1], ARGV[1], now + ttl)
 if redis.call('PTTL', KEYS[1]) < ttl then redis.call('PEXPIRE', KEYS[1], ttl) end
-local b = redis.call('GET', KEYS[2])
-if (not b) or (b == '${BUSY_V2}' and redis.call('PTTL', KEYS[2]) < ttl) then
-  redis.call('SET', KEYS[2], '${BUSY_V2}', 'PX', ttl)
-end
-return 1`;
-/** Deletes the v2 busy marker (key `busy`) once no holder record (hash `holders`) is left. */
-const dropV2 = (holders, busy) => `
-if redis.call('HLEN', ${holders}) == 0 and redis.call('GET', ${busy}) == '${BUSY_V2}' then
-  redis.call('DEL', ${busy})
-end`;
-/** KEYS holders, busy; ARGV token. */
-const UNREGISTER = `
-redis.call('HDEL', KEYS[1], ARGV[1])
-${dropV2("KEYS[1]", "KEYS[2]")}
-return 1`;
+return 1`);
 /**
- * KEYS lock, users, holders, busy; ARGV the caller's exclusive token (or ''). Removes and returns
- * the holder fields without a live lease (expired fields are dropped without being returned: the
- * in-sandbox time limit ended their commands); claims an older kernel's busy marker only for the
- * caller holding the exclusive lease (`cur == token`, so no shared lease is live and killing
- * everything cannot hit a live sibling). The v2 marker is never claimed; it goes with the last
- * record. Returns { legacy, tag… }.
+ * KEYS lock, users, holders. Removes and returns the holder fields without a live lease (expired
+ * fields are dropped without being returned: the in-sandbox time limit ended their commands). The
+ * caller's own token is live (a shared lease, or the exclusive token in the lock key), so it is
+ * never returned. Returns the tags.
  */
-const CLAIM = `${NOW}
-${PURGE}
-local out = {0}
+const CLAIM = sharedLeaseReadScript(`local out = {}
 local f = redis.call('HGETALL', KEYS[3])
 for i = 1, #f, 2 do
   local tok = f[i]
@@ -197,16 +94,7 @@ for i = 1, #f, 2 do
     table.insert(out, tok)
   end
 end
-${dropV2("KEYS[3]", "KEYS[4]")}
-local b = redis.call('GET', KEYS[4])
-if ARGV[1] ~= '' and cur == ARGV[1] and b and b ~= '${BUSY_V2}' then
-  redis.call('DEL', KEYS[4])
-  out[1] = 1
-end
-return out`;
-/** Compare-and-delete / compare-and-expire of a single-valued key. */
-const DEL_IF = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
-const EXPIRE_IF = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end return 0`;
+return out`);
 const abortReason = (signal) => signal.reason ?? new DOMException("This operation was aborted", "AbortError");
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -225,19 +113,41 @@ function sleep(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
-/** The lease protocol; no state in process beyond the leases this process holds. */
-export class SandboxLeases {
+/** A signal that aborts with {@link SandboxLockLostError} when `lost` aborts. */
+function lostSignal(lost, env) {
+    const ctl = new AbortController();
+    const abort = () => ctl.abort(new SandboxLockLostError(env));
+    if (lost.aborted)
+        abort();
+    else
+        lost.addEventListener("abort", abort, { once: true });
+    return ctl.signal;
+}
+/** Optional provider: {@link SandboxLeaseTimings} that replace some defaults (tests make them shorter). */
+export const SANDBOX_LEASE_TIMINGS = Symbol("SANDBOX_LEASE_TIMINGS");
+/**
+ * The lease protocol over {@link LockService}'s shared leases; no state in process beyond the
+ * leases this process holds.
+ */
+let SandboxLeases = class SandboxLeases {
+    locks;
     redis;
     log;
+    /** Lease TTL (ms). */
     ttlMs;
+    /** Poll interval while waiting (ms, jittered up to 2×). */
     pollMs;
+    /** Path lease TTL (ms). */
     pathTtlMs;
-    constructor(d) {
-        this.redis = d.redis;
-        this.log = d.log;
-        this.ttlMs = d.ttlMs ?? SANDBOX_LOCK_TTL_MS;
-        this.pollMs = d.pollMs ?? 100;
-        this.pathTtlMs = d.pathTtlMs ?? PATH_LEASE_TTL_MS;
+    constructor(locks, 
+    /** The holder records (scripts of this file). */
+    redis, log, timings = {}) {
+        this.locks = locks;
+        this.redis = redis;
+        this.log = log;
+        this.ttlMs = timings.ttlMs ?? SANDBOX_LOCK_TTL_MS;
+        this.pollMs = timings.pollMs ?? 100;
+        this.pathTtlMs = timings.pathTtlMs ?? PATH_LEASE_TTL_MS;
     }
     /**
      * TTL of an intent (ms): 4 × the poll interval (a jittered wait is up to 2 × the interval plus
@@ -246,8 +156,12 @@ export class SandboxLeases {
     get intentTtlMs() {
         return Math.max(this.pollMs * 4, INTENT_TTL_FLOOR_MS);
     }
-    keys(conv) {
-        return [`${SANDBOX_LOCK_PREFIX}${conv}`, `${USERS_PREFIX}${conv}`, `${INTENT_PREFIX}${conv}`];
+    keys(env) {
+        return {
+            lock: `${SANDBOX_LOCK_PREFIX}${env}`,
+            users: `${USERS_PREFIX}${env}`,
+            intent: `${INTENT_PREFIX}${env}`,
+        };
     }
     wait(signal) {
         return sleep(this.pollMs + Math.floor(Math.random() * this.pollMs), signal);
@@ -257,15 +171,15 @@ export 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.
      */
-    async acquireShared(conv, cap, signal, capMs) {
+    async acquireShared(env, cap, signal, capMs) {
         const token = randomUUID();
         const deadline = Date.now() + capMs;
         for (;;) {
             if (signal.aborted)
                 throw abortReason(signal);
-            const ok = await this.redis.eval(ACQUIRE_SHARED, 3, ...this.keys(conv), token, cap, this.ttlMs);
-            if (Number(ok) === 1)
-                return this.hold(conv, token, "shared");
+            const lease = await this.tryShared(env, cap, token);
+            if (lease)
+                return lease;
             if (Date.now() + this.pollMs > deadline)
                 throw sandboxBusy();
             await this.wait(signal);
@@ -277,17 +191,16 @@ export class SandboxLeases {
      * (refreshed while it waits) so new shared leases stop being granted; it is cleared on success
      * and when the wait ends otherwise.
      */
-    async acquireExclusive(conv, signal, capMs, o = {}) {
+    async acquireExclusive(env, signal, capMs, o = {}) {
         const token = randomUUID();
         const deadline = capMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + capMs;
-        const keys = this.keys(conv);
         try {
             for (;;) {
                 if (signal.aborted)
                     throw abortReason(signal);
-                const ok = await this.redis.eval(ACQUIRE_EXCLUSIVE, 3, ...keys, token, this.ttlMs, o.intent ? 1 : 0, this.intentTtlMs);
-                if (Number(ok) === 1)
-                    return this.hold(conv, token, "exclusive");
+                const lease = await this.tryExclusive(env, { token, intent: o.intent === true });
+                if (lease)
+                    return lease;
                 if (Date.now() + this.pollMs > deadline)
                     throw sandboxBusy();
                 await this.wait(signal);
@@ -295,9 +208,7 @@ export class SandboxLeases {
         }
         catch (e) {
             if (o.intent) {
-                await this.redis
-                    .eval(DEL_IF, 1, keys[2], token)
-                    .catch((err) => this.log.warn("cannot clear sandbox intent", { conversationId: conv, err }));
+                await this.clearIntent(env, token).catch((err) => this.log.warn("cannot clear sandbox intent", { environmentId: env, err }));
             }
             throw e;
         }
@@ -307,209 +218,114 @@ export 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.
      */
-    async tryExclusive(conv, o = {}) {
-        const token = o.token ?? randomUUID();
-        const ok = await this.redis.eval(ACQUIRE_EXCLUSIVE, 3, ...this.keys(conv), token, this.ttlMs, o.intent ? 1 : 0, this.intentTtlMs);
-        return Number(ok) === 1 ? this.hold(conv, token, "exclusive") : null;
+    async tryExclusive(env, o = {}) {
+        const h = await this.locks.tryExclusive(this.keys(env), o.token ?? randomUUID(), this.ttlMs, o.intent ? this.intentTtlMs : undefined);
+        return h ? this.held(env, h) : null;
     }
     /**
      * One try at a shared lease (`cap` holders at most); null when it is not granted. `token` is the
      * lease token; a waiter that set an intent with the same token is let through its own intent
      * (it should then {@link clearIntent}).
      */
-    async tryShared(conv, cap, token = randomUUID()) {
-        const ok = await this.redis.eval(ACQUIRE_SHARED, 3, ...this.keys(conv), token, cap, this.ttlMs);
-        return Number(ok) === 1 ? this.hold(conv, token, "shared") : null;
-    }
-    /** Deletes the conversation's intent when it is `token`'s. */
-    async clearIntent(conv, token) {
-        await this.redis.eval(DEL_IF, 1, this.keys(conv)[2], token);
+    async tryShared(env, cap, token = randomUUID()) {
+        const h = await this.locks.tryShared(this.keys(env), token, cap, this.ttlMs);
+        return h ? this.held(env, h) : null;
     }
-    /** Whether the single busy marker of a kernel before phase C is present (v2 does not count). */
-    async legacyMarker(conv) {
-        const v = await this.redis.get(`${SANDBOX_BUSY_PREFIX}${conv}`);
-        return v !== null && v !== BUSY_V2;
+    /** Deletes the environment'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 conversation. */
-    async sharedCount(conv) {
-        const [lock, users] = this.keys(conv);
-        return Number(await this.redis.eval(COUNT, 2, lock, users));
+    /** Live shared leases of the environment. */
+    sharedCount(env) {
+        return this.locks.sharedCount(this.keys(env));
     }
     /**
      * 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.
      */
-    async registerHolder(conv, token, ttlMs) {
-        await this.redis.eval(REGISTER, 2, `${HOLDERS_PREFIX}${conv}`, `${SANDBOX_BUSY_PREFIX}${conv}`, token, ttlMs);
+    async registerHolder(env, token, ttlMs) {
+        await this.redis.eval(REGISTER, 1, `${HOLDERS_PREFIX}${env}`, token, ttlMs);
     }
-    /** Deletes a holder record (after its provider calls); the v2 marker goes with the last one. */
-    async unregisterHolder(conv, token) {
-        await this.redis.eval(UNREGISTER, 2, `${HOLDERS_PREFIX}${conv}`, `${SANDBOX_BUSY_PREFIX}${conv}`, token);
+    /** Deletes a holder record (after its provider calls). */
+    async unregisterHolder(env, token) {
+        await this.redis.hdel(`${HOLDERS_PREFIX}${env}`, token);
     }
     /**
-     * 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.
      */
-    async claimDeadHolders(conv, exclusiveToken) {
-        const [lock, users] = this.keys(conv);
-        const r = (await this.redis.eval(CLAIM, 4, lock, users, `${HOLDERS_PREFIX}${conv}`, `${SANDBOX_BUSY_PREFIX}${conv}`, exclusiveToken ?? ""));
-        const [legacy, ...tags] = r;
-        return { tags, legacyMarker: Number(legacy) === 1 };
+    async claimDeadHolders(env) {
+        const { lock, users } = this.keys(env);
+        return (await this.redis.eval(CLAIM, 3, lock, users, `${HOLDERS_PREFIX}${env}`));
     }
     /**
      * 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`.
+     * up to `capMs`, then throws {@link SandboxPathBusyError}. A {@link LockService.hold} lease
+     * (renewed every TTL / 3): when it is lost its `signal` aborts.
      */
-    async pathLease(conv, path, signal, capMs) {
-        const key = `${PATH_PREFIX}${conv}:${createHash("sha256").update(path).digest("hex")}`;
+    async pathLease(env, path, signal, capMs) {
+        const key = `${PATH_PREFIX}${env}:${createHash("sha256").update(path).digest("hex")}`;
         const token = randomUUID();
-        const ttl = this.pathTtlMs;
         const deadline = Date.now() + capMs;
+        let h;
         for (;;) {
             if (signal.aborted)
                 throw abortReason(signal);
-            if ((await this.redis.set(key, token, "PX", ttl, "NX")) === "OK")
+            h = await this.locks.hold(key, token, this.pathTtlMs);
+            if (h)
                 break;
             if (Date.now() + this.pollMs > deadline)
                 throw new SandboxPathBusyError();
             await this.wait(signal);
         }
-        const ctl = new AbortController();
-        const timer = setInterval(() => {
-            this.redis
-                .eval(EXPIRE_IF, 1, key, token, ttl)
-                .then((ok) => {
-                if (Number(ok) === 1 || ctl.signal.aborted)
-                    return;
-                this.log.warn("sandbox path lease lost", { conversationId: conv });
-                ctl.abort(new SandboxLockLostError(conv));
-                clearInterval(timer);
-            })
-                .catch((err) => this.log.warn("sandbox path lease renew failed", { conversationId: conv, err }));
-        }, Math.max(1, Math.floor(ttl / 3)));
-        timer.unref();
-        return {
-            signal: ctl.signal,
-            release: async () => {
-                clearInterval(timer);
-                await this.redis.eval(DEL_IF, 1, key, token);
-            },
-        };
-    }
-    /**
-     * 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).
-     */
-    hold(conv, token, kind) {
-        const ctl = new AbortController();
-        const staleMs = Math.floor((this.ttlMs * 2) / 3);
-        let inFlight = false;
-        const s = {
-            kind,
-            token,
-            conv,
-            ctl,
-            lastOk: Date.now(),
-            released: false,
-            stop: () => {
-                clearInterval(timer);
-                clearInterval(watchdog);
-            },
-        };
-        const stale = () => Date.now() - s.lastOk > staleMs;
-        const tick = () => {
-            if (stale())
-                this.lose(s);
-            if (ctl.signal.aborted) {
-                s.stop();
-                return;
-            }
-            if (inFlight)
-                return;
-            inFlight = true;
-            void this.renew(s).finally(() => {
-                inFlight = false;
-            });
-        };
-        const timer = setInterval(tick, Math.max(1, Math.floor(this.ttlMs / 3)));
-        timer.unref();
-        // a finer check (at most every 5 s): notices a renewal that hangs
-        const watchdog = setInterval(() => {
-            if (stale())
-                this.lose(s);
-            if (ctl.signal.aborted)
-                s.stop();
-        }, Math.min(5000, Math.max(1, Math.floor(this.ttlMs / 6))));
-        watchdog.unref();
-        return this.view(s, kind);
+        const held = h;
+        return { signal: lostSignal(held.lost, env), release: () => held.release() };
     }
-    lose(s) {
-        if (s.ctl.signal.aborted)
-            return;
-        this.log.warn("sandbox lease lost", { conversationId: s.conv, kind: s.kind });
-        s.ctl.abort(new SandboxLockLostError(s.conv));
-        s.stop();
+    /** A sandbox lease over a held {@link SharedLeaseHandle}, as its current kind. */
+    held(env, h) {
+        return this.view(env, h, lostSignal(h.lost, env), h.kind);
     }
-    async renew(s) {
-        if (s.ctl.signal.aborted)
-            return false;
-        const [lock, users] = this.keys(s.conv);
-        // Redis computes the new expiry when it runs the script: freshness counts from the send
-        const sent = Date.now();
-        try {
-            const ok = Number(await this.redis.eval(RENEW, 2, lock, users, s.token, this.ttlMs, s.kind));
-            if (ok === 1)
-                s.lastOk = Math.max(s.lastOk, sent);
-            else
-                this.lose(s);
-        }
-        catch (err) {
-            this.log.warn("sandbox lease renew failed", { conversationId: s.conv, err });
-        }
-        if (Date.now() - s.lastOk > Math.floor((this.ttlMs * 2) / 3))
-            this.lose(s);
-        return !s.ctl.signal.aborted;
-    }
-    /** A lease view of `s` as `kind`; a view stops working once the lease changes kind. */
-    view(s, kind) {
-        const [lock, users] = this.keys(s.conv);
-        const current = () => s.kind === kind;
+    /** A lease view of `h` as `kind`; a view stops working once the lease changes kind. */
+    view(env, h, signal, kind) {
+        const current = () => h.kind === kind;
         return {
             kind,
-            token: s.token,
-            conversationId: s.conv,
-            signal: s.ctl.signal,
-            renew: () => (current() ? this.renew(s) : Promise.resolve(false)),
+            token: h.token,
+            environmentId: env,
+            signal,
+            // a Redis error is warned, not thrown: the deadline decides whether the lease is lost
+            renew: async () => {
+                if (!current())
+                    return false;
+                try {
+                    return await h.renew();
+                }
+                catch (err) {
+                    this.log.warn("sandbox lease renew failed", { environmentId: env, err });
+                    return !signal.aborted;
+                }
+            },
             // Any view releases the lease in its current kind (a caller that kept only the exclusive
             // view after a downgrade must not leak the shared lease, which would renew forever)
-            release: async () => {
-                if (s.released)
-                    return;
-                s.released = true;
-                s.stop();
-                await this.redis
-                    .eval(RELEASE, 2, lock, users, s.token, s.kind)
-                    .catch((err) => this.log.warn("cannot release sandbox lease", { conversationId: s.conv, err }));
-            },
+            release: () => h.release(),
             downgrade: async () => {
-                if (!current() || s.kind !== "exclusive" || s.released) {
+                if (!current() || h.kind !== "exclusive")
                     throw new Error("sandbox lease is not exclusive");
-                }
-                if (s.ctl.signal.aborted)
-                    throw abortReason(s.ctl.signal);
-                const sent = Date.now();
-                const ok = Number(await this.redis.eval(DOWNGRADE, 2, lock, users, s.token, this.ttlMs));
-                if (ok !== 1) {
-                    this.lose(s);
-                    throw new SandboxLockLostError(s.conv);
-                }
-                s.kind = "shared";
-                s.lastOk = Math.max(s.lastOk, sent);
-                return this.view(s, "shared");
+                if (signal.aborted)
+                    throw abortReason(signal);
+                if (!(await h.downgrade()))
+                    throw new SandboxLockLostError(env);
+                return this.view(env, h, signal, "shared");
             },
         };
     }
-}
+};
+SandboxLeases = __decorate([
+    Injectable(),
+    __param(0, Inject(LockService)),
+    __param(1, Inject(REDIS)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Optional()),
+    __param(3, Inject(SANDBOX_LEASE_TIMINGS))
+], SandboxLeases);
+export { SandboxLeases };