@inflexa-ai/harness 0.37.0 → 0.39.0

package/dist/sandbox/docker-client.d.ts

@@ -40,10 +40,11 @@
  */
 import Docker from "dockerode";
 import { ResultAsync } from "neverthrow";
+import type { SpawnSession } from "../auth/types.js";
 import type { Logger } from "../lib/logger.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type SandboxError } from "./sandbox-error.js";
-import type { CreateSandboxMeta, FarmSource, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport, ToolchainSource } from "./types.js";
+import type { FarmSource, ManagedSandbox, SandboxIdentity, SandboxLabels, SandboxLiveness, SandboxRef, SandboxSpec, SandboxTransport, ToolchainSource } from "./types.js";
 export interface DockerClientConfig {
     image: string;
     /** Cortex base URL injected into the sandbox env in callback mode so callbacks land here. Unused in poll mode. */
@@ -112,7 +113,7 @@ export interface DockerClientConfig {
      */
     logger?: Logger;
     /** Hook called after the registry row is written. */
-    registerSandbox: (meta: CreateSandboxMeta, ref: SandboxRef) => Promise<void>;
+    registerSandbox: (session: SpawnSession, spec: SandboxSpec, ref: SandboxRef) => Promise<void>;
 }
 /**
  * dockerode connection options for a configured engine socket, or `undefined`
@@ -123,7 +124,7 @@ export interface DockerClientConfig {
  */
 export declare function engineConnectionOptions(engineSocketPath: string | undefined): Docker.DockerOptions | undefined;
 export declare function createDockerSandboxOps(config: DockerClientConfig): {
-    createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
+    createSandbox(session: SpawnSession, spec: SandboxSpec, identity: SandboxIdentity, hostLabels: SandboxLabels): ResultAsync<SandboxRef, SandboxError>;
     teardown(ref: SandboxRef): ResultAsync<void, SandboxError>;
     teardownById(sandboxId: string): ResultAsync<void, SandboxError>;
     isAlive(ref: SandboxRef): ResultAsync<SandboxLiveness, SandboxError>;

package/dist/sandbox/docker-client.js

@@ -47,7 +47,8 @@ import { createNoopLogger } from "../lib/console-logger.js";
 import { tailWritePrefix } from "../workspace/paths.js";
 import { trySandbox } from "./sandbox-error.js";
 import { readFarmLock, resolveFarmSource } from "./farm.js";
-import { buildMountPlan, sandboxWriteTail } from "./mount-plan.js";
+import { harnessLabels, MANAGED_BY_LABEL, MANAGED_BY_VALUE, mergeLabels, OWNER_WORKFLOW_KEY, SANDBOX_ID_LABEL } from "./labels.js";
+import { buildMountPlan, mountCoordsOf, sandboxWriteTail } from "./mount-plan.js";
 import { CPU_ONLINE_PATH, CPUINFO_PATH, cpuFiles, readHostCpuinfoOnce } from "./cpu-files.js";
 import { threadLimitEnv } from "./thread-env.js";
 /** Read the originating HTTP status off any `SandboxError` variant that carries one. */
@@ -69,11 +70,7 @@ const SANDBOX_USER = "1000:1000";
  */
 const SANDBOX_ROOT_USER = "0:0";
 const HEALTH_POLL_MS = 250;
-const MANAGED_BY_LABEL = "app.kubernetes.io/managed-by";
-const MANAGED_BY_VALUE = "cortex";
-const OWNER_WORKFLOW_LABEL = "cortex/owner-workflow-id";
-const RUN_ID_LABEL = "cortex/run-id";
-const STEP_ID_LABEL = "cortex/step-id";
+const OWNER_WORKFLOW_LABEL = OWNER_WORKFLOW_KEY;
 /** The directory next to the workspace root that holds the cpu files of each sandbox. */
 const CPU_FILES_DIR = ".cpu";
 /**
@@ -232,15 +229,17 @@ export function createDockerSandboxOps(config) {
     /** The cpu directory of each sandbox that this process wrote, for `teardown`. */
     const cpuDirs = new Map();
     return {
-        createSandbox(meta, identity) {
+        createSandbox(session, spec, identity, hostLabels) {
             return new ResultAsync((async () => {
                 const { sandboxId, callbackSecret } = identity;
+                const analysisId = session.scope.analysisId;
+                const coords = mountCoordsOf(session, spec);
                 // Farm resolution comes before any container work: a resolver
                 // refusal and a resolver throw refuse the whole call, and no
                 // container is made. The reason of the embedder rides in the error.
                 let farm;
                 if (config.libStorePath) {
-                    const resolved = await resolveFarmSource(config.farmSource, meta.analysisId, "docker.createSandbox");
+                    const resolved = await resolveFarmSource(config.farmSource, analysisId, "docker.createSandbox");
                     if (resolved.isErr())
                         return err(resolved.error);
                     farm = resolved.value;
@@ -262,7 +261,7 @@ export function createDockerSandboxOps(config) {
                         return err({
                             type: "farm_unusable",
                             op: "docker.createSandbox",
-                            analysisId: meta.analysisId,
+                            analysisId,
                             farmPath: farm.farmPath,
                             lockPath: lock.error.lockPath,
                             lockError: lock.error.type,
@@ -292,20 +291,20 @@ export function createDockerSandboxOps(config) {
                 // not installed reference data yet — and warning on every create would be
                 // noise. A store that appears mid-session is picked up by the next create.
                 const refsMounted = !!config.refStorePath && refStoreUsable(config.refStorePath);
-                const plan = buildMountPlan(meta, {
+                const plan = buildMountPlan(coords, {
                     libs: libsMounted,
                     refs: refsMounted,
                     toolchainSource: config.toolchainSource,
                     cache: cacheBindable,
                 });
-                const hostTreePath = config.resolveWorkspaceRoot(meta.analysisId);
+                const hostTreePath = config.resolveWorkspaceRoot(analysisId);
                 // `tailWritePrefix` (not a raw `join`) so the RW bind source runs through
                 // the same validation as the pre-created write tree — a crafted stepId or
                 // a crafted tail cannot escape the resolved root into the container. The
                 // tail is the step directory, or the one the caller declared.
-                const write = sandboxWriteTail(meta);
+                const write = sandboxWriteTail(coords);
                 // The same floor as `threadLimitEnv`: a fractional cpu request is one cpu.
-                const threads = Math.max(1, Math.floor(meta.resources.cpu));
+                const threads = Math.max(1, Math.floor(spec.resources.cpu));
                 const cpuinfo = await readHostCpuinfo();
                 if (cpuinfo === undefined) {
                     logger.debug("no host /proc/cpuinfo — the sandbox gets the online file only", { sandboxId });
@@ -336,8 +335,8 @@ export function createDockerSandboxOps(config) {
                     status,
                     cause,
                 });
-                const image = meta.image ?? config.image;
-                const spec = meta.resources;
+                const image = spec.image ?? config.image;
+                const limits = spec.resources;
                 // Poll mode never dials out and carries no CORTEX_BASE_URL; it sets the
                 // firewall flag so the root entrypoint installs the egress block before
                 // dropping to uid 1000. Callback mode is the inverse.
@@ -349,9 +348,9 @@ export function createDockerSandboxOps(config) {
                     SANDBOX_TRANSPORT: transport,
                     SANDBOX_CALLBACK_SECRET: callbackSecret,
                     ...(pollMode ? { SANDBOX_EGRESS_FIREWALL: "1" } : { CORTEX_BASE_URL: config.cortexBaseUrl }),
-                    ...threadLimitEnv(spec),
+                    ...threadLimitEnv(limits),
                     ...plan.env,
-                    ...(meta.extraEnv ?? {}),
+                    ...(spec.extraEnv ?? {}),
                 }).map(([k, v]) => `${k}=${v}`);
                 const createOpts = {
                     name: sandboxId,
@@ -360,14 +359,7 @@ export function createDockerSandboxOps(config) {
                     Env: env,
                     User: pollMode ? SANDBOX_ROOT_USER : SANDBOX_USER,
                     WorkingDir: plan.workingDir,
-                    Labels: {
-                        [MANAGED_BY_LABEL]: MANAGED_BY_VALUE,
-                        [OWNER_WORKFLOW_LABEL]: meta.childWorkflowId,
-                        [RUN_ID_LABEL]: meta.runId,
-                        [STEP_ID_LABEL]: meta.stepId,
-                        role: "sandbox",
-                        "cortex/sandbox-id": sandboxId,
-                    },
+                    Labels: mergeLabels(hostLabels, { ...harnessLabels(session, sandboxId), [OWNER_WORKFLOW_LABEL]: spec.childWorkflowId }),
                     ExposedPorts: { [`${SANDBOX_SERVER_PORT}/tcp`]: {} },
                     HostConfig: {
                         Binds: binds,
@@ -385,17 +377,17 @@ export function createDockerSandboxOps(config) {
                         // — and `no-new-privileges` prevents regaining any.
                         ...(pollMode ? { CapAdd: ["NET_ADMIN", "SETUID", "SETGID", "SETPCAP"] } : {}),
                         SecurityOpt: ["no-new-privileges"],
-                        NanoCpus: Math.round(spec.cpu * 1e9),
-                        Memory: spec.memoryGb * 1024 ** 3,
+                        NanoCpus: Math.round(limits.cpu * 1e9),
+                        Memory: limits.memoryGb * 1024 ** 3,
                         // `Memory` alone lets the container swap as much again. A fork
                         // storm then thrashes for minutes, and sandbox-server stops to
                         // answer. With no swap the OOM killer removes the largest fork in
                         // seconds, and sandbox-server survives. K8s runs with no swap.
-                        MemorySwap: spec.memoryGb * 1024 ** 3,
+                        MemorySwap: limits.memoryGb * 1024 ** 3,
                         AutoRemove: false,
                     },
                 };
-                const sandbox = await createOrAdopt(docker, createOpts, sandboxId, meta.childWorkflowId, createFailed, logger);
+                const sandbox = await createOrAdopt(docker, createOpts, sandboxId, spec.childWorkflowId, createFailed, logger);
                 if (sandbox.isErr())
                     return err(sandbox.error);
                 if (!sandbox.value.alreadyRunning) {
@@ -425,7 +417,7 @@ export function createDockerSandboxOps(config) {
                     backend: "docker",
                     callbackSecret,
                 };
-                const registered = await trySandbox(() => config.registerSandbox(meta, ref), createFailed);
+                const registered = await trySandbox(() => config.registerSandbox(session, spec, ref), createFailed);
                 if (registered.isErr())
                     return err(registered.error);
                 return ok(ref);
@@ -450,7 +442,7 @@ export function createDockerSandboxOps(config) {
                 .map((c) => {
                 const labels = c.Labels ?? {};
                 return {
-                    sandboxId: labels["cortex/sandbox-id"] ?? "",
+                    sandboxId: labels[SANDBOX_ID_LABEL] ?? "",
                     // Docker label values are unconstrained, so the id is stored verbatim.
                     ownerWorkflowId: labels[OWNER_WORKFLOW_LABEL] ?? null,
                     // Docker reports `Created` as unix seconds.

package/dist/sandbox/k8s-client.d.ts

@@ -16,18 +16,9 @@ import { BatchV1Api, CoreV1Api, type V1Toleration } from "@kubernetes/client-nod
 import { ResultAsync } from "neverthrow";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type SandboxError } from "./sandbox-error.js";
-import type { CreateSandboxMeta, FarmSource, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport, ToolchainSource } from "./types.js";
+import type { SpawnSession } from "../auth/types.js";
+import type { FarmSource, ManagedSandbox, SandboxIdentity, SandboxLabels, SandboxLiveness, SandboxRef, SandboxSpec, SandboxTransport, ToolchainSource } from "./types.js";
 import type { Logger } from "../lib/logger.js";
-/**
- * Coerce an arbitrary identifier into a valid K8s label value:
- * ≤63 chars, `[A-Za-z0-9._-]` only, starting and ending alphanumeric.
- * Without it one malformed value gets the whole Job rejected at admission.
- *
- * Lossy by construction: `:` becomes `-` and anything past 63 chars is dropped,
- * neither of which is recoverable. No label value may therefore be used as a
- * lookup key — see {@link OWNER_WORKFLOW_ANNOTATION}.
- */
-export declare function sanitizeLabelValue(value: string): string;
 export interface K8sClientConfig {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
@@ -93,7 +84,7 @@ export interface K8sClientConfig {
     /** Injected for tests. */
     batchApi?: BatchV1Api;
     coreApi?: CoreV1Api;
-    registerSandbox: (meta: CreateSandboxMeta, ref: SandboxRef) => Promise<void>;
+    registerSandbox: (session: SpawnSession, spec: SandboxSpec, ref: SandboxRef) => Promise<void>;
 }
 /** Clock and sleep seams, so a test can drive the slow-pod warning without waiting a minute. */
 export interface WaitForPodReadyDeps {
@@ -106,7 +97,7 @@ export declare function waitForPodReady(coreApi: CoreV1Api, namespace: string, s
     podName: string;
 }, SandboxError>;
 export declare function createK8sSandboxOps(config: K8sClientConfig): {
-    createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
+    createSandbox(session: SpawnSession, spec: SandboxSpec, identity: SandboxIdentity, hostLabels: SandboxLabels): ResultAsync<SandboxRef, SandboxError>;
     teardown(ref: SandboxRef): ResultAsync<void, SandboxError>;
     teardownById(sandboxId: string): ResultAsync<void, SandboxError>;
     isAlive(ref: SandboxRef): ResultAsync<SandboxLiveness, SandboxError>;

package/dist/sandbox/k8s-client.js

@@ -17,7 +17,8 @@ import { BatchV1Api, CoreV1Api, KubeConfig, } from "@kubernetes/client-node";
 import { ResultAsync, err, ok } from "neverthrow";
 import { trySandbox } from "./sandbox-error.js";
 import { readFarmLock, resolveFarmSource } from "./farm.js";
-import { buildMountPlan, buildSessionSubPaths } from "./mount-plan.js";
+import { harnessLabels, MANAGED_BY_LABEL, MANAGED_BY_VALUE, mergeLabels, OWNER_WORKFLOW_KEY, SANDBOX_ID_LABEL } from "./labels.js";
+import { buildMountPlan, buildSessionSubPaths, mountCoordsOf } from "./mount-plan.js";
 import { threadLimitEnv } from "./thread-env.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 /** Read the originating HTTP status off any `SandboxError` variant that carries one. */
@@ -37,34 +38,14 @@ const POD_POLL_INTERVAL_MS = 1_000;
  * and the run pays that minute before any command executes.
  */
 const POD_READY_SLOW_MS = 60_000;
-const MANAGED_BY_LABEL = "app.kubernetes.io/managed-by";
-const MANAGED_BY_VALUE = "cortex";
 /**
  * Annotation key of the owning DBOS workflow id. An annotation value has neither
  * a length cap nor a charset restriction, so the id round-trips verbatim and can
  * be handed back to `DBOS.getWorkflowStatus`. Deliberately not a label: nothing
- * selects on it, and a label value could not hold it (see {@link sanitizeLabelValue}).
+ * selects on it, and a DBOS workflow id can be longer than 63 characters and can
+ * hold `:`, thus it is not a valid label value.
  */
-const OWNER_WORKFLOW_ANNOTATION = "cortex/owner-workflow-id";
-const RUN_ID_LABEL = "cortex/run-id";
-const STEP_ID_LABEL = "cortex/step-id";
-const ANALYSIS_ID_LABEL = "cortex/analysis-id";
-/**
- * Coerce an arbitrary identifier into a valid K8s label value:
- * ≤63 chars, `[A-Za-z0-9._-]` only, starting and ending alphanumeric.
- * Without it one malformed value gets the whole Job rejected at admission.
- *
- * Lossy by construction: `:` becomes `-` and anything past 63 chars is dropped,
- * neither of which is recoverable. No label value may therefore be used as a
- * lookup key — see {@link OWNER_WORKFLOW_ANNOTATION}.
- */
-export function sanitizeLabelValue(value) {
-    return value
-        .replace(/[^A-Za-z0-9._-]/g, "-")
-        .replace(/^[^A-Za-z0-9]+/, "")
-        .slice(0, 63)
-        .replace(/[^A-Za-z0-9]+$/, "");
-}
+const OWNER_WORKFLOW_ANNOTATION = OWNER_WORKFLOW_KEY;
 /** The owner workflow id recorded on a Job, or null if it records none. */
 function readOwnerWorkflowId(metadata) {
     return metadata?.annotations?.[OWNER_WORKFLOW_ANNOTATION] ?? null;
@@ -129,21 +110,22 @@ function pvcSubPath(value, what) {
     }
     return value;
 }
-function buildJobSpec(meta, config, identity, farm, libsMounted) {
+function buildJobSpec(session, sandboxSpec, hostLabels, config, identity, farm, libsMounted) {
     const { sandboxId } = identity;
     // The lock gate of the package-store spec: `farmPath` is PVC-relative,
     // thus this host can prove the lock only through `libStorePvcRoot`. The
     // caller runs that proof and hands the verdict in `libsMounted`. Without
     // the root, the proof duty stays whole on the farm resolver — see
     // {@link ResolveAnalysisFarm}.
-    const plan = buildMountPlan(meta, {
+    const coords = mountCoordsOf(session, sandboxSpec);
+    const plan = buildMountPlan(coords, {
         libs: libsMounted,
         refs: !!config.refStorePvc,
         toolchainSource: config.toolchainSource,
         cache: libsMounted && farm?.cachePath !== undefined,
     });
     const transport = config.transport ?? "poll";
-    const spec = meta.resources;
+    const spec = sandboxSpec.resources;
     // Composed as one record, not as a list of `{name, value}`. A duplicate name
     // in the env of a container resolves at the kubelet, thus the later spread
     // must win here, not there.
@@ -156,7 +138,7 @@ function buildJobSpec(meta, config, identity, farm, libsMounted) {
         SANDBOX_CALLBACK_SECRET: identity.callbackSecret,
         ...threadLimitEnv(spec),
         ...plan.env,
-        ...(meta.extraEnv ?? {}),
+        ...(sandboxSpec.extraEnv ?? {}),
     }).map(([name, value]) => ({ name, value }));
     // requests == limits → Guaranteed QoS and a predictable OOM bound; also
     // satisfies the namespace ResourceQuota, which rejects any pod that omits
@@ -172,7 +154,7 @@ function buildJobSpec(meta, config, identity, farm, libsMounted) {
     const volumes = [];
     const volumeMounts = [];
     if (config.sessionPvc) {
-        const subPaths = buildSessionSubPaths(meta, workspaceSubPathFor(config, meta.analysisId));
+        const subPaths = buildSessionSubPaths(coords, workspaceSubPathFor(config, session.scope.analysisId));
         volumes.push({
             name: SESSION_VOLUME_NAME,
             persistentVolumeClaim: { claimName: config.sessionPvc },
@@ -244,7 +226,7 @@ function buildJobSpec(meta, config, identity, farm, libsMounted) {
         containers: [
             {
                 name: "sandbox",
-                image: meta.image ?? config.image,
+                image: sandboxSpec.image ?? config.image,
                 imagePullPolicy: "IfNotPresent",
                 env,
                 resources,
@@ -277,14 +259,8 @@ function buildJobSpec(meta, config, identity, farm, libsMounted) {
     if (config.runtimeClassName)
         podSpec.runtimeClassName = config.runtimeClassName;
     // Pod-template placement is load-bearing: a cost reconciler allocates by pod
-    // labels, thus a Job-only label is invisible to it. The host labels stay
-    // opaque — every value passes through `sanitizeLabelValue`, because one
-    // malformed value makes the API server reject the whole Job at admission.
-    const attributionLabels = {
-        [ANALYSIS_ID_LABEL]: sanitizeLabelValue(meta.analysisId),
-        [RUN_ID_LABEL]: sanitizeLabelValue(meta.runId),
-        ...Object.fromEntries(Object.entries(meta.podLabels ?? {}).map(([key, value]) => [key, sanitizeLabelValue(value)])),
-    };
+    // labels, thus a Job-only label is invisible to it.
+    const labels = mergeLabels(hostLabels, harnessLabels(session, sandboxId));
     return {
         apiVersion: "batch/v1",
         kind: "Job",
@@ -292,26 +268,16 @@ function buildJobSpec(meta, config, identity, farm, libsMounted) {
             name: sandboxId,
             namespace: config.namespace,
             annotations: {
-                [OWNER_WORKFLOW_ANNOTATION]: meta.childWorkflowId,
-            },
-            labels: {
-                [MANAGED_BY_LABEL]: MANAGED_BY_VALUE,
-                role: "sandbox",
-                "cortex/sandbox-id": sandboxId,
-                [STEP_ID_LABEL]: sanitizeLabelValue(meta.stepId),
-                ...attributionLabels,
+                [OWNER_WORKFLOW_ANNOTATION]: sandboxSpec.childWorkflowId,
             },
+            labels,
         },
         spec: {
             backoffLimit: 0,
             ttlSecondsAfterFinished: 60,
             template: {
                 metadata: {
-                    labels: {
-                        role: "sandbox",
-                        "cortex/sandbox-id": sandboxId,
-                        ...attributionLabels,
-                    },
+                    labels,
                 },
                 spec: podSpec,
             },
@@ -345,7 +311,7 @@ export function waitForPodReady(coreApi, namespace, sandboxId, deps = {}) {
         while (now() < deadline) {
             const listed = await trySandbox(() => coreApi.listNamespacedPod({
                 namespace,
-                labelSelector: `cortex/sandbox-id=${sandboxId}`,
+                labelSelector: `${SANDBOX_ID_LABEL}=${sandboxId}`,
             }), createFailed);
             if (listed.isErr())
                 return err(listed.error);
@@ -386,7 +352,7 @@ export function waitForPodReady(coreApi, namespace, sandboxId, deps = {}) {
 function existingPodIsTerminal(coreApi, namespace, sandboxId) {
     return trySandbox(() => coreApi.listNamespacedPod({
         namespace,
-        labelSelector: `cortex/sandbox-id=${sandboxId}`,
+        labelSelector: `${SANDBOX_ID_LABEL}=${sandboxId}`,
     }), (status, cause) => ({
         type: "container_create_failed",
         op: "k8s.existingPodIsTerminal",
@@ -484,15 +450,16 @@ function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflow
 export function createK8sSandboxOps(config) {
     const { batchApi, coreApi } = config.batchApi && config.coreApi ? { batchApi: config.batchApi, coreApi: config.coreApi } : buildKubeApi();
     return {
-        createSandbox(meta, identity) {
+        createSandbox(session, spec, identity, hostLabels) {
             return new ResultAsync((async () => {
                 const { sandboxId } = identity;
+                const analysisId = session.scope.analysisId;
                 // Farm resolution comes before any cluster work: a resolver
                 // refusal and a resolver throw refuse the whole call, and no
                 // Job is made.
                 let farm;
                 if (config.libStorePvc) {
-                    const resolved = await resolveFarmSource(config.farmSource, meta.analysisId, "k8s.createSandbox");
+                    const resolved = await resolveFarmSource(config.farmSource, analysisId, "k8s.createSandbox");
                     if (resolved.isErr())
                         return err(resolved.error);
                     farm = resolved.value;
@@ -517,7 +484,7 @@ export function createK8sSandboxOps(config) {
                         return err({
                             type: "farm_unusable",
                             op: "k8s.createSandbox",
-                            analysisId: meta.analysisId,
+                            analysisId,
                             farmPath: farm.farmPath,
                             lockPath: lock.error.lockPath,
                             lockError: lock.error.type,
@@ -530,8 +497,8 @@ export function createK8sSandboxOps(config) {
                             .warn("the farm of the analysis has no usable inflexa.lock at sandbox creation — mounting no package store (sandbox degrades to available:false)", { libStorePvc: config.libStorePvc, farmPath: farm.farmPath, lockError: lock.error.type, sandboxId });
                     }
                 }
-                const job = buildJobSpec(meta, config, identity, farm, libsMounted);
-                const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, meta.childWorkflowId, job);
+                const job = buildJobSpec(session, spec, hostLabels, config, identity, farm, libsMounted);
+                const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, spec.childWorkflowId, job);
                 if (adopted.isErr())
                     return err(adopted.error);
                 // A Job whose pod never schedules (quota rejection, no nodes, spot
@@ -549,7 +516,7 @@ export function createK8sSandboxOps(config) {
                         backend: "k8s",
                         callbackSecret: identity.callbackSecret,
                     };
-                    const registered = await trySandbox(() => config.registerSandbox(meta, ref), (status, cause) => ({
+                    const registered = await trySandbox(() => config.registerSandbox(session, spec, ref), (status, cause) => ({
                         type: "container_create_failed",
                         op: "k8s.registerSandbox",
                         sandboxId,
@@ -586,7 +553,7 @@ export function createK8sSandboxOps(config) {
                 const labels = j.metadata?.labels ?? {};
                 const ts = j.metadata?.creationTimestamp;
                 return {
-                    sandboxId: labels["cortex/sandbox-id"] ?? j.metadata?.name ?? "",
+                    sandboxId: labels[SANDBOX_ID_LABEL] ?? j.metadata?.name ?? "",
                     ownerWorkflowId: readOwnerWorkflowId(j.metadata),
                     createdAtMs: ts ? new Date(ts).getTime() : null,
                 };
@@ -601,7 +568,7 @@ export function createK8sSandboxOps(config) {
     function isAliveById(sandboxId) {
         return trySandbox(() => coreApi.listNamespacedPod({
             namespace: config.namespace,
-            labelSelector: `cortex/sandbox-id=${sandboxId}`,
+            labelSelector: `${SANDBOX_ID_LABEL}=${sandboxId}`,
         }), (status, cause) => ({
             type: "liveness_failed",
             op: "k8s.isAlive",

package/dist/sandbox/labels.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The labels of a sandbox, the same on the Docker backend and on the K8s
+ * backend (sandbox-labels spec).
+ *
+ * Each harness value is a valid K8s label value by construction. A run id is a
+ * UUID or a short literal of the harness, a step id obeys the step-id rule of
+ * the plan validator, and the harness makes the sandbox id. The analysis id
+ * comes from the host, thus on K8s the host must give one that is a valid
+ * label value.
+ *
+ * The host labels merge first and the harness labels last, thus a harness key
+ * wins a clash. The harness stamps each host value as the host gives it and
+ * changes no value: a host reconciler uses a label value as a lookup key, and
+ * a changed value cannot find its record. On K8s the API server does a check of
+ * each value at admission, and it is the authority.
+ */
+import type { SpawnSession } from "../auth/types.js";
+import type { SandboxLabels } from "./types.js";
+export declare const MANAGED_BY_LABEL = "app.kubernetes.io/managed-by";
+export declare const MANAGED_BY_VALUE = "cortex";
+export declare const SANDBOX_ID_LABEL = "cortex/sandbox-id";
+export declare const ANALYSIS_ID_LABEL = "cortex/analysis-id";
+export declare const RUN_ID_LABEL = "cortex/run-id";
+export declare const STEP_ID_LABEL = "cortex/step-id";
+/**
+ * A Docker label value has no limit, thus Docker keeps the owner workflow id as
+ * a label. A DBOS workflow id can be longer than 63 characters and can hold
+ * `:`, thus K8s keeps it as a Job annotation.
+ */
+export declare const OWNER_WORKFLOW_KEY = "cortex/owner-workflow-id";
+/** The harness never applies it to a host value. */
+export declare function isLabelValue(value: string): boolean;
+export declare function harnessLabels(session: SpawnSession, sandboxId: string): Record<string, string>;
+export declare function mergeLabels(hostLabels: SandboxLabels, harness: Readonly<Record<string, string>>): Record<string, string>;

package/dist/sandbox/labels.js

@@ -0,0 +1,47 @@
+/**
+ * The labels of a sandbox, the same on the Docker backend and on the K8s
+ * backend (sandbox-labels spec).
+ *
+ * Each harness value is a valid K8s label value by construction. A run id is a
+ * UUID or a short literal of the harness, a step id obeys the step-id rule of
+ * the plan validator, and the harness makes the sandbox id. The analysis id
+ * comes from the host, thus on K8s the host must give one that is a valid
+ * label value.
+ *
+ * The host labels merge first and the harness labels last, thus a harness key
+ * wins a clash. The harness stamps each host value as the host gives it and
+ * changes no value: a host reconciler uses a label value as a lookup key, and
+ * a changed value cannot find its record. On K8s the API server does a check of
+ * each value at admission, and it is the authority.
+ */
+export const MANAGED_BY_LABEL = "app.kubernetes.io/managed-by";
+export const MANAGED_BY_VALUE = "cortex";
+export const SANDBOX_ID_LABEL = "cortex/sandbox-id";
+export const ANALYSIS_ID_LABEL = "cortex/analysis-id";
+export const RUN_ID_LABEL = "cortex/run-id";
+export const STEP_ID_LABEL = "cortex/step-id";
+/**
+ * A Docker label value has no limit, thus Docker keeps the owner workflow id as
+ * a label. A DBOS workflow id can be longer than 63 characters and can hold
+ * `:`, thus K8s keeps it as a Job annotation.
+ */
+export const OWNER_WORKFLOW_KEY = "cortex/owner-workflow-id";
+/** A valid K8s label value: 1 to 63 characters, `[A-Za-z0-9._-]` only, a letter or a digit at each end. */
+const LABEL_VALUE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,61}[A-Za-z0-9])?$/;
+/** The harness never applies it to a host value. */
+export function isLabelValue(value) {
+    return LABEL_VALUE.test(value);
+}
+export function harnessLabels(session, sandboxId) {
+    return {
+        [MANAGED_BY_LABEL]: MANAGED_BY_VALUE,
+        role: "sandbox",
+        [SANDBOX_ID_LABEL]: sandboxId,
+        [ANALYSIS_ID_LABEL]: session.scope.analysisId,
+        [RUN_ID_LABEL]: session.runFrame.runId,
+        [STEP_ID_LABEL]: session.runFrame.stepId,
+    };
+}
+export function mergeLabels(hostLabels, harness) {
+    return { ...hostLabels, ...harness };
+}

package/dist/sandbox/mount-plan.d.ts

@@ -27,7 +27,8 @@
  * resolved root directly, K8s addresses it as a `subPath` into the session PVC
  * (see {@link buildSessionSubPaths}).
  */
-import type { ToolchainSource } from "./types.js";
+import type { SpawnSession } from "../auth/types.js";
+import type { SandboxSpec, ToolchainSource } from "./types.js";
 export declare const STEP_SUBDIRS: readonly ["output", "scripts", "figures", "logs", "notebooks"];
 /**
  * Container mountpoints of the two read-only stores. Exported because they are
@@ -64,6 +65,7 @@ export interface MountPlanCoords {
      */
     writableTail?: string;
 }
+export declare function mountCoordsOf(session: SpawnSession, spec: Pick<SandboxSpec, "readOnly" | "writableTail">): MountPlanCoords;
 export interface MountPlanStores {
     /** Lib store is mounted at `/mnt/libs`, with the farm nested inside it, and its env is emitted. */
     libs: boolean;

package/dist/sandbox/mount-plan.js

@@ -47,6 +47,15 @@ export const FARM_CACHE_CONTAINER_PATH = "/mnt/libs/cache";
 export function farmContainerPath(toolchainSource) {
     return toolchainSource === "image" ? `${LIBS_CONTAINER_PATH}/farm` : `${LIBS_CONTAINER_PATH}/current`;
 }
+export function mountCoordsOf(session, spec) {
+    return {
+        analysisId: session.scope.analysisId,
+        runId: session.runFrame.runId,
+        stepId: session.runFrame.stepId,
+        ...(spec.readOnly !== undefined ? { readOnly: spec.readOnly } : {}),
+        ...(spec.writableTail !== undefined ? { writableTail: spec.writableTail } : {}),
+    };
+}
 /**
  * The step tail beneath an analysis's workspace root, in both container and
  * PVC-relative space. The harness owns this layout (workspace-layout spec).

package/dist/sandbox/sandbox-error.d.ts

@@ -25,21 +25,21 @@
  *    propagate untouched. `await-exec.ts` is NOT converted; `trySandbox` only
  *    ever wraps the single SDK/HTTP call handed to it.
  *
- * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
- * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
- * seam throws the described failure with the variant on `.cause` and on
- * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
- * exception — it is already its own DBOS step and throws directly, so the seam
- * forwards its `Promise<void>` as-is.)
- * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
- * `DBOS.runStep`, so the re-thrown error records the step as failed;
- * non-workflow consumers (`reaper`, `watchdog`,
- * `data-profile`, `run-exec`) already handle a thrown failure. They are
- * untouched by this wave.
+ * `createSandbox` of the public `SandboxClient` gives each `SandboxError` as
+ * an `err` value, because a refusal of the label hook must reach the spawn path
+ * as a value. A spawn path splits the result with `keepSuspendingRefusal`: a
+ * refusal with the suspend flag stays a value, and each other failure throws
+ * as a `SandboxFailure`.
+ * Each other op keeps a `Promise<T>` signature. `create-sandbox.ts` is the
+ * composition seam: it builds the backend ops, maps each `err` of such an op to
+ * a `SandboxFailure`, and `unwrapOrThrow`s it, so the seam throws the described
+ * failure with the variant on `.cause` and on `.error`. A `catch` never sees
+ * the raw variant. (`submitExec` is the exception — it is already its own DBOS
+ * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
  */
-import { ResultAsync } from "neverthrow";
+import { ResultAsync, type Result } from "neverthrow";
 import type { FarmLockError } from "./farm.js";
+import type { SandboxRef } from "./types.js";
 /**
  * A sandbox backend failure. Absence / idempotent "already gone" is NOT
  * modelled — those ride the OK channel (`ok(false)` for a dead/missing machine,
@@ -82,6 +82,18 @@ export type SandboxError = {
     readonly sandboxId?: string;
     readonly status?: number;
     readonly cause: unknown;
+} | {
+    /**
+     * The label hook of the host refused the spawn. The client made no
+     * step tree and called no backend. `reason` is the text of the host,
+     * and `suspend` asks the caller to suspend the work in place of a
+     * failure (see `lib/hooks.ts`).
+     */
+    readonly type: "labels_refused";
+    readonly op: string;
+    readonly reason: string;
+    readonly suspend: boolean;
+    readonly cause?: unknown;
 } | {
     /**
      * The farm source refused the analysis: the resolver returned
@@ -137,6 +149,17 @@ export declare class SandboxFailure extends Error {
     readonly error: SandboxError;
     constructor(error: SandboxError);
 }
+export type SuspendingRefusal = Extract<SandboxError, {
+    readonly type: "labels_refused";
+}> & {
+    readonly suspend: true;
+};
+/**
+ * Split the result of a spawn at a DBOS boundary. Call it inside the step of
+ * the spawn, before the checkpoint: the cause of a backend failure does not
+ * survive the serialization of a `Result`.
+ */
+export declare function keepSuspendingRefusal(result: Result<SandboxRef, SandboxError>): Result<SandboxRef, SuspendingRefusal>;
 /**
  * Wrap a single sandbox backend call (Docker SDK op, K8s API op, or the
  * `/exec` POST). A throw becomes `err(toError(status, cause))`; the caller