@inflexa-ai/harness 0.30.1 → 0.30.3

package/dist/providers/ai-sdk.js

@@ -1,4 +1,4 @@
-import { generateText, streamText, wrapLanguageModel, } from "ai";
+import { streamText, wrapLanguageModel, } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
@@ -255,10 +255,10 @@ function requestedModelIdOf(model) {
 }
 /**
  * Capture the served model id at the raw model boundary, because that is the
- * only place it is still distinguishable from the requested one: `generateText`
- * and `streamText` both coalesce an unreported response model id to the bound
- * model's own id, so reading `result.response.modelId` would silently republish
- * the requested id as an endpoint's claim. A middleware sees the provider's
+ * only place it is still distinguishable from the requested one: `streamText`
+ * coalesces an unreported response model id to the bound model's own id, so
+ * reading `result.response.modelId` would silently republish the requested id
+ * as an endpoint's claim. A middleware sees the provider's
  * result before that fallback applies, so "reported nothing" stays absent.
  *
  * Built per call, never per provider: one provider instance serves concurrent
@@ -303,16 +303,6 @@ function responseFromMessages(input) {
     }
     return { message, finishReason, rawFinishReason, usage, requestedModelId, servedModelId };
 }
-function responseFromGenerate(result, identity) {
-    return responseFromMessages({
-        messages: result.responseMessages,
-        fallbackText: result.text,
-        finishReason: result.finishReason,
-        rawFinishReason: result.rawFinishReason,
-        usage: result.usage,
-        ...identity,
-    });
-}
 /**
  * Drop empty text parts — and messages left with no content at all — before
  * the wire call. The Anthropic Messages API rejects any request containing an
@@ -356,9 +346,57 @@ async function pullNextDelta(iterator) {
             return { kind: "delta", text: part.text };
         if (part.type === "abort")
             return { kind: "aborted", reason: part.reason };
+        // The SDK reports a wire failure as a part, not as a rejection, and it
+        // then closes the stream. Skipping it would turn a failed call into an
+        // empty assistant turn that the loop reads as a real answer.
+        if (part.type === "error")
+            return { kind: "failed", error: part.error };
     }
     return { kind: "end" };
 }
+/**
+ * The HTTP status that each Anthropic stream error type stands for.
+ *
+ * A provider names a mid-stream failure in the payload, not in the status line:
+ * a stream that carries `overloaded_error` reports the condition that a 529
+ * names on the non-streaming wire. The classifier reads the status alone, thus
+ * the part has to reach it as an error that names one, or the same condition
+ * would classify one way on `chat` and another way on `chatStream`.
+ */
+const STREAM_ERROR_STATUS = {
+    invalid_request_error: 400,
+    authentication_error: 401,
+    permission_error: 403,
+    not_found_error: 404,
+    request_too_large: 413,
+    rate_limit_error: 429,
+    timeout_error: 408,
+    api_error: 500,
+    overloaded_error: 529,
+};
+/**
+ * The failure that an `error` part of the SDK stream stands for.
+ *
+ * The part carries whatever the provider put on the wire, and that is often a
+ * bare object rather than an `Error`. Left as it is, it reaches the message as
+ * `[object Object]` and reaches the classifier with no status at all.
+ */
+function streamPartFailure(error) {
+    if (error instanceof Error)
+        return error;
+    if (typeof error !== "object" || error === null)
+        return new Error(String(error));
+    const reported = error;
+    const type = typeof reported.type === "string" ? reported.type : undefined;
+    const message = typeof reported.message === "string" ? reported.message : undefined;
+    const failure = new Error(message ?? type ?? "The provider reported a stream error.", { cause: error });
+    const status = type === undefined ? undefined : STREAM_ERROR_STATUS[type];
+    // `extractStatus` walks the chain for this field, thus the named condition
+    // classifies the same way it would from a status line.
+    if (status !== undefined)
+        Object.assign(failure, { status });
+    return failure;
+}
 /**
  * The failure that an `abort` part of the SDK stream stands for.
  *
@@ -394,16 +432,46 @@ export function createAiSdkProvider(deps) {
     const requestTimeoutMs = deps.requestTimeoutMs;
     const requestedModelId = requestedModelIdOf(deps.model);
     routeSdkWarningsTo(logger);
+    /**
+     * Record a call that the envelope gave up on.
+     *
+     * The envelope reports one attempt at `debug`, thus a deployment that runs
+     * at `info` keeps no trace of a call that exhausted its retries: the reply
+     * carries the failure to the user and the operator sees nothing. This is the
+     * one record that names the outcome.
+     */
+    function logFailure(session, failure, thrown) {
+        logger.error("provider call failed", {
+            workload: workloadOf(session),
+            kind: failure.type,
+            retryable: failure.retryable,
+            ...logger.errorFields(thrown),
+        });
+    }
     function chat(req, session, signal) {
         const run = async () => {
             const retry = createRetry(signal, logger, maxRetries);
             const capture = captureServedModelId(deps.model);
             try {
-                const result = await retry(async () => {
+                const collected = await retry(async () => {
                     // Attribution headers are time-limited; resolving them inside the
                     // retried closure keeps them fresh across a multi-minute window.
                     const headers = await resolveBillingHeaders(deps.resolveBilling, session);
-                    return generateText({
+                    // The call streams on the wire and collapses below.
+                    //
+                    // A non-streaming turn sends no header until the model completes,
+                    // thus the `headersTimeout` of the host HTTP client bounds the whole
+                    // generation. No option of the SDK lifts that bound, because it sits
+                    // under the fetch. Node defaults the field to 300s, and a turn near
+                    // 18k output tokens reaches it, while `DEFAULT_MAX_OUTPUT_TOKENS`
+                    // asks for up to 64k. A cut turn then costs twice: the envelope
+                    // starts the same generation again from zero.
+                    //
+                    // Anthropic states the rule for its own SDKs: a large `max_tokens`
+                    // makes streaming necessary, to prevent an HTTP timeout. Thus a
+                    // ceiling this size streams whether or not a consumer wants the
+                    // deltas, and `chatStream` stays the seam that forwards them.
+                    const result = streamText({
                         model: capture.model,
                         system: req.system,
                         messages: sanitizeMessages(req.messages),
@@ -416,20 +484,53 @@ export function createAiSdkProvider(deps) {
                         maxRetries: 0,
                         headers,
                         abortSignal: signal,
-                        // No SDK timeout rides here. `chunkMs` bounds a stream only,
-                        // thus it is inert on this call. The fetch guard is the full
-                        // bound, because the headers of a non-streaming response arrive
-                        // when the model completes.
+                        // `firstChunkMs` bounds the wait for the first content chunk,
+                        // and `chunkMs` bounds each later gap. Thus each silent interval
+                        // carries the one configured bound, and a turn that writes
+                        // steadily runs as long as it needs.
+                        ...(requestTimeoutMs !== undefined ? { timeout: { firstChunkMs: requestTimeoutMs, chunkMs: requestTimeoutMs } } : {}),
                         providerOptions: req.providerOptions,
                         reasoning: req.reasoning,
                     });
+                    // The drain sits inside the retried closure, thus a failure at any
+                    // point of the stream re-runs the whole attempt and the envelope
+                    // keeps its whole-call scope. No delta reaches a consumer here —
+                    // `chatStream` is the seam that forwards them.
+                    const iterator = result.fullStream[Symbol.asyncIterator]();
+                    let text = "";
+                    for (let pull = await pullNextDelta(iterator); pull.kind !== "end"; pull = await pullNextDelta(iterator)) {
+                        // A caller abort rides out as the reason of its own signal, thus
+                        // it stays a cancellation and reaches the caller as a throw.
+                        if (pull.kind === "aborted")
+                            throw abortedStreamFailure(signal, pull.reason, requestTimeoutMs);
+                        if (pull.kind === "failed")
+                            throw streamPartFailure(pull.error);
+                        text += pull.text;
+                    }
+                    // These promises settle only once the stream is fully drained, thus
+                    // the loop above must reach its end before this point.
+                    return {
+                        messages: await result.responseMessages,
+                        fallbackText: text,
+                        finishReason: await result.finishReason,
+                        rawFinishReason: await result.rawFinishReason,
+                        usage: await result.usage,
+                    };
                 });
-                return ok(responseFromGenerate(result, { requestedModelId, servedModelId: capture.servedModelId() }));
+                return ok(responseFromMessages({
+                    ...collected,
+                    requestedModelId,
+                    // Read after the drain: the metadata chunk that carries the
+                    // served id reaches the capture only as the stream is consumed.
+                    servedModelId: capture.servedModelId(),
+                }));
             }
             catch (e) {
                 if (isAbortError(e) || signal?.aborted)
                     throw e;
-                return err(toProviderError(unwrapForClassification(e), workloadOf(session)));
+                const failure = toProviderError(unwrapForClassification(e), workloadOf(session));
+                logFailure(session, failure, e);
+                return err(failure);
             }
         };
         return new ResultAsync(run());
@@ -477,6 +578,8 @@ export function createAiSdkProvider(deps) {
                 // fresh window under the retry policy of a connection error.
                 if (first.kind === "aborted")
                     throw abortedStreamFailure(signal, first.reason, requestTimeoutMs);
+                if (first.kind === "failed")
+                    throw streamPartFailure(first.error);
                 if (first.kind === "end") {
                     // A doStream promise rejection — the shape a real connection
                     // failure takes — does NOT surface at this first pull: streamText
@@ -522,6 +625,8 @@ export function createAiSdkProvider(deps) {
                 // terminal `ProviderError` from the throwable.
                 if (pull.kind === "aborted")
                     throw abortedStreamFailure(signal, pull.reason, requestTimeoutMs);
+                if (pull.kind === "failed")
+                    throw streamPartFailure(pull.error);
                 text += pull.text;
                 yield { type: "text-delta", text: pull.text };
             }
@@ -541,7 +646,9 @@ export function createAiSdkProvider(deps) {
         catch (e) {
             if (isAbortError(e) || signal?.aborted)
                 throw e;
-            throw toProviderError(unwrapForClassification(e), workloadOf(session));
+            const failure = toProviderError(unwrapForClassification(e), workloadOf(session));
+            logFailure(session, failure, e);
+            throw failure;
         }
     }
     // The provider advertises the guard limit on its own instance, thus a

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;

package/dist/sandbox/k8s-client.js

@@ -16,6 +16,8 @@ import { BatchV1Api, CoreV1Api, KubeConfig, } from "@kubernetes/client-node";
 import { ResultAsync, err, ok } from "neverthrow";
 import { trySandbox } from "./sandbox-error.js";
 import { buildMountPlan, buildSessionSubPaths } from "./mount-plan.js";
+import { threadLimitEnv } from "./thread-env.js";
+import { CPU_ONLINE_PATH, CPUINFO_PATH, cpuFiles, readHostCpuinfoOnce } from "./cpu-files.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 /** Read the originating HTTP status off any `SandboxError` variant that carries one. */
 function statusOf(e) {
@@ -24,6 +26,8 @@ function statusOf(e) {
 const SESSION_VOLUME_NAME = "session";
 const LIBS_VOLUME_NAME = "libs";
 const REFS_VOLUME_NAME = "refs";
+/** The ConfigMap volume that holds the two cpu files of the sandbox (`cpu-files.ts`). */
+const CPU_VOLUME_NAME = "cpu";
 const SANDBOX_SERVER_PORT = 8765;
 const POD_READY_TIMEOUT_MS = 5 * 60_000;
 const POD_POLL_INTERVAL_MS = 1_000;
@@ -59,6 +63,19 @@ export function sanitizeLabelValue(value) {
 function readOwnerWorkflowId(metadata) {
     return metadata?.annotations?.[OWNER_WORKFLOW_ANNOTATION] ?? null;
 }
+function deleteConfigMapIgnoreMissing(coreApi, namespace, name) {
+    return trySandbox(async () => {
+        await coreApi.deleteNamespacedConfigMap({ namespace, name });
+    }, (status, cause) => ({
+        type: "teardown_failed",
+        op: "k8s.teardown",
+        sandboxId: name,
+        status,
+        cause,
+    })).orElse((e) => 
+    // A 404 means the owner reference removed it with the Job already.
+    statusOf(e) === 404 ? ok(undefined) : err(e));
+}
 function deleteJobIgnoreMissing(batchApi, namespace, name) {
     return trySandbox(async () => {
         await batchApi.deleteNamespacedJob({
@@ -107,31 +124,32 @@ function workspaceSubPathFor(config, analysisId) {
     }
     return posix;
 }
-function buildJobSpec(meta, config, identity) {
+function buildJobSpec(meta, config, identity, cpu) {
     const { sandboxId } = identity;
     const plan = buildMountPlan(meta, {
         libs: !!config.libStorePvc,
         refs: !!config.refStorePvc,
     });
     const transport = config.transport ?? "poll";
-    const env = [
-        { name: "SANDBOX_TRANSPORT", value: transport },
+    const spec = meta.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.
+    const env = Object.entries({
+        SANDBOX_TRANSPORT: transport,
         // Poll mode never dials out, so the URL is omitted (matching the Docker
         // backend) — the pod spec itself then documents that no callback egress
         // is expected. sandbox-server neither reads nor requires it in poll mode.
-        ...(transport === "callback" ? [{ name: "CORTEX_BASE_URL", value: config.cortexBaseUrl }] : []),
-        { name: "SANDBOX_CALLBACK_SECRET", value: identity.callbackSecret },
-        ...Object.entries(plan.env).map(([name, value]) => ({ name, value })),
-        ...Object.entries(meta.extraEnv ?? {}).map(([k, v]) => ({
-            name: k,
-            value: v,
-        })),
-    ];
+        ...(transport === "callback" ? { CORTEX_BASE_URL: config.cortexBaseUrl } : {}),
+        SANDBOX_CALLBACK_SECRET: identity.callbackSecret,
+        ...threadLimitEnv(spec),
+        ...plan.env,
+        ...(meta.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
     // requests.cpu/memory. The CPU limit can throttle a hot step, but a throttle
     // beats an eviction.
-    const spec = meta.resources;
     const quantities = {
         cpu: String(spec.cpu),
         memory: `${spec.memoryGb}Gi`,
@@ -187,6 +205,16 @@ function buildJobSpec(meta, config, identity) {
             readOnly: true,
         });
     }
+    // The cpu files ride in a ConfigMap named after the Job (`ensureCpuConfigMap`).
+    // A `subPath` mount of one key over one kernel path is accepted by the API
+    // server, the kubelet, and gVisor. Under gVisor the sandbox sees no cgroup
+    // at all, thus these two files are the only source of the quota for
+    // `parallel::detectCores()` and `os.cpu_count()`.
+    volumes.push({ name: CPU_VOLUME_NAME, configMap: { name: sandboxId } });
+    volumeMounts.push({ name: CPU_VOLUME_NAME, mountPath: CPU_ONLINE_PATH, subPath: "online", readOnly: true });
+    if (cpu.hasCpuinfo) {
+        volumeMounts.push({ name: CPU_VOLUME_NAME, mountPath: CPUINFO_PATH, subPath: "cpuinfo", readOnly: true });
+    }
     const podSpec = {
         automountServiceAccountToken: false,
         restartPolicy: "Never",
@@ -357,6 +385,9 @@ function waitForJobGone(batchApi, namespace, name) {
  * means an (astronomically rare) name collision with a *different* step —
  * adopting its pod would HMAC-fail every callback, and deleting its Job would
  * kill a live sibling. Refuse loudly instead.
+ *
+ * The result is the uid of the Job that the pod belongs to, for the owner
+ * reference of the cpu ConfigMap.
  */
 function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflowId, job) {
     const createFailed = (status, cause) => ({
@@ -369,7 +400,7 @@ function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflow
     return new ResultAsync((async () => {
         const created = await trySandbox(() => batchApi.createNamespacedJob({ namespace, body: job }), createFailed);
         if (created.isOk())
-            return ok(undefined);
+            return ok(created.value?.metadata?.uid);
         if (statusOf(created.error) !== 409)
             return err(created.error);
         const existingRead = await trySandbox(() => batchApi.readNamespacedJob({ namespace, name: sandboxId }), createFailed);
@@ -397,20 +428,92 @@ function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflow
             const recreated = await trySandbox(() => batchApi.createNamespacedJob({ namespace, body: job }), createFailed);
             if (recreated.isErr())
                 return err(recreated.error);
+            return ok(recreated.value?.metadata?.uid);
         }
+        return ok(existingRead.value.metadata?.uid);
+    })());
+}
+/**
+ * Make the cpu ConfigMap of a Job, or bring an existing one up to date.
+ *
+ * The ConfigMap comes after the Job, because the Job is its owner. Thus the
+ * TTL of the Job and a Foreground delete both remove the ConfigMap with it.
+ * The pod waits at its mount until the ConfigMap exists, and that wait is
+ * shorter than the schedule of the pod.
+ *
+ * A `409 AlreadyExists` is the recovery re-run of the spawn step, or a
+ * ConfigMap whose prior owner Job is not yet collected. Both cases get the
+ * same data and the current owner through a replace.
+ */
+function ensureCpuConfigMap(coreApi, namespace, sandboxId, jobUid, files) {
+    const createFailed = (status, cause) => ({
+        type: "container_create_failed",
+        op: "k8s.createNamespacedConfigMap",
+        sandboxId,
+        status,
+        cause,
+    });
+    const body = {
+        apiVersion: "v1",
+        kind: "ConfigMap",
+        metadata: {
+            name: sandboxId,
+            namespace,
+            labels: {
+                [MANAGED_BY_LABEL]: MANAGED_BY_VALUE,
+                role: "sandbox",
+                "cortex/sandbox-id": sandboxId,
+            },
+            ...(jobUid !== undefined && {
+                ownerReferences: [{ apiVersion: "batch/v1", kind: "Job", name: sandboxId, uid: jobUid }],
+            }),
+        },
+        data: {
+            online: files.online,
+            ...(files.cpuinfo !== undefined && { cpuinfo: files.cpuinfo }),
+        },
+    };
+    return new ResultAsync((async () => {
+        const created = await trySandbox(() => coreApi.createNamespacedConfigMap({ namespace, body }), createFailed);
+        if (created.isOk())
+            return ok(undefined);
+        if (statusOf(created.error) !== 409)
+            return err(created.error);
+        const existing = await trySandbox(() => coreApi.readNamespacedConfigMap({ namespace, name: sandboxId }), createFailed);
+        if (existing.isErr())
+            return err(existing.error);
+        const replaced = await trySandbox(() => coreApi.replaceNamespacedConfigMap({
+            namespace,
+            name: sandboxId,
+            body: { ...body, metadata: { ...body.metadata, resourceVersion: existing.value.metadata?.resourceVersion } },
+        }), createFailed);
+        if (replaced.isErr())
+            return err(replaced.error);
         return ok(undefined);
     })());
 }
 export function createK8sSandboxOps(config) {
     const { batchApi, coreApi } = config.batchApi && config.coreApi ? { batchApi: config.batchApi, coreApi: config.coreApi } : buildKubeApi();
+    const readHostCpuinfo = config.readHostCpuinfo ?? readHostCpuinfoOnce;
     return {
         createSandbox(meta, identity) {
             return new ResultAsync((async () => {
                 const { sandboxId } = identity;
-                const job = buildJobSpec(meta, config, identity);
+                // The same floor as `threadLimitEnv`: a fraction of a core still
+                // keeps one thread busy, and a count of zero is not representable.
+                const threads = Math.max(1, Math.floor(meta.resources.cpu));
+                const files = cpuFiles(threads, await readHostCpuinfo());
+                const job = buildJobSpec(meta, config, identity, { hasCpuinfo: files.cpuinfo !== undefined });
                 const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, meta.childWorkflowId, job);
                 if (adopted.isErr())
                     return err(adopted.error);
+                const cpuMap = await ensureCpuConfigMap(coreApi, config.namespace, sandboxId, adopted.value, files);
+                if (cpuMap.isErr()) {
+                    // A pod whose ConfigMap never comes stays at ContainerCreating
+                    // until the ready wait expires. Fail now, with the real cause.
+                    await cleanupFailedJob(batchApi, coreApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
+                    return err(cpuMap.error);
+                }
                 // A Job whose pod never schedules (quota rejection, no nodes, spot
                 // reclaim) is reaped by neither backoffLimit (an admission rejection
                 // creates no pod to count) nor ttlSecondsAfterFinished (the Job never
@@ -434,20 +537,22 @@ export function createK8sSandboxOps(config) {
                         cause,
                     }));
                     if (registered.isErr()) {
-                        await cleanupFailedJob(batchApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
+                        await cleanupFailedJob(batchApi, coreApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
                         return err(registered.error);
                     }
                     return ok(ref);
                 }
-                await cleanupFailedJob(batchApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
+                await cleanupFailedJob(batchApi, coreApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
                 return err(ready.error);
             })());
         },
+        // The owner reference removes the cpu ConfigMap with the Job. The explicit
+        // delete covers a ConfigMap that got no owner, and it is a no-op on 404.
         teardown(ref) {
-            return deleteJobIgnoreMissing(batchApi, config.namespace, ref.sandboxId);
+            return deleteJobIgnoreMissing(batchApi, config.namespace, ref.sandboxId).andThen(() => deleteConfigMapIgnoreMissing(coreApi, config.namespace, ref.sandboxId));
         },
         teardownById(sandboxId) {
-            return deleteJobIgnoreMissing(batchApi, config.namespace, sandboxId);
+            return deleteJobIgnoreMissing(batchApi, config.namespace, sandboxId).andThen(() => deleteConfigMapIgnoreMissing(coreApi, config.namespace, sandboxId));
         },
         listManagedSandboxes() {
             return trySandbox(() => batchApi.listNamespacedJob({
@@ -508,9 +613,13 @@ export function createK8sSandboxOps(config) {
  * matters; a delete error here is logged and swallowed so it never masks the
  * create error returned to the caller.
  */
-async function cleanupFailedJob(batchApi, namespace, sandboxId, logger) {
+async function cleanupFailedJob(batchApi, coreApi, namespace, sandboxId, logger) {
     const deleted = await deleteJobIgnoreMissing(batchApi, namespace, sandboxId);
     if (deleted.isErr()) {
         logger.named("k8s-client").error("failed to delete Job after startup failure", { sandboxId, err: deleted.error });
     }
+    const deletedMap = await deleteConfigMapIgnoreMissing(coreApi, namespace, sandboxId);
+    if (deletedMap.isErr()) {
+        logger.named("k8s-client").error("failed to delete cpu ConfigMap after startup failure", { sandboxId, err: deletedMap.error });
+    }
 }

package/dist/sandbox/thread-env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Thread-count env for a sandbox container.
+ *
+ * Each backend turns the `ResourceSpec` of a step into a hard cgroup limit:
+ * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s. A
+ * cgroup quota is invisible to most runtimes inside it. `parallel::detectCores()`
+ * greps `/proc/cpuinfo`, and `os.cpu_count()` reads
+ * `/sys/devices/system/cpu/online`. Both files describe the host. Thus a step
+ * with 2 CPUs on a host of 12 cores forks 12 workers into a cgroup of 2 CPUs,
+ * and each fork copies its working set until the memory limit stops it.
+ *
+ * The env below publishes the quota to each library that reads a thread count
+ * from the environment. `parallelly::availableCores()` and `joblib.cpu_count()`
+ * read the cgroup quota on their own, thus they need no value here.
+ *
+ * `MC_CORES` is absent on purpose. R defaults `mclapply` to 2 workers, not to
+ * the core count. A value there raises the fork count instead of a decrease.
+ */
+import type { ResourceSpec } from "../config/resource-limits.js";
+/**
+ * Env that binds each parallel library in the container to `spec.cpu`.
+ *
+ * A fractional CPU request floors to one thread. A pool of zero is not
+ * representable, and two threads on half a core only add context switches.
+ *
+ * The caller puts these before `plan.env` and before the `extraEnv` of the
+ * embedder, thus a host that knows more about a step keeps the last word.
+ */
+export declare function threadLimitEnv(spec: ResourceSpec): Record<string, string>;

package/dist/sandbox/thread-env.js

@@ -0,0 +1,49 @@
+/**
+ * Thread-count env for a sandbox container.
+ *
+ * Each backend turns the `ResourceSpec` of a step into a hard cgroup limit:
+ * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s. A
+ * cgroup quota is invisible to most runtimes inside it. `parallel::detectCores()`
+ * greps `/proc/cpuinfo`, and `os.cpu_count()` reads
+ * `/sys/devices/system/cpu/online`. Both files describe the host. Thus a step
+ * with 2 CPUs on a host of 12 cores forks 12 workers into a cgroup of 2 CPUs,
+ * and each fork copies its working set until the memory limit stops it.
+ *
+ * The env below publishes the quota to each library that reads a thread count
+ * from the environment. `parallelly::availableCores()` and `joblib.cpu_count()`
+ * read the cgroup quota on their own, thus they need no value here.
+ *
+ * `MC_CORES` is absent on purpose. R defaults `mclapply` to 2 workers, not to
+ * the core count. A value there raises the fork count instead of a decrease.
+ */
+/**
+ * Env that binds each parallel library in the container to `spec.cpu`.
+ *
+ * A fractional CPU request floors to one thread. A pool of zero is not
+ * representable, and two threads on half a core only add context switches.
+ *
+ * The caller puts these before `plan.env` and before the `extraEnv` of the
+ * embedder, thus a host that knows more about a step keeps the last word.
+ */
+export function threadLimitEnv(spec) {
+    const threads = String(Math.max(1, Math.floor(spec.cpu)));
+    return {
+        // OpenMP: the compiled code of R and Python packages.
+        OMP_NUM_THREADS: threads,
+        // OpenBLAS keeps a private pool. A pthread build reads this name first.
+        OPENBLAS_NUM_THREADS: threads,
+        // MKL reads this name before OMP_NUM_THREADS.
+        MKL_NUM_THREADS: threads,
+        // BiocParallel sizes `bpparam()` from this name. DESeq2 `parallel=TRUE`
+        // and the other Bioconductor packages size their workers from `bpparam()`.
+        BIOCPARALLEL_WORKER_NUMBER: threads,
+        // data.table defaults to half of the host cores.
+        R_DATATABLE_NUM_THREADS: threads,
+        // The Python numerical stack.
+        NUMBA_NUM_THREADS: threads,
+        NUMEXPR_MAX_THREADS: threads,
+        LOKY_MAX_CPU_COUNT: threads,
+        POLARS_MAX_THREADS: threads,
+        RAYON_NUM_THREADS: threads,
+    };
+}

package/dist/state/data-profile.d.ts

@@ -171,6 +171,41 @@ export declare function reconcileOrphanedDataProfile(pool: Querier, analysisId:
  * finds no running row to stamp and no-ops instead of re-seeding the cleared one.
  */
 export declare function clearDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * Stamp a row `completed` with no result, because the analysis has no input files.
+ *
+ * A profile describes files. An analysis with no files has nothing to describe, and
+ * thus the profile is complete at once: no claim into `running`, no workflow, and no
+ * sandbox. The write is a terminal write like {@link completeDataProfile}, but it starts
+ * from a settled row or an empty row, not from a `running` one. As a result
+ * `data_profile_started_at` and `data_profile_completed_at` carry the same instant, and
+ * `data_profile_workflow_id` stays NULL, because no stream is addressable (see
+ * {@link recordDataProfileWorkflowId}).
+ *
+ * The seed is written as `[]`, so the completed row names the set that it covers: the
+ * empty set. A `completed` row with a NULL seed stays forbidden (see
+ * {@link completeDataProfile}). A prior `data_profile_result` is replaced with NULL,
+ * because it describes files that the analysis no longer has. A prior `failed` row is
+ * replaced too, because the set that failed is gone.
+ *
+ * Two guards ride in the CAS:
+ * - `IS DISTINCT FROM 'running'`: a live workflow owns the row, and its terminal write
+ *   must not land on a row that this write moved. The same reason as
+ *   {@link clearDataProfile}.
+ * - {@link UNSEEDED}: the row names no file. A seed upsert that lands between a caller's
+ *   pre-read and this write makes the row a seeded, startable row. A `completed` stamp
+ *   over it would hide those files behind a finished profile. The CAS refuses that row,
+ *   and the caller reads the status again to name the cause.
+ *
+ * The rerun claim carries {@link SEEDED}, so a completed-empty row is not claimable until
+ * a later seed upsert names files. Then `tryRerunDataProfile` takes it, the same as any
+ * completed row.
+ *
+ * `ok(true)` when this call stamped the row. `ok(false)` when the guard refused it: no
+ * such analysis, a live run, or a seed that names files. A refusal stays in the ok
+ * channel, the same as the sibling CAS ops.
+ */
+export declare function completeEmptyDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
 /**
  * Load an analysis's data-profile ledger state. Returns `null` for BOTH miss
  * conditions, deliberately indistinguishable to consumers:

package/dist/state/data-profile.js

@@ -20,6 +20,13 @@ import { tryMutation, tryQuery } from "../lib/db-result.js";
  * and surfacing a hand-corrupted row as a `DbError` beats silently claiming it.
  */
 const SEEDED = "seed_input_file_ids IS NOT NULL AND jsonb_array_length(seed_input_file_ids) > 0";
+/**
+ * The negation of {@link SEEDED}: the row names no input file. A NULL seed and `[]`
+ * both name zero files, and {@link completeEmptyDataProfile} treats them the same.
+ * The two predicates are disjoint, so a claim into `running` and an empty-set
+ * completion can never both win on one row.
+ */
+const UNSEEDED = "(seed_input_file_ids IS NULL OR jsonb_array_length(seed_input_file_ids) = 0)";
 /**
  * Try to claim a startable row into `running`. Startable means `'pending'` (seeded,
  * not yet run) or NULL (no profile: never profiled, or cleared by `clearDataProfile`).
@@ -279,6 +286,55 @@ export function clearDataProfile(pool, analysisId) {
         return (result.rowCount ?? 0) > 0;
     });
 }
+/**
+ * Stamp a row `completed` with no result, because the analysis has no input files.
+ *
+ * A profile describes files. An analysis with no files has nothing to describe, and
+ * thus the profile is complete at once: no claim into `running`, no workflow, and no
+ * sandbox. The write is a terminal write like {@link completeDataProfile}, but it starts
+ * from a settled row or an empty row, not from a `running` one. As a result
+ * `data_profile_started_at` and `data_profile_completed_at` carry the same instant, and
+ * `data_profile_workflow_id` stays NULL, because no stream is addressable (see
+ * {@link recordDataProfileWorkflowId}).
+ *
+ * The seed is written as `[]`, so the completed row names the set that it covers: the
+ * empty set. A `completed` row with a NULL seed stays forbidden (see
+ * {@link completeDataProfile}). A prior `data_profile_result` is replaced with NULL,
+ * because it describes files that the analysis no longer has. A prior `failed` row is
+ * replaced too, because the set that failed is gone.
+ *
+ * Two guards ride in the CAS:
+ * - `IS DISTINCT FROM 'running'`: a live workflow owns the row, and its terminal write
+ *   must not land on a row that this write moved. The same reason as
+ *   {@link clearDataProfile}.
+ * - {@link UNSEEDED}: the row names no file. A seed upsert that lands between a caller's
+ *   pre-read and this write makes the row a seeded, startable row. A `completed` stamp
+ *   over it would hide those files behind a finished profile. The CAS refuses that row,
+ *   and the caller reads the status again to name the cause.
+ *
+ * The rerun claim carries {@link SEEDED}, so a completed-empty row is not claimable until
+ * a later seed upsert names files. Then `tryRerunDataProfile` takes it, the same as any
+ * completed row.
+ *
+ * `ok(true)` when this call stamped the row. `ok(false)` when the guard refused it: no
+ * such analysis, a live run, or a seed that names files. A refusal stays in the ok
+ * channel, the same as the sibling CAS ops.
+ */
+export function completeEmptyDataProfile(pool, analysisId) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.completeEmptyDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'completed', data_profile_error = NULL,
+                data_profile_started_at = $1, data_profile_completed_at = $1,
+                data_profile_result = NULL, data_profile_workflow_id = NULL,
+                seed_input_file_ids = '[]'::jsonb
+            WHERE analysis_id = $2 AND data_profile_status IS DISTINCT FROM 'running' AND ${UNSEEDED}`,
+            values: [now, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
 /**
  * Load an analysis's data-profile ledger state. Returns `null` for BOTH miss
  * conditions, deliberately indistinguishable to consumers:

package/dist/state/index.d.ts

@@ -20,7 +20,7 @@ export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes,
 export type { ActiveSandboxRow } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
 export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
-export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileDimension, DataProfileGroup, DataProfileGroupSlot, DataProfileFile, DataProfileMemberAnnotation, DataProfileObservation, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileKind, DataProfileAxis, DataProfileInputSignature, DataProfileCoverage, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { createAnalysisPurge } from "./purge-analysis.js";

package/dist/state/index.js

@@ -14,7 +14,7 @@ setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
-export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 // Not per-entity: one analysis's whole Postgres footprint, reached from its id
 // alone, with the workflow ledger behind an injected seam.

package/dist/tasks/data-profile.d.ts

@@ -132,7 +132,16 @@ export declare function registerDataProfileWorkflow(deps: DataProfileDeps): (inp
  * 'failed' on error, and revokes the run authorization on every terminal path.
  */
 export declare function runDataProfileBody(input: DataProfileWorkflowInput, deps: DataProfileDeps): Promise<void>;
-export type DataProfileTriggerResult = "started" | "restarted" | "already_running" | "failed";
+/**
+ * What the trigger did:
+ * - `"started"`: a first profile claimed the row and a workflow runs.
+ * - `"restarted"`: a re-profile claimed a `completed` row and a workflow runs.
+ * - `"already_running"`: a workflow already owns the row, and nothing new ran.
+ * - `"completed"`: the analysis has no input files, so the row is `completed` at once
+ *   with no result. No workflow ran (see {@link completeEmptyDataProfile}).
+ * - `"failed"`: the trigger refused the call or faulted, and the row is unchanged.
+ */
+export type DataProfileTriggerResult = "started" | "restarted" | "already_running" | "completed" | "failed";
 /**
  * Route-side deps for triggering the data-profile workflow: the ledger pool,
  * the run authorizer, and the registered workflow callable. The body's
@@ -188,6 +197,12 @@ export declare function dataProfileWorkflowId(analysisId: string, nonce: string)
  * row is claimed by neither: retrying a failure is a deliberate act the caller drives
  * through `tryRetryDataProfile` + `runDataProfile`.
  *
+ * An analysis with no input files takes none of the claims. An empty manifest against
+ * a seed that names no file stamps the row `completed` at once, with no result and no
+ * workflow (see {@link completeEmptyDataProfile}), and the trigger returns
+ * `"completed"`. An empty manifest against a seed that names files is a divergence
+ * between the caller and the ledger, and the trigger refuses it.
+ *
  * Returns what happened, so the caller can surface it (e.g. in the seed response).
  */
 export declare function triggerDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<DataProfileTriggerResult>;

package/dist/tasks/data-profile.js

@@ -44,7 +44,7 @@ import { scanInputTree } from "../input-scan/scan.js";
 import { PROFILE_INDEX_TYPES, buildProfileIndexEntries } from "./data-profile-index.js";
 import { absorbRecipe, renderAbsorbDelta } from "./data-profile-absorb.js";
 import { formatResolutionErrors, resolveProfileSubmission } from "./data-profile-resolve.js";
-import { completeDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
+import { completeDataProfile, completeEmptyDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
 import { createProfileActivityEmitter } from "./data-profile-activity.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
 // The run literal is declared in `contracts/` — a consumer reads it back off recorded usage, and this
@@ -668,6 +668,12 @@ async function startDataProfileWorkflow(deps, params) {
  * row is claimed by neither: retrying a failure is a deliberate act the caller drives
  * through `tryRetryDataProfile` + `runDataProfile`.
  *
+ * An analysis with no input files takes none of the claims. An empty manifest against
+ * a seed that names no file stamps the row `completed` at once, with no result and no
+ * workflow (see {@link completeEmptyDataProfile}), and the trigger returns
+ * `"completed"`. An empty manifest against a seed that names files is a divergence
+ * between the caller and the ledger, and the trigger refuses it.
+ *
  * Returns what happened, so the caller can surface it (e.g. in the seed response).
  */
 export async function triggerDataProfile(deps, params) {
@@ -682,17 +688,32 @@ export async function triggerDataProfile(deps, params) {
         // `loadSeedInputFileIds`, which returns null for BOTH a missing analysis row and
         // a NULL-seed row (`loadDataProfileStatus` would hide the seed of a cleared row).
         const seeded = unwrapOrThrow(await loadSeedInputFileIds(deps.pool, analysisId));
-        if (seeded === null || seeded.length === 0) {
-            logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
+        if (params.stagedInputs.length === 0) {
+            // The trigger validates the manifest it is about to dispatch against the ledger
+            // seed. A seeded row profiled against an EMPTY manifest would claim `running` and
+            // then hit the body's empty-manifest path, and complete with a NULL result while
+            // the seed still names files. Refuse the divergence before any claim.
+            if (seeded !== null && seeded.length > 0) {
+                logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
+                return "failed";
+            }
+            // The analysis has no input files, so there is nothing to profile. The row is
+            // `completed` at once, with no workflow. The CAS carries the same seed
+            // predicate as this pre-read, so a seed upsert that lands in between cannot be
+            // hidden behind a finished profile: the stamp refuses, and the status read
+            // below names the cause.
+            if (unwrapOrThrow(await completeEmptyDataProfile(deps.pool, analysisId)))
+                return "completed";
+            const current = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
+            if (current?.status === "running")
+                return "already_running";
+            logger.error("trigger rejected: empty-set completion refused (no analysis row, or the seed now names files)");
             return "failed";
         }
-        // The trigger validates the ledger seed above; it must also validate the manifest
-        // it is about to dispatch. A seeded row profiled against an EMPTY manifest would
-        // claim `running` and then hit the body's empty-manifest path — completing with a
-        // NULL result while the seed still names files, an incoherence a staleness policy
-        // then loops on re-triggering. Refuse the divergence before any claim.
-        if (params.stagedInputs.length === 0) {
-            logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
+        // A non-empty manifest against a seed that names no file: the caller skipped the
+        // seed, or the analysis row is missing. Name the cause before any claim.
+        if (seeded === null || seeded.length === 0) {
+            logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
             return "failed";
         }
         const started = unwrapOrThrow(await tryStartDataProfile(deps.pool, analysisId));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.30.1",
+    "version": "0.30.3",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",