@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/runtime/boot.js

@@ -2,7 +2,7 @@
  * `bootHarness` — the harness-owned boot sequence.
  *
  * `assembleCoreRuntime` stays sync and pure (it is the register-before-launch
- * cohort SOT, driven by tests on `passthroughStep`). `bootHarness` wraps it with
+ * cohort SOT, driven by tests outside a workflow). `bootHarness` wraps it with
  * the ordered, effectful boot steps every host must run in the same order, and
  * returns a `shutdown` handle the embedder wires to its process signals. The
  * ordering is load-bearing and runs cheapest-failure-first:

package/dist/runtime/connection-budget.d.ts

@@ -20,20 +20,20 @@
  * Runs after `launchDbos` and before the HTTP listener accepts traffic so a
  * misconfigured pod fails boot loudly instead of degrading under load.
  */
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import type { Logger } from "../lib/logger.js";
 /**
  * Narrow config slice the budget guard reads — only the optional app-pool
  * size override. Composition roots map `Env.DB_POOL_MAX` onto this.
  */
-export interface ConnectionBudgetConfig {
+export type ConnectionBudgetConfig = {
     readonly poolMax?: string;
-}
-export interface AssertConnectionBudgetOptions {
-    pool: Pool;
+};
+export type AssertConnectionBudgetOptions = {
+    pool: Querier;
     logger: Logger;
     config: ConnectionBudgetConfig;
-}
+};
 /**
  * Verify a single pod's pool footprint fits inside pg `max_connections`.
  * Throws on shortfall — the caller must abort boot. Returns the per-pod

package/dist/runtime/connection-budget.js

@@ -31,7 +31,7 @@ export async function assertConnectionBudget({ pool, logger, config }) {
     const dbosPoolSize = DBOS_SYSTEM_POOL_SIZE;
     const podFootprint = appPoolSize + dbosPoolSize;
     const { rows } = await pool.query("SELECT current_setting('max_connections') AS max");
-    const maxConnections = parseInt(rows[0].max, 10);
+    const maxConnections = parseInt(rows[0]?.max ?? "0", 10);
     if (podFootprint + SAFETY_MARGIN > maxConnections) {
         throw new Error(`FATAL: pg max_connections (${maxConnections}) cannot hold one pod's pool footprint ` +
             `(${podFootprint}) = app=${appPoolSize} + dbos=${dbosPoolSize}, plus margin=${SAFETY_MARGIN}. ` +

package/dist/runtime/dbos.d.ts

@@ -1,25 +1,15 @@
 /**
- * DBOS Transact bootstrap.
- *
- * This is the only module that imports `@dbos-inc/dbos-sdk` directly. The
- * agent loop and routes depend on the `RunStep` shape (`harness/loop/types.ts`),
- * so DBOS stays swappable and the chat path never reaches into the workflow
- * runtime. `harness/loop/run-step.ts` wraps `DBOS.runStep` for the durable
- * variant; nothing else here.
- *
- * Launch is dormant — this change registers no workflows. The durability seam
- * exists; the engine is running; nothing is durable yet.
- *
- * See `openspec/changes/harness-dbos-runtime`.
+ * DBOS Transact bootstrap: the config of the engine, its launch, the
+ * schedules of the scheduled workflows, and its shutdown.
  */
 import { type DBOSConfig, type DLogger } from "@dbos-inc/dbos-sdk";
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import type { Logger } from "../lib/logger.js";
 /**
  * Narrow config slice the DBOS bootstrap reads. Composition roots map their
  * validated `Env` onto this and pass the executor id in (the harness reads no env).
  */
-export interface DbosConfig {
+export type DbosConfig = {
     readonly dbHost: string;
     readonly dbPort: string;
     readonly dbName: string;
@@ -28,7 +18,6 @@ export interface DbosConfig {
     readonly dbSslMode: "disable" | "require" | "verify-ca" | "verify-full";
     readonly appName: string;
     readonly applicationVersion?: string;
-    readonly adminPort: string;
     /** Stable per-pod executor id (e.g. `process.env.HOSTNAME ?? "local-dev"`). */
     readonly executorId: string;
     /**
@@ -66,12 +55,12 @@ export interface DbosConfig {
      * new root trace, with no link to the trace of the original execution.
      */
     readonly tracingEnabled?: boolean;
-}
+};
 /** DBOS lifecycle facts a host's readiness probe reports on. */
-export interface DbosState {
+export type DbosState = {
     launched: boolean;
     recoveryStarted: boolean;
-}
+};
 /**
  * Bridge the SDK's internal logger onto the harness `Logger` seam, so the
  * SDK's own lines (`Recovering N workflows…`, migration chatter) land in the
@@ -88,6 +77,27 @@ export declare function dbosSdkLogger(logger: Logger, logLevel: string | undefin
  * assert on the mapping without a launch.
  */
 export declare function dbosSdkConfig(config: DbosConfig, logger: Logger): DBOSConfig;
+/**
+ * Whether a failure ends the execution because it no longer owns its workflow. A
+ * cancel raises `DBOSWorkflowCancelledError` at the next operation. A cancel that
+ * lands while a step runs clears the owner of the workflow, and the record of the
+ * step then raises `DBOSWorkflowConflictError`. Neither execution may write a
+ * terminal state, thus each one leaves with the error.
+ */
+export declare function isWorkflowCancellation(err: unknown): boolean;
+/** One scheduled workflow: a registered workflow, and the crontab that starts it. */
+export type WorkflowSchedule = {
+    readonly scheduleName: string;
+    readonly workflowFn: () => Promise<void>;
+    /** A crontab with an optional leading field for the seconds. */
+    readonly schedule: string;
+};
+/**
+ * Schedule a registered workflow. DBOS stores a schedule in its system database,
+ * and it accepts one only after the launch, thus `launchDbos` applies each
+ * schedule of this list. A second call with the same name replaces the first.
+ */
+export declare function scheduleWorkflow(schedule: WorkflowSchedule): void;
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.
@@ -126,7 +136,7 @@ export declare function shutdownDbos({ logger: injected }: {
  * DB is the same database as the app pool, so the pool reaches it directly.
  */
 export declare function sweepEphemeralWorkflows({ pool, logger: injectedLogger, executorId, }: {
-    pool: Pool;
+    pool: Querier;
     logger: Logger;
     /** Stable per-pod executor id — must match `launchDbos`'s `executorId`. */
     executorId: string;

package/dist/runtime/dbos.js

@@ -1,18 +1,11 @@
 /**
- * DBOS Transact bootstrap.
- *
- * This is the only module that imports `@dbos-inc/dbos-sdk` directly. The
- * agent loop and routes depend on the `RunStep` shape (`harness/loop/types.ts`),
- * so DBOS stays swappable and the chat path never reaches into the workflow
- * runtime. `harness/loop/run-step.ts` wraps `DBOS.runStep` for the durable
- * variant; nothing else here.
- *
- * Launch is dormant — this change registers no workflows. The durability seam
- * exists; the engine is running; nothing is durable yet.
- *
- * See `openspec/changes/harness-dbos-runtime`.
+ * DBOS Transact bootstrap: the config of the engine, its launch, the
+ * schedules of the scheduled workflows, and its shutdown.
  */
-import { DBOS } from "@dbos-inc/dbos-sdk";
+import { z } from "zod";
+import { textOf } from "../lib/unknown-text.js";
+import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import { presentGet } from "../lib/present.js";
 import { DBOS_SYSTEM_POOL_SIZE } from "./pools.js";
 import { errRecipe, okRecipe } from "./result-serialization.js";
 const state = {
@@ -69,16 +62,16 @@ const SDK_DEFAULT_LOG_LEVEL = "info";
  */
 export function dbosSdkLogger(logger, logLevel) {
     const sink = logger.named("sdk");
-    const threshold = SDK_LOG_LEVEL_RANK[logLevel ?? SDK_DEFAULT_LOG_LEVEL] ?? SDK_LOG_LEVEL_RANK[SDK_DEFAULT_LOG_LEVEL];
-    const passes = (level) => SDK_LOG_LEVEL_RANK[level] <= threshold;
+    const threshold = SDK_LOG_LEVEL_RANK[logLevel ?? SDK_DEFAULT_LOG_LEVEL] ?? presentGet(SDK_LOG_LEVEL_RANK, SDK_DEFAULT_LOG_LEVEL, "the default log-level rank");
+    const passes = (level) => presentGet(SDK_LOG_LEVEL_RANK, level, "the log-level rank") <= threshold;
     const fields = (metadata) => {
         const attributes = metadata?.span?.attributes;
         const stack = metadata?.stack;
         if (attributes === undefined && stack === undefined)
             return undefined;
-        return { ...attributes, ...(stack !== undefined ? { stack } : {}) };
+        return { ...attributes, stack };
     };
-    const message = (entry) => (typeof entry === "string" ? entry : String(entry));
+    const message = (entry) => (typeof entry === "string" ? entry : textOf(entry));
     return {
         debug: (entry, metadata) => {
             if (passes("debug"))
@@ -109,13 +102,34 @@ export function dbosSdkConfig(config, logger) {
         systemDatabasePoolSize: DBOS_SYSTEM_POOL_SIZE,
         executorID: config.executorId,
         applicationVersion: config.applicationVersion,
-        adminPort: parseInt(config.adminPort, 10),
+        // With no version from the host, DBOS keeps the one version `PATCHING_ENABLED` across upgrades, thus a paused
+        // workflow recovers after an upgrade. A change of the operations of a workflow body goes behind `DBOS.patch`.
+        enablePatching: true,
         logLevel: config.logLevel,
         logger: dbosSdkLogger(logger, config.logLevel),
         tracingEnabled: config.tracingEnabled ?? false,
         otelAttributeFormat: "semconv",
     };
 }
+/**
+ * Whether a failure ends the execution because it no longer owns its workflow. A
+ * cancel raises `DBOSWorkflowCancelledError` at the next operation. A cancel that
+ * lands while a step runs clears the owner of the workflow, and the record of the
+ * step then raises `DBOSWorkflowConflictError`. Neither execution may write a
+ * terminal state, thus each one leaves with the error.
+ */
+export function isWorkflowCancellation(err) {
+    return err instanceof DBOSErrors.DBOSWorkflowCancelledError || err instanceof DBOSErrors.DBOSWorkflowConflictError;
+}
+const pendingSchedules = new Map();
+/**
+ * Schedule a registered workflow. DBOS stores a schedule in its system database,
+ * and it accepts one only after the launch, thus `launchDbos` applies each
+ * schedule of this list. A second call with the same name replaces the first.
+ */
+export function scheduleWorkflow(schedule) {
+    pendingSchedules.set(schedule.scheduleName, schedule);
+}
 let resultRecipesRegistered = false;
 /**
  * DBOS refuses a registration after the launch, and the registry of SuperJSON
@@ -146,12 +160,13 @@ export async function launchDbos({ config, logger: injected }) {
     registerResultSerialization();
     const start = performance.now();
     await DBOS.launch();
+    if (pendingSchedules.size > 0)
+        await DBOS.applySchedules([...pendingSchedules.values()]);
     state.launched = true;
     state.recoveryStarted = true;
     logger.info("launched", {
         executorID: sdkConfig.executorID,
         applicationVersion: config.applicationVersion,
-        adminPort: sdkConfig.adminPort,
         tracingEnabled: sdkConfig.tracingEnabled,
         durationMs: Math.round(performance.now() - start),
     });
@@ -215,7 +230,7 @@ export async function sweepEphemeralWorkflows({ pool, logger: injectedLogger, ex
     }
     catch (err) {
         // First-ever boot: DBOS has not created its schema yet — nothing to sweep.
-        if (err && typeof err === "object" && "code" in err && err.code === "42P01") {
+        if (z.object({ code: z.literal("42P01") }).safeParse(err).success) {
             return;
         }
         logger.error("legacy ephemeral-row sweep failed", { executorID, ...logger.errorFields(err) });

package/dist/runtime/result-serialization.js

@@ -15,22 +15,35 @@
  * inside the step, before the checkpoint.
  */
 import { Err, Ok, err, ok } from "neverthrow";
+import { z } from "zod";
+import { parseJsonAs } from "../lib/parse-json.js";
+import { errorOf } from "../lib/thrown.js";
 /**
  * The JSON form of the value inside a `Result`, with the rules of
  * `JSON.stringify`. An `Error` becomes `{ name, message }`, because
  * `JSON.stringify` gives `{}` for one. A `bigint` becomes its decimal text,
  * because `JSON.stringify` throws on one.
  */
-function toJson(value) {
-    const text = JSON.stringify(value, (_key, v) => {
-        if (v instanceof Error)
-            return { name: v.name, message: v.message };
+/**
+ * The stringify with the Error and bigint replacer. The declared return is honest where
+ * the lib signature lies: the format gives back `undefined` for a value it cannot hold.
+ */
+function stringifyJson(value) {
+    return JSON.stringify(value, (_key, v) => {
+        const error = errorOf(v);
+        if (error !== undefined)
+            return { name: error.name, message: error.message };
         if (typeof v === "bigint")
             return v.toString();
         return v;
     });
-    return text === undefined ? undefined : JSON.parse(text);
 }
+function toJson(value) {
+    const text = stringifyJson(value);
+    // The stringify round-trip holds only JSON values, so the parse cannot refuse.
+    return text === undefined ? undefined : parseJsonAs(text, JsonSchema);
+}
+const JsonSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(JsonSchema), z.record(z.string(), JsonSchema)]));
 export const okRecipe = {
     name: "neverthrow.Ok",
     isApplicable: (v) => v instanceof Ok,

package/dist/runtime/shutdown.d.ts

@@ -19,7 +19,7 @@
  * any single step's failure.
  */
 import type { Logger } from "../lib/logger.js";
-export interface ShutdownDeps {
+export type ShutdownDeps = {
     signal: string;
     logger: Logger;
     markDraining: () => void;
@@ -29,5 +29,5 @@ export interface ShutdownDeps {
     flushLogger: () => Promise<void>;
     shutdownOtel: () => Promise<void>;
     exit: (code: number) => void;
-}
+};
 export declare function runShutdownSequence(deps: ShutdownDeps): Promise<void>;

package/dist/sandbox/client.d.ts

@@ -21,7 +21,7 @@ import type { ResultAsync } from "neverthrow";
 import type { SpawnSession } from "../auth/types.js";
 import type { SandboxError } from "./sandbox-error.js";
 import type { ExecEmit, ExecRequest, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxSpec, ToolchainSource } from "./types.js";
-export interface SandboxClient {
+export type SandboxClient = {
     /**
      * The declared owner of the sandbox toolchain, as the client was composed
      * with it: `"image"` when the config declared it, `"store"` when the config
@@ -59,11 +59,15 @@ export interface SandboxClient {
      * same step gets the same id, and the sandbox gives it the result of the
      * first. Outside a workflow it throws.
      *
+     * `execId` replaces that id. A caller that runs more than one exec in one
+     * step, or an exec outside a workflow, gives its own id
+     * (`sandbox/step-sandbox.ts`).
+     *
      * A recovered step submits again under the same id. The sandbox dedups the
      * submit on the id, thus the poll attaches to the exec that already ran or
      * runs, and `emit` sees its events again from the start.
      */
-    exec(ref: SandboxRef, request: ExecRequest, emit: ExecEmit, deadline: number): Promise<ExecResult>;
+    exec(ref: SandboxRef, request: ExecRequest, emit: ExecEmit, deadline: number, execId?: string): Promise<ExecResult>;
     /**
      * Per-sandbox-machine liveness. `alive: false` only when observably dead
      * (terminal pod phase, missing container); `oomKilled` marks a death the
@@ -99,4 +103,4 @@ export interface SandboxClient {
      * ref the caller already holds; this one finds machines Cortex has forgotten.
      */
     listManagedSandboxes(): Promise<ManagedSandbox[]>;
-}
+};

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

@@ -17,7 +17,7 @@
 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 {
+export type CpuFiles = {
     /** Content of `/sys/devices/system/cpu/online`: `0` for one thread, else the range `0-<n-1>`. */
     readonly online: string;
     /**
@@ -25,7 +25,7 @@ export interface CpuFiles {
      * 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.
  *

package/dist/sandbox/cpu-files.js

@@ -14,6 +14,7 @@
  * the content in a ConfigMap and mounts each key with `subPath`.
  */
 import { readFile } from "node:fs/promises";
+import { splitLines } from "../lib/text.js";
 /** 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";
@@ -33,10 +34,26 @@ export function readHostCpuinfoOnce() {
  * 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));
+    const blocks = [];
+    let block = [];
+    for (const line of splitLines(cpuinfo)) {
+        if (line.trim() === "") {
+            if (block.length > 0)
+                blocks.push(block.join("\n"));
+            block = [];
+            continue;
+        }
+        block.push(line);
+    }
+    if (block.length > 0)
+        blocks.push(block.join("\n"));
+    return blocks.filter(hasProcessorLine);
+}
+function hasProcessorLine(block) {
+    return splitLines(block).some((line) => line.startsWith("processor") && !isWordChar(line.charAt("processor".length)));
+}
+function isWordChar(char) {
+    return (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || (char >= "0" && char <= "9") || char === "_";
 }
 /**
  * The content of the two cpu files for `threads` cpus.

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

@@ -12,11 +12,10 @@
  * backend-agnostic — it only needs the SandboxRef.
  */
 import type { V1Toleration } from "@kubernetes/client-node";
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import type { Logger } from "../lib/logger.js";
 import { type ResourceLimits } from "../config/resource-limits.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
-import { clearSandboxRef } from "../state/index.js";
 import type { SandboxClient } from "./client.js";
 import { type ExecDeps } from "./exec.js";
 import { type MountPlanCoords } from "./mount-plan.js";
@@ -26,13 +25,13 @@ import type { FarmSource, ResolveSandboxLabels, ToolchainSource } from "./types.
  * default and the K8s namespace fallback. Composition roots map their
  * validated `Env` onto this.
  */
-export interface SandboxBackendConfig {
+export type SandboxBackendConfig = {
     readonly backend: "docker" | "k8s";
     readonly namespace: string;
-}
-export interface CreateSandboxClientConfig {
+};
+export type CreateSandboxClientConfig = {
     /** App pool — used for registry writes inside the create/teardown steps. */
-    pool: Pool;
+    pool: Querier;
     /** Backend default + namespace fallback source. */
     env: SandboxBackendConfig;
     /** Default sandbox-base image when the workflow doesn't override per-step. */
@@ -150,7 +149,7 @@ export interface CreateSandboxClientConfig {
      * An `isAlive` here wins over the backend inspect that the client wires.
      */
     execDeps?: ExecDeps;
-}
+};
 /**
  * Backend-agnostic pre-creation of the writable tree under the analysis's
  * resolved workspace root. On Docker that root is the host dir the container
@@ -177,4 +176,4 @@ export declare function precreateStepTree(deps: {
 }, coords: MountPlanCoords): Promise<void>;
 export declare function createSandboxClient(config: CreateSandboxClientConfig): SandboxClient;
 /** Re-exports so consumers import once from this module. */
-export { clearSandboxRef };
+export { clearSandboxRef } from "../state/index.js";

package/dist/sandbox/create-sandbox.js

@@ -22,7 +22,7 @@ import { clampResources } from "../config/resource-limits.js";
 import { tailWritePrefix } from "../workspace/paths.js";
 import { tryMutation } from "../lib/db-result.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { clearSandboxRef, setSandboxRef } from "../state/index.js";
+import { setSandboxRef } from "../state/index.js";
 import { capExecStreams, EXEC_STREAM_BYTE_CAP } from "../tools/workspace/result-bounds.js";
 import { createDockerSandboxOps } from "./docker-client.js";
 import { runExec, stepExecId } from "./exec.js";
@@ -95,8 +95,8 @@ export function createSandboxClient(config) {
      * variant as the message, and the variant itself on `cause`. The `mapErr`
      * happens before the bridge because `toThrowable` passes an `Error`
      * through untouched — thus `unwrapOrThrow` stays the single sanctioned
-     * Result→throw bridge, no second bridge is introduced, and the
-     * `must-use-result` lint patch keeps recognizing every site. The registry
+     * Result→throw bridge, no second bridge is introduced, and the type check
+     * command keeps recognizing every site. The registry
      * unwraps below stay on the plain bridge: they carry a `DbError`.
      */
     const failing = (e) => new SandboxFailure(e);
@@ -182,12 +182,6 @@ export function createSandboxClient(config) {
             sandboxId: identity.sandboxId,
             cause,
         });
-        // Every caller must declare resources — a sandbox with no cpu/memory
-        // request is a semantic error, not something to paper over with a
-        // default.
-        if (!spec.resources) {
-            return err(createFailed("createSandbox")(new Error(`createSandbox: ${session.scope.analysisId}/${session.runFrame.runId}/${session.runFrame.stepId} has no resources — every caller must declare cpu/memoryGb`)));
-        }
         // The config states an engine fact (binds preserve host ownership);
         // which remediation that fact demands — today, a world-writable step
         // write tree — is harness-owned and chosen here, not by the embedder.
@@ -218,8 +212,8 @@ export function createSandboxClient(config) {
         // recovered step reaches this line again. `capExecStreams` cuts the
         // streams and keeps every other field, thus the kernel accounting the
         // sandbox reported reaches the record intact.
-        exec: (ref, request, emit, deadline) => DBOS.runStep(async () => {
-            const execId = stepExecId();
+        exec: (ref, request, emit, deadline, givenExecId) => DBOS.runStep(async () => {
+            const execId = givenExecId ?? stepExecId();
             stableSpan("sandbox.exec", "sandbox.exec", { [ATTR_INFLEXA_EXEC_ID]: execId });
             const result = capExecStreams(await runExec(ref, execId, request, emit, deadline, execDeps), streamCap);
             recordSandboxExec({
@@ -240,4 +234,4 @@ export function createSandboxClient(config) {
     };
 }
 /** Re-exports so consumers import once from this module. */
-export { clearSandboxRef };
+export { clearSandboxRef } from "../state/index.js";

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

@@ -39,7 +39,51 @@ import type { Logger } from "../lib/logger.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type SandboxError } from "./sandbox-error.js";
 import type { FarmSource, ManagedSandbox, SandboxIdentity, SandboxLabels, SandboxLiveness, SandboxRef, SandboxSpec, ToolchainSource } from "./types.js";
-export interface DockerClientConfig {
+/**
+ * The surface of a Docker engine that this module reads. The classes of
+ * `dockerode` carry private members, so an injected engine — a test double or a
+ * wrapper — names this shape instead. A real `Docker` instance satisfies it.
+ */
+type EngineContainer = {
+    start(): Promise<unknown>;
+    stop(options?: {
+        t?: number;
+    }): Promise<unknown>;
+    remove(options?: {
+        force?: boolean;
+        v?: boolean;
+    }): Promise<unknown>;
+    inspect(): Promise<EngineInspectInfo>;
+};
+type EngineInspectInfo = {
+    Config?: {
+        Labels?: Record<string, string>;
+    };
+    State: {
+        Running?: boolean;
+        OOMKilled?: boolean;
+    };
+    NetworkSettings: {
+        Ports?: Record<string, Array<{
+            HostPort?: string;
+        }>>;
+    };
+};
+type EngineContainerInfo = {
+    Labels?: Record<string, string>;
+    Created?: unknown;
+};
+export type DockerEngine = {
+    createContainer(options: Docker.ContainerCreateOptions): Promise<EngineContainer>;
+    getContainer(id: string): EngineContainer;
+    listContainers(options?: {
+        all?: boolean;
+        filters?: {
+            label?: string[];
+        };
+    }): Promise<EngineContainerInfo[]>;
+};
+export type DockerClientConfig = {
     image: string;
     /** Workspace-root resolution seam; each analysis's resolved root is the bind source for its tree mounts. */
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
@@ -87,7 +131,7 @@ export interface DockerClientConfig {
      */
     engineSocketPath?: string;
     /** Injected for tests. */
-    docker?: Docker;
+    docker?: DockerEngine;
     /** Injected for tests so `/health` polling can be stubbed. */
     fetch?: typeof fetch;
     /**
@@ -104,7 +148,7 @@ export interface DockerClientConfig {
     logger?: Logger;
     /** Hook called after the registry row is written. */
     registerSandbox: (session: SpawnSession, spec: SandboxSpec, ref: SandboxRef) => Promise<void>;
-}
+};
 /**
  * dockerode connection options for a configured engine socket, or `undefined`
  * to leave construction as a bare `new Docker()` — which preserves dockerode's
@@ -121,3 +165,4 @@ export declare function createDockerSandboxOps(config: DockerClientConfig): {
     isAliveById(sandboxId: string): ResultAsync<SandboxLiveness, SandboxError>;
     listManagedSandboxes(): ResultAsync<ManagedSandbox[], SandboxError>;
 };
+export {};

package/dist/sandbox/docker-client.js

@@ -32,9 +32,12 @@
  * The workload ends as uid 1000 with `no-new-privileges` and no effective
  * capabilities.
  */
+import { errorMessageOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
 import { lstatSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import Docker from "dockerode";
 import { ResultAsync, err, ok } from "neverthrow";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -135,9 +138,9 @@ async function pollHealth(fetchImpl, url, timeoutMs) {
         catch (err) {
             lastErr = err;
         }
-        await new Promise((r) => setTimeout(r, HEALTH_POLL_MS));
+        await sleep(HEALTH_POLL_MS);
     }
-    throw new Error(`sandbox /health did not return 200 within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+    throw new Error(`sandbox /health did not return 200 within ${timeoutMs}ms: ${errorMessageOf(lastErr) ?? textOf(lastErr)}`);
 }
 /**
  * dockerode connection options for a configured engine socket, or `undefined`
@@ -312,10 +315,10 @@ export function createDockerSandboxOps(config) {
                     ...(write && plan.writableStepPath
                         ? [`${tailWritePrefix({ workspaceRoot: hostTreePath, tail: write.tail })}:${plan.writableStepPath}:rw`]
                         : []),
-                    ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
+                    ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${String(plan.libsPath)}:ro`] : []),
                     ...(libsMounted && farm && plan.farmPath ? [`${farm.farmPath}:${plan.farmPath}:ro`] : []),
                     ...(libsMounted && cacheBindable && farm?.cachePath && plan.cachePath ? [`${farm.cachePath}:${plan.cachePath}:rw`] : []),
-                    ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
+                    ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${String(plan.refsPath)}:ro`] : []),
                     ...cpuBinds,
                 ];
                 const createFailed = (status, cause) => ({
@@ -337,11 +340,10 @@ export function createDockerSandboxOps(config) {
                     SANDBOX_EGRESS_FIREWALL: "1",
                     ...threadLimitEnv(limits),
                     ...plan.env,
-                    ...(spec.extraEnv ?? {}),
+                    ...spec.extraEnv,
                 }).map(([k, v]) => `${k}=${v}`);
                 const createOpts = {
                     name: sandboxId,
-                    ...(config.platform !== undefined && { platform: config.platform }),
                     Image: image,
                     Env: env,
                     User: SANDBOX_ROOT_USER,
@@ -374,6 +376,8 @@ export function createDockerSandboxOps(config) {
                         AutoRemove: false,
                     },
                 };
+                if (config.platform !== undefined)
+                    createOpts.platform = config.platform;
                 const sandbox = await createOrAdopt(docker, createOpts, sandboxId, spec.childWorkflowId, createFailed, logger);
                 if (sandbox.isErr())
                     return err(sandbox.error);

package/dist/sandbox/estimate-data-profile-resources.js

@@ -57,13 +57,8 @@ function factorFor(relativePath) {
 export function estimateDataProfileResources(files) {
     if (files.length === 0)
         return { cpu: 1, memoryGb: 2 };
-    let largest = files[0];
-    let totalBytes = 0;
-    for (const f of files) {
-        totalBytes += f.size;
-        if (f.size > largest.size)
-            largest = f;
-    }
+    const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
+    const largest = files.reduce((a, b) => (b.size > a.size ? b : a));
     const memoryGb = Math.max(2, Math.ceil(2 + (largest.size * factorFor(largest.relativePath)) / 1e9));
     let cpu = totalBytes < 100 * 1e6 ? 1 : totalBytes < 1e9 ? 2 : totalBytes < 10 * 1e9 ? 4 : 8;
     if (files.length >= 8)

package/dist/sandbox/exec-outcome.d.ts

@@ -26,7 +26,7 @@ import type { ExecResult } from "./types.js";
  */
 export declare function sandboxExecOutcomeOf(result: ExecResult): SandboxExecOutcome;
 /** The account of one exec that a failure record can hold. Text-free by construction. */
-export interface ExecOutcomeSummary {
+export type ExecOutcomeSummary = {
     readonly exitCode: number | null;
     readonly timedOut: boolean;
     /**
@@ -36,7 +36,7 @@ export interface ExecOutcomeSummary {
      */
     readonly stderrTotalBytes: number;
     readonly syntheticFailureReason?: string;
-}
+};
 /** Reduce a result to its summary. */
 export declare function summarizeExec(result: ExecResult): ExecOutcomeSummary;
 /** Keep `summary` as the last known exec of `sandboxId`. */