@inflexa-ai/harness 0.43.0 → 0.44.0

package/dist/agents/report-session-agent.d.ts

@@ -94,7 +94,7 @@ export interface ReportSessionAgentDeps {
     readonly makeResolver?: (scope: {
         analysisId: string;
         auth: AuthContext;
-    }) => ReferenceResolver;
+    }) => Promise<ReferenceResolver>;
     /**
      * Page-asset lookup -- the preview tool maps the module specifier of a manifest
      * entry onto a file on disk. Omitted falls back to the module resolution of the

package/dist/app/synthesize-run.js

@@ -26,7 +26,7 @@ export async function synthesizeRun(deps, params) {
     const { analysisId, runId, completedSteps, session, emit, onProgress } = params;
     await onProgress("starting", "Beginning literature-grounded synthesis");
     try {
-        const workspaceRoot = resolveWorkspaceRoot(analysisId);
+        const workspaceRoot = await resolveWorkspaceRoot(analysisId);
         const summaries = await loadStepSummariesFromDisk({
             workspaceRoot,
             runId,

package/dist/execution/post-step-pipeline.js

@@ -116,7 +116,7 @@ export function describeStepRegistrationFailure(failure) {
 export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest) {
     const { input, session, lineageCollector } = postCtx;
     const reconciled = await reconcileManifestWithDisk({
-        workspaceRoot: deps.resolveWorkspaceRoot(input.analysisId),
+        workspaceRoot: await deps.resolveWorkspaceRoot(input.analysisId),
         resourceId: input.analysisId,
         runId: input.runId,
         stepId: input.stepId,

package/dist/index.d.ts

@@ -184,8 +184,8 @@ export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.j
 export type { DbError } from "./lib/db-result.js";
 export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
 export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset } from "./reference-data/catalog.js";
-export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
-export type { ReferenceInstallReceipt, ReferenceReceiptArtifact } from "./reference-data/receipt.js";
+export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt, referenceReceiptContentDigest, } from "./reference-data/receipt.js";
+export type { ReferenceInstallReceipt, ReferenceReceiptArtifact, ReferenceReceiptContent } from "./reference-data/receipt.js";
 export { runStepDir } from "./workspace/paths.js";
 export { reportSessionDir } from "./workspace/paths.js";
 export type { LogFields, LogLevel, Logger } from "./lib/logger.js";

package/dist/index.js

@@ -288,7 +288,7 @@ export { queryStepsByRun } from "./state/step-executions.js";
 // artifact names the third-party upstream it is fetched from; embedders own all
 // transfer/storage behavior but never choose a different source.
 export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
-export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
+export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt, referenceReceiptContentDigest, } from "./reference-data/receipt.js";
 // Workspace-tree path convention — the root-relative step directory each
 // sandbox step confines its artifact writes to (join onto the resolved root).
 export { runStepDir } from "./workspace/paths.js";

package/dist/reference-data/receipt.d.ts

@@ -1,24 +1,36 @@
 import { z } from "zod";
 /** Schema version for installation receipts shared by all embedders. */
-export declare const REFERENCE_INSTALL_RECEIPT_VERSION: 1;
+export declare const REFERENCE_INSTALL_RECEIPT_VERSION: 2;
 /**
  * What was actually written to disk for one artifact. The size and digest are
  * *observed at install* — the catalog carries neither, so this receipt is the
  * sole record of the bytes the upstream served, and what `verify` later checks
- * the local files against. A receipt written by an older build may still carry
- * an `integrity` field; it is simply ignored (unknown keys are stripped).
+ * the local files against.
  */
 declare const ReferenceReceiptArtifactSchema: z.ZodObject<{
     path: z.ZodString;
     bytes: z.ZodNumber;
     sha256: z.ZodString;
 }, z.core.$strip>;
+/** The fields of a receipt that identify the installed content. */
+export interface ReferenceReceiptContent {
+    readonly datasetId: string;
+    readonly datasetVersion: string;
+    readonly artifacts: readonly ReferenceReceiptArtifact[];
+}
+/**
+ * The identity of the installed bytes, independent of the install time. Consumers outside the
+ * harness recompute it, so the input bytes are a contract: the SHA-256 of the compact JSON array
+ * `[datasetId, datasetVersion, [[path, bytes, sha256], ...]]`, artifacts in code-unit order of path.
+ */
+export declare function referenceReceiptContentDigest(content: ReferenceReceiptContent): string;
 /** Optional metadata describing one activated reference dataset version. */
 export declare const ReferenceInstallReceiptSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
+    version: z.ZodLiteral<2>;
     datasetId: z.ZodString;
     datasetVersion: z.ZodString;
     activatedAt: z.ZodISODateTime;
+    contentDigest: z.ZodString;
     artifacts: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         bytes: z.ZodNumber;

package/dist/reference-data/receipt.js

@@ -1,19 +1,32 @@
+import { createHash } from "node:crypto";
 import { z } from "zod";
 import { ReferenceArtifactPathSchema, ReferenceDatasetSchema, ReferenceSha256Schema } from "./catalog.js";
 /** Schema version for installation receipts shared by all embedders. */
-export const REFERENCE_INSTALL_RECEIPT_VERSION = 1;
+export const REFERENCE_INSTALL_RECEIPT_VERSION = 2;
 /**
  * What was actually written to disk for one artifact. The size and digest are
  * *observed at install* — the catalog carries neither, so this receipt is the
  * sole record of the bytes the upstream served, and what `verify` later checks
- * the local files against. A receipt written by an older build may still carry
- * an `integrity` field; it is simply ignored (unknown keys are stripped).
+ * the local files against.
  */
 const ReferenceReceiptArtifactSchema = z.object({
     path: ReferenceArtifactPathSchema,
     bytes: z.number().int().nonnegative(),
     sha256: ReferenceSha256Schema,
 });
+/**
+ * The identity of the installed bytes, independent of the install time. Consumers outside the
+ * harness recompute it, so the input bytes are a contract: the SHA-256 of the compact JSON array
+ * `[datasetId, datasetVersion, [[path, bytes, sha256], ...]]`, artifacts in code-unit order of path.
+ */
+export function referenceReceiptContentDigest(content) {
+    const artifacts = [...content.artifacts]
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .map((artifact) => [artifact.path, artifact.bytes, artifact.sha256]);
+    return createHash("sha256")
+        .update(JSON.stringify([content.datasetId, content.datasetVersion, artifacts]), "utf8")
+        .digest("hex");
+}
 /** Optional metadata describing one activated reference dataset version. */
 export const ReferenceInstallReceiptSchema = z
     .object({
@@ -21,6 +34,7 @@ export const ReferenceInstallReceiptSchema = z
     datasetId: ReferenceDatasetSchema.shape.id,
     datasetVersion: ReferenceDatasetSchema.shape.version,
     activatedAt: z.iso.datetime({ offset: true }),
+    contentDigest: ReferenceSha256Schema,
     artifacts: z.array(ReferenceReceiptArtifactSchema).min(1),
 })
     .superRefine((receipt, ctx) => {
@@ -31,6 +45,9 @@ export const ReferenceInstallReceiptSchema = z
         }
         paths.add(artifact.path);
     }
+    if (receipt.contentDigest !== referenceReceiptContentDigest(receipt)) {
+        ctx.addIssue({ code: "custom", message: "Receipt content digest does not match its dataset and artifacts", path: ["contentDigest"] });
+    }
 });
 /** Parse optional/untrusted receipt metadata; invalid receipts are ignored. */
 export function parseReferenceInstallReceipt(input) {

package/dist/report-model/pin-snapshot.js

@@ -166,10 +166,10 @@ function citationsOf(text) {
 async function collectCitations(pool, resolveWorkspaceRoot, analysisId) {
     let root;
     try {
-        root = resolveWorkspaceRoot(analysisId);
+        root = await resolveWorkspaceRoot(analysisId);
     }
     catch {
-        // The seam signals an unresolvable resource by a throw. The artifact map still states the
+        // The seam signals an unresolvable resource by a rejection. The artifact map still states the
         // membership of the session, thus the fault costs the citation list alone.
         return ok({ keys: [], records: new Map() });
     }

package/dist/runtime/assemble.d.ts

@@ -97,7 +97,7 @@ export interface ReportResolverScope {
  * The factory that gives the reference resolver of one report tool call. The harness wires the production
  * realization, and an embedder can bind its own at its composition root.
  */
-export type MakeReportReferenceResolver = (scope: ReportResolverScope) => ReferenceResolver;
+export type MakeReportReferenceResolver = (scope: ReportResolverScope) => Promise<ReferenceResolver>;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;

package/dist/runtime/assemble.js

@@ -152,10 +152,10 @@ export function assembleCoreRuntime(deps) {
     // for each tool call. The extraction arm falls through to the registered extract-values
     // callable for an over-cap file or a host parse fault. The cap gates the host read, and
     // the resolver defaults it to 16 MiB.
-    const makeProductionReportResolver = (scope) => {
+    const makeProductionReportResolver = async (scope) => {
         const arm = createExtractionArm(bindExtractionTrigger({ runAuthorizer: conversation.runAuthorizer, workflow: extractValues }, { auth: scope.auth, analysisId: scope.analysisId }));
         return createProductionResolver({
-            workspaceRoot: conversation.resolveWorkspaceRoot(scope.analysisId),
+            workspaceRoot: await conversation.resolveWorkspaceRoot(scope.analysisId),
             analysisId: scope.analysisId,
             extractionArm: arm,
             readCache: reportArtifactReads.forAnalysis(scope.analysisId),

package/dist/sandbox/client.d.ts

@@ -43,7 +43,7 @@ export interface SandboxClient {
      * Each spawn failure is an `err` value, the refusal of the label hook
      * (`labels_refused`) included: a spawn path splits the result with
      * `keepSuspendingRefusal`. Only a defect of the deployment config, or a
-     * throw of the workspace-root resolver, throws, and it fails the workflow.
+     * rejection of the workspace-root resolver, throws, and it fails the workflow.
      */
     createSandbox(session: SpawnSession, spec: SandboxSpec, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
     /**

package/dist/sandbox/create-sandbox.js

@@ -57,7 +57,7 @@ export async function precreateStepTree(deps, coords) {
     // `tailWritePrefix` (not a raw `join`) so every segment runs through the same
     // id validation the mount builders apply — a crafted tail cannot escape the
     // resolved root.
-    const writeDir = tailWritePrefix({ workspaceRoot: deps.resolveWorkspaceRoot(coords.analysisId), tail: write.tail });
+    const writeDir = tailWritePrefix({ workspaceRoot: await deps.resolveWorkspaceRoot(coords.analysisId), tail: write.tail });
     await mkdir(writeDir, { recursive: true });
     await Promise.all(write.subdirs.map((sub) => mkdir(join(writeDir, sub), { recursive: true })));
     if (deps.stepTreeAccess === "world-writable") {

package/dist/sandbox/docker-client.js

@@ -287,7 +287,7 @@ export function createDockerSandboxOps(config) {
                     toolchainSource: config.toolchainSource,
                     cache: cacheBindable,
                 });
-                const hostTreePath = config.resolveWorkspaceRoot(analysisId);
+                const hostTreePath = await config.resolveWorkspaceRoot(analysisId);
                 // `tailWritePrefix` (not a raw `join`) so the RW bind source runs through
                 // the same validation as the pre-created write tree — a crafted stepId or
                 // a crafted tail cannot escape the resolved root into the container. The

package/dist/sandbox/k8s-client.js

@@ -88,11 +88,11 @@ function buildKubeApi() {
  * mount a directory the harness never wrote to — fail loudly instead. `createSandbox` runs
  * inside a DBOS workflow body, where a throw is the durable failure signal.
  */
-function workspaceSubPathFor(config, analysisId) {
+async function workspaceSubPathFor(config, analysisId) {
     if (!config.sessionPvcRoot) {
         throw new Error("k8s sandbox: sessionPvc is set but sessionPvcRoot is not — the PVC subPath of a workspace root cannot be derived");
     }
-    const rel = relativePath(config.sessionPvcRoot, config.resolveWorkspaceRoot(analysisId));
+    const rel = relativePath(config.sessionPvcRoot, await config.resolveWorkspaceRoot(analysisId));
     const posix = rel.split(sep).join("/");
     if (posix.length === 0 || posix.startsWith("..")) {
         throw new Error(`k8s sandbox: workspace root for ${analysisId} does not live under sessionPvcRoot (${config.sessionPvcRoot})`);
@@ -111,7 +111,7 @@ function pvcSubPath(value, what) {
     }
     return value;
 }
-function buildJobSpec(session, sandboxSpec, hostLabels, config, identity, farm, libsMounted) {
+async function buildJobSpec(session, sandboxSpec, hostLabels, config, identity, farm, libsMounted) {
     const { sandboxId } = identity;
     // The lock gate of the package-store spec: `farmPath` is PVC-relative,
     // thus this host can prove the lock only through `libStorePvcRoot`. The
@@ -148,7 +148,7 @@ function buildJobSpec(session, sandboxSpec, hostLabels, config, identity, farm,
     const volumes = [];
     const volumeMounts = [];
     if (config.sessionPvc) {
-        const subPaths = buildSessionSubPaths(coords, workspaceSubPathFor(config, session.scope.analysisId));
+        const subPaths = buildSessionSubPaths(coords, await workspaceSubPathFor(config, session.scope.analysisId));
         volumes.push({
             name: SESSION_VOLUME_NAME,
             persistentVolumeClaim: { claimName: config.sessionPvc },
@@ -491,7 +491,7 @@ export function createK8sSandboxOps(config) {
                             .warn("the farm of the analysis has no usable inflexa.lock at sandbox creation — mounting no package store (sandbox degrades to available:false)", { libStorePvc: config.libStorePvc, farmPath: farm.farmPath, lockError: lock.error.type, sandboxId });
                     }
                 }
-                const job = buildJobSpec(session, spec, hostLabels, config, identity, farm, libsMounted);
+                const job = await buildJobSpec(session, spec, hostLabels, config, identity, farm, libsMounted);
                 const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, spec.childWorkflowId, job);
                 if (adopted.isErr())
                     return err(adopted.error);

package/dist/tasks/data-profile.js

@@ -356,10 +356,10 @@ export async function runDataProfileBody(input, deps) {
         const executionId = generateExecutionId(DATA_PROFILE_AGENT_ID);
         const workflowId = DBOS.workflowID ?? `${DATA_PROFILE_RUN_LITERAL}:${executionId}`;
         const childSession = forSubAgent(runSession, DATA_PROFILE_AGENT_ID);
-        // A resolver throw fails the workflow loudly (workspace-root-resolution
+        // A resolver rejection fails the workflow loudly (workspace-root-resolution
         // contract) — profiling an analysis whose root cannot be resolved is
         // meaningless, so no softer handling is warranted.
-        const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
+        const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
         const profileWritePrefix = `${workspaceRoot}/runs/${DATA_PROFILE_RUN_LITERAL}/${DATA_PROFILE_STEP_LITERAL}`;
         // 3. The deterministic scan, before any container and before the agent's first turn.
         // It is always needed and its result does not depend on agent judgement, so spending

package/dist/tools/report-session/derive-table.js

@@ -221,7 +221,7 @@ export function createDeriveTableTool(deps) {
             }
             let root;
             try {
-                root = deps.resolveWorkspaceRoot(analysisId);
+                root = await deps.resolveWorkspaceRoot(analysisId);
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/examine-page.js

@@ -276,7 +276,7 @@ export function createExaminePageTool(deps) {
             const { threadId, analysisId } = opened.value;
             let root;
             try {
-                root = deps.resolveWorkspaceRoot(analysisId);
+                root = await deps.resolveWorkspaceRoot(analysisId);
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/list-artifacts.js

@@ -170,11 +170,11 @@ export function createListPinnedArtifactsTool(deps) {
                 return ok({ outcome: "refused", refusal: opened.error });
             }
             const { threadId, analysisId, state } = opened.value;
-            // The seam signals an unresolvable resource by a throw. The listing still serves the path and
+            // The seam signals an unresolvable resource by a rejection. The listing still serves the path and
             // the file type of each entry, thus the fault costs the columns alone and never the whole call.
             let root;
             try {
-                root = deps.resolveWorkspaceRoot(analysisId);
+                root = await deps.resolveWorkspaceRoot(analysisId);
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/preview-report.d.ts

@@ -139,7 +139,7 @@ export interface PreviewReportToolDeps {
     readonly makeResolver?: (scope: {
         analysisId: string;
         auth: AuthContext;
-    }) => ReferenceResolver;
+    }) => Promise<ReferenceResolver>;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly resolvePageAsset?: ResolvePageAsset;
     readonly makeSessionPages?: MakeSessionPagePublisher;

package/dist/tools/report-session/preview-report.js

@@ -165,8 +165,8 @@ async function resolveDocument(document, resolver, snapshot) {
 /**
  * Resolve the page root, stage each bound image and each manifest entry, and write the page.
  *
- * The workspace-root seam signals an unresolvable resource by a throw, thus the resolution sits inside
- * the protection and its throw becomes a value. Each `fs` call runs through `tryFsWrite`, the one
+ * The workspace-root seam signals an unresolvable resource by a rejection, thus the resolution sits inside
+ * the protection and its rejection becomes a value. Each `fs` call runs through `tryFsWrite`, the one
  * sanctioned `fs` guard, thus a genuine I/O fault becomes a value and a control-flow exception such as a
  * cancellation propagates.
  *
@@ -186,7 +186,7 @@ async function resolveDocument(document, resolver, snapshot) {
 async function renderToWorkspace(args) {
     let root;
     try {
-        root = args.resolveWorkspaceRoot(args.analysisId);
+        root = await args.resolveWorkspaceRoot(args.analysisId);
     }
     catch (cause) {
         return err({ kind: "fs", error: { type: "read_failed", op: "preview.resolveWorkspaceRoot", path: args.analysisId, cause } });
@@ -382,12 +382,12 @@ export function createPreviewReportTool(deps) {
             if (deps.makeResolver === undefined) {
                 return ok({ outcome: "resolver-unavailable" });
             }
-            // The resolver construction resolves the workspace root inside, and that seam throws on an
-            // unresolvable root. The guard turns the throw into a typed outcome that names the fault, thus a
+            // The resolver construction resolves the workspace root inside, and that seam rejects on an
+            // unresolvable root. The guard turns the rejection into a typed outcome that names the fault, thus a
             // control-flow exception propagates and the unresolvable root does not.
             let resolver;
             try {
-                resolver = deps.makeResolver({ analysisId, auth: ctx.session.auth });
+                resolver = await deps.makeResolver({ analysisId, auth: ctx.session.auth });
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/record-version.d.ts

@@ -105,7 +105,7 @@ export interface RecordVersionToolDeps {
     readonly makeResolver?: (scope: {
         analysisId: string;
         auth: AuthContext;
-    }) => ReferenceResolver;
+    }) => Promise<ReferenceResolver>;
     /** The provenance seam; an unbound session emit emits nothing and the record runs the same. */
     readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;

package/dist/tools/report-session/record-version.js

@@ -86,7 +86,7 @@ async function pruneUnusedDerivations(args) {
     let root;
     let derivedDir;
     try {
-        root = args.resolveWorkspaceRoot(args.analysisId);
+        root = await args.resolveWorkspaceRoot(args.analysisId);
         derivedDir = resolvePath(root, reportSessionDerivedDir(args.threadId));
     }
     catch (cause) {
@@ -169,12 +169,12 @@ export function createRecordVersionTool(deps) {
             if (deps.makeResolver === undefined) {
                 return ok({ outcome: "resolver-unavailable" });
             }
-            // The resolver construction resolves the workspace root inside, and that seam throws on an
-            // unresolvable root. The guard turns the throw into a typed outcome that names the fault, thus a
+            // The resolver construction resolves the workspace root inside, and that seam rejects on an
+            // unresolvable root. The guard turns the rejection into a typed outcome that names the fault, thus a
             // control-flow exception propagates and the unresolvable root does not.
             let resolver;
             try {
-                resolver = deps.makeResolver({ analysisId, auth: ctx.session.auth });
+                resolver = await deps.makeResolver({ analysisId, auth: ctx.session.auth });
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...logger.errorFields(cause) });

package/dist/tools/workspace/mutator.js

@@ -201,9 +201,9 @@ export function createSessionWorkspaceMutator(deps) {
             const scope = session.scope;
             if (scope.kind !== "analysis")
                 return { status: "out_of_scope", path };
-            // Throws on an unknown analysis — the loop's dispatch catch maps
+            // Rejects on an unknown analysis — the loop's dispatch catch maps
             // it to an error tool result, like any unexpected host failure.
-            const workspaceRoot = deps.resolveWorkspaceRoot(scope.analysisId);
+            const workspaceRoot = await deps.resolveWorkspaceRoot(scope.analysisId);
             const landed = await confinedWrite({
                 workspaceRoot,
                 analysisId: scope.analysisId,

package/dist/workflows/execute-analysis.js

@@ -250,7 +250,7 @@ export async function gatherStepPackage(args) {
         throw new Error(`executeAnalysis: step "${stepId}" missing from planStepById — every step must carry its plan data`);
     }
     const analysisId = input.analysisId;
-    const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
+    const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
     // The paths the agent actually sees: the tree is bind-mounted at
     // `/{analysisId}`, and the step's writable directory is its cwd. Derived
     // through the same helpers the sandbox mount and the mutate tools use, so
@@ -661,10 +661,10 @@ async function validateAndInit(input, runId, deps) {
         return { kind: "joined-existing", runId: existing.runId };
     }
     await DBOS.runStep(async () => {
-        // A resolver throw here (unknown analysis, unresolvable root) fails the
+        // A resolver rejection here (unknown analysis, unresolvable root) fails the
         // step durably — exactly the contract the workspace-root-resolution spec
         // requires of failures inside DBOS bodies.
-        await mkdir(join(deps.resolveWorkspaceRoot(input.analysisId), runDir(runId)), {
+        await mkdir(join(await deps.resolveWorkspaceRoot(input.analysisId), runDir(runId)), {
             recursive: true,
         });
     }, { name: "init-run-filesystem" });

package/dist/workflows/sandbox-step.d.ts

@@ -263,12 +263,12 @@ export interface SandboxStepDeps {
      * agent from the catalog, wires its workspace tools, and returns the
      * configured `AgentDefinition` runAgent will drive.
      */
-    buildAgent(ctx: SandboxAgentBuildContext): AgentDefinition;
+    buildAgent(ctx: SandboxAgentBuildContext): Promise<AgentDefinition>;
     /**
      * Resolve the absolute writable artifact prefix for this step. The
      * workspace mutate tools enforce write confinement against this path.
      */
-    resolveWritePrefix(input: SandboxStepInput): string;
+    resolveWritePrefix(input: SandboxStepInput): Promise<string>;
 }
 /**
  * Per-step context passed to every post-step dep. Carries the durable input

package/dist/workflows/sandbox-step.js

@@ -176,7 +176,7 @@ export async function runSandboxStepBody(input, deps) {
     // "conversation-agent"). `run-agent.ts` builds source from
     // `session.provenance.agentId`, and billing tags ride the same provenance.
     const session = forSubAgent(input.runSession, input.agentId);
-    const writePrefix = deps.resolveWritePrefix(input);
+    const writePrefix = await deps.resolveWritePrefix(input);
     const lineageCollector = createLineageCollector(input);
     // (2a) sandbox.mint — checkpoint the machine's identity (its name)
     // BEFORE it is spawned (see the harness-sandbox-exec spec). Durable-before-create is what makes (2b)
@@ -220,7 +220,7 @@ export async function runSandboxStepBody(input, deps) {
     const stepDeadlineMs = (await DBOS.now()) + (input.timeoutSeconds ?? DEFAULT_STEP_TIMEOUT_SECONDS) * 1000;
     const blockerHolder = createBlockerHolder();
     const fileMetadata = createFileMetadataCell();
-    const agent = deps.buildAgent({
+    const agent = await deps.buildAgent({
         input,
         session,
         sandbox,

package/dist/workspace/filesystem.js

@@ -32,7 +32,7 @@ import { lstat as fsLstat, open as fsOpen, readdir as fsReaddir, stat as fsStat
 import { constants as fsConstants } from "node:fs";
 import { createInterface } from "node:readline";
 import { join } from "node:path";
-import { ResultAsync, err, errAsync, ok } from "neverthrow";
+import { ResultAsync, ok } from "neverthrow";
 import { scopeResource } from "../auth/types.js";
 import { tryFetch, tryFs } from "../lib/fs-result.js";
 import { classifyWithinRoot } from "../lib/fs-helpers.js";
@@ -41,7 +41,7 @@ import { resolveWorkspacePath } from "./paths.js";
 export function createWorkspaceFilesystem(deps) {
     const { resolveWorkspaceRoot, presignedFallback } = deps;
     /**
-     * `ResolveWorkspaceRoot` signals an unresolvable resource by throwing — the contract that
+     * `ResolveWorkspaceRoot` signals an unresolvable resource by a rejection — the contract that
      * makes a resolution failure inside a DBOS body a durably-failed step. This seam is not a
      * DBOS body: it promises `Result`, and the read tools it backs are reachable from a live
      * chat turn whose analysis folder may have been moved or deleted since the turn began.
@@ -50,14 +50,12 @@ export function createWorkspaceFilesystem(deps) {
      */
     function resolveFor(session, path, workingDir) {
         const { resourceId: analysisId } = scopeResource(session.scope);
-        let workspaceRoot;
-        try {
-            workspaceRoot = resolveWorkspaceRoot(analysisId);
-        }
-        catch (cause) {
-            return err({ type: "read_failed", op: "workspace.resolveWorkspaceRoot", path: analysisId, cause });
-        }
-        return ok({ resolved: resolveWorkspacePath({ workspaceRoot, analysisId, path, workingDir }), workspaceRoot });
+        return ResultAsync.fromThrowable(resolveWorkspaceRoot, (cause) => ({
+            type: "read_failed",
+            op: "workspace.resolveWorkspaceRoot",
+            path: analysisId,
+            cause,
+        }))(analysisId).map((workspaceRoot) => ({ resolved: resolveWorkspacePath({ workspaceRoot, analysisId, path, workingDir }), workspaceRoot }));
     }
     /**
      * Lexical resolution PLUS a symlink-following confinement check — the single
@@ -70,18 +68,16 @@ export function createWorkspaceFilesystem(deps) {
      * presigned-fallback handling still runs (a non-existent path leaks nothing).
      */
     function confinedResolve(session, path, workingDir) {
-        const base = resolveFor(session, path, workingDir);
-        if (base.isErr())
-            return errAsync(base.error);
-        const { resolved, workspaceRoot } = base.value;
-        if (resolved.kind === "out_of_scope")
-            return okAsync(resolved);
-        return ResultAsync.fromPromise(classifyWithinRoot(workspaceRoot, resolved.absolute), (cause) => ({
-            type: "read_failed",
-            op: "workspace.confineRealpath",
-            path: resolved.absolute,
-            cause,
-        })).map((verdict) => (verdict === "escaped" ? { kind: "out_of_scope" } : resolved));
+        return resolveFor(session, path, workingDir).andThen(({ resolved, workspaceRoot }) => {
+            if (resolved.kind === "out_of_scope")
+                return okAsync(resolved);
+            return ResultAsync.fromPromise(classifyWithinRoot(workspaceRoot, resolved.absolute), (cause) => ({
+                type: "read_failed",
+                op: "workspace.confineRealpath",
+                path: resolved.absolute,
+                cause,
+            })).map((verdict) => (verdict === "escaped" ? { kind: "out_of_scope" } : resolved));
+        });
     }
     return {
         readFile({ session, path, maxBytes, headLines, tailLines, workingDir }) {

package/dist/workspace/paths.d.ts

@@ -43,11 +43,14 @@
  *   - **Stable while the resource has an active run** — derived paths are
  *     recorded in durable step outputs; preventing mid-run moves is the
  *     embedder's job.
- *   - **Throws on unknown resources** — inside DBOS bodies the failure must
- *     cross the step boundary as a throw so the step is durably recorded as
- *     failed (see `lib/result.ts` house rules).
+ *   - **Rejects on unknown resources** — inside DBOS bodies the awaited
+ *     rejection must cross the step boundary as a throw so the step is durably
+ *     recorded as failed (see `lib/result.ts` house rules).
+ *
+ * Async so that a realization can read host state (a marker file on a network
+ * mount) without a block of the event loop.
  */
-export type ResolveWorkspaceRoot = (resourceId: string) => string;
+export type ResolveWorkspaceRoot = (resourceId: string) => Promise<string>;
 /** Result of resolving a workspace path against the canonical layout. */
 export type ResolvedPath = {
     readonly kind: "ok";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.43.0",
+    "version": "0.44.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -33,7 +33,7 @@
         "directory": "harness"
     },
     "scripts": {
-        "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
+        "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
         "design:fixture": "bun scripts/render-fixture.ts",
         "design:gallery": "bun scripts/render-gallery.ts",
         "format": "prettier --write src/",
@@ -41,12 +41,12 @@
         "gallery:data": "bash scripts/gallery-data.sh",
         "lint": "eslint .",
         "lint:python": "ruff check src/input-scan/decoder && ruff format --check src/input-scan/decoder",
-        "prepare": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
+        "prepare": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
         "prepublishOnly": "bun run build && bun run smoke",
         "smoke": "node scripts/smoke.mjs",
         "test:full": "bash scripts/test-full.sh",
         "test:python": "python3 -m pytest src/input-scan/decoder -q",
-        "typecheck": "tsc --noEmit"
+        "typecheck": "tsc -p tsconfig.json --noEmit"
     },
     "dependencies": {
         "@ai-sdk/anthropic": "^4.0.62",
@@ -70,6 +70,8 @@
         "@opentelemetry/sdk-trace-base": "^2.9.0",
         "@opentelemetry/sdk-trace-node": "^2.9.0",
         "@opentelemetry/semantic-conventions": "^1.43.0",
+        "@types/dockerode": "^3.3.47",
+        "@types/pg": "^8.20.0",
         "ag-grid-community": "36.1.0",
         "ai": "^7.0.113",
         "cheerio": "^1.2.0",
@@ -101,10 +103,8 @@
         "@ai-sdk/amazon-bedrock": "^5.0.93",
         "@eslint/js": "^10.0.1",
         "@types/bun": "latest",
-        "@types/dockerode": "^3.3.47",
         "@types/node": "^24.13.3",
         "@types/pdf-parse": "^1.1.5",
-        "@types/pg": "^8.20.0",
         "csstree-validator": "^4.0.1",
         "eslint": "^10.7.0",
         "eslint-plugin-neverthrow": "^1.1.4",