@inflexa-ai/harness 0.30.2 → 0.31.0

package/dist/contracts/target-dossier.d.ts

@@ -140,8 +140,8 @@ export declare const EntitySchema: z.ZodObject<{
     displayName: z.ZodString;
     entityType: z.ZodEnum<{
         gene: "gene";
-        rna: "rna";
         protein: "protein";
+        rna: "rna";
         complex: "complex";
     }>;
     ontology: z.ZodString;
@@ -5985,8 +5985,8 @@ export declare const DossierSchema: z.ZodObject<{
         displayName: z.ZodString;
         entityType: z.ZodEnum<{
             gene: "gene";
-            rna: "rna";
             protein: "protein";
+            rna: "rna";
             complex: "complex";
         }>;
         ontology: z.ZodString;
@@ -9243,64 +9243,6 @@ export type Dossier = z.infer<typeof DossierSchema>;
  * and validates the complete dossier against `DossierSchema`.
  */
 export declare const DossierBodySchema: z.ZodObject<{
-    drug_interactions: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        coverage: z.ZodLiteral<"available">;
-        data: z.ZodObject<{
-            rows: z.ZodArray<z.ZodObject<{
-                drug_id: z.ZodNullable<z.ZodString>;
-                drug_name: z.ZodString;
-                best_score: z.ZodNumber;
-                predicates: z.ZodArray<z.ZodString>;
-                sources: z.ZodArray<z.ZodString>;
-                paper_count: z.ZodNumber;
-                dominant_direction: z.ZodEnum<{
-                    unknown: "unknown";
-                    positive: "positive";
-                    negative: "negative";
-                    mixed: "mixed";
-                }>;
-                has_human_evidence: z.ZodBoolean;
-                has_clinical_evidence: z.ZodBoolean;
-                evidence: z.ZodArray<z.ZodObject<{
-                    pmid: z.ZodOptional<z.ZodString>;
-                    doi: z.ZodOptional<z.ZodString>;
-                    accession: z.ZodOptional<z.ZodString>;
-                    source: z.ZodString;
-                    predicate: z.ZodOptional<z.ZodString>;
-                    score: z.ZodOptional<z.ZodNumber>;
-                    strength: z.ZodOptional<z.ZodString>;
-                    is_human: z.ZodOptional<z.ZodBoolean>;
-                    is_clinical: z.ZodOptional<z.ZodBoolean>;
-                    excerpt: z.ZodOptional<z.ZodString>;
-                    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-                    regulatory_reference: z.ZodOptional<z.ZodObject<{
-                        document: z.ZodString;
-                        section: z.ZodOptional<z.ZodString>;
-                        doc_id: z.ZodOptional<z.ZodString>;
-                        doc_url: z.ZodOptional<z.ZodString>;
-                    }, z.core.$strip>>;
-                }, z.core.$strip>>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>;
-        dropped_count: z.ZodOptional<z.ZodNumber>;
-        inference_path: z.ZodOptional<z.ZodString>;
-        truncated: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip>, z.ZodObject<{
-        coverage: z.ZodLiteral<"queried_no_data">;
-        error: z.ZodOptional<z.ZodObject<{
-            message: z.ZodString;
-            source: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>;
-        inference_path: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        coverage: z.ZodLiteral<"filtered">;
-        filter: z.ZodString;
-        dropped_count: z.ZodNumber;
-        inference_path: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        coverage: z.ZodLiteral<"not_loaded">;
-        reason: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>], "coverage">;
     tractability: z.ZodDiscriminatedUnion<[z.ZodObject<{
         coverage: z.ZodLiteral<"available">;
         data: z.ZodObject<{
@@ -9348,8 +9290,8 @@ export declare const DossierBodySchema: z.ZodObject<{
         displayName: z.ZodString;
         entityType: z.ZodEnum<{
             gene: "gene";
-            rna: "rna";
             protein: "protein";
+            rna: "rna";
             complex: "complex";
         }>;
         ontology: z.ZodString;
@@ -9647,6 +9589,64 @@ export declare const DossierBodySchema: z.ZodObject<{
         coverage: z.ZodLiteral<"not_loaded">;
         reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "coverage">;
+    drug_interactions: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        coverage: z.ZodLiteral<"available">;
+        data: z.ZodObject<{
+            rows: z.ZodArray<z.ZodObject<{
+                drug_id: z.ZodNullable<z.ZodString>;
+                drug_name: z.ZodString;
+                best_score: z.ZodNumber;
+                predicates: z.ZodArray<z.ZodString>;
+                sources: z.ZodArray<z.ZodString>;
+                paper_count: z.ZodNumber;
+                dominant_direction: z.ZodEnum<{
+                    unknown: "unknown";
+                    positive: "positive";
+                    negative: "negative";
+                    mixed: "mixed";
+                }>;
+                has_human_evidence: z.ZodBoolean;
+                has_clinical_evidence: z.ZodBoolean;
+                evidence: z.ZodArray<z.ZodObject<{
+                    pmid: z.ZodOptional<z.ZodString>;
+                    doi: z.ZodOptional<z.ZodString>;
+                    accession: z.ZodOptional<z.ZodString>;
+                    source: z.ZodString;
+                    predicate: z.ZodOptional<z.ZodString>;
+                    score: z.ZodOptional<z.ZodNumber>;
+                    strength: z.ZodOptional<z.ZodString>;
+                    is_human: z.ZodOptional<z.ZodBoolean>;
+                    is_clinical: z.ZodOptional<z.ZodBoolean>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    regulatory_reference: z.ZodOptional<z.ZodObject<{
+                        document: z.ZodString;
+                        section: z.ZodOptional<z.ZodString>;
+                        doc_id: z.ZodOptional<z.ZodString>;
+                        doc_url: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        dropped_count: z.ZodOptional<z.ZodNumber>;
+        inference_path: z.ZodOptional<z.ZodString>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        coverage: z.ZodLiteral<"queried_no_data">;
+        error: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        inference_path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        coverage: z.ZodLiteral<"filtered">;
+        filter: z.ZodString;
+        dropped_count: z.ZodNumber;
+        inference_path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        coverage: z.ZodLiteral<"not_loaded">;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "coverage">;
     clinical_development: z.ZodObject<{
         trials: z.ZodDiscriminatedUnion<[z.ZodObject<{
             coverage: z.ZodLiteral<"available">;

package/dist/execution/run-synthesis.js

@@ -33,6 +33,7 @@ import { BiologicalThemeSchema, KeyReferenceSchema, RunSynthesisSchema, Synthesi
 import { synthesisAgentPrompt } from "../prompts/synthesis-agent.js";
 import { composeSystemPrompt } from "../agents/system-prompt.js";
 import { runDir } from "../workspace/paths.js";
+import { decodeObjectString } from "../lib/zod-issues.js";
 import { runToTerminal } from "../loop/run-to-terminal.js";
 import { passthroughStep } from "../loop/run-step.js";
 import { defineTool } from "../tools/define-tool.js";
@@ -262,17 +263,21 @@ function buildValidateTool(ctx) {
             "field-by-field synthesis schema is the arg schema of " +
             "submit_synthesis — this tool deliberately does not restate it. " +
             "Non-terminal: call as often as needed to iterate toward a clean " +
-            "synthesis, then submit_synthesis.",
+            "synthesis, then submit_synthesis. A candidate that arrives as a " +
+            "JSON-encoded string is decoded before the checks run, so the " +
+            "result describes the synthesis inside the string.",
         // Deliberately permissive: a structurally-invalid candidate must reach
         // `execute` so the model gets a structured {valid:false, issues} result —
         // including semantic issues — instead of a bare Zod rejection at the loop's
         // input boundary. `execute` re-parses against RunSynthesisSchema itself.
+        // The permissive schema also means the loop's string repair never runs
+        // here, so `execute` decodes a JSON-encoded string itself.
         inputSchema: z.object({
             synthesis: z.unknown().describe("The candidate synthesis, in any shape. Field-by-field schema: see submit_synthesis."),
         }),
         describeCall: "none",
         execute: async (input) => {
-            const result = fullyValidate(input.synthesis, ctx);
+            const result = fullyValidate(decodeObjectString(input.synthesis), ctx);
             return ok(result.valid ? { valid: true, issues: [] } : { valid: false, issues: result.issues });
         },
     });

package/dist/lib/zod-issues.d.ts

@@ -82,3 +82,11 @@ export declare function hintForZodIssue(issue: z.core.$ZodIssue, input: unknown)
  * is not re-examined — one pass, no recursion — and no input causes a throw.
  */
 export declare function repairToolInput(input: unknown, error: z.ZodError): unknown | undefined;
+/**
+ * Decode a value that a model sent as a JSON-encoded object string, with or
+ * without a wrapper artifact. The decoded object is returned when the string
+ * parses to one. Each other value comes back as it is, thus a caller can apply
+ * this to an argument of any type. This is the repair that `repairToolInput`
+ * applies at the loop boundary, for a tool whose schema accepts the string.
+ */
+export declare function decodeObjectString(value: unknown): unknown;

package/dist/lib/zod-issues.js

@@ -131,6 +131,19 @@ export function repairToolInput(input, error) {
         return undefined;
     }
 }
+/**
+ * Decode a value that a model sent as a JSON-encoded object string, with or
+ * without a wrapper artifact. The decoded object is returned when the string
+ * parses to one. Each other value comes back as it is, thus a caller can apply
+ * this to an argument of any type. This is the repair that `repairToolInput`
+ * applies at the loop boundary, for a tool whose schema accepts the string.
+ */
+export function decodeObjectString(value) {
+    if (typeof value !== "string" || value.length > MAX_REPAIRABLE_STRING_LENGTH)
+        return value;
+    const parsed = parseAs(value, "object") ?? parseAs(stripWrappers(value).text, "object");
+    return parsed === undefined ? value : parsed.value;
+}
 /**
  * The measurement of a string that broke its maximum length, or `undefined` for
  * any other issue.

package/dist/literature/sources/semantic-scholar.d.ts

@@ -1,4 +1,38 @@
+/**
+ * Absence policy: Semantic Scholar gives each requested key, and it sends an
+ * explicit `null` for an absent value such as `abstract` or `year`. An absent
+ * `venue` is the empty string.
+ */
+import { z } from "zod";
 import { type SourceHttpOptions, type SourceHttpResult } from "./http.js";
+export declare const ExactPaperSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    abstract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    venue: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    citationCount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    authors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    externalIds: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>>;
+    paperId: z.ZodString;
+}, z.core.$loose>;
+export declare const SearchResponseSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        paperId: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        abstract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        venue: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        citationCount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+        externalIds: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>>;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
 export interface SemanticScholarPaper {
     id: string;
     title?: string;

package/dist/literature/sources/semantic-scholar.js

@@ -1,3 +1,8 @@
+/**
+ * Absence policy: Semantic Scholar gives each requested key, and it sends an
+ * explicit `null` for an absent value such as `abstract` or `year`. An absent
+ * `venue` is the empty string.
+ */
 import { z } from "zod";
 import { requestJson } from "./http.js";
 const BASE_URL = "https://api.semanticscholar.org/graph/v1";
@@ -12,15 +17,21 @@ const WirePaperSchema = z
     citationCount: z.number().nullable().optional(),
     url: z.string().nullable().optional(),
     authors: z.array(z.object({ name: z.string().nullable().optional() })).optional(),
-    externalIds: z.record(z.string(), z.unknown()).nullable().optional(),
+    // An external id is a string, but `CorpusId` is a JSON integer on every
+    // observed paper. A string-only value type drops it at the map site below.
+    externalIds: z
+        .record(z.string(), z.union([z.string(), z.number()]))
+        .nullable()
+        .optional(),
 })
     .passthrough();
-const ExactPaperSchema = WirePaperSchema.extend({ paperId: z.string() });
-const SearchResponseSchema = z.object({ data: z.array(WirePaperSchema).optional() });
+export const ExactPaperSchema = WirePaperSchema.extend({ paperId: z.string() });
+export const SearchResponseSchema = z.object({ data: z.array(WirePaperSchema).optional() });
+/** Give one text form to each external id, thus a numeric `CorpusId` reaches a caller that keys on a string. */
 function stringExternalIds(value) {
     if (value === null || value === undefined)
         return undefined;
-    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    const entries = Object.entries(value).map(([key, raw]) => [key, typeof raw === "string" ? raw : String(raw)]);
     return entries.length === 0 ? undefined : Object.fromEntries(entries);
 }
 function mapPaper(raw) {

package/dist/sandbox/cpu-files.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The two cpu files that a sandbox reads for its core count.
+ *
+ * The thread env (`thread-env.ts`) reaches each library that reads a thread
+ * count from the environment. Two base calls read a kernel file instead:
+ * `parallel::detectCores()` greps `/proc/cpuinfo`, and `os.cpu_count()` of
+ * Python 3.12 reads `/sys/devices/system/cpu/online` through glibc. Both files
+ * describe the host, not the cgroup. A read-only bind of a small file over each
+ * path makes both calls report the quota.
+ *
+ * This module makes the content of the two files, and it reads the
+ * `/proc/cpuinfo` of the harness host that the content is cut from. The Docker
+ * backend writes the content to the host and binds it. The K8s backend puts
+ * the content in a ConfigMap and mounts each key with `subPath`.
+ */
+/** The two container paths that the cpu files cover. */
+export declare const CPU_ONLINE_PATH = "/sys/devices/system/cpu/online";
+export declare const CPUINFO_PATH = "/proc/cpuinfo";
+export declare function readHostCpuinfoOnce(): Promise<string | undefined>;
+export interface CpuFiles {
+    /** Content of `/sys/devices/system/cpu/online`: `0` for one thread, else the range `0-<n-1>`. */
+    readonly online: string;
+    /**
+     * Content of `/proc/cpuinfo`: the first n `processor` blocks of the real file
+     * of the host. `undefined` when the host gives no `/proc/cpuinfo`.
+     */
+    readonly cpuinfo: string | undefined;
+}
+/**
+ * The content of the two cpu files for `threads` cpus.
+ *
+ * `threads` is a positive integer. The caller applies the same floor as
+ * `threadLimitEnv`: `Math.max(1, Math.floor(spec.cpu))`. When the host has fewer
+ * processor blocks than `threads`, all blocks stay. Each block keeps its own
+ * text, thus the `processor` numbers stay `0` to `n-1` as in the real file.
+ */
+export declare function cpuFiles(threads: number, hostCpuinfo: string | undefined): CpuFiles;

package/dist/sandbox/cpu-files.js

@@ -0,0 +1,55 @@
+/**
+ * The two cpu files that a sandbox reads for its core count.
+ *
+ * The thread env (`thread-env.ts`) reaches each library that reads a thread
+ * count from the environment. Two base calls read a kernel file instead:
+ * `parallel::detectCores()` greps `/proc/cpuinfo`, and `os.cpu_count()` of
+ * Python 3.12 reads `/sys/devices/system/cpu/online` through glibc. Both files
+ * describe the host, not the cgroup. A read-only bind of a small file over each
+ * path makes both calls report the quota.
+ *
+ * This module makes the content of the two files, and it reads the
+ * `/proc/cpuinfo` of the harness host that the content is cut from. The Docker
+ * backend writes the content to the host and binds it. The K8s backend puts
+ * the content in a ConfigMap and mounts each key with `subPath`.
+ */
+import { readFile } from "node:fs/promises";
+/** The two container paths that the cpu files cover. */
+export const CPU_ONLINE_PATH = "/sys/devices/system/cpu/online";
+export const CPUINFO_PATH = "/proc/cpuinfo";
+/**
+ * The `/proc/cpuinfo` of the harness host, read once per process. The content
+ * does not change while the process runs. A host with no such file, for
+ * example macOS, gives `undefined`, and the caller covers only `online`.
+ */
+let hostCpuinfo;
+export function readHostCpuinfoOnce() {
+    hostCpuinfo ??= readFile(CPUINFO_PATH, "utf8").catch(() => undefined);
+    return hostCpuinfo;
+}
+/**
+ * Split the text of `/proc/cpuinfo` into its `processor` blocks. A blank line
+ * ends a block. A block with no `processor` line, for example the `Hardware`
+ * trailer of an ARM kernel, is not a processor and is dropped.
+ */
+function processorBlocks(cpuinfo) {
+    return cpuinfo
+        .split(/\n\s*\n/)
+        .map((block) => block.trim())
+        .filter((block) => /^processor\b/m.test(block));
+}
+/**
+ * The content of the two cpu files for `threads` cpus.
+ *
+ * `threads` is a positive integer. The caller applies the same floor as
+ * `threadLimitEnv`: `Math.max(1, Math.floor(spec.cpu))`. When the host has fewer
+ * processor blocks than `threads`, all blocks stay. Each block keeps its own
+ * text, thus the `processor` numbers stay `0` to `n-1` as in the real file.
+ */
+export function cpuFiles(threads, hostCpuinfo) {
+    const online = `${threads === 1 ? "0" : `0-${threads - 1}`}\n`;
+    if (hostCpuinfo === undefined)
+        return { online, cpuinfo: undefined };
+    const blocks = processorBlocks(hostCpuinfo).slice(0, threads);
+    return { online, cpuinfo: blocks.map((block) => `${block}\n\n`).join("") };
+}

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

@@ -7,6 +7,15 @@
  * `/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`).
  *
+ * ## The cpu files
+ *
+ * Two more binds put a small file over `/sys/devices/system/cpu/online` and
+ * over `/proc/cpuinfo` (`cpu-files.ts`). Each file describes `spec.cpu` cpus,
+ * not the host. The host side of each bind is a file under
+ * `<parent of the workspace root>/.cpu/<sandboxId>/`, thus outside the tree
+ * that the sandbox sees. `teardown` removes the directory when this process
+ * wrote it. A directory from an earlier process stays.
+ *
  * ## Transport and confinement
  *
  * The container joins the default bridge and publishes sandbox-server's port to
@@ -69,6 +78,12 @@ export interface DockerClientConfig {
     docker?: Docker;
     /** Injected for tests so `/health` polling can be stubbed. */
     fetch?: typeof fetch;
+    /**
+     * Injected for tests so the `/proc/cpuinfo` of the host can be stubbed. The
+     * default reads the file once per process. `undefined` means that the host
+     * has no such file, for example macOS.
+     */
+    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

package/dist/sandbox/docker-client.js

@@ -7,6 +7,15 @@
  * `/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`).
  *
+ * ## The cpu files
+ *
+ * Two more binds put a small file over `/sys/devices/system/cpu/online` and
+ * over `/proc/cpuinfo` (`cpu-files.ts`). Each file describes `spec.cpu` cpus,
+ * not the host. The host side of each bind is a file under
+ * `<parent of the workspace root>/.cpu/<sandboxId>/`, thus outside the tree
+ * that the sandbox sees. `teardown` removes the directory when this process
+ * wrote it. A directory from an earlier process stays.
+ *
  * ## Transport and confinement
  *
  * The container joins the default bridge and publishes sandbox-server's port to
@@ -29,13 +38,16 @@
  * effective capabilities.
  */
 import { existsSync, lstatSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import Docker from "dockerode";
 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 { buildMountPlan, 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. */
 function statusOf(e) {
     return "status" in e ? e.status : undefined;
@@ -60,6 +72,8 @@ 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";
+/** 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
@@ -104,6 +118,39 @@ function refStoreUsable(refStorePath) {
         return false;
     }
 }
+/**
+ * Write the cpu files of one sandbox into `dir` and return their binds.
+ *
+ * The directory `.cpu` is made with no `recursive` option on purpose. The
+ * parent of the workspace root must exist already. Thus a root that is not on
+ * disk gives no directory at an unexpected place, and the sandbox starts with
+ * no cpu files. The failure is a degradation, not an error: the thread env
+ * still limits each library, but `detectCores()` and `os.cpu_count()` report
+ * the host.
+ */
+async function writeCpuFiles(dir, files, logger, sandboxId) {
+    const ignoreExists = (cause) => {
+        if (cause.code !== "EEXIST")
+            throw cause;
+    };
+    try {
+        await mkdir(dirname(dir)).catch(ignoreExists);
+        await mkdir(dir).catch(ignoreExists);
+        const online = join(dir, "online");
+        await writeFile(online, files.online);
+        const binds = [`${online}:${CPU_ONLINE_PATH}:ro`];
+        if (files.cpuinfo !== undefined) {
+            const cpuinfo = join(dir, "cpuinfo");
+            await writeFile(cpuinfo, files.cpuinfo);
+            binds.push(`${cpuinfo}:${CPUINFO_PATH}:ro`);
+        }
+        return binds;
+    }
+    catch (cause) {
+        logger.warn("cpu files not written — the sandbox reports the cores of the host", { sandboxId, dir, cause });
+        return [];
+    }
+}
 async function pollHealth(fetchImpl, url, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     let lastErr;
@@ -199,6 +246,9 @@ export function createDockerSandboxOps(config) {
     const fetchImpl = config.fetch ?? fetch;
     const transport = config.transport ?? "poll";
     const pollMode = transport === "poll";
+    const readHostCpuinfo = config.readHostCpuinfo ?? readHostCpuinfoOnce;
+    /** The cpu directory of each sandbox that this process wrote, for `teardown`. */
+    const cpuDirs = new Map();
     return {
         createSandbox(meta, identity) {
             return new ResultAsync((async () => {
@@ -228,6 +278,18 @@ export function createDockerSandboxOps(config) {
                 // 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);
+                // The same floor as `threadLimitEnv`: a fractional cpu request is one cpu.
+                const threads = Math.max(1, Math.floor(meta.resources.cpu));
+                const cpuinfo = await readHostCpuinfo();
+                if (cpuinfo === undefined) {
+                    logger.debug("no host /proc/cpuinfo — the sandbox gets the online file only", { sandboxId });
+                }
+                // Next to the workspace root, not under it: the root is bound read-only
+                // at `/{analysisId}`, and a file under it is visible in the sandbox.
+                const cpuDir = join(dirname(hostTreePath), CPU_FILES_DIR, sandboxId);
+                const cpuBinds = await writeCpuFiles(cpuDir, cpuFiles(threads, cpuinfo), logger, sandboxId);
+                if (cpuBinds.length > 0)
+                    cpuDirs.set(sandboxId, cpuDir);
                 const binds = [
                     `${hostTreePath}:${plan.readonlyTreePath}:ro`,
                     ...(write && plan.writableStepPath
@@ -235,6 +297,7 @@ export function createDockerSandboxOps(config) {
                         : []),
                     ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
                     ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
+                    ...cpuBinds,
                 ];
                 const createFailed = (status, cause) => ({
                     type: "container_create_failed",
@@ -244,17 +307,22 @@ export function createDockerSandboxOps(config) {
                     cause,
                 });
                 const image = meta.image ?? config.image;
+                const spec = meta.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.
-                const env = [
-                    `SANDBOX_TRANSPORT=${transport}`,
-                    `SANDBOX_CALLBACK_SECRET=${callbackSecret}`,
-                    ...(pollMode ? ["SANDBOX_EGRESS_FIREWALL=1"] : [`CORTEX_BASE_URL=${config.cortexBaseUrl}`]),
-                    ...Object.entries(plan.env).map(([k, v]) => `${k}=${v}`),
-                    ...Object.entries(meta.extraEnv ?? {}).map(([k, v]) => `${k}=${v}`),
-                ];
-                const spec = meta.resources;
+                //
+                // Composed as one record, not as a list of `K=V`. A duplicate key in
+                // the Env array resolves at the libc that scans `environ`, thus the
+                // later spread must win here, not there.
+                const env = Object.entries({
+                    SANDBOX_TRANSPORT: transport,
+                    SANDBOX_CALLBACK_SECRET: callbackSecret,
+                    ...(pollMode ? { SANDBOX_EGRESS_FIREWALL: "1" } : { CORTEX_BASE_URL: config.cortexBaseUrl }),
+                    ...threadLimitEnv(spec),
+                    ...plan.env,
+                    ...(meta.extraEnv ?? {}),
+                }).map(([k, v]) => `${k}=${v}`);
                 const createOpts = {
                     name: sandboxId,
                     ...(config.platform !== undefined && { platform: config.platform }),
@@ -289,6 +357,11 @@ export function createDockerSandboxOps(config) {
                         SecurityOpt: ["no-new-privileges"],
                         NanoCpus: Math.round(spec.cpu * 1e9),
                         Memory: spec.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,
                         AutoRemove: false,
                     },
                 };
@@ -329,10 +402,10 @@ export function createDockerSandboxOps(config) {
             })());
         },
         teardown(ref) {
-            return removeContainerIgnoreMissing(docker, ref.sandboxId);
+            return teardownSandbox(ref.sandboxId);
         },
         teardownById(sandboxId) {
-            return removeContainerIgnoreMissing(docker, sandboxId);
+            return teardownSandbox(sandboxId);
         },
         listManagedSandboxes() {
             return trySandbox(() => docker.listContainers({
@@ -361,6 +434,22 @@ export function createDockerSandboxOps(config) {
         },
         isAliveById,
     };
+    /**
+     * Remove the container, then the cpu files that this process wrote for it.
+     * A failure of the file removal does not fail the teardown: the container is
+     * gone, and a stale small directory is not a risk to a later sandbox.
+     */
+    function teardownSandbox(sandboxId) {
+        return removeContainerIgnoreMissing(docker, sandboxId).map(async () => {
+            const cpuDir = cpuDirs.get(sandboxId);
+            if (cpuDir === undefined)
+                return;
+            cpuDirs.delete(sandboxId);
+            await rm(cpuDir, { recursive: true, force: true }).catch((cause) => {
+                logger.debug("cpu files not removed", { sandboxId, cpuDir, cause });
+            });
+        });
+    }
     function isAliveById(sandboxId) {
         return trySandbox(async () => {
             const info = await docker.getContainer(sandboxId).inspect();

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

@@ -60,6 +60,11 @@ export interface K8sClientConfig {
     tolerations?: V1Toleration[];
     /** RuntimeClass for runtime isolation (e.g. `gvisor`). Omit for the default runtime. */
     runtimeClassName?: string;
+    /**
+     * The `/proc/cpuinfo` text that the cpu ConfigMap of each Job is cut from.
+     * Defaults to the file of the host of this process, read once. Injected for tests.
+     */
+    readHostCpuinfo?: () => Promise<string | undefined>;
     /** Injected for tests. */
     batchApi?: BatchV1Api;
     coreApi?: CoreV1Api;