@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/sandbox/leases.d.ts

@@ -0,0 +1,169 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { ApiError } from "../errors.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:
+ *
+ * - `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
+ *   server clock).
+ * - `capk:sandbox-intent:<conv>`: 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
+ *   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}.
+ */
+/** Prefix of the lock key `capk:sandbox:<conversationId>`. */
+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). */
+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");
+}
+/** Another holder kept writing the same file longer than the path lease wait (model-visible text). */
+export declare class SandboxPathBusyError extends Error {
+    constructor();
+}
+export type LeaseKind = "shared" | "exclusive";
+/** A lease this process holds. */
+export interface SandboxLease {
+    readonly kind: LeaseKind;
+    readonly token: string;
+    readonly conversationId: 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). */
+    renew(): Promise<boolean>;
+    /** Stops renewing and releases the lease (only this holder's). */
+    release(): Promise<void>;
+    /** 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. */
+    readonly signal: AbortSignal;
+    release(): Promise<void>;
+}
+/** The lease protocol; no state in process beyond the leases this process holds. */
+export declare class SandboxLeases {
+    private readonly redis;
+    private readonly log;
+    private readonly ttlMs;
+    private readonly pollMs;
+    private readonly pathTtlMs;
+    constructor(d: SandboxLeasesDeps);
+    /**
+     * 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.
+     */
+    private get intentTtlMs();
+    private keys;
+    private wait;
+    /**
+     * A shared lease (`cap` holders at most), polling until one is free; `sandbox.busy` after
+     * `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>;
+    /**
+     * 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?: {
+        intent?: boolean;
+    }): Promise<SandboxLease>;
+    /**
+     * One try at an exclusive lease; null when any lease exists. Without `o` (sweeps) it sets no
+     * 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?: {
+        token?: string;
+        intent?: boolean;
+    }): Promise<SandboxLease | 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}).
+     */
+    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>;
+    /**
+     * 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}).
+     */
+    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>;
+    /**
+     * 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).
+     */
+    claimDeadHolders(conv: string, exclusiveToken?: string): Promise<{
+        tags: string[];
+        legacyMarker: boolean;
+    }>;
+    /**
+     * 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).
+     */
+    private hold;
+    private lose;
+    private renew;
+    /** A lease view of `s` as `kind`; a view stops working once the lease changes kind. */
+    private view;
+}

package/dist/sandbox/leases.js

@@ -0,0 +1,515 @@
+import { createHash, randomUUID } from "node:crypto";
+import { ApiError } from "../errors.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:
+ *
+ * - `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
+ *   server clock).
+ * - `capk:sandbox-intent:<conv>`: 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
+ *   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}.
+ */
+/** Prefix of the lock key `capk:sandbox:<conversationId>`. */
+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:";
+const PATH_PREFIX = "capk:sandbox-path:";
+/** TTL of a path lease (ms); renewed while held. */
+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");
+/** 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") {
+        super(reason === "lock"
+            ? `sandbox lock lost for conversation ${conversationId}`
+            : `sandbox state of conversation ${conversationId} changed concurrently (generation mismatch)`);
+        this.name = "SandboxLockLostError";
+        this.reason = reason;
+    }
+}
+/** Another holder kept writing the same file longer than the path lease wait (model-visible text). */
+export class SandboxPathBusyError extends Error {
+    constructor() {
+        super("another sub-agent is writing this file; try again");
+        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])
+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`;
+/**
+ * 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… }.
+ */
+const CLAIM = `${NOW}
+${PURGE}
+local out = {0}
+local f = redis.call('HGETALL', KEYS[3])
+for i = 1, #f, 2 do
+  local tok = f[i]
+  if tonumber(f[i + 1]) <= now then
+    redis.call('HDEL', KEYS[3], tok)
+  elseif tok ~= cur and not redis.call('ZSCORE', KEYS[2], tok) then
+    redis.call('HDEL', KEYS[3], tok)
+    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`;
+const abortReason = (signal) => signal.reason ?? new DOMException("This operation was aborted", "AbortError");
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(abortReason(signal));
+        };
+        const t = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** The lease protocol; no state in process beyond the leases this process holds. */
+export class SandboxLeases {
+    redis;
+    log;
+    ttlMs;
+    pollMs;
+    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;
+    }
+    /**
+     * 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.
+     */
+    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}`];
+    }
+    wait(signal) {
+        return sleep(this.pollMs + Math.floor(Math.random() * this.pollMs), signal);
+    }
+    /**
+     * A shared lease (`cap` holders at most), polling until one is free; `sandbox.busy` after
+     * `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) {
+        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");
+            if (Date.now() + this.pollMs > deadline)
+                throw sandboxBusy();
+            await this.wait(signal);
+        }
+    }
+    /**
+     * 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.
+     */
+    async acquireExclusive(conv, 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");
+                if (Date.now() + this.pollMs > deadline)
+                    throw sandboxBusy();
+                await this.wait(signal);
+            }
+        }
+        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 }));
+            }
+            throw e;
+        }
+    }
+    /**
+     * One try at an exclusive lease; null when any lease exists. Without `o` (sweeps) it sets no
+     * 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;
+    }
+    /**
+     * 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);
+    }
+    /** 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;
+    }
+    /** 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));
+    }
+    /**
+     * 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}).
+     */
+    async registerHolder(conv, token, ttlMs) {
+        await this.redis.eval(REGISTER, 2, `${HOLDERS_PREFIX}${conv}`, `${SANDBOX_BUSY_PREFIX}${conv}`, 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);
+    }
+    /**
+     * 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).
+     */
+    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 };
+    }
+    /**
+     * 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`.
+     */
+    async pathLease(conv, path, signal, capMs) {
+        const key = `${PATH_PREFIX}${conv}:${createHash("sha256").update(path).digest("hex")}`;
+        const token = randomUUID();
+        const ttl = this.pathTtlMs;
+        const deadline = Date.now() + capMs;
+        for (;;) {
+            if (signal.aborted)
+                throw abortReason(signal);
+            if ((await this.redis.set(key, token, "PX", ttl, "NX")) === "OK")
+                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);
+    }
+    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();
+    }
+    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;
+        return {
+            kind,
+            token: s.token,
+            conversationId: s.conv,
+            signal: s.ctl.signal,
+            renew: () => (current() ? this.renew(s) : Promise.resolve(false)),
+            // 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 }));
+            },
+            downgrade: async () => {
+                if (!current() || s.kind !== "exclusive" || s.released) {
+                    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");
+            },
+        };
+    }
+}