@inflexa-ai/harness 0.32.0 → 0.33.0

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

@@ -20,7 +20,7 @@ import { clearSandboxRef } from "../state/index.js";
 import { type AwaitExecOptions } from "./await-exec.js";
 import type { SandboxClient } from "./client.js";
 import { type SubmitExecDeps } from "./submit-exec.js";
-import { type CreateSandboxMeta, type SandboxTransport } from "./types.js";
+import { type CreateSandboxMeta, type FarmSource, type SandboxTransport, type ToolchainSource } from "./types.js";
 /**
  * Narrow config slice the sandbox factory reads off `Env` — the backend
  * default and the K8s namespace fallback. Composition roots map their
@@ -65,6 +65,21 @@ export interface CreateSandboxClientConfig {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Docker: host dir bind-mounted read-only at `/mnt/libs`. */
     libStorePath?: string;
+    /**
+     * Where the farm of an analysis comes from. Required of every embedder —
+     * the harness never invents a farm location, and it reads no store-root
+     * `current` pointer. On Docker, `FarmLocation.farmPath` is a host
+     * directory. On K8s, it is a `subPath` into `libStorePvc`. Consulted only
+     * when a store is configured.
+     */
+    farmSource: FarmSource;
+    /**
+     * The declared toolchain owner. `"image"` keys the resolver env and the
+     * orient-core prompt text onto the image-owned toolchain. Absent means
+     * `"store"`: the legacy environment, byte-identical to the one before
+     * this field existed.
+     */
+    toolchainSource?: ToolchainSource;
     /** Docker: host dir bind-mounted read-only at `/mnt/refs`. */
     refStorePath?: string;
     /** Docker: force the container platform (e.g. `linux/amd64`) so the sandbox matches the mounted lib store's arch. */
@@ -109,9 +124,10 @@ export interface CreateSandboxClientConfig {
     /** Override the backend selection — defaults to `env.SANDBOX_BACKEND`. */
     backend?: "docker" | "k8s";
     /**
-     * Optional logger forwarded to the Docker backend so a lib-store degradation
-     * (a configured store whose `current` vanished/went incomplete mid-session) is
-     * observable rather than a silent mount drop. No-op when unset.
+     * Optional logger forwarded to the Docker backend so a store degradation
+     * (a resolved farm whose `inflexa.lock` vanished or went invalid
+     * mid-session) is observable rather than a silent mount drop. No-op when
+     * unset.
      */
     logger?: Logger;
     /** Dependency seams (fetch, durable step/sleep, clock, recv, warn sink) forwarded to submit/await. */

package/dist/sandbox/create-sandbox.js

@@ -86,6 +86,8 @@ export function createSandboxClient(config) {
             sessionPvcRoot: config.sessionPvcRoot,
             resolveWorkspaceRoot: config.resolveWorkspaceRoot,
             libStorePvc: config.libStorePvc,
+            farmSource: config.farmSource,
+            toolchainSource: config.toolchainSource,
             refStorePvc: config.refStorePvc,
             nodeSelector: config.nodeSelector,
             tolerations: config.tolerations,
@@ -98,6 +100,8 @@ export function createSandboxClient(config) {
             transport,
             resolveWorkspaceRoot: config.resolveWorkspaceRoot,
             libStorePath: config.libStorePath,
+            farmSource: config.farmSource,
+            toolchainSource: config.toolchainSource,
             refStorePath: config.refStorePath,
             platform: config.platform,
             engineSocketPath: config.engineSocketPath,

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

@@ -3,9 +3,10 @@
  *
  * Thin wrapper around `dockerode`. Storage is wired via `HostConfig.Binds`:
  * a flat read-only mount of the analysis tree at `/{resourceId}`, a nested
- * read-write mount of the step's artifact dir, and the lib/ref stores at
- * `/mnt/libs` / `/mnt/refs` when their host paths are configured. Container
- * paths and lib-store env come from the shared mount plan (`mount-plan.ts`).
+ * read-write mount of the step's artifact dir, the package store at
+ * `/mnt/libs` with the resolved farm nested inside it, and the ref store at
+ * `/mnt/refs` when its host path is configured. Container paths and
+ * lib-store env come from the shared mount plan (`mount-plan.ts`).
  *
  * ## The cpu files
  *
@@ -42,7 +43,7 @@ import { ResultAsync } from "neverthrow";
 import type { Logger } from "../lib/logger.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type SandboxError } from "./sandbox-error.js";
-import type { CreateSandboxMeta, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport } from "./types.js";
+import type { CreateSandboxMeta, FarmSource, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, 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. */
@@ -53,6 +54,15 @@ export interface DockerClientConfig {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Host lib store; bind-mounted read-only at `/mnt/libs` when set. */
     libStorePath?: string;
+    /**
+     * Where the farm of an analysis comes from. Required — the harness never
+     * invents a farm location. `FarmLocation.farmPath` is a host directory
+     * here, bind-mounted read-only at the farm container path. Consulted only
+     * when `libStorePath` is set.
+     */
+    farmSource: FarmSource;
+    /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
+    toolchainSource?: ToolchainSource;
     /**
      * Host ref store; bind-mounted read-only at `/mnt/refs`. Embedders pass the
      * configured store location unconditionally — existence is (re-)checked at each
@@ -85,8 +95,8 @@ export interface DockerClientConfig {
      */
     readHostCpuinfo?: () => Promise<string | undefined>;
     /**
-     * Optional logger so a lib-store degradation (a configured store whose `current`
-     * vanished or went incomplete by sandbox-create time) is observable instead of a
+     * Optional logger so a store degradation (a resolved farm whose `inflexa.lock`
+     * is absent or invalid by sandbox-create time) is observable instead of a
      * silent libs-mount drop. Matches the `reaper`/`watchdog` logger seam.
      */
     logger?: Logger;

package/dist/sandbox/docker-client.js

@@ -3,9 +3,10 @@
  *
  * Thin wrapper around `dockerode`. Storage is wired via `HostConfig.Binds`:
  * a flat read-only mount of the analysis tree at `/{resourceId}`, a nested
- * read-write mount of the step's artifact dir, and the lib/ref stores at
- * `/mnt/libs` / `/mnt/refs` when their host paths are configured. Container
- * paths and lib-store env come from the shared mount plan (`mount-plan.ts`).
+ * read-write mount of the step's artifact dir, the package store at
+ * `/mnt/libs` with the resolved farm nested inside it, and the ref store at
+ * `/mnt/refs` when its host path is configured. Container paths and
+ * lib-store env come from the shared mount plan (`mount-plan.ts`).
  *
  * ## The cpu files
  *
@@ -37,7 +38,7 @@
  * Either way the workload ends as uid 1000 with `no-new-privileges` and no
  * effective capabilities.
  */
-import { existsSync, lstatSync, statSync } from "node:fs";
+import { lstatSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import Docker from "dockerode";
@@ -45,6 +46,7 @@ import { ResultAsync, err, ok } from "neverthrow";
 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 { CPU_ONLINE_PATH, CPUINFO_PATH, cpuFiles, readHostCpuinfoOnce } from "./cpu-files.js";
 import { threadLimitEnv } from "./thread-env.js";
@@ -74,26 +76,6 @@ const RUN_ID_LABEL = "cortex/run-id";
 const STEP_ID_LABEL = "cortex/step-id";
 /** The directory next to the workspace root that holds the cpu files of each sandbox. */
 const CPU_FILES_DIR = ".cpu";
-/**
- * Whether the lib store's `current` resolves to a COMPLETE, usable version, not merely a
- * present symlink. By sandbox-create time `current` may be gone (concurrent prune/`rm`), a
- * dangling symlink (its target pruned), or an incomplete tree. Binding a missing source
- * makes Docker auto-create a root-owned dir (bricking a later store refresh); binding a broken
- * one mounts broken content. Require a resolved directory carrying both completeness
- * markers `activate` writes before it flips the pointer.
- */
-function libStoreUsable(libStorePath) {
-    const current = join(libStorePath, "current");
-    try {
-        // statSync FOLLOWS the symlink, so a dangling `current` throws here and is rejected.
-        if (!statSync(current).isDirectory())
-            return false;
-    }
-    catch {
-        return false;
-    }
-    return existsSync(join(current, "packages.txt")) && existsSync(join(current, "meta.json"));
-}
 /**
  * Whether `refStorePath` is, right now, a real directory fit to be a bind authority.
  * Deliberately shallow — it checks existence-as-a-directory only, never the store's
@@ -253,13 +235,41 @@ export function createDockerSandboxOps(config) {
         createSandbox(meta, identity) {
             return new ResultAsync((async () => {
                 const { sandboxId, callbackSecret } = identity;
-                // Re-check AT sandbox-creation time: `config.libStorePath` was fixed at CLI
-                // boot and the store may have gone away since (see libStoreUsable). Not
-                // usable → skip the mount (sandbox degrades to available:false) and log it,
-                // since an otherwise-silent libs-mount drop is invisible to operators.
-                const libsMounted = !!config.libStorePath && libStoreUsable(config.libStorePath);
-                if (config.libStorePath && !libsMounted) {
-                    logger.warn("lib store configured but `current` is missing or incomplete at sandbox creation — mounting no library store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, sandboxId });
+                // 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");
+                    if (resolved.isErr())
+                        return err(resolved.error);
+                    farm = resolved.value;
+                }
+                // The `inflexa.lock` gate runs at each create: the store may have
+                // gone away, or the farm may be half-written. A gate failure
+                // degrades — both store mounts drop, the container is still made,
+                // and the sandbox reports the store as unavailable. The warning is
+                // logged because an otherwise-silent mount drop is invisible to
+                // operators.
+                let libsMounted = false;
+                if (config.libStorePath && farm) {
+                    const lock = readFarmLock(farm.farmPath);
+                    libsMounted = lock.isOk();
+                    if (lock.isErr()) {
+                        logger.warn("the farm of the analysis has no usable inflexa.lock at sandbox creation — mounting no package store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, farmPath: farm.farmPath, lockError: lock.error.type, sandboxId });
+                    }
+                }
+                // The cache path is the one farm value with no gate of its
+                // own: the lock gate proves `farmPath`, and this bind string
+                // would carry a malformed cache path verbatim. An unusable
+                // value degrades to no cache mount — the rule of a missing
+                // one — because the entrypoint fallback covers the caches.
+                const cacheBindable = farm?.cachePath !== undefined && farm.cachePath.startsWith("/") && !farm.cachePath.includes(":");
+                if (farm?.cachePath !== undefined && !cacheBindable) {
+                    logger.warn("the farm cache path cannot ride a docker bind — mounting no cache", {
+                        cachePath: farm.cachePath,
+                        sandboxId,
+                    });
                 }
                 // Re-checked here too, so a ref store installed after boot is mounted into
                 // the next sandbox. Unlike libs, a missing ref store is NOT warned: a missing
@@ -271,6 +281,8 @@ export function createDockerSandboxOps(config) {
                 const plan = buildMountPlan(meta, {
                     libs: libsMounted,
                     refs: refsMounted,
+                    toolchainSource: config.toolchainSource,
+                    cache: cacheBindable,
                 });
                 const hostTreePath = config.resolveWorkspaceRoot(meta.analysisId);
                 // `tailWritePrefix` (not a raw `join`) so the RW bind source runs through
@@ -290,12 +302,16 @@ export function createDockerSandboxOps(config) {
                 const cpuBinds = await writeCpuFiles(cpuDir, cpuFiles(threads, cpuinfo), logger, sandboxId);
                 if (cpuBinds.length > 0)
                     cpuDirs.set(sandboxId, cpuDir);
+                // The farm bind comes after the store bind, thus the nesting is
+                // stable; the cache bind comes after the two store binds.
                 const binds = [
                     `${hostTreePath}:${plan.readonlyTreePath}:ro`,
                     ...(write && plan.writableStepPath
                         ? [`${tailWritePrefix({ workspaceRoot: hostTreePath, tail: write.tail })}:${plan.writableStepPath}:rw`]
                         : []),
                     ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
+                    ...(libsMounted && farm && plan.farmPath ? [`${farm.farmPath}:${plan.farmPath}:ro`] : []),
+                    ...(libsMounted && cacheBindable && farm?.cachePath && plan.cachePath ? [`${farm.cachePath}:${plan.cachePath}:rw`] : []),
                     ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
                     ...cpuBinds,
                 ];

package/dist/sandbox/farm.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Farm-source resolution and the `inflexa.lock` farm contract.
+ *
+ * A farm carries exactly one metadata file, `inflexa.lock`, beside its link
+ * trees and its caches (the lib-store spec). The mount gate and the package
+ * inventory read this one file — `packages.txt`, `meta.json`, and
+ * `lock.json` are not part of the farm contract.
+ *
+ * The resolution and the gate refuse differently, on purpose:
+ * - A resolver refusal (`unavailable`, or a throw) is a `farm_unavailable`
+ *   `SandboxError` — the call refuses and no container is made.
+ * - A lock-gate failure degrades — the backend drops both store mounts,
+ *   logs a warning, and still makes the container.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+import type { SandboxError } from "./sandbox-error.js";
+import type { FarmLocation, FarmSource } from "./types.js";
+/** The one metadata file of a farm. */
+export declare const FARM_LOCK_FILE = "inflexa.lock";
+/** One linked distribution. `requested` obeys the PEP 376 meaning: true for a direct ask, false for a transitive dependency. */
+export declare const FarmLockPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    track: z.ZodString;
+    store_dir: z.ZodString;
+    hash: z.ZodString;
+    requested: z.ZodBoolean;
+}, z.core.$loose>;
+/**
+ * `inflexa.lock` at schema version 1. Additive fields pass through — a
+ * breaking change to the shape must move the schema number instead.
+ */
+export declare const FarmLockSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    arch: z.ZodEnum<{
+        amd64: "amd64";
+        arm64: "arm64";
+    }>;
+    packages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        track: z.ZodString;
+        store_dir: z.ZodString;
+        hash: z.ZodString;
+        requested: z.ZodBoolean;
+    }, z.core.$loose>>;
+    languages: z.ZodObject<{
+        python: z.ZodOptional<z.ZodObject<{
+            version: z.ZodString;
+            index: z.ZodString;
+        }, z.core.$loose>>;
+        r: z.ZodOptional<z.ZodObject<{
+            version: z.ZodString;
+            bioc_releases: z.ZodArray<z.ZodString>;
+            pak_lock: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    warm: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        script_sha256: z.ZodString;
+        cache_entries: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>>;
+    merge_conflicts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        entry: z.ZodString;
+        action: z.ZodEnum<{
+            skipped: "skipped";
+            "kept-first": "kept-first";
+        }>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type FarmLock = z.infer<typeof FarmLockSchema>;
+export type FarmLockError = {
+    readonly type: "lock_unreadable";
+    readonly lockPath: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "lock_invalid";
+    readonly lockPath: string;
+    readonly cause: unknown;
+};
+/**
+ * Read and validate the `inflexa.lock` of a farm directory. The mount gate
+ * accepts a farm only when this returns ok — a farm whose lock is absent,
+ * unparseable, or at an unknown schema version is not usable.
+ */
+export declare function readFarmLock(farmPath: string): Result<FarmLock, FarmLockError>;
+/** Read and validate one `inflexa.lock` by its file path. The package inventory reads through this too. */
+export declare function readFarmLockFile(lockPath: string): Result<FarmLock, FarmLockError>;
+/**
+ * Resolve the farm source of one analysis. Runs before any container work.
+ * `fixed` answers at once. `per-analysis` calls the resolver of the
+ * embedder — an `unavailable` result and a throw both refuse the call with
+ * `farm_unavailable`, and the reason of the embedder rides in the error.
+ */
+export declare function resolveFarmSource(source: FarmSource, analysisId: string, op: string): Promise<Result<FarmLocation, SandboxError>>;

package/dist/sandbox/farm.js

@@ -0,0 +1,127 @@
+/**
+ * Farm-source resolution and the `inflexa.lock` farm contract.
+ *
+ * A farm carries exactly one metadata file, `inflexa.lock`, beside its link
+ * trees and its caches (the lib-store spec). The mount gate and the package
+ * inventory read this one file — `packages.txt`, `meta.json`, and
+ * `lock.json` are not part of the farm contract.
+ *
+ * The resolution and the gate refuse differently, on purpose:
+ * - A resolver refusal (`unavailable`, or a throw) is a `farm_unavailable`
+ *   `SandboxError` — the call refuses and no container is made.
+ * - A lock-gate failure degrades — the backend drops both store mounts,
+ *   logs a warning, and still makes the container.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+/** The one metadata file of a farm. */
+export const FARM_LOCK_FILE = "inflexa.lock";
+/** One linked distribution. `requested` obeys the PEP 376 meaning: true for a direct ask, false for a transitive dependency. */
+export const FarmLockPackageSchema = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+    /** The link subtree of the package (for example `python`, `cran`, `bioconductor`). */
+    track: z.string(),
+    store_dir: z.string(),
+    /** The full sha256 of the sorted store tree. */
+    hash: z.string(),
+    requested: z.boolean(),
+})
+    .passthrough();
+/**
+ * `inflexa.lock` at schema version 1. Additive fields pass through — a
+ * breaking change to the shape must move the schema number instead.
+ */
+export const FarmLockSchema = z
+    .object({
+    schema: z.literal(1),
+    arch: z.enum(["amd64", "arm64"]),
+    packages: z.array(FarmLockPackageSchema),
+    /** Per-language provenance. Each language object owns its own fields. */
+    languages: z
+        .object({
+        python: z.object({ version: z.string(), index: z.string() }).passthrough().optional(),
+        r: z
+            .object({
+            version: z.string(),
+            bioc_releases: z.array(z.string()),
+            /** The embedded pak lock of the build, verbatim. */
+            pak_lock: z.unknown().optional(),
+        })
+            .passthrough()
+            .optional(),
+    })
+        .passthrough(),
+    /** The warm replay record. Present in the catalog farm only. */
+    warm: z
+        .record(z.string(), z
+        .object({
+        script_sha256: z.string(),
+        cache_entries: z.array(z.string()),
+    })
+        .passthrough())
+        .optional(),
+    /** The top-level entries that the link merge kept-first or skipped. */
+    merge_conflicts: z
+        .array(z
+        .object({
+        entry: z.string(),
+        action: z.enum(["kept-first", "skipped"]),
+    })
+        .passthrough())
+        .optional(),
+})
+    .passthrough();
+/**
+ * Read and validate the `inflexa.lock` of a farm directory. The mount gate
+ * accepts a farm only when this returns ok — a farm whose lock is absent,
+ * unparseable, or at an unknown schema version is not usable.
+ */
+export function readFarmLock(farmPath) {
+    return readFarmLockFile(join(farmPath, FARM_LOCK_FILE));
+}
+/** Read and validate one `inflexa.lock` by its file path. The package inventory reads through this too. */
+export function readFarmLockFile(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, "utf8");
+    }
+    catch (cause) {
+        return err({ type: "lock_unreadable", lockPath, cause });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        return err({ type: "lock_invalid", lockPath, cause });
+    }
+    const lock = FarmLockSchema.safeParse(parsed);
+    if (!lock.success) {
+        return err({ type: "lock_invalid", lockPath, cause: lock.error });
+    }
+    return ok(lock.data);
+}
+/**
+ * Resolve the farm source of one analysis. Runs before any container work.
+ * `fixed` answers at once. `per-analysis` calls the resolver of the
+ * embedder — an `unavailable` result and a throw both refuse the call with
+ * `farm_unavailable`, and the reason of the embedder rides in the error.
+ */
+export async function resolveFarmSource(source, analysisId, op) {
+    if (source.kind === "fixed")
+        return ok(source.location);
+    try {
+        const resolution = await source.resolve(analysisId);
+        if (resolution.kind === "unavailable") {
+            return err({ type: "farm_unavailable", op, analysisId, reason: resolution.reason });
+        }
+        return ok(resolution.location);
+    }
+    catch (cause) {
+        return err({ type: "farm_unavailable", op, analysisId, reason: "the farm resolver threw", cause });
+    }
+}

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

@@ -6,16 +6,17 @@
  * Storage is wired via the shared session PVC: a flat read-only `volumeMount`
  * of the analysis tree at `/{resourceId}` plus a nested read-write mount of the
  * step's artifact dir, with the lib/ref stores mounted read-only at `/mnt/libs`
- * / `/mnt/refs` when their PVCs are set. Container paths and lib-store env come
- * from the shared mount plan; the PVC `subPath`s are derived from the same
- * `resolveWorkspaceRoot` seam the harness pre-creates the step tree under, so
- * both sides address one directory by construction.
+ * / `/mnt/refs` when their PVCs are set. The farm of the analysis mounts as a
+ * read-only `subPath` of the libs PVC, after the store mount. Container paths
+ * and lib-store env come from the shared mount plan; the PVC `subPath`s are
+ * derived from the same `resolveWorkspaceRoot` seam the harness pre-creates
+ * the step tree under, so both sides address one directory by construction.
  */
 import { BatchV1Api, CoreV1Api, type V1Toleration } from "@kubernetes/client-node";
 import { ResultAsync } from "neverthrow";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type SandboxError } from "./sandbox-error.js";
-import type { CreateSandboxMeta, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport } from "./types.js";
+import type { CreateSandboxMeta, FarmSource, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport, ToolchainSource } from "./types.js";
 import type { Logger } from "../lib/logger.js";
 /**
  * Coerce an arbitrary identifier into a valid K8s label value:
@@ -52,6 +53,24 @@ export interface K8sClientConfig {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** PVC claim mounted read-only at `/mnt/libs` when set. */
     libStorePvc?: string;
+    /**
+     * Absolute mountpoint of `libStorePvc` on THIS process's filesystem, for
+     * a host that mounts the same volume (cortex mounts it at `/mnt/libs`).
+     * With the root set, the backend proves the `inflexa.lock` of the
+     * resolved farm before the mount — the same gate, and the same degrade,
+     * as the Docker backend. Without it, the proof duty stays whole on the
+     * farm resolver — see {@link ResolveAnalysisFarm}.
+     */
+    libStorePvcRoot?: string;
+    /**
+     * Where the farm of an analysis comes from. Required — the harness never
+     * invents a farm location. The farm is a `subPath` into `libStorePvc`,
+     * thus `FarmLocation.farmPath` is PVC-relative here. Consulted only when
+     * `libStorePvc` is set.
+     */
+    farmSource: FarmSource;
+    /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
+    toolchainSource?: ToolchainSource;
     /** PVC claim mounted read-only at `/mnt/refs` when set. */
     refStorePvc?: string;
     /** Node selector pinning sandbox pods to the dedicated agent pool. Omit for default scheduling. */

package/dist/sandbox/k8s-client.js

@@ -6,15 +6,17 @@
  * Storage is wired via the shared session PVC: a flat read-only `volumeMount`
  * of the analysis tree at `/{resourceId}` plus a nested read-write mount of the
  * step's artifact dir, with the lib/ref stores mounted read-only at `/mnt/libs`
- * / `/mnt/refs` when their PVCs are set. Container paths and lib-store env come
- * from the shared mount plan; the PVC `subPath`s are derived from the same
- * `resolveWorkspaceRoot` seam the harness pre-creates the step tree under, so
- * both sides address one directory by construction.
+ * / `/mnt/refs` when their PVCs are set. The farm of the analysis mounts as a
+ * read-only `subPath` of the libs PVC, after the store mount. Container paths
+ * and lib-store env come from the shared mount plan; the PVC `subPath`s are
+ * derived from the same `resolveWorkspaceRoot` seam the harness pre-creates
+ * the step tree under, so both sides address one directory by construction.
  */
-import { relative as relativePath, sep } from "node:path";
+import { join, relative as relativePath, sep } from "node:path";
 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 { threadLimitEnv } from "./thread-env.js";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -108,11 +110,30 @@ function workspaceSubPathFor(config, analysisId) {
     }
     return posix;
 }
-function buildJobSpec(meta, config, identity) {
+/**
+ * A farm location on K8s is a `subPath` into the libs PVC. A subPath must be
+ * a relative path with no `..` — an absolute or escaping value would mount a
+ * directory nothing resolved. `createSandbox` runs inside a DBOS workflow
+ * body, where a throw is the durable failure signal.
+ */
+function pvcSubPath(value, what) {
+    if (value.length === 0 || value.startsWith("/") || value.split("/").includes("..")) {
+        throw new Error(`k8s sandbox: ${what} must be a non-empty PVC-relative path without '..' (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+function buildJobSpec(meta, 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, {
-        libs: !!config.libStorePvc,
+        libs: libsMounted,
         refs: !!config.refStorePvc,
+        toolchainSource: config.toolchainSource,
+        cache: libsMounted && farm?.cachePath !== undefined,
     });
     const transport = config.transport ?? "poll";
     const spec = meta.resources;
@@ -168,15 +189,36 @@ function buildJobSpec(meta, config, identity) {
         }
     }
     if (config.libStorePvc && plan.libsPath) {
+        const cacheSubPath = farm?.cachePath !== undefined && plan.cachePath ? pvcSubPath(farm.cachePath, "the farm cache") : undefined;
         volumes.push({
             name: LIBS_VOLUME_NAME,
-            persistentVolumeClaim: { claimName: config.libStorePvc, readOnly: true },
+            // Volume-level readOnly only when nothing writes through the claim:
+            // the cache mount needs write access, and the per-mount flags keep
+            // the store and the farm read-only either way.
+            persistentVolumeClaim: { claimName: config.libStorePvc, ...(cacheSubPath === undefined ? { readOnly: true } : {}) },
         });
         volumeMounts.push({
             name: LIBS_VOLUME_NAME,
             mountPath: plan.libsPath,
             readOnly: true,
         });
+        // The farm mount comes after the store mount, thus the nesting is stable.
+        if (farm && plan.farmPath) {
+            volumeMounts.push({
+                name: LIBS_VOLUME_NAME,
+                mountPath: plan.farmPath,
+                subPath: pvcSubPath(farm.farmPath, "the farm"),
+                readOnly: true,
+            });
+        }
+        if (cacheSubPath !== undefined && plan.cachePath) {
+            volumeMounts.push({
+                name: LIBS_VOLUME_NAME,
+                mountPath: plan.cachePath,
+                subPath: cacheSubPath,
+                readOnly: false,
+            });
+        }
     }
     if (config.refStorePvc && plan.refsPath) {
         volumes.push({
@@ -410,7 +452,34 @@ export function createK8sSandboxOps(config) {
         createSandbox(meta, identity) {
             return new ResultAsync((async () => {
                 const { sandboxId } = identity;
-                const job = buildJobSpec(meta, config, identity);
+                // 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");
+                    if (resolved.isErr())
+                        return err(resolved.error);
+                    farm = resolved.value;
+                }
+                // The `inflexa.lock` gate, for a host that mounts the libs
+                // volume itself. The resolver owes the proof either way,
+                // but a farm half-written between the resolution and this
+                // create still mounts without a second look. A gate failure
+                // degrades exactly as the Docker backend does: no store
+                // mount, the Job is still made, and the sandbox reports the
+                // store as unavailable.
+                let libsMounted = !!config.libStorePvc;
+                if (config.libStorePvc && config.libStorePvcRoot && farm) {
+                    const lock = readFarmLock(join(config.libStorePvcRoot, farm.farmPath));
+                    libsMounted = lock.isOk();
+                    if (lock.isErr()) {
+                        (config.logger ?? createNoopLogger())
+                            .named("k8s-client")
+                            .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);
                 if (adopted.isErr())
                     return err(adopted.error);