@inflexa-ai/harness 0.46.2 → 0.47.0

package/dist/schemas/workflow-state.js

@@ -84,18 +84,6 @@ export const AnalysisStepSchema = z.object({
         .array(z.string())
         .describe("IDs of steps in this plan that must complete before this one runs. Empty when the step has no prerequisites. The graph must be acyclic."),
     status: z.enum(["pending", "running", "completed", "failed", "skipped"]).default("pending"),
-    // Optional on the persistence schema so historical plans (pre-resources)
-    // still parse on the read side. `PlanStepSchema` re-requires it for planner
-    // output, and the execution path rejects any step that reaches it without
-    // resources (no silent default) and clamps to cluster limits before use.
-    resources: z
-        .object({
-        cpu: z.number().describe("CPU cores the step needs."),
-        memoryGb: z.number().describe("Memory in GB the step needs."),
-        gpu: z.object({ count: z.number() }).optional().describe("GPUs the step needs. Omit unless the step genuinely requires one."),
-    })
-        .optional()
-        .describe("Resources the step needs. Ground the estimate in the actual data size — see the resource-estimation rules."),
     grounding: GroundingSchema.optional().describe("The knowledge grounding of a method step: fill it from the answer of `knowledge_recommend` when that tool is attached. Omit it when no knowledge tool is attached."),
     // Execution fields
     agent: z.string().optional().describe("Assigned sandbox agent name from registry"),
@@ -108,7 +96,6 @@ export const AnalysisStepSchema = z.object({
         .describe("The one capability phrase of the assigned agent that this step uses, copied EXACTLY from the agent catalog. " +
         "One phrase, verbatim — never a paraphrase, never a list, never your own wording. " +
         "The launch resolves the reference data that the capability declares before the run starts, so a reworded phrase loses that check and the step discovers an absent source itself."),
-    timeout: z.number().optional().describe("Execution timeout in seconds (falls back to image default)"),
     maxSteps: z.number().describe("Max LLM agentic steps for sandbox agent"),
     description: z.string().optional().describe("Human-readable description of what the step produces."),
     // Step result fields (populated during execution)
@@ -128,6 +115,10 @@ export const AnalysisPlanSchema = z.object({
     created_at: z.string().describe("ISO-8601 timestamp for when the plan was created."),
     omicsType: z.string().optional().describe("Omics data type detected from the data context (e.g. transcriptomics, proteomics, metabolomics)."),
     omicsSubtype: z.string().optional().describe("Subtype detected from the data context (e.g. bulk-rna-seq, single-cell, microarray)."),
+    request: z
+        .string()
+        .optional()
+        .describe("The request that the plan answers, as `generate_plan` received it. The briefing of each step renders it. Absent on an ad hoc plan and on a historical plan."),
 });
 // ── Suspension Payload ──────────────────────────────────────────────
 /**

package/dist/state/index.d.ts

@@ -16,7 +16,6 @@ setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis
 export type { InsertRunInput, RunPage, RunReservation } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
-export { setSandboxRef, clearSandboxRef, reconcileReapedSandbox } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
 export type { InsertPlanInput, UpsertPlanInput, PlanRecord, PlanRowQuerier } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";

package/dist/state/index.js

@@ -12,7 +12,6 @@ export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifact
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
-export { setSandboxRef, clearSandboxRef, reconcileReapedSandbox } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";

package/dist/state/migrations/20261030120000_lease_the_sandboxes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Record each sandbox lease. A row is one generation of a lease and its lease
+ * workflow: the request, the grant, the current machine, and the release. The
+ * lease table replaces the sandbox handle on the step rows.
+ */
+import type { Migration } from "kysely/migration";
+export declare const leaseTheSandboxes: Migration;

package/dist/state/migrations/20261030120000_lease_the_sandboxes.js

@@ -0,0 +1,34 @@
+/**
+ * Record each sandbox lease. A row is one generation of a lease and its lease
+ * workflow: the request, the grant, the current machine, and the release. The
+ * lease table replaces the sandbox handle on the step rows.
+ */
+import { sql } from "kysely";
+export const leaseTheSandboxes = {
+    async up(db) {
+        await sql `CREATE TABLE IF NOT EXISTS cortex_sandbox_leases (
+            lease_workflow_id TEXT PRIMARY KEY,
+            lease_key TEXT NOT NULL,
+            generation INTEGER NOT NULL,
+            analysis_id TEXT NOT NULL,
+            owner_workflow_id TEXT NOT NULL,
+            work_kind TEXT NOT NULL,
+            work_id TEXT NOT NULL,
+            requested JSONB NOT NULL,
+            granted JSONB,
+            state TEXT NOT NULL,
+            release_reason TEXT,
+            machine JSONB,
+            machine_generation INTEGER NOT NULL DEFAULT 0,
+            exec_salt TEXT NOT NULL DEFAULT gen_random_uuid()::text,
+            requested_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            granted_at TIMESTAMPTZ,
+            last_used_at TIMESTAMPTZ,
+            released_at TIMESTAMPTZ
+        )`.execute(db);
+        await sql `CREATE UNIQUE INDEX IF NOT EXISTS idx_cortex_sandbox_leases_active_key ON cortex_sandbox_leases(lease_key) WHERE state <> 'released'`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_sandbox_leases_waiting ON cortex_sandbox_leases(requested_at) WHERE state = 'requested'`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_sandbox_leases_analysis ON cortex_sandbox_leases(analysis_id)`.execute(db);
+        await sql `ALTER TABLE cortex_step_executions DROP COLUMN IF EXISTS sandbox_ref`.execute(db);
+    },
+};

package/dist/state/migrations/20261030120100_drop_the_report_derivations.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A report session derives no table, thus the session state keeps no list of derivations.
+ */
+import type { Migration } from "kysely/migration";
+export declare const dropTheReportDerivations: Migration;

package/dist/state/migrations/20261030120100_drop_the_report_derivations.js

@@ -0,0 +1,9 @@
+/**
+ * A report session derives no table, thus the session state keeps no list of derivations.
+ */
+import { sql } from "kysely";
+export const dropTheReportDerivations = {
+    async up(db) {
+        await sql `ALTER TABLE cortex_report_session_state DROP COLUMN IF EXISTS derivations`.execute(db);
+    },
+};

package/dist/state/migrations/20261030120200_keep_the_report_derivations.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A report session derives a table in a script, thus the session state keeps its list of derivations again. A
+ * database that ran the drop gets the column back with no rows in it. Each other database keeps its column.
+ */
+import type { Migration } from "kysely/migration";
+export declare const keepTheReportDerivations: Migration;

package/dist/state/migrations/20261030120200_keep_the_report_derivations.js

@@ -0,0 +1,10 @@
+/**
+ * A report session derives a table in a script, thus the session state keeps its list of derivations again. A
+ * database that ran the drop gets the column back with no rows in it. Each other database keeps its column.
+ */
+import { sql } from "kysely";
+export const keepTheReportDerivations = {
+    async up(db) {
+        await sql `ALTER TABLE cortex_report_session_state ADD COLUMN IF NOT EXISTS derivations JSONB`.execute(db);
+    },
+};

package/dist/state/migrations/index.js

@@ -21,6 +21,9 @@ import { recordThePausedWork } from "./20261028120000_record_the_paused_work.js"
 import { endTheSuspendedRuns } from "./20261028120100_end_the_suspended_runs.js";
 import { referenceTheRunMandate } from "./20261029120000_reference_the_run_mandate.js";
 import { recordTheRunSessionOfAPause } from "./20261029120100_record_the_run_session_of_a_pause.js";
+import { leaseTheSandboxes } from "./20261030120000_lease_the_sandboxes.js";
+import { dropTheReportDerivations } from "./20261030120100_drop_the_report_derivations.js";
+import { keepTheReportDerivations } from "./20261030120200_keep_the_report_derivations.js";
 export function cortexMigrations(logger) {
     return {
         "20260927120000_baseline": baseline(logger),
@@ -39,5 +42,8 @@ export function cortexMigrations(logger) {
         "20261028120100_end_the_suspended_runs": endTheSuspendedRuns,
         "20261029120000_reference_the_run_mandate": referenceTheRunMandate,
         "20261029120100_record_the_run_session_of_a_pause": recordTheRunSessionOfAPause,
+        "20261030120000_lease_the_sandboxes": leaseTheSandboxes,
+        "20261030120100_drop_the_report_derivations": dropTheReportDerivations,
+        "20261030120200_keep_the_report_derivations": keepTheReportDerivations,
     };
 }

package/dist/state/purge-analysis.d.ts

@@ -29,8 +29,10 @@
  * What it does not reach, so that absent coverage is never read as delivered:
  * scheduled operational workflows (they belong to no analysis and accumulate
  * independently of any purge), the shared regulatory corpus, `messages` rows whose
- * thread row is already gone (nothing attributes them to an analysis), and
- * workspace files on disk (the embedder owns their disposal).
+ * thread row is already gone (nothing attributes them to an analysis), the sandbox
+ * machines (the purge cancels their lease workflows, and the sandbox reconciler then
+ * removes each machine whose lease workflow ended), and workspace files on disk (the
+ * embedder owns their disposal).
  */
 import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";

package/dist/state/purge-analysis.js

@@ -29,8 +29,10 @@
  * What it does not reach, so that absent coverage is never read as delivered:
  * scheduled operational workflows (they belong to no analysis and accumulate
  * independently of any purge), the shared regulatory corpus, `messages` rows whose
- * thread row is already gone (nothing attributes them to an analysis), and
- * workspace files on disk (the embedder owns their disposal).
+ * thread row is already gone (nothing attributes them to an analysis), the sandbox
+ * machines (the purge cancels their lease workflows, and the sandbox reconciler then
+ * removes each machine whose lease workflow ended), and workspace files on disk (the
+ * embedder owns their disposal).
  */
 import { errAsync, okAsync } from "neverthrow";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -45,8 +47,9 @@ import { isSqlIdentifier } from "./vector-store.js";
  *    id and interpolated into `DROP TABLE`, because an identifier cannot be a bind
  *    parameter. Confining the id to `[a-z0-9_-]` is what makes that derived name an
  *    identifier at all.
- *  - An unambiguous `dataprofile:` namespace. Profile workflows are found by the id
- *    prefix `dataprofile:{analysisId}:`, matched with `starts_with` and no
+ *  - An unambiguous `dataprofile:` and `sandboxlease:` namespace. Profile workflows
+ *    and lease workflows are found by the id prefixes `dataprofile:{analysisId}:` and
+ *    `sandboxlease:{analysisId}:`, matched with `starts_with` and no
  *    delimiter check. An id holding a `:` makes analysis `a`'s prefix equally a
  *    prefix of every workflow id of an analysis named `a:x` — and each id that
  *    prefix returns is cancelled, then deleted with its descendants, taking another
@@ -78,6 +81,7 @@ function isPurgeableAnalysisIdShape(analysisId) {
 const ANALYSIS_KEYED_DELETES = [
     { op: "purgeAnalysis.artifacts", sql: "DELETE FROM cortex_artifacts WHERE analysis_id = $1" },
     { op: "purgeAnalysis.stepExecutions", sql: "DELETE FROM cortex_step_executions WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.sandboxLeases", sql: "DELETE FROM cortex_sandbox_leases WHERE analysis_id = $1" },
     { op: "purgeAnalysis.runs", sql: "DELETE FROM cortex_runs WHERE analysis_id = $1" },
     { op: "purgeAnalysis.workingMemory", sql: "DELETE FROM cortex_working_memory WHERE analysis_id = $1" },
     { op: "purgeAnalysis.asks", sql: "DELETE FROM cortex_asks WHERE analysis_id = $1" },
@@ -113,8 +117,10 @@ export function createAnalysisPurge({ pool, workflows, logger: injected }) {
     /**
      * Every workflow id the analysis can still be traced to, read while the rows
      * that record them are all still on disk. `cortex_runs.run_id` IS the parent
-     * workflow id, and those rows together with the `dataprofile:{analysisId}:` id
-     * namespace are the ONLY mapping from an analysis to its workflows: a delete
+     * workflow id, and those rows together with the `dataprofile:{analysisId}:` and the
+     * `sandboxlease:{analysisId}:` id namespaces are the ONLY mapping from an analysis to its
+     * workflows. A lease workflow is no descendant of its consumer, thus only its namespace
+     * reaches it. A delete
      * of `cortex_runs` that lands before this read completes strands the largest
      * part of the footprint permanently out of reach.
      */
@@ -124,12 +130,17 @@ export function createAnalysisPurge({ pool, workflows, logger: injected }) {
             values: [analysisId],
         });
         return rows.map((row) => row.run_id);
-    }).andThen((runIds) => workflows.findByIdPrefix(`dataprofile:${analysisId}:`).map((profileIds) => {
-        logger.debug("collected workflow identity", { analysisId, runs: runIds.length, dataProfiles: profileIds.length });
-        // The two id sources cannot overlap, but collapsing duplicates keeps a
+    }).andThen((runIds) => workflows.findByIdPrefix(`dataprofile:${analysisId}:`).andThen((profileIds) => workflows.findByIdPrefix(`sandboxlease:${analysisId}:`).map((leaseIds) => {
+        logger.debug("collected workflow identity", {
+            analysisId,
+            runs: runIds.length,
+            dataProfiles: profileIds.length,
+            sandboxLeases: leaseIds.length,
+        });
+        // The id sources cannot overlap, but collapsing duplicates keeps a
         // repeated id out of the reclaimed count regardless.
-        return [...new Set([...runIds, ...profileIds])];
-    }));
+        return [...new Set([...runIds, ...profileIds, ...leaseIds])];
+    })));
     /**
      * One transaction for the whole `cortex_*` stage, so a mid-stage failure leaves
      * no half-deleted analysis behind.

package/dist/state/sandbox-leases.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The rows of `cortex_sandbox_leases`: one row for each generation of a sandbox lease and its lease workflow. The
+ * sandbox module writes them, and the reconciler and the purge read them.
+ *
+ * The grant is the one place that compares a request against the budget. It runs under one transaction-scoped
+ * advisory lock, thus two grants never read the same free capacity.
+ */
+import type { ResultAsync } from "neverthrow";
+import { type MachineBudget, type ResourceSpec } from "../config/resource-limits.js";
+import type { WorkKind } from "../contracts/chat-parts.js";
+import { type Connectable, type DbError } from "../lib/db-result.js";
+import type { Querier } from "./db.js";
+import { type PersistedSandboxRef } from "./schema.js";
+export type LeaseState = "requested" | "granted" | "released";
+/** One generation of a lease, as its row records it. */
+export type LeaseRecord = {
+    readonly leaseWorkflowId: string;
+    readonly leaseKey: string;
+    readonly generation: number;
+    readonly analysisId: string;
+    readonly ownerWorkflowId: string;
+    readonly workKind: WorkKind;
+    readonly workId: string;
+    readonly requested: ResourceSpec;
+    readonly granted?: ResourceSpec;
+    readonly state: LeaseState;
+    readonly releaseReason?: string;
+    readonly machine?: PersistedSandboxRef;
+    readonly machineGeneration: number;
+    /** The random value of the exec ids of the lease. No machine receives it, thus a command cannot derive a later exec id. */
+    readonly execSalt: string;
+};
+/** What a request writes. The row starts in `requested`, and the time of the insert orders the queue. */
+export type LeaseRequest = Omit<LeaseRecord, "granted" | "state" | "releaseReason" | "machine" | "machineGeneration" | "execSalt">;
+/**
+ * Write the request of a new generation. A key that holds a lease that is not released keeps it: the insert does
+ * nothing, and the caller reads the active lease again.
+ */
+export declare function requestLease(pool: Querier, request: LeaseRequest): ResultAsync<void, DbError>;
+/** The lease of the key that is not released, or `undefined`. */
+export declare function activeLease(pool: Querier, leaseKey: string): ResultAsync<LeaseRecord | undefined, DbError>;
+export declare function readLease(pool: Querier, leaseWorkflowId: string): ResultAsync<LeaseRecord | undefined, DbError>;
+/** The highest generation of the key, or 0 for a key with no lease. */
+export declare function latestGeneration(pool: Querier, leaseKey: string): ResultAsync<number, DbError>;
+export type GrantOutcome = {
+    readonly kind: "granted";
+    readonly size: ResourceSpec;
+} | {
+    readonly kind: "waiting";
+} | {
+    readonly kind: "released";
+};
+/** Grant the lease when it is the oldest waiting request and it fits the budget. With no budget, grant at once. */
+export declare function tryGrant(pool: Connectable, leaseWorkflowId: string, budget: MachineBudget | undefined): ResultAsync<GrantOutcome, DbError>;
+/** The lease workflow of the oldest waiting request, the next one that a free capacity can wake. */
+export declare function oldestWaiting(pool: Querier): ResultAsync<string | undefined, DbError>;
+/** Record the machine of a machine generation. */
+export declare function setMachine(pool: Querier, leaseWorkflowId: string, machine: PersistedSandboxRef, machineGeneration: number): ResultAsync<void, DbError>;
+/**
+ * Clear the machine of one machine generation, and give the machine that the row held. A row whose generation
+ * moved on keeps its machine, thus a late report of an old death clears nothing.
+ */
+export declare function clearMachine(pool: Querier, leaseWorkflowId: string, machineGeneration: number): ResultAsync<PersistedSandboxRef | undefined, DbError>;
+/**
+ * Clear the machine of an idle lease: no exec used the lease for `idleMs`. An exec writes `last_used_at` before it
+ * submits, under the same row lock, thus an exec that starts can never lose its machine to this clear.
+ */
+export declare function clearIdleMachine(pool: Querier, leaseWorkflowId: string, machineGeneration: number, idleMs: number): ResultAsync<PersistedSandboxRef | undefined, DbError>;
+/** Mark the lease used now, and give its machine. A lease that is not granted gives `undefined`. */
+export declare function touchLease(pool: Querier, leaseWorkflowId: string): ResultAsync<{
+    machine?: PersistedSandboxRef;
+    machineGeneration: number;
+} | undefined, DbError>;
+/** Mark the lease released, and give the machine that it still held. A second release gives `undefined`. */
+export declare function releaseLease(pool: Querier, leaseWorkflowId: string, reason: string): ResultAsync<{
+    machine?: PersistedSandboxRef;
+} | undefined, DbError>;
+/** Each lease of the given owner workflows that is not released. */
+export declare function leasesOwnedBy(pool: Querier, ownerWorkflowIds: readonly string[]): ResultAsync<LeaseRecord[], DbError>;
+/** Each lease that is not released, for the sweep of the reconciler. */
+export declare function openLeases(pool: Querier): ResultAsync<LeaseRecord[], DbError>;

package/dist/state/sandbox-leases.js

@@ -0,0 +1,247 @@
+/**
+ * The rows of `cortex_sandbox_leases`: one row for each generation of a sandbox lease and its lease workflow. The
+ * sandbox module writes them, and the reconciler and the purge read them.
+ *
+ * The grant is the one place that compares a request against the budget. It runs under one transaction-scoped
+ * advisory lock, thus two grants never read the same free capacity.
+ */
+import { z } from "zod";
+import { ResourceSpecSchema } from "../config/resource-limits.js";
+import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { PersistedSandboxRefSchema } from "./schema.js";
+const LeaseRowSchema = z.object({
+    lease_workflow_id: z.string(),
+    lease_key: z.string(),
+    generation: z.number(),
+    analysis_id: z.string(),
+    owner_workflow_id: z.string(),
+    work_kind: z.enum(["turn", "run", "profile"]),
+    work_id: z.string(),
+    requested: ResourceSpecSchema,
+    granted: ResourceSpecSchema.nullable(),
+    state: z.enum(["requested", "granted", "released"]),
+    release_reason: z.string().nullable(),
+    machine: PersistedSandboxRefSchema.nullable(),
+    machine_generation: z.number(),
+    exec_salt: z.string(),
+});
+const COLUMNS = "lease_workflow_id, lease_key, generation, analysis_id, owner_workflow_id, work_kind, work_id, requested, granted, state, release_reason, machine, machine_generation, exec_salt";
+/** The one key of the advisory lock of the grant. Any constant works; it only has to be the same for each grant. */
+const GRANT_LOCK_KEY = 74_210_031;
+function recordOf(row) {
+    const parsed = LeaseRowSchema.parse(row);
+    return {
+        leaseWorkflowId: parsed.lease_workflow_id,
+        leaseKey: parsed.lease_key,
+        generation: parsed.generation,
+        analysisId: parsed.analysis_id,
+        ownerWorkflowId: parsed.owner_workflow_id,
+        workKind: parsed.work_kind,
+        workId: parsed.work_id,
+        requested: parsed.requested,
+        granted: parsed.granted ?? undefined,
+        state: parsed.state,
+        releaseReason: parsed.release_reason ?? undefined,
+        machine: parsed.machine ?? undefined,
+        machineGeneration: parsed.machine_generation,
+        execSalt: parsed.exec_salt,
+    };
+}
+/**
+ * Write the request of a new generation. A key that holds a lease that is not released keeps it: the insert does
+ * nothing, and the caller reads the active lease again.
+ */
+export function requestLease(pool, request) {
+    return tryMutation("sandboxLeases.request", async () => {
+        await pool.query({
+            text: `INSERT INTO cortex_sandbox_leases
+                (lease_workflow_id, lease_key, generation, analysis_id, owner_workflow_id, work_kind, work_id, requested, state)
+                VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, 'requested')
+                ON CONFLICT DO NOTHING`,
+            values: [
+                request.leaseWorkflowId,
+                request.leaseKey,
+                request.generation,
+                request.analysisId,
+                request.ownerWorkflowId,
+                request.workKind,
+                request.workId,
+                JSON.stringify(request.requested),
+            ],
+        });
+    });
+}
+/** The lease of the key that is not released, or `undefined`. */
+export function activeLease(pool, leaseKey) {
+    return tryQuery("sandboxLeases.active", async () => {
+        const { rows } = await pool.query({
+            text: `SELECT ${COLUMNS} FROM cortex_sandbox_leases WHERE lease_key = $1 AND state <> 'released'`,
+            values: [leaseKey],
+        });
+        return rows.length === 0 ? undefined : recordOf(rows[0]);
+    });
+}
+export function readLease(pool, leaseWorkflowId) {
+    return tryQuery("sandboxLeases.read", async () => {
+        const { rows } = await pool.query({
+            text: `SELECT ${COLUMNS} FROM cortex_sandbox_leases WHERE lease_workflow_id = $1`,
+            values: [leaseWorkflowId],
+        });
+        return rows.length === 0 ? undefined : recordOf(rows[0]);
+    });
+}
+/** The highest generation of the key, or 0 for a key with no lease. */
+export function latestGeneration(pool, leaseKey) {
+    return tryQuery("sandboxLeases.latestGeneration", async () => {
+        const { rows } = await pool.query({
+            text: `SELECT max(generation) AS generation FROM cortex_sandbox_leases WHERE lease_key = $1`,
+            values: [leaseKey],
+        });
+        return rows[0]?.generation ?? 0;
+    });
+}
+function fits(budget, held, request) {
+    return held.cpu + request.cpu <= budget.cpu && held.memoryGb + request.memoryGb <= budget.memoryGb;
+}
+function grantIn(client, leaseWorkflowId, budget) {
+    return tryMutation("sandboxLeases.grant", async () => {
+        await client.query({ text: "SELECT pg_advisory_xact_lock($1)", values: [GRANT_LOCK_KEY] });
+        const own = await client.query({ text: `SELECT ${COLUMNS} FROM cortex_sandbox_leases WHERE lease_workflow_id = $1`, values: [leaseWorkflowId] });
+        const lease = own.rows.length === 0 ? undefined : recordOf(own.rows[0]);
+        if (lease === undefined || lease.state === "released")
+            return { kind: "released" };
+        if (lease.state === "granted")
+            return { kind: "granted", size: lease.granted ?? lease.requested };
+        if (budget !== undefined) {
+            // The strict order of the requests: only the oldest waiting request can take a grant.
+            const head = await client.query(`SELECT lease_workflow_id FROM cortex_sandbox_leases WHERE state = 'requested' ORDER BY requested_at, lease_workflow_id LIMIT 1`);
+            if (head.rows[0]?.lease_workflow_id !== leaseWorkflowId)
+                return { kind: "waiting" };
+            const sums = await client.query(`SELECT sum((granted->>'cpu')::numeric) AS cpu, sum((granted->>'memoryGb')::numeric) AS memory_gb
+                 FROM cortex_sandbox_leases WHERE state = 'granted'`);
+            const held = { cpu: Number(sums.rows[0]?.cpu ?? 0), memoryGb: Number(sums.rows[0]?.memory_gb ?? 0) };
+            if (!fits(budget, held, lease.requested))
+                return { kind: "waiting" };
+        }
+        await client.query({
+            text: `UPDATE cortex_sandbox_leases SET state = 'granted', granted = requested, granted_at = now(), last_used_at = now()
+                   WHERE lease_workflow_id = $1`,
+            values: [leaseWorkflowId],
+        });
+        return { kind: "granted", size: lease.requested };
+    });
+}
+/** Grant the lease when it is the oldest waiting request and it fits the budget. With no budget, grant at once. */
+export function tryGrant(pool, leaseWorkflowId, budget) {
+    return withTransaction(pool, "sandboxLeases.tryGrant", (client) => grantIn(client, leaseWorkflowId, budget));
+}
+/** The lease workflow of the oldest waiting request, the next one that a free capacity can wake. */
+export function oldestWaiting(pool) {
+    return tryQuery("sandboxLeases.oldestWaiting", async () => {
+        const { rows } = await pool.query(`SELECT lease_workflow_id FROM cortex_sandbox_leases WHERE state = 'requested' ORDER BY requested_at, lease_workflow_id LIMIT 1`);
+        return rows[0]?.lease_workflow_id;
+    });
+}
+/** Record the machine of a machine generation. */
+export function setMachine(pool, leaseWorkflowId, machine, machineGeneration) {
+    return tryMutation("sandboxLeases.setMachine", async () => {
+        await pool.query({
+            text: `UPDATE cortex_sandbox_leases SET machine = $2::jsonb, machine_generation = $3, last_used_at = now()
+                   WHERE lease_workflow_id = $1 AND state = 'granted'`,
+            values: [leaseWorkflowId, JSON.stringify(machine), machineGeneration],
+        });
+    });
+}
+/**
+ * Clear the machine of one machine generation, and give the machine that the row held. A row whose generation
+ * moved on keeps its machine, thus a late report of an old death clears nothing.
+ */
+export function clearMachine(pool, leaseWorkflowId, machineGeneration) {
+    return tryMutation("sandboxLeases.clearMachine", async () => {
+        const { rows } = await pool.query({
+            text: `WITH old AS (
+                       SELECT lease_workflow_id, machine FROM cortex_sandbox_leases
+                       WHERE lease_workflow_id = $1 AND machine_generation = $2 AND machine IS NOT NULL
+                       FOR UPDATE
+                   )
+                   UPDATE cortex_sandbox_leases AS l SET machine = NULL FROM old
+                   WHERE l.lease_workflow_id = old.lease_workflow_id
+                   RETURNING old.machine`,
+            values: [leaseWorkflowId, machineGeneration],
+        });
+        return rows.length === 0 ? undefined : PersistedSandboxRefSchema.parse(rows[0]?.machine);
+    });
+}
+/**
+ * Clear the machine of an idle lease: no exec used the lease for `idleMs`. An exec writes `last_used_at` before it
+ * submits, under the same row lock, thus an exec that starts can never lose its machine to this clear.
+ */
+export function clearIdleMachine(pool, leaseWorkflowId, machineGeneration, idleMs) {
+    return tryMutation("sandboxLeases.clearIdleMachine", async () => {
+        const { rows } = await pool.query({
+            text: `WITH old AS (
+                       SELECT lease_workflow_id, machine FROM cortex_sandbox_leases
+                       WHERE lease_workflow_id = $1 AND machine_generation = $2 AND machine IS NOT NULL
+                         AND last_used_at < now() - make_interval(secs => $3::double precision / 1000)
+                       FOR UPDATE
+                   )
+                   UPDATE cortex_sandbox_leases AS l SET machine = NULL FROM old
+                   WHERE l.lease_workflow_id = old.lease_workflow_id
+                   RETURNING old.machine`,
+            values: [leaseWorkflowId, machineGeneration, idleMs],
+        });
+        return rows.length === 0 ? undefined : PersistedSandboxRefSchema.parse(rows[0]?.machine);
+    });
+}
+/** Mark the lease used now, and give its machine. A lease that is not granted gives `undefined`. */
+export function touchLease(pool, leaseWorkflowId) {
+    return tryMutation("sandboxLeases.touch", async () => {
+        const { rows } = await pool.query({
+            text: `UPDATE cortex_sandbox_leases SET last_used_at = now()
+                   WHERE lease_workflow_id = $1 AND state = 'granted'
+                   RETURNING machine, machine_generation`,
+            values: [leaseWorkflowId],
+        });
+        if (rows.length === 0)
+            return undefined;
+        const row = z.object({ machine: PersistedSandboxRefSchema.nullable(), machine_generation: z.number() }).parse(rows[0]);
+        return { machine: row.machine ?? undefined, machineGeneration: row.machine_generation };
+    });
+}
+/** Mark the lease released, and give the machine that it still held. A second release gives `undefined`. */
+export function releaseLease(pool, leaseWorkflowId, reason) {
+    return tryMutation("sandboxLeases.release", async () => {
+        const { rows } = await pool.query({
+            text: `WITH old AS (
+                       SELECT lease_workflow_id, machine FROM cortex_sandbox_leases
+                       WHERE lease_workflow_id = $1 AND state <> 'released'
+                       FOR UPDATE
+                   )
+                   UPDATE cortex_sandbox_leases AS l SET state = 'released', release_reason = $2, released_at = now(), machine = NULL
+                   FROM old WHERE l.lease_workflow_id = old.lease_workflow_id
+                   RETURNING old.machine`,
+            values: [leaseWorkflowId, reason],
+        });
+        if (rows.length === 0)
+            return undefined;
+        const machine = PersistedSandboxRefSchema.nullable().parse(rows[0]?.machine);
+        return { machine: machine ?? undefined };
+    });
+}
+/** Each lease of the given owner workflows that is not released. */
+export function leasesOwnedBy(pool, ownerWorkflowIds) {
+    return tryQuery("sandboxLeases.ownedBy", async () => {
+        const { rows } = await pool.query({
+            text: `SELECT ${COLUMNS} FROM cortex_sandbox_leases WHERE owner_workflow_id = ANY($1::text[]) AND state <> 'released'`,
+            values: [[...ownerWorkflowIds]],
+        });
+        return rows.map(recordOf);
+    });
+}
+/** Each lease that is not released, for the sweep of the reconciler. */
+export function openLeases(pool) {
+    return tryQuery("sandboxLeases.open", async () => {
+        const { rows } = await pool.query(`SELECT ${COLUMNS} FROM cortex_sandbox_leases WHERE state <> 'released'`);
+        return rows.map(recordOf);
+    });
+}

package/dist/state/schema.d.ts

@@ -99,10 +99,7 @@ export declare const CortexRunRowSchema: z.ZodObject<{
     planId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type CortexRunRow = z.infer<typeof CortexRunRowSchema>;
-/**
- * Persistable sandbox handle — what the active-sandbox registry stores on
- * `cortex_step_executions.sandbox_ref`.
- */
+/** Persistable sandbox handle — the machine that a lease row of `cortex_sandbox_leases` holds. */
 export declare const PersistedSandboxRefSchema: z.ZodObject<{
     sandboxId: z.ZodString;
     host: z.ZodString;
@@ -137,15 +134,6 @@ export declare const StepExecutionRowSchema: z.ZodObject<{
     finishReason: z.ZodNullable<z.ZodString>;
     hitMaxSteps: z.ZodDefault<z.ZodBoolean>;
     blockedReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-    sandboxRef: z.ZodDefault<z.ZodNullable<z.ZodObject<{
-        sandboxId: z.ZodString;
-        host: z.ZodString;
-        port: z.ZodNumber;
-        backend: z.ZodEnum<{
-            docker: "docker";
-            k8s: "k8s";
-        }>;
-    }, z.core.$strip>>>;
     childWorkflowId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type StepExecutionRow = z.infer<typeof StepExecutionRowSchema>;

package/dist/state/schema.js

@@ -57,10 +57,7 @@ export const CortexRunRowSchema = z.object({
     mandateId: z.string().nullable(), // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
     planId: z.string().nullable(),
 });
-/**
- * Persistable sandbox handle — what the active-sandbox registry stores on
- * `cortex_step_executions.sandbox_ref`.
- */
+/** Persistable sandbox handle — the machine that a lease row of `cortex_sandbox_leases` holds. */
 export const PersistedSandboxRefSchema = z.object({
     sandboxId: z.string(),
     host: z.string(),
@@ -88,8 +85,6 @@ export const StepExecutionRowSchema = z.object({
     hitMaxSteps: z.boolean().default(false),
     /** Agent-declared blocker reason (see the harness-sandbox-agents spec); null unless `status === "blocked"`. */
     blockedReason: z.string().nullable().default(null),
-    /** Active-sandbox registry handle; null when no sandbox is live for this step. */
-    sandboxRef: PersistedSandboxRefSchema.nullable().default(null),
     /** DBOS child workflow id (`"${parentWorkflowId}-${N}"`); null on pre-DBOS rows. */
     childWorkflowId: z.string().nullable().default(null),
 });

package/dist/state/step-executions.d.ts

@@ -1,7 +1,5 @@
 /**
  * `cortex_step_executions` operations — step lifecycle and retry telemetry.
- * The `sandbox_ref` column is read/written by the sibling `active-sandboxes`
- * module.
  */
 import type { ResultAsync } from "neverthrow";
 import type { QueryConfig } from "pg";