@inflexa-ai/harness 0.3.0 → 0.4.0

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

@@ -20,7 +20,7 @@ import { clearSandboxRef } from "../state/index.js";
 import { type AwaitExecOptions } from "./await-exec.js";
 import type { SandboxClient } from "./client.js";
 import { type SubmitExecDeps } from "./submit-exec.js";
-import { type SandboxTransport } from "./types.js";
+import { type CreateSandboxMeta, type SandboxTransport } from "./types.js";
 /**
  * Narrow config slice the sandbox factory reads off `Env` — the backend
  * default and the K8s namespace fallback. Composition roots map their
@@ -62,6 +62,25 @@ export interface CreateSandboxClientConfig {
     refStorePath?: string;
     /** Docker: force the container platform (e.g. `linux/amd64`) so the sandbox matches the mounted lib store's arch. */
     platform?: string;
+    /**
+     * Docker: unix socket of the Docker-API engine to dial — a Docker daemon
+     * socket or a podman Docker-compat socket. Unset preserves dockerode's
+     * default resolution (`DOCKER_HOST`, then the default Docker socket).
+     */
+    engineSocketPath?: string;
+    /**
+     * Docker: the engine's bind mounts expose honest host file ownership to
+     * the container — podman machine's virtiofs and native Linux binds present
+     * the embedder user's real uid and modes, which the uid-1000 sandbox
+     * workload cannot write; Docker Desktop's file-sharing layer masks that
+     * mismatch, so it stays unset there. When set, the client loosens each
+     * step's pre-created write tree so workload writes land. The field names
+     * the engine fact rather than the remediation, so how the harness
+     * compensates can evolve without changing the embedder surface; a
+     * single-valued union (not a boolean) so future ownership classes extend
+     * it without a breaking change.
+     */
+    engineBindOwnership?: "host-preserved";
     /** K8s: PVC claim backing the session PVC the workspace roots live under. */
     sessionPvc?: string;
     /**
@@ -100,6 +119,25 @@ export interface CreateSandboxClientConfig {
  * Exported for tests.
  */
 export declare function composeAwaitOptions(base: AwaitExecOptions | undefined, transport: SandboxTransport, isAlive: NonNullable<AwaitExecOptions["isAlive"]>): AwaitExecOptions;
+/**
+ * Backend-agnostic pre-creation of the writable step tree under the analysis's
+ * resolved workspace root. On Docker that root is the host dir the container
+ * binds; on K8s it lives under the session PVC the sandbox pod mounts via
+ * subPath. `mkdir(recursive)` is idempotent, so an existing tree (replay, retry)
+ * is not an error. A read-only sandbox has no writable step mount, so there is
+ * nothing to pre-create.
+ *
+ * `stepTreeAccess: "world-writable"` chmods the step dir and each subdir so the
+ * uid-1000 sandbox workload can write them through engines that honor host bind
+ * ownership. The chmod is explicit, not `mkdir`'s `mode` option: the process
+ * umask masks `mkdir`'s mode, and on replay the dirs already exist so `mkdir`
+ * would not touch them either way. Scoped to the step write tree — the
+ * read-only mount sources are never re-moded. Exported for tests.
+ */
+export declare function precreateStepTree(deps: {
+    resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    stepTreeAccess?: "world-writable";
+}, meta: CreateSandboxMeta): Promise<void>;
 export declare function createSandboxClient(config: CreateSandboxClientConfig): SandboxClient;
 /** Re-exports so consumers import once from this module. */
 export { clearSandboxRef };

package/dist/sandbox/create-sandbox.js

@@ -11,7 +11,7 @@
  * coupling (they just call the closures we hand them). `submitExec` and
  * `awaitExec` are backend-agnostic — they only need the SandboxRef.
  */
-import { mkdir } from "node:fs/promises";
+import { chmod, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { clampResources } from "../config/resource-limits.js";
 import { stepWritePrefix } from "../workspace/paths.js";
@@ -34,6 +34,36 @@ import { toPersistedRef } from "./types.js";
 export function composeAwaitOptions(base, transport, isAlive) {
     return { isAlive, ...base, transport };
 }
+/**
+ * Backend-agnostic pre-creation of the writable step tree under the analysis's
+ * resolved workspace root. On Docker that root is the host dir the container
+ * binds; on K8s it lives under the session PVC the sandbox pod mounts via
+ * subPath. `mkdir(recursive)` is idempotent, so an existing tree (replay, retry)
+ * is not an error. A read-only sandbox has no writable step mount, so there is
+ * nothing to pre-create.
+ *
+ * `stepTreeAccess: "world-writable"` chmods the step dir and each subdir so the
+ * uid-1000 sandbox workload can write them through engines that honor host bind
+ * ownership. The chmod is explicit, not `mkdir`'s `mode` option: the process
+ * umask masks `mkdir`'s mode, and on replay the dirs already exist so `mkdir`
+ * would not touch them either way. Scoped to the step write tree — the
+ * read-only mount sources are never re-moded. Exported for tests.
+ */
+export async function precreateStepTree(deps, meta) {
+    if (meta.readOnly)
+        return;
+    const stepDir = stepWritePrefix({
+        workspaceRoot: deps.resolveWorkspaceRoot(meta.analysisId),
+        runId: meta.runId,
+        stepId: meta.stepId,
+    });
+    await mkdir(stepDir, { recursive: true });
+    await Promise.all(STEP_SUBDIRS.map((sub) => mkdir(join(stepDir, sub), { recursive: true })));
+    if (deps.stepTreeAccess === "world-writable") {
+        await chmod(stepDir, 0o777);
+        await Promise.all(STEP_SUBDIRS.map((sub) => chmod(join(stepDir, sub), 0o777)));
+    }
+}
 export function createSandboxClient(config) {
     const backend = config.backend ?? config.env.backend;
     const transport = config.transport ?? "poll";
@@ -64,26 +94,10 @@ export function createSandboxClient(config) {
             libStorePath: config.libStorePath,
             refStorePath: config.refStorePath,
             platform: config.platform,
+            engineSocketPath: config.engineSocketPath,
             logger: config.logger,
             registerSandbox,
         });
-    // Backend-agnostic pre-creation of the writable step tree under the
-    // analysis's resolved workspace root. On Docker that root is the host dir
-    // the container binds; on K8s it lives under the session PVC the sandbox
-    // pod mounts via subPath. mkdir(recursive) is idempotent, so an existing
-    // tree (replay, retry) is not an error.
-    const precreateStepTree = async (meta) => {
-        // A read-only sandbox has no writable step mount — nothing to pre-create.
-        if (meta.readOnly)
-            return;
-        const stepDir = stepWritePrefix({
-            workspaceRoot: config.resolveWorkspaceRoot(meta.analysisId),
-            runId: meta.runId,
-            stepId: meta.stepId,
-        });
-        await mkdir(stepDir, { recursive: true });
-        await Promise.all(STEP_SUBDIRS.map((sub) => mkdir(join(stepDir, sub), { recursive: true })));
-    };
     // `teardown` needs the registry-clear closure but the SandboxRef alone
     // doesn't carry runId/stepId. Wrap the backend impl so callers pass the
     // ref + step coordinates and the wrapper does the clear after the
@@ -109,7 +123,13 @@ export function createSandboxClient(config) {
     const isAlive = async (ref) => unwrapOrThrow(await ops.isAlive(ref));
     return {
         createSandbox: async (meta, identity) => {
-            await precreateStepTree(meta);
+            // 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.
+            await precreateStepTree({
+                resolveWorkspaceRoot: config.resolveWorkspaceRoot,
+                stepTreeAccess: config.engineBindOwnership === "host-preserved" ? "world-writable" : undefined,
+            }, meta);
             // Every caller must declare resources — a sandbox with no cpu/memory
             // request is a semantic error, not something to paper over with a
             // default (a DBOS replay of a pre-resources workflow input lands here).

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

@@ -53,6 +53,13 @@ export interface DockerClientConfig {
      * create rather than crashing inside the sandbox.
      */
     platform?: string;
+    /**
+     * Unix socket of the Docker-API engine to dial — a Docker daemon socket or a
+     * podman Docker-compat socket (both serve the identical REST API). Unset
+     * preserves dockerode's default resolution (`DOCKER_HOST`, then the default
+     * Docker socket).
+     */
+    engineSocketPath?: string;
     /** Injected for tests. */
     docker?: Docker;
     /** Injected for tests so `/health` polling can be stubbed. */
@@ -66,6 +73,14 @@ export interface DockerClientConfig {
     /** Hook called after the registry row is written. */
     registerSandbox: (meta: CreateSandboxMeta, 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
+ * default resolution (`DOCKER_HOST`, then the default Docker socket). A set
+ * `engineSocketPath` dials that unix socket instead (a Docker daemon or a
+ * podman Docker-compat socket).
+ */
+export declare function engineConnectionOptions(engineSocketPath: string | undefined): Docker.DockerOptions | undefined;
 export declare function createDockerSandboxOps(config: DockerClientConfig): {
     createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
     teardown(ref: SandboxRef): ResultAsync<void, SandboxError>;

package/dist/sandbox/docker-client.js

@@ -97,36 +97,58 @@ async function pollHealth(fetchImpl, url, timeoutMs) {
     }
     throw new Error(`sandbox /health did not return 200 within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
 }
+/**
+ * dockerode connection options for a configured engine socket, or `undefined`
+ * to leave construction as a bare `new Docker()` — which preserves dockerode's
+ * default resolution (`DOCKER_HOST`, then the default Docker socket). A set
+ * `engineSocketPath` dials that unix socket instead (a Docker daemon or a
+ * podman Docker-compat socket).
+ */
+export function engineConnectionOptions(engineSocketPath) {
+    return engineSocketPath === undefined ? undefined : { socketPath: engineSocketPath };
+}
 /**
  * Create the container, or adopt the one already standing under this
- * checkpointed name (a recovery re-run, see the harness-sandbox-exec spec). A
- * running container is adopted as-is; a stopped prior attempt is removed and
- * recreated. A 409 whose container belongs to a different workflow is a refused
- * name collision — never adopt or remove someone else's container.
+ * checkpointed name on a recovery re-run. Any create failure triggers an
+ * inspect of the name: engines disagree on the duplicate-name status (Docker
+ * answers 409, podman's compat API 500), so the reconcile keys on whether a
+ * container stands under the name, not on a status code. A standing container
+ * this workflow owns is adopted as-is if running, removed and recreated if
+ * stopped; one owned by a different workflow is a refused name collision — never
+ * adopt or remove someone else's container. When no container stands, the
+ * failure was not a name collision and the original create error is returned;
+ * the inspect's own failure is never surfaced, so a transient engine outage
+ * (both calls fail) still reports the create failure.
  */
-async function createOrAdopt(docker, createOpts, name, ownerWorkflowId, createFailed) {
+async function createOrAdopt(docker, createOpts, name, ownerWorkflowId, createFailed, logger) {
     const created = await trySandbox(() => docker.createContainer(createOpts), createFailed);
     if (created.isOk())
         return ok({ container: created.value, alreadyRunning: false });
-    if (statusOf(created.error) !== 409)
-        return err(created.error);
     const existing = docker.getContainer(name);
     const inspected = await trySandbox(() => existing.inspect(), createFailed);
+    // No container stands under the name → the create failure was not a name
+    // collision, so surface the original create error rather than the inspect's.
     if (inspected.isErr())
-        return err(inspected.error);
+        return err(created.error);
     const info = inspected.value;
     const owner = info.Config?.Labels?.[OWNER_WORKFLOW_LABEL];
     if (owner !== ownerWorkflowId) {
         return err({ type: "name_conflict", op: "docker.createSandbox", sandboxId: name, owner: owner ?? null });
     }
-    if (info.State.Running)
+    // Both mutating reconcile outcomes are logged: adoption reuses a container the
+    // current attempt did not create, so without a record here nothing ties the
+    // step's sandbox back to the prior attempt that made it.
+    if (info.State.Running) {
+        logger.info("adopted standing container on recovery re-run", { sandboxId: name, ownerWorkflowId });
         return ok({ container: existing, alreadyRunning: true });
+    }
     const removed = await removeContainerIgnoreMissing(docker, name);
     if (removed.isErr())
         return err(removed.error);
     const recreated = await trySandbox(() => docker.createContainer(createOpts), createFailed);
     if (recreated.isErr())
         return err(recreated.error);
+    logger.info("removed stopped prior attempt and recreated", { sandboxId: name, ownerWorkflowId });
     return ok({ container: recreated.value, alreadyRunning: false });
 }
 function removeContainerIgnoreMissing(docker, sandboxId) {
@@ -145,7 +167,11 @@ function removeContainerIgnoreMissing(docker, sandboxId) {
     statusOf(e) === 404 ? ok(undefined) : err(e));
 }
 export function createDockerSandboxOps(config) {
-    const docker = config.docker ?? new Docker();
+    // The injected test instance wins; otherwise a configured socket dials that
+    // engine and an unset one stays a bare `new Docker()` (default resolution).
+    const connection = engineConnectionOptions(config.engineSocketPath);
+    const docker = config.docker ?? (connection ? new Docker(connection) : new Docker());
+    const logger = (config.logger ?? createNoopLogger()).named("docker-client");
     const fetchImpl = config.fetch ?? fetch;
     const transport = config.transport ?? "poll";
     const pollMode = transport === "poll";
@@ -159,9 +185,7 @@ export function createDockerSandboxOps(config) {
                 // since an otherwise-silent libs-mount drop is invisible to operators.
                 const libsMounted = !!config.libStorePath && libStoreUsable(config.libStorePath);
                 if (config.libStorePath && !libsMounted) {
-                    (config.logger ?? createNoopLogger())
-                        .named("docker-client")
-                        .warn("lib store configured but `current` is missing or incomplete at sandbox creation — mounting no library store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, sandboxId });
+                    logger.warn("lib store configured but `current` is missing or incomplete at sandbox creation — mounting no library store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, sandboxId });
                 }
                 const plan = buildMountPlan(meta, {
                     libs: libsMounted,
@@ -234,7 +258,7 @@ export function createDockerSandboxOps(config) {
                         AutoRemove: false,
                     },
                 };
-                const sandbox = await createOrAdopt(docker, createOpts, sandboxId, meta.childWorkflowId, createFailed);
+                const sandbox = await createOrAdopt(docker, createOpts, sandboxId, meta.childWorkflowId, createFailed, logger);
                 if (sandbox.isErr())
                     return err(sandbox.error);
                 if (!sandbox.value.alreadyRunning) {

package/package.json

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