feat(sparsekernel): enforce sandbox lease budgets

Author: AbrahamGreenman

docs/architecture/four-gb-vm-design.md

@@ -23,6 +23,6 @@ Five hundred logical agents are feasible because most are parked in SQLite as co
 
 Book-writing and file-writing agents can run at higher active counts than coding agents because they do not all need browsers, sandboxes, test runners, or heavy model contexts. Expensive work should be scarce, leased, and scheduled.
 
-Resource leases let SparseKernel answer which task owned which expensive resource and when it was released or expired.
+Resource leases let SparseKernel answer which task owned which expensive resource and when it was released or expired. Trust-zone budgets are enforced at lease creation for sandbox work: `max_processes` caps active sandbox leases, and `max_runtime_seconds` clamps lease runtime and expiry. This keeps a 4 GB machine from materializing more heavy execution work than its configured trust zone allows.
 
 Browser targets and observations are compact ledger rows, not retained screenshots or traces. This lets small machines keep enough browser provenance to answer which target made a request, emitted console output, or produced an artifact while still pruning old observations with `openclaw runtime prune`.

docs/architecture/local-agent-kernel.md

@@ -108,7 +108,7 @@ The broker applies configured trust-zone network policy to explicit allowed orig
 
 ## Sandbox broker
 
-The sandbox broker records allocations and leases behind a backend abstraction. Current v0 includes a local/no-isolation backend that can run trusted local commands behind an active sandbox lease for scheduling, timeout, output, usage, and audit accounting. Lease metadata persists the selected backend, isolation description, and trust-zone policy snapshot in SQLite so a restarted broker instance can recover the allocation backend without relying on an in-memory map. The broker can also build command spawn plans for requested bwrap and minijail backends when those binaries are available. Docker is now a policy-backed command backend: it requires a locally available `docker` CLI plus an explicit `dockerImage` or `OPENCLAW_SPARSEKERNEL_DOCKER_IMAGE`, uses `--pull never`, drops capabilities, sets `no-new-privileges`, applies read-only root/tmpfs defaults, maps trust-zone memory/process limits to Docker flags, and keeps networking disabled unless a policy proxy is configured. Set `OPENCLAW_RUNTIME_SANDBOX_REQUIRE_PROXY=1` to fail closed when a network-allowing trust zone lacks a valid loopback `network_policies.proxy_ref`; Docker command plans translate that host loopback proxy to `host.docker.internal` for container workers. This is proxy configuration and allocation gating, not a kernel firewall. SSH, OpenShell, and VM-backed execution remain future wrappers and are not silently executed on the host. In daemon broker mode, embedded runs grant sandbox allocation capability and allocate/release the `code_execution` sandbox lease through the SparseKernel daemon API before falling back to local accounting.
+The sandbox broker records allocations and leases behind a backend abstraction. Current v0 includes a local/no-isolation backend that can run trusted local commands behind an active sandbox lease for scheduling, timeout, output, usage, and audit accounting. Lease metadata persists the selected backend, isolation description, and trust-zone policy snapshot in SQLite so a restarted broker instance can recover the allocation backend without relying on an in-memory map. The broker can also build command spawn plans for requested bwrap and minijail backends when those binaries are available. Docker is now a policy-backed command backend: it requires a locally available `docker` CLI plus an explicit `dockerImage` or `OPENCLAW_SPARSEKERNEL_DOCKER_IMAGE`, uses `--pull never`, drops capabilities, sets `no-new-privileges`, applies read-only root/tmpfs defaults, maps trust-zone memory/process limits to Docker flags, and keeps networking disabled unless a policy proxy is configured. Trust-zone `max_processes` now caps active sandbox leases, and `max_runtime_seconds` clamps resource lease runtime and expiry. Set `OPENCLAW_RUNTIME_SANDBOX_REQUIRE_PROXY=1` to fail closed when a network-allowing trust zone lacks a valid loopback `network_policies.proxy_ref`; Docker command plans translate that host loopback proxy to `host.docker.internal` for container workers. This is proxy configuration and allocation gating, not a kernel firewall. SSH, OpenShell, and VM-backed execution remain future wrappers and are not silently executed on the host. In daemon broker mode, embedded runs grant sandbox allocation capability and allocate/release the `code_execution` sandbox lease through the SparseKernel daemon API before falling back to local accounting.
 
 Important boundary: `local/no_isolation` means accounting only. It does not provide process, filesystem, network, kernel, or VM isolation. Docker, bwrap, minijail, gVisor, or VM backends must be described by their actual guarantees when implemented.
 

src/local-kernel/database.test.ts

@@ -476,6 +476,58 @@ describe("local runtime kernel database", () => {
     });
   });
 
+  it("enforces trust-zone sandbox budgets and runtime clamps", () => {
+    const db = openTempDb();
+    expect(
+      db.updateTrustZoneLimits({
+        id: "code_execution",
+        maxProcesses: 1,
+        maxRuntimeSeconds: 2,
+      }),
+    ).toBe(true);
+    const first = db.createResourceLease({
+      id: "sandbox-budget-a",
+      resourceType: "sandbox",
+      resourceId: "sandbox-budget-a",
+      trustZoneId: "code_execution",
+      maxRuntimeMs: 10_000,
+      leaseUntil: "2030-01-01T00:00:00.000Z",
+      now: "2026-01-01T00:00:00.000Z",
+    });
+    expect(db.getResourceLease(first)).toMatchObject({
+      maxRuntimeMs: 2_000,
+      leaseUntil: "2026-01-01T00:00:02.000Z",
+    });
+    expect(() =>
+      db.createResourceLease({
+        id: "sandbox-budget-b",
+        resourceType: "sandbox",
+        resourceId: "sandbox-budget-b",
+        trustZoneId: "code_execution",
+        now: "2026-01-01T00:00:01.000Z",
+      }),
+    ).toThrow(/budget exhausted/);
+    const audit = db.db
+      .prepare("SELECT action, payload_json FROM audit_log ORDER BY id DESC LIMIT 1")
+      .get() as { action: string; payload_json: string };
+    expect(audit.action).toBe("resource_lease.denied_budget_exhausted");
+    expect(JSON.parse(audit.payload_json)).toMatchObject({
+      trustZoneId: "code_execution",
+      resourceType: "sandbox",
+      active: 1,
+      limit: 1,
+    });
+    expect(db.releaseResourceLease(first)).toBe(true);
+    expect(
+      db.createResourceLease({
+        id: "sandbox-budget-c",
+        resourceType: "sandbox",
+        resourceId: "sandbox-budget-c",
+        trustZoneId: "code_execution",
+      }),
+    ).toBe("sandbox-budget-c");
+  });
+
   it("brokers local/no-isolation sandbox allocations without pretending isolation", () => {
     const db = openTempDb();
     db.ensureAgent({ id: "main" });

src/local-kernel/database.ts

@@ -239,6 +239,16 @@ type RuntimeInfoRow = {
   updated_at: string;
 };
 
+class ResourceLeaseBudgetError extends Error {
+  constructor(
+    message: string,
+    readonly payload: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "ResourceLeaseBudgetError";
+  }
+}
+
 export type OpenLocalKernelDatabaseOptions = {
   dbPath?: string;
   env?: NodeJS.ProcessEnv;
@@ -526,6 +536,8 @@ export class LocalKernelDatabase {
   readonly dbPath: string;
   private readonly walMaintenance: SqliteWalMaintenance;
   private closed = false;
+  private transactionDepth = 0;
+  private savepointCounter = 0;
 
   constructor(options: OpenLocalKernelDatabaseOptions = {}) {
     const env = options.env ?? process.env;
@@ -748,7 +760,26 @@ export class LocalKernelDatabase {
   }
 
   withTransaction<T>(fn: () => T): T {
+    if (this.transactionDepth > 0) {
+      const savepoint = `local_kernel_sp_${++this.savepointCounter}`;
+      this.db.exec(`SAVEPOINT ${savepoint}`);
+      this.transactionDepth += 1;
+      try {
+        const result = fn();
+        this.db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+        return result;
+      } catch (error) {
+        try {
+          this.db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+          this.db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+        } catch {}
+        throw error;
+      } finally {
+        this.transactionDepth -= 1;
+      }
+    }
     this.db.exec("BEGIN IMMEDIATE");
+    this.transactionDepth += 1;
     try {
       const result = fn();
       this.db.exec("COMMIT");
@@ -758,6 +789,8 @@ export class LocalKernelDatabase {
         this.db.exec("ROLLBACK");
       } catch {}
       throw error;
+    } finally {
+      this.transactionDepth -= 1;
     }
   }
 
@@ -1994,37 +2027,120 @@ export class LocalKernelDatabase {
   }): string {
     const id = input.id ?? `lease_${crypto.randomUUID()}`;
     const now = input.now ?? nowIso();
-    this.db
-      .prepare(
-        `INSERT INTO resource_leases(
-          id, resource_type, resource_id, owner_task_id, owner_agent_id, trust_zone_id,
-          status, lease_until, max_runtime_ms, max_bytes_out, max_tokens, metadata_json, created_at, updated_at
-        ) VALUES(?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?)`,
-      )
-      .run(
-        id,
-        input.resourceType,
-        input.resourceId,
-        input.ownerTaskId ?? null,
-        input.ownerAgentId ?? null,
-        input.trustZoneId ?? null,
-        input.leaseUntil ?? null,
-        input.maxRuntimeMs ?? null,
-        input.maxBytesOut ?? null,
-        input.maxTokens ?? null,
-        jsonToText(input.metadata),
-        now,
-        now,
-      );
-    this.recordAudit({
-      actor: { type: "runtime" },
-      action: "resource_lease.created",
-      objectType: "resource_lease",
-      objectId: id,
-      payload: { resourceType: input.resourceType, resourceId: input.resourceId },
-      createdAt: now,
-    });
-    return id;
+    try {
+      return this.withTransaction(() => {
+        const budget = this.resolveResourceLeaseBudget(input, now);
+        this.db
+          .prepare(
+            `INSERT INTO resource_leases(
+              id, resource_type, resource_id, owner_task_id, owner_agent_id, trust_zone_id,
+              status, lease_until, max_runtime_ms, max_bytes_out, max_tokens, metadata_json, created_at, updated_at
+            ) VALUES(?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?)`,
+          )
+          .run(
+            id,
+            input.resourceType,
+            input.resourceId,
+            input.ownerTaskId ?? null,
+            input.ownerAgentId ?? null,
+            input.trustZoneId ?? null,
+            budget.leaseUntil ?? null,
+            budget.maxRuntimeMs ?? null,
+            input.maxBytesOut ?? null,
+            input.maxTokens ?? null,
+            jsonToText(input.metadata),
+            now,
+            now,
+          );
+        this.recordAudit({
+          actor: { type: "runtime" },
+          action: "resource_lease.created",
+          objectType: "resource_lease",
+          objectId: id,
+          payload: {
+            resourceType: input.resourceType,
+            resourceId: input.resourceId,
+            ...(input.trustZoneId ? { trustZoneId: input.trustZoneId } : {}),
+            ...(budget.maxRuntimeMs !== input.maxRuntimeMs
+              ? { maxRuntimeMs: budget.maxRuntimeMs }
+              : {}),
+          },
+          createdAt: now,
+        });
+        return id;
+      });
+    } catch (error) {
+      if (error instanceof ResourceLeaseBudgetError) {
+        this.recordAudit({
+          actor: { type: "runtime" },
+          action: "resource_lease.denied_budget_exhausted",
+          objectType: "trust_zone",
+          objectId: input.trustZoneId,
+          payload: error.payload,
+          createdAt: now,
+        });
+      }
+      throw error;
+    }
+  }
+
+  private resolveResourceLeaseBudget(
+    input: {
+      resourceType: string;
+      trustZoneId?: string;
+      leaseUntil?: string;
+      maxRuntimeMs?: number;
+    },
+    now: string,
+  ): { leaseUntil?: string; maxRuntimeMs?: number } {
+    const zone = input.trustZoneId
+      ? this.listTrustZones().find((entry) => entry.id === input.trustZoneId)
+      : undefined;
+    if (
+      zone?.maxProcesses !== undefined &&
+      input.resourceType === "sandbox" &&
+      zone.maxProcesses >= 0
+    ) {
+      const row = this.db
+        .prepare(
+          `SELECT COUNT(*) AS count
+           FROM resource_leases
+           WHERE trust_zone_id = ? AND resource_type = 'sandbox' AND status = 'active'`,
+        )
+        .get(zone.id) as CountRow;
+      const active = Number(row.count);
+      if (active >= zone.maxProcesses) {
+        throw new ResourceLeaseBudgetError(
+          `Trust zone ${zone.id} sandbox budget exhausted: ${active}/${zone.maxProcesses} active`,
+          {
+            trustZoneId: zone.id,
+            resourceType: input.resourceType,
+            active,
+            limit: zone.maxProcesses,
+          },
+        );
+      }
+    }
+
+    let maxRuntimeMs = input.maxRuntimeMs;
+    if (zone?.maxRuntimeSeconds !== undefined) {
+      const trustZoneMaxMs = Math.max(1, Math.trunc(zone.maxRuntimeSeconds * 1000));
+      maxRuntimeMs =
+        maxRuntimeMs === undefined
+          ? trustZoneMaxMs
+          : Math.min(Math.max(1, Math.trunc(maxRuntimeMs)), trustZoneMaxMs);
+    } else if (maxRuntimeMs !== undefined) {
+      maxRuntimeMs = Math.max(1, Math.trunc(maxRuntimeMs));
+    }
+
+    let leaseUntil = input.leaseUntil;
+    if (maxRuntimeMs !== undefined) {
+      const runtimeLeaseUntil = futureIso(now, maxRuntimeMs);
+      if (!leaseUntil || Date.parse(leaseUntil) > Date.parse(runtimeLeaseUntil)) {
+        leaseUntil = runtimeLeaseUntil;
+      }
+    }
+    return { leaseUntil, maxRuntimeMs };
   }
 
   getResourceLease(id: string): ResourceLeaseRecord | undefined {

src/local-kernel/sandbox-broker.ts

@@ -572,6 +572,7 @@ export class LocalSandboxBroker implements SandboxBroker {
         policy,
       },
     });
+    const lease = this.db.getResourceLease(allocationId);
     this.db.recordAudit({
       actor: request.agentId ? { type: "agent", id: request.agentId } : { type: "runtime" },
       action: "sandbox.allocated",
@@ -593,7 +594,7 @@ export class LocalSandboxBroker implements SandboxBroker {
       backend,
       status: "active",
       createdAt: new Date().toISOString(),
-      leaseUntil: request.requirements?.leaseUntil,
+      leaseUntil: lease?.leaseUntil ?? request.requirements?.leaseUntil,
     };
   }