@inflexa-ai/harness 0.34.0 → 0.35.0

package/dist/agents/sandbox/shared.d.ts

@@ -20,7 +20,7 @@ import type { Pool } from "pg";
 import type { AgentDefinition } from "../../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../../providers/types.js";
 import type { SandboxClient } from "../../sandbox/client.js";
-import type { ExtendAnalysisFarm, SandboxRef, ToolchainSource } from "../../sandbox/types.js";
+import type { ExtendAnalysisFarm, SandboxRef } from "../../sandbox/types.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { ProvenanceCollector as LineageCollector } from "../../provenance/collector.js";
 import { type BioToolKeys } from "../../tools/bio/keys.js";
@@ -91,12 +91,6 @@ export interface SandboxAgentDeps extends EnvironmentStorePaths {
      * and the package-link prompt layer appends. Without it, neither exists.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
-    /**
-     * The declared toolchain owner. Keys the orient-core environment text.
-     * Absent keeps the legacy text, thus an old embedder keeps its cached
-     * prompt prefix.
-     */
-    readonly toolchainSource?: ToolchainSource;
 }
 /** Per-agent override for the prompt composition and tool surface. */
 export interface SandboxAgentPromptOptions {

package/dist/agents/sandbox/shared.js

@@ -183,10 +183,13 @@ function buildWorkspaceTools(deps, readOnly) {
 export function createSandboxAgent(deps, meta, body, opts = {}) {
     const appendStandards = opts.appendAnalysisStepStandards ?? true;
     // The layer order is fixed by the harness-sandbox-agents spec: the agent
-    // body, the orient core keyed on the declared toolchain, the package-link
-    // layer only when the seam is bound, then the step standards.
+    // body, the orient core keyed on the toolchain of the sandbox client, the
+    // package-link layer only when the seam is bound, then the step standards.
+    // The client is the one declaration: the environment it provisions and the
+    // text that describes it come from the same value, thus a bag cannot
+    // describe a toolchain the sandbox does not have.
     const sandboxLayer = [
-        sandboxOrientCorePromptFor(deps.toolchainSource),
+        sandboxOrientCorePromptFor(deps.sandboxClient.toolchainSource),
         ...(deps.extendAnalysisFarm ? [sandboxPackageLinkPrompt] : []),
         ...(appendStandards ? [sandboxAnalysisStepStandardsPrompt] : []),
     ];

package/dist/config/environment-stores.d.ts

@@ -45,11 +45,14 @@ export interface EnvironmentStorePaths {
      */
     readonly farmLockFile?: string;
     /**
-     * Host path of the baked image inventory fragment
-     * (`image-packages.txt`) — the image-owned tools that
-     * `list_available_packages` merges into its report. Omit when the host
-     * cannot read one; a missing fragment merges nothing, and that is a
-     * normal state.
+     * Host path of the image inventory record, `image-packages.json` at the
+     * root of the package store — the image-owned tools and Node packages
+     * that `list_available_packages` merges into its report. Omit when the
+     * host's own process sees the store at the container mountpoint, which
+     * makes `/mnt/libs/image-packages.json` correct as-is; set it when the
+     * host reads the store somewhere else. An absent or invalid record
+     * merges nothing, and that is a normal state: a store packed before the
+     * record existed carries none, and the rest of the report stays whole.
      */
     readonly imagePackagesFile?: string;
     /**
@@ -81,7 +84,7 @@ export type PoolInventoryRead = {
 /** One package entry of an inventory section, with the store identity where the source records it. */
 export interface PoolInventoryPackage {
     readonly name: string;
-    /** The pinned version, rendered as `name==version`. Absent for an image-fragment tool. */
+    /** The pinned version, rendered as `name==version`. Absent where the source pins none. */
     readonly version?: string;
     /** The content-addressed store directory of the package. */
     readonly storeDir?: string;

package/dist/index.d.ts

@@ -134,9 +134,12 @@ export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/create-sandbox.js";
 export type { SandboxClient } from "./sandbox/client.js";
+export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
+export type { SandboxError } from "./sandbox/sandbox-error.js";
 export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequest, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
 export type { FarmLock, FarmLockError } from "./sandbox/farm.js";
+export { IMAGE_PACKAGES_FILE } from "./sandbox/image-packages.js";
 export type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventoryRead, PoolInventorySection } from "./config/environment-stores.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export type { MachineBudget, ResourceLimits, ResourcePolicy, ResourceSpec } from "./config/resource-limits.js";

package/dist/index.js

@@ -237,9 +237,15 @@ export { createAnalysisPurge } from "./state/purge-analysis.js";
 // the failure a fixed-width comparand exists to prevent.
 export { computeInputSignature } from "./execution/input-signature.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
+// The throw of the client seam. An embedder matches the class and reads the
+// typed variant on `error`, instead of a string match on the message.
+export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
 // The farm contract: one `inflexa.lock` per farm. An embedder that composes
 // farms writes this shape, and the mount gate reads it — one schema, no copy.
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
+// The image record: one file name at the root of the store. An embedder joins
+// it onto its own store root for `imagePackagesFile`.
+export { IMAGE_PACKAGES_FILE } from "./sandbox/image-packages.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";
 // Exec-callback ingress building blocks. Delivery goes through

package/dist/prompts/sandbox-standards.d.ts

@@ -22,20 +22,20 @@
  * `prompts/briefing.ts`), which is composed per dispatch and where per-step
  * content belongs.
  *
- * The orient-core text keys on the declared `toolchainSource`
- * (`sandboxOrientCorePromptFor`). The absent field gives the legacy constant
- * untouched, thus an old embedder keeps its cached prefix byte-identical.
- * Both variants are composition-time constants, thus each composition stays
- * byte-stable across its own steps.
+ * The orient-core text keys on the `toolchainSource` of the sandbox client
+ * (`sandboxOrientCorePromptFor`). `"store"` gives the legacy constant
+ * untouched, thus an embedder that declares no toolchain keeps its cached
+ * prefix byte-identical. Both variants are composition-time constants, thus
+ * each composition stays byte-stable across its own steps.
  */
 import type { ToolchainSource } from "../sandbox/types.js";
 export declare const sandboxOrientCorePrompt = "# Sandbox Orient-Core\n\nThese apply to every agent that talks to a sandbox.\n\n## Your Briefing Is Authoritative\n\nYour first message is your briefing, composed for this step at the instant it was\ndispatched \u2014 after every step it depends on had finished. It names your task, your\nworking directory and the read-only analysis root, what the input dataset is\n(domain, organism, design, quality concerns, files), and what each upstream step\nproduced and where it put it. Work from it.\n\nDo NOT re-derive what it already gives you: no filesystem hunt for your inputs, no\nre-reading an upstream step whose summary you were handed, no re-deriving the\norganism or the dimensions from raw bytes. Reach further only where the briefing is\ngenuinely thin for what you must do:\n\n- `inspect_data_profile` \u2014 the full dataset profile: `scope:'overview'` for the\n  identity and the file census, `scope:'groups'` for the groups and the dimensions\n  that vary across them, `scope:'files'` for the members the profiler annotated\n  individually. It is the ONLY record of what the input data IS; no file on disk\n  carries it. Use it when the briefing's orientation is not enough, or when it\n  carried none.\n- `read_file` on an upstream step's summary \u2014 its path is in your briefing \u2014 when\n  the excerpt you were handed is not enough to build on.\n- `workspace_search({ query })` \u2014 natural-language search for a file the briefing\n  does not name. Optional `type` filter (`input-group` | `input-dimension` |\n  `input` | `output` | `summary` | `synthesis`) and `limit` (1-50, default 8).\n  Returns paths, descriptions, and metadata \u2014 not file contents. Most input files\n  carry no entry of their own; reach them through their group and `list_files`.\n\n## Your Workspace\n\nYour **working directory** \u2014 writable, and your cwd \u2014 and the read-only\n**analysis root** are named in your briefing. Use those paths exactly; do not\ninvent or guess one.\n\n- **Relative paths resolve against your working directory** \u2014 in `read_file`,\n  `list_files`, `file_stat`, `grep`, `write_file`, `edit_file`,\n  `execute_command`, and any script you run. `output/de.csv` means\n  `<working directory>/output/de.csv` everywhere \u2014 a file you write at a\n  relative path is read back at the same relative path.\n- **You may write only inside your working directory.** A write outside it\n  comes back as an `out_of_prefix` result (no I/O performed); fix the path.\n- The rest of the analysis is mounted **read-only** at the analysis root. Reach\n  input data (under `data/inputs/`) and other steps' outputs (under `runs/`)\n  with an **absolute** path beneath it.\n- **Absolute analysis-root paths are canonical** \u2014 use one whenever you\n  reference a file you didn't create in this step.\n\n`write_file` creates parent directories as needed \u2014 no separate mkdir.\n\n## Scope \u2014 Analysis Starts at Processed Data\n\nThis environment does **tertiary analysis**: turning processed data into\nbiological findings. Read processing \u2014 alignment, quantification, variant\ncalling, peak calling \u2014 belongs upstream, wherever the instrument output was\nhandled. No tool for it is installed, and none can be.\n\nYour inputs are count and expression matrices, called variants, peak sets,\nsignal tracks, and the metadata describing them. When a request arrives as raw\nreads or unprocessed instrument output, name the processed form you need and\nstop. Do not improvise a pipeline, do not substitute a Python reimplementation\nof an aligner or peak caller, and do not treat a missing upstream tool as an\nobstacle to route around \u2014 it is the boundary of the product, not a gap.\n\nData that has already been processed can still be **read**: `samtools`,\n`bcftools`, `tabix`, `bedtools` and `vcftools` are installed so you can\ninspect, subset, and convert existing BAM/CRAM, VCF and BED. Reading evidence at\nsites you already have is in scope; producing the calls is not.\n\n## Environment \u2014 No Network, No Installs\n\n**There is no egress from this sandbox.** Outbound connections are blocked at the\nfirewall, not merely discouraged: every download, API call, package install, and\n`ExperimentHub`/`AnnotationHub`/`models.download_*` style fetch fails outright.\nThere is no proxy, no mirror, and no retry that succeeds. Packages and reference\ndata were staged onto read-only mounts by the host **before** this container\nstarted, and that is the whole of what exists. Work that genuinely requires the\ninternet \u2014 fetching a dataset, querying an external API, literature lookup \u2014 is\ndone **outside** the sandbox through the host's tools, not from your scripts.\n\nSo: check what you need when you need it \u2014 a targeted lookup, never a catalog dump\nup front.\n\n- **Packages** \u2014 before importing a package you are not certain is present, look it\n  up with `list_available_packages`, narrowed to the packages you actually intend\n  to import. Importing one that isn't installed fails the script; the lookup costs\n  one call.\n- **Reference data** \u2014 `list_available_refs` resolves reference data into a real\n  path against the store mounted read-only at `/mnt/refs`. **Search by what the\n  data IS, not by where you expect it** (\"TF-target regulons\", \"hallmark gene\n  sets\", \"mouse\"): the store's directory layout is an installer detail, it differs\n  between hosts, and no path you have seen before is guaranteed to exist here.\n  Catalogued entries come back with the organism, the format, and the file's\n  internal shape, so read the entry and use the reader and species it names rather\n  than assuming \u2014 formats vary per dataset, and there is no guarantee any given\n  collection ships in the format your tool prefers.\n  The store is OPTIONAL and may be absent or hold none of what you want \u2014 a normal\n  state, not an error. Never assume a reference path exists and never hardcode one:\n  if a reference you need is not in the inventory, say so plainly and proceed with\n  what you do have (or state what must be provisioned) rather than inventing a path\n  or substituting something else unannounced. Pass reference paths EXPLICITLY to the\n  library \u2014 nothing in the image points a library at the store, so a library that\n  resolves data by name from an env var (CellTypist reads `$CELLTYPIST_FOLDER`)\n  will not find it unless you export that variable yourself, in the same command,\n  using a path the inventory actually returned.\n- Do NOT call a library's built-in data fetcher \u2014 `dc.op.collectri()`,\n  `dc.op.progeny()`, `dc.op.msigdb()` and every other `dc.op.*()`, CellTypist's\n  `models.download_models()`, gseapy's Enrichr library names, `ExperimentHub`/\n  `AnnotationHub` \u2014 they all reach for the network and will fail. Load from an\n  inventory path instead. Do NOT download data or install packages at runtime.\n\n## CPU Budget and Parallelism\n\nYour briefing names this step's CPU quota and memory limit. The container's\ncore-count calls (`parallel::detectCores()`, `os.cpu_count()`) report the\nquota, so worker counts sized from them are safe.\n\nBLAS/OpenMP thread pools default to **1 thread** (`OMP_NUM_THREADS`,\n`OPENBLAS_NUM_THREADS`, `MKL_NUM_THREADS`, \u2026). A forked worker inherits its\nparent's pool size, so this default is what keeps `mclapply` /\n`multiprocessing` from running workers \u00D7 threads on a quota sized for one of\nthem. The rule: **workers \u00D7 threads-per-worker must not exceed the quota.** A\nmix is fine while the product stays inside it.\n\n- **Fork/worker parallelism** (`mclapply`, `BiocParallel`, `joblib`,\n  `multiprocessing`): size the workers from the reported core count and leave\n  the thread defaults alone \u2014 there is nothing to raise. `joblib` also\n  divides its own thread budget across its workers; do not manage it.\n- **Thread parallelism** (one process: xgboost, WGCNA, data.table, polars, a\n  single large BLAS fit): raise the thread variables for that command through\n  `execute_command`'s `env`, e.g.\n  `env: { \"OMP_NUM_THREADS\": \"4\", \"OPENBLAS_NUM_THREADS\": \"4\" }` on a 4-CPU\n  quota.\n\nExceeding the quota does not kill the step \u2014 the cgroup throttles it \u2014 but an\noversubscribed step runs slower and can starve the exec server that runs your\ncommands.\n\n## Output Contract \u2014 Persisted Files Are the Deliverable\n\nThis is a hard requirement, not a convention. **Your deliverable is persisted\nfiles**, nothing else:\n\n- the **script** you wrote, in `scripts/`,\n- the **data it computed** (derived from the input data), in `output/`,\n- any **figures**, in `figures/`.\n\nConclusions are drawn from those computed output files \u2014 never narrated from\n`execute_command` stdout. stdout/stderr are ephemeral; they are gone the\nmoment the command returns. **A step that ends without persisted\nscripts + outputs has produced nothing**, even if its transcript reads as if\nwork was done. In particular: running the analysis as an inline `python -c` /\n`Rscript -e` one-liner and reporting the numbers it printed produces nothing \u2014\nwrite the script to `scripts/` and persist what it computes to `output/`.\n\nA genuine verdict / QC / decision step that has no tabular result may instead\nwrite a short Markdown memo to `output/` (e.g. `output/qc-verdict.md`) stating\nthe finding and the evidence it rests on \u2014 a real persisted artifact. Do not\nfabricate a CSV just to have one.\n\nIf you genuinely cannot fulfill the step \u2014 required input data is missing, a\ntool you need is unavailable, or the environment is broken \u2014 call\n`report_blocker({ reason })` with a clear, specific reason. Do NOT improvise an\ninline result, fabricate outputs, or end on a prose narrative pretending the\nwork was done. `report_blocker` is the honest exit; an empty step that claims\nsuccess is not.\n\n## Skills \u2014 Method Selection and API Details\n\nSkills hold the full decision trees, API references, contrast syntax, worked\nexamples, and domain anti-patterns that do not fit in prompts. Use them\nactively \u2014 they are your authoritative source on methods.\n\n- `skill_search(query)` \u2014 keyword search across the skills available to you.\n  Start here when picking a method or verifying an API detail. Examples:\n  `skill_search(\"PyDESeq2 contrast syntax\")`,\n  `skill_search(\"Leiden clustering resolution\")`.\n- `skill_read(skill, path)` \u2014 read a file from one of your skills, e.g.\n  `skill_read(\"bulk-transcriptomics\", \"SKILL.md\")` or\n  `skill_read(\"bulk-transcriptomics\", \"references/pydeseq2-api.md\")`.\n\nThe skills you have access to are listed in your agent instructions.\n\n## Context7 \u2014 Documentation Lookup\n\nLook up current documentation via context7 before writing non-trivial code:\n1. `resolve_library_id` with the package name to get the library ID.\n2. `query_docs` with the library ID and the specific function or method.\n\nCritical for rapidly-evolving packages (scvi-tools, spatialdata, cellrank,\npertpy, muon) but applies broadly. Do NOT guess API details from memory \u2014\nverify with context7 or skill references first.\n\n## Command Execution\n\n`execute_command` runs analysis work \u2014 scripts, bioinformatics CLI tools,\nshell pipes, and anything the workspace tools don't express. It starts in your\nworking directory; a relative `cwd` argument is resolved against it.\n\nFor these tasks, prefer the dedicated workspace tools \u2014 they are faster than\nshelling out and don't waste a turn on path discovery:\n\n| Task                            | Use this tool   | Instead of                 |\n|-|-|-|\n| List files in a directory       | `list_files`    | `ls` / `ls -la` / `find -name` |\n| Read a text/source/result file  | `read_file`     | `cat` / `less`             |\n| Search file contents by pattern | `grep`          | shell `grep` / `rg`        |\n| Size / type of a path           | `file_stat`     | `stat` / `wc -c`           |\n\n**Use `execute_command` for everything else**, including:\n\n- **Running scripts** \u2014 `python scripts/run.py`, `Rscript scripts/de.R`,\n  `ruff check scripts/foo.py`.\n- **Previewing huge / binary files** \u2014 `wc -l file.tsv`, `zcat file.gz | head`.\n  For text files, prefer `read_file` with `headLines` / `tailLines`.\n- **Shell pipes / chaining** \u2014 `sort | uniq -c | sort -rn | head`.\n- **`find` with non-name predicates** \u2014 `find . -mtime -1`, `find . -size +10M`.\n- **Real CLI tools** \u2014 `samtools`, `bcftools`, `tabix`, `bedtools`,\n  `vcftools`, version probes like `python -c \"import x; print(x.__version__)\"`.\n\n**Shell behavior to know:**\n\n- `cd` does NOT persist across calls \u2014 each exec starts in your working\n  directory. For cross-call state, pass `cwd` or chain with `&&` in one exec.\n- Quote paths with spaces: `head \"data/inputs/My Folder/file.csv\"`. In Python,\n  use `pathlib.Path` or `os.path`.\n\n## Editing Files\n\n`edit_file` replaces `old_string` with `new_string`. Read the file first to\nget the exact text. When `replace_all` is false (default), `old_string` must\noccur exactly once \u2014 include surrounding context to make it unique.\n";
 /**
  * The orient-core layer for one declared toolchain. `"image"` states that an
  * acquisition is a host action and directs the agent to report a missing
- * package. The absent field gives the legacy constant untouched.
+ * package. `"store"` gives the legacy constant untouched.
  */
-export declare function sandboxOrientCorePromptFor(toolchainSource: ToolchainSource | undefined): string;
+export declare function sandboxOrientCorePromptFor(toolchainSource: ToolchainSource): string;
 /**
  * The package-link layer — appended to the sandbox system prompt only when
  * the embedder binds the `ExtendAnalysisFarm` seam. A composition-time

package/dist/prompts/sandbox-standards.js

@@ -22,11 +22,11 @@
  * `prompts/briefing.ts`), which is composed per dispatch and where per-step
  * content belongs.
  *
- * The orient-core text keys on the declared `toolchainSource`
- * (`sandboxOrientCorePromptFor`). The absent field gives the legacy constant
- * untouched, thus an old embedder keeps its cached prefix byte-identical.
- * Both variants are composition-time constants, thus each composition stays
- * byte-stable across its own steps.
+ * The orient-core text keys on the `toolchainSource` of the sandbox client
+ * (`sandboxOrientCorePromptFor`). `"store"` gives the legacy constant
+ * untouched, thus an embedder that declares no toolchain keeps its cached
+ * prefix byte-identical. Both variants are composition-time constants, thus
+ * each composition stays byte-stable across its own steps.
  */
 export const sandboxOrientCorePrompt = `# Sandbox Orient-Core
 
@@ -291,7 +291,7 @@ sandbox.`), `- **Packages** — before importing a package you are not certain i
 /**
  * The orient-core layer for one declared toolchain. `"image"` states that an
  * acquisition is a host action and directs the agent to report a missing
- * package. The absent field gives the legacy constant untouched.
+ * package. `"store"` gives the legacy constant untouched.
  */
 export function sandboxOrientCorePromptFor(toolchainSource) {
     return toolchainSource === "image" ? imageToolchainOrientCorePrompt : sandboxOrientCorePrompt;

package/dist/sandbox/client.d.ts

@@ -25,8 +25,17 @@
  * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
  * rule yet, thus a new caller must read this paragraph.
  */
-import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody } from "./types.js";
+import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody, ToolchainSource } from "./types.js";
 export interface 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
+     * declared nothing. The mount plan and the orient-core prompt both key on
+     * this one value, thus the environment a sandbox gets and the text that
+     * describes it cannot disagree. Required rather than optional, because an
+     * optional field would carry two meanings, undeclared and unknown.
+     */
+    readonly toolchainSource: ToolchainSource;
     /**
      * DBOS step (`sandbox.create`) — the spawn half of the two-step create
      * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the

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

@@ -80,6 +80,18 @@ export interface CreateSandboxClientConfig {
      * this field existed.
      */
     toolchainSource?: ToolchainSource;
+    /**
+     * The deployment cannot run an analysis without the package store. Under
+     * the fact, a farm that fails the `inflexa.lock` gate refuses the create
+     * with `farm_unusable`, and neither backend makes a machine. Absent keeps
+     * the degrade: the store mounts drop, a warning is logged, and the
+     * sandbox reports the store as unavailable. The field names the
+     * deployment fact rather than the remediation, so how the harness answers
+     * it can evolve without changing the embedder surface; a single-valued
+     * union (not a boolean) so future store classes extend it without a
+     * breaking change.
+     */
+    packageStore?: "required";
     /** Docker: host dir bind-mounted read-only at `/mnt/refs`. */
     refStorePath?: string;
     /** Docker: force the container platform (e.g. `linux/amd64`) so the sandbox matches the mounted lib store's arch. */

package/dist/sandbox/create-sandbox.js

@@ -23,6 +23,7 @@ import { awaitExec } from "./await-exec.js";
 import { createDockerSandboxOps } from "./docker-client.js";
 import { createK8sSandboxOps } from "./k8s-client.js";
 import { sandboxWriteTail } from "./mount-plan.js";
+import { SandboxFailure } from "./sandbox-error.js";
 import { submitExec } from "./submit-exec.js";
 import { toPersistedRef } from "./types.js";
 /**
@@ -73,6 +74,39 @@ export async function precreateStepTree(deps, meta) {
 export function createSandboxClient(config) {
     const backend = config.backend ?? config.env.backend;
     const transport = config.transport ?? "poll";
+    // Normalized once, here, and handed to the backends and to the client
+    // alike: the mount plan and the orient-core prompt then key on one value,
+    // and an absent declaration means "store" on both sides.
+    const toolchainSource = config.toolchainSource ?? "store";
+    // The declared fact needs a gate that can prove it. Each combination below
+    // leaves the backend with no gate at all, thus the fact could never be
+    // proved and every create would pass an unproved store. The refusal is at
+    // composition, where the embedder states the fact — the same rule as the
+    // tail-beside-readOnly throw in `mount-plan.ts` — because a contradiction
+    // found at the first sandbox costs a whole run. A K8s `per-analysis` farm
+    // source with no `libStorePvcRoot` is NOT a contradiction: there the
+    // resolver owes the proof, and its refusal already stops the create.
+    if (config.packageStore === "required") {
+        if (backend === "docker" && !config.libStorePath) {
+            throw new Error("createSandboxClient: packageStore is required but no libStorePath is configured — the docker lock gate has no store to prove");
+        }
+        if (backend === "k8s" && !config.libStorePvc) {
+            throw new Error("createSandboxClient: packageStore is required but no libStorePvc is configured — the k8s lock gate has no store to prove");
+        }
+        if (backend === "k8s" && config.farmSource.kind === "fixed" && !config.libStorePvcRoot) {
+            throw new Error("createSandboxClient: packageStore is required but a fixed farm source has no libStorePvcRoot — no resolver and no host-side gate can prove the store");
+        }
+    }
+    /**
+     * What the seam throws for a backend failure: the description of the
+     * 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
+     * unwraps below stay on the plain bridge: they carry a `DbError`.
+     */
+    const failing = (e) => new SandboxFailure(e);
     const registerSandbox = async (meta, ref) => {
         unwrapOrThrow(await setSandboxRef(config.pool, meta.runId, meta.stepId, toPersistedRef(ref), meta.execId ?? null));
     };
@@ -88,7 +122,8 @@ export function createSandboxClient(config) {
             libStorePvc: config.libStorePvc,
             libStorePvcRoot: config.libStorePvcRoot,
             farmSource: config.farmSource,
-            toolchainSource: config.toolchainSource,
+            toolchainSource,
+            packageStore: config.packageStore,
             refStorePvc: config.refStorePvc,
             nodeSelector: config.nodeSelector,
             tolerations: config.tolerations,
@@ -103,7 +138,8 @@ export function createSandboxClient(config) {
             resolveWorkspaceRoot: config.resolveWorkspaceRoot,
             libStorePath: config.libStorePath,
             farmSource: config.farmSource,
-            toolchainSource: config.toolchainSource,
+            toolchainSource,
+            packageStore: config.packageStore,
             refStorePath: config.refStorePath,
             platform: config.platform,
             engineSocketPath: config.engineSocketPath,
@@ -115,7 +151,7 @@ export function createSandboxClient(config) {
     // ref + step coordinates and the wrapper does the clear after the
     // backend-level removal.
     const teardown = async (ref) => {
-        unwrapOrThrow(await ops.teardown(ref));
+        unwrapOrThrow((await ops.teardown(ref)).mapErr(failing));
         // Sandboxes are 1-per-step (see `sandbox-step.ts` body — each child
         // workflow calls `createSandbox` once then `teardown` once), so the
         // broad WHERE clause matches exactly one row. If that invariant ever
@@ -132,8 +168,9 @@ export function createSandboxClient(config) {
     };
     // One arbiter for both surfaces: the client's `isAlive` method and the
     // poll loop's escalation probe are the same backend inspect.
-    const isAlive = async (ref) => unwrapOrThrow(await ops.isAlive(ref));
+    const isAlive = async (ref) => unwrapOrThrow((await ops.isAlive(ref)).mapErr(failing));
     return {
+        toolchainSource,
         createSandbox: async (meta, identity) => {
             // The config states an engine fact (binds preserve host ownership);
             // which remediation that fact demands — today, a world-writable step
@@ -150,7 +187,7 @@ export function createSandboxClient(config) {
             }
             // Clamp to cluster ceilings so the pod is always quota-admissible.
             const resources = clampResources(meta.resources, config.resourceLimits);
-            return unwrapOrThrow(await ops.createSandbox({ ...meta, resources }, identity));
+            return unwrapOrThrow((await ops.createSandbox({ ...meta, resources }, identity)).mapErr(failing));
         },
         submitExec: async (ref, body) => submitExec(ref, body, {
             ...config.submitDeps,
@@ -163,10 +200,10 @@ export function createSandboxClient(config) {
         // retention budget and still returns whole streams.
         awaitExec: async (ref, execId, emit, deadline) => capExecStreams(await awaitExec(ref, execId, emit, deadline, composeAwaitOptions(config.awaitOptions, transport, isAlive)), config.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP),
         isAlive,
-        isAliveById: async (sandboxId) => unwrapOrThrow(await ops.isAliveById(sandboxId)),
+        isAliveById: async (sandboxId) => unwrapOrThrow((await ops.isAliveById(sandboxId)).mapErr(failing)),
         teardown,
-        teardownById: async (sandboxId) => unwrapOrThrow(await ops.teardownById(sandboxId)),
-        listManagedSandboxes: async () => unwrapOrThrow(await ops.listManagedSandboxes()),
+        teardownById: async (sandboxId) => unwrapOrThrow((await ops.teardownById(sandboxId)).mapErr(failing)),
+        listManagedSandboxes: async () => unwrapOrThrow((await ops.listManagedSandboxes()).mapErr(failing)),
     };
 }
 /** Re-exports so consumers import once from this module. */

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

@@ -63,6 +63,17 @@ export interface DockerClientConfig {
     farmSource: FarmSource;
     /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
     toolchainSource?: ToolchainSource;
+    /**
+     * The deployment cannot run an analysis without the package store. Under
+     * the fact, a farm that fails the `inflexa.lock` gate refuses the create
+     * with `farm_unusable` and no container is made. Absent keeps the
+     * degrade: the store mounts drop, a warning is logged, and the container
+     * is still made. The field names the deployment fact rather than the
+     * remediation, so how the harness answers it can evolve without changing
+     * the embedder surface; a single-valued union (not a boolean) so future
+     * store classes extend it without a breaking change.
+     */
+    packageStore?: "required";
     /**
      * Host ref store; bind-mounted read-only at `/mnt/refs`. Embedders pass the
      * configured store location unconditionally — existence is (re-)checked at each

package/dist/sandbox/docker-client.js

@@ -246,15 +246,29 @@ export function createDockerSandboxOps(config) {
                     farm = resolved.value;
                 }
                 // The `inflexa.lock` gate runs at each create: the store may have
-                // gone away, or the farm may be half-written. A gate failure
-                // degrades — both store mounts drop, the container is still made,
-                // and the sandbox reports the store as unavailable. The warning is
-                // logged because an otherwise-silent mount drop is invisible to
-                // operators.
+                // gone away, or the farm may be half-written. The failure has two
+                // outcomes. Under the declared fact the call refuses with
+                // `farm_unusable` before any container work, and it logs nothing:
+                // the returned value carries the reason, and the consumer logs the
+                // throw, thus a warning here would record the one fault twice.
+                // Without the fact it degrades — both store mounts drop, the
+                // container is still made, and the sandbox reports the store as
+                // unavailable. That drop is otherwise silent, thus it is warned.
                 let libsMounted = false;
                 if (config.libStorePath && farm) {
                     const lock = readFarmLock(farm.farmPath);
                     libsMounted = lock.isOk();
+                    if (lock.isErr() && config.packageStore === "required") {
+                        return err({
+                            type: "farm_unusable",
+                            op: "docker.createSandbox",
+                            analysisId: meta.analysisId,
+                            farmPath: farm.farmPath,
+                            lockPath: lock.error.lockPath,
+                            lockError: lock.error.type,
+                            cause: lock.error.cause,
+                        });
+                    }
                     if (lock.isErr()) {
                         logger.warn("the farm of the analysis has no usable inflexa.lock at sandbox creation — mounting no package store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, farmPath: farm.farmPath, lockError: lock.error.type, sandboxId });
                     }

package/dist/sandbox/farm.d.ts

@@ -10,7 +10,9 @@
  * - A resolver refusal (`unavailable`, or a throw) is a `farm_unavailable`
  *   `SandboxError` — the call refuses and no container is made.
  * - A lock-gate failure degrades — the backend drops both store mounts,
- *   logs a warning, and still makes the container.
+ *   logs a warning, and still makes the container. Under a config that
+ *   declares `packageStore: "required"`, the same failure refuses with
+ *   `farm_unusable`, and no container is made.
  */
 import { type Result } from "neverthrow";
 import { z } from "zod";

package/dist/sandbox/farm.js

@@ -10,7 +10,9 @@
  * - A resolver refusal (`unavailable`, or a throw) is a `farm_unavailable`
  *   `SandboxError` — the call refuses and no container is made.
  * - A lock-gate failure degrades — the backend drops both store mounts,
- *   logs a warning, and still makes the container.
+ *   logs a warning, and still makes the container. Under a config that
+ *   declares `packageStore: "required"`, the same failure refuses with
+ *   `farm_unusable`, and no container is made.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";

package/dist/sandbox/image-packages.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `image-packages.json` — the self-description of the sandbox image.
+ *
+ * The image bakes two package tracks that the content-addressed store cannot
+ * hold: the conda tools at `/opt/conda` and the Node packages at `/opt/node`.
+ * The image writes one record of them at `/opt/inflexa/image-packages.json`,
+ * and the catalog build copies that record verbatim into the root of the
+ * package store it packed beside it. Thus every reader of a store learns the
+ * image inventory from the store alone — with no container engine, no
+ * registry client, and no path outside the store.
+ *
+ * The record is JSON with a `schema` number, the same convention as
+ * {@link FarmLockSchema}: an additive field passes through untouched, and a
+ * breaking change to the shape moves the number instead. A structured record
+ * is what lets a row carry its version, and what lets a later change compare
+ * the recorded image against the configured one.
+ *
+ * This schema is the ONE definition of the shape. The image writes the bytes
+ * and the harness validates them, thus a producer that drifts is refused here
+ * rather than half-read downstream.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+/**
+ * The file name of the record, at the root of the package store. Exported,
+ * as `FARM_LOCK_FILE` is, thus an embedder that joins the path onto its own
+ * store root never spells the name by hand.
+ */
+export declare const IMAGE_PACKAGES_FILE = "image-packages.json";
+/** The image the record describes. The pair of tags shares one version string. */
+export declare const ImageIdentitySchema: z.ZodObject<{
+    repository: z.ZodString;
+    version: z.ZodString;
+    arch: z.ZodEnum<{
+        amd64: "amd64";
+        arm64: "arm64";
+    }>;
+}, z.core.$loose>;
+/** The interpreter versions of the image, so a reader can compare them against the lock. */
+export declare const ImageRuntimesSchema: z.ZodObject<{
+    python: z.ZodString;
+    r: z.ZodString;
+    node: z.ZodString;
+}, z.core.$loose>;
+/**
+ * One conda tool of the image. `executable` carries the binary name when it
+ * differs from the package name (the manifest `binaries:` map holds those
+ * exceptions), because an agent invokes the binary and not the package.
+ */
+export declare const ImageSystemToolSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    executable: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** One Node package of the image. */
+export declare const ImageNodePackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+}, z.core.$loose>;
+/**
+ * `image-packages.json` at schema version 1. The keys `system_tools` and
+ * `node` are the keys of the image manifest, thus one name means one track
+ * across the build and the reader.
+ */
+export declare const ImagePackagesSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    image: z.ZodObject<{
+        repository: z.ZodString;
+        version: z.ZodString;
+        arch: z.ZodEnum<{
+            amd64: "amd64";
+            arm64: "arm64";
+        }>;
+    }, z.core.$loose>;
+    runtimes: z.ZodObject<{
+        python: z.ZodString;
+        r: z.ZodString;
+        node: z.ZodString;
+    }, z.core.$loose>;
+    system_tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        executable: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    node: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ImagePackages = z.infer<typeof ImagePackagesSchema>;
+export type ImagePackagesError = {
+    readonly type: "record_unreadable";
+    readonly recordPath: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "record_invalid";
+    readonly recordPath: string;
+    readonly cause: unknown;
+};
+/**
+ * Read and validate one `image-packages.json` by its file path. The read is
+ * synchronous, the same as {@link readFarmLockFile}, because the caller reads
+ * the record on each call and a store download can land while the process
+ * runs. Both errors are normal states of a host that reads a store from
+ * before this record existed.
+ */
+export declare function readImagePackagesFile(recordPath: string): Result<ImagePackages, ImagePackagesError>;

package/dist/sandbox/image-packages.js

@@ -0,0 +1,107 @@
+/**
+ * `image-packages.json` — the self-description of the sandbox image.
+ *
+ * The image bakes two package tracks that the content-addressed store cannot
+ * hold: the conda tools at `/opt/conda` and the Node packages at `/opt/node`.
+ * The image writes one record of them at `/opt/inflexa/image-packages.json`,
+ * and the catalog build copies that record verbatim into the root of the
+ * package store it packed beside it. Thus every reader of a store learns the
+ * image inventory from the store alone — with no container engine, no
+ * registry client, and no path outside the store.
+ *
+ * The record is JSON with a `schema` number, the same convention as
+ * {@link FarmLockSchema}: an additive field passes through untouched, and a
+ * breaking change to the shape moves the number instead. A structured record
+ * is what lets a row carry its version, and what lets a later change compare
+ * the recorded image against the configured one.
+ *
+ * This schema is the ONE definition of the shape. The image writes the bytes
+ * and the harness validates them, thus a producer that drifts is refused here
+ * rather than half-read downstream.
+ */
+import { readFileSync } from "node:fs";
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+/**
+ * The file name of the record, at the root of the package store. Exported,
+ * as `FARM_LOCK_FILE` is, thus an embedder that joins the path onto its own
+ * store root never spells the name by hand.
+ */
+export const IMAGE_PACKAGES_FILE = "image-packages.json";
+/** The image the record describes. The pair of tags shares one version string. */
+export const ImageIdentitySchema = z
+    .object({
+    repository: z.string(),
+    version: z.string(),
+    arch: z.enum(["amd64", "arm64"]),
+})
+    .passthrough();
+/** The interpreter versions of the image, so a reader can compare them against the lock. */
+export const ImageRuntimesSchema = z
+    .object({
+    python: z.string(),
+    r: z.string(),
+    node: z.string(),
+})
+    .passthrough();
+/**
+ * One conda tool of the image. `executable` carries the binary name when it
+ * differs from the package name (the manifest `binaries:` map holds those
+ * exceptions), because an agent invokes the binary and not the package.
+ */
+export const ImageSystemToolSchema = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+    executable: z.string().optional(),
+})
+    .passthrough();
+/** One Node package of the image. */
+export const ImageNodePackageSchema = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+})
+    .passthrough();
+/**
+ * `image-packages.json` at schema version 1. The keys `system_tools` and
+ * `node` are the keys of the image manifest, thus one name means one track
+ * across the build and the reader.
+ */
+export const ImagePackagesSchema = z
+    .object({
+    schema: z.literal(1),
+    image: ImageIdentitySchema,
+    runtimes: ImageRuntimesSchema,
+    system_tools: z.array(ImageSystemToolSchema),
+    node: z.array(ImageNodePackageSchema),
+})
+    .passthrough();
+/**
+ * Read and validate one `image-packages.json` by its file path. The read is
+ * synchronous, the same as {@link readFarmLockFile}, because the caller reads
+ * the record on each call and a store download can land while the process
+ * runs. Both errors are normal states of a host that reads a store from
+ * before this record existed.
+ */
+export function readImagePackagesFile(recordPath) {
+    let raw;
+    try {
+        raw = readFileSync(recordPath, "utf8");
+    }
+    catch (cause) {
+        return err({ type: "record_unreadable", recordPath, cause });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        return err({ type: "record_invalid", recordPath, cause });
+    }
+    const record = ImagePackagesSchema.safeParse(parsed);
+    if (!record.success) {
+        return err({ type: "record_invalid", recordPath, cause: record.error });
+    }
+    return ok(record.data);
+}

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

@@ -71,6 +71,17 @@ export interface K8sClientConfig {
     farmSource: FarmSource;
     /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
     toolchainSource?: ToolchainSource;
+    /**
+     * The deployment cannot run an analysis without the package store. Under
+     * the fact, a farm that fails the `inflexa.lock` gate refuses the create
+     * with `farm_unusable` and no Job is made. Absent keeps the degrade: the
+     * store mounts drop, a warning is logged, and the Job is still made. The
+     * field names the deployment fact rather than the remediation, so how the
+     * harness answers it can evolve without changing the embedder surface; a
+     * single-valued union (not a boolean) so future store classes extend it
+     * without a breaking change.
+     */
+    packageStore?: "required";
     /** PVC claim mounted read-only at `/mnt/refs` when set. */
     refStorePvc?: string;
     /** Node selector pinning sandbox pods to the dedicated agent pool. Omit for default scheduling. */

package/dist/sandbox/k8s-client.js

@@ -465,14 +465,30 @@ export function createK8sSandboxOps(config) {
                 // The `inflexa.lock` gate, for a host that mounts the libs
                 // volume itself. The resolver owes the proof either way,
                 // but a farm half-written between the resolution and this
-                // create still mounts without a second look. A gate failure
-                // degrades exactly as the Docker backend does: no store
-                // mount, the Job is still made, and the sandbox reports the
-                // store as unavailable.
+                // create still mounts without a second look. The failure
+                // has the two outcomes of the Docker backend. Under the
+                // declared fact the call refuses with `farm_unusable`
+                // before any cluster work, and it logs nothing: the
+                // returned value carries the reason, and the consumer logs
+                // the throw, thus a warning here would record the one fault
+                // twice. Without the fact it degrades — no store mount, the
+                // Job is still made, and the sandbox reports the store as
+                // unavailable.
                 let libsMounted = !!config.libStorePvc;
                 if (config.libStorePvc && config.libStorePvcRoot && farm) {
                     const lock = readFarmLock(join(config.libStorePvcRoot, farm.farmPath));
                     libsMounted = lock.isOk();
+                    if (lock.isErr() && config.packageStore === "required") {
+                        return err({
+                            type: "farm_unusable",
+                            op: "k8s.createSandbox",
+                            analysisId: meta.analysisId,
+                            farmPath: farm.farmPath,
+                            lockPath: lock.error.lockPath,
+                            lockError: lock.error.type,
+                            cause: lock.error.cause,
+                        });
+                    }
                     if (lock.isErr()) {
                         (config.logger ?? createNoopLogger())
                             .named("k8s-client")

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

@@ -26,10 +26,12 @@
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, then
- * `unwrapOrThrow`s each op's `ResultAsync` so the seam re-throws a genuine
- * `SandboxError`. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
+ * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
+ * seam throws the described failure with the variant on `.cause` and on
+ * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
+ * exception — it is already its own DBOS step and throws directly, so the seam
+ * forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
  * non-workflow consumers (`reaper`, `watchdog`,
@@ -37,6 +39,7 @@
  * untouched by this wave.
  */
 import { ResultAsync } from "neverthrow";
+import type { FarmLockError } from "./farm.js";
 /**
  * A sandbox backend failure. Absence / idempotent "already gone" is NOT
  * modelled — those ride the OK channel (`ok(false)` for a dead/missing machine,
@@ -91,6 +94,22 @@ export type SandboxError = {
     readonly analysisId: string;
     readonly reason: string;
     readonly cause?: unknown;
+} | {
+    /**
+     * The gate proved the `inflexa.lock` at the resolved farm and the
+     * farm is not usable. Raised only when the config declares
+     * `packageStore: "required"`; without the fact the same gate
+     * failure degrades to no store mount. The sibling
+     * `farm_unavailable` is the resolver refusing to name a farm at
+     * all — here a farm was named, and its lock does not hold up.
+     */
+    readonly type: "farm_unusable";
+    readonly op: string;
+    readonly analysisId: string;
+    readonly farmPath: string;
+    readonly lockPath: string;
+    readonly lockError: FarmLockError["type"];
+    readonly cause: unknown;
 };
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
@@ -100,8 +119,24 @@ export type SandboxError = {
  * `typeof === "number"` to avoid returning it as a status.
  */
 export declare function sandboxStatusOf(cause: unknown): number | undefined;
-/** A one-line, user-facing description of a `SandboxError` for logs/error bodies. */
+/**
+ * A one-line, user-facing description of a `SandboxError` for logs/error
+ * bodies. The variant gives the head. Where the cause names a reason, that
+ * bounded line closes the description, thus the engine or the parser says why
+ * on the operator surfaces.
+ */
 export declare function describeSandboxError(e: SandboxError): string;
+/**
+ * The throw of the `SandboxClient` seam. The message is
+ * `describeSandboxError`, thus a surface that renders a message alone still
+ * names the fault and its reason. The variant rides two ways: on `cause`, so
+ * a cause-chain reader keeps working, and on `error`, so a consumer that
+ * matches the class reads the typed fields without a walk.
+ */
+export declare class SandboxFailure extends Error {
+    readonly error: SandboxError;
+    constructor(error: SandboxError);
+}
 /**
  * Wrap a single sandbox backend call (Docker SDK op, K8s API op, or the
  * `/exec` POST). A throw becomes `err(toError(status, cause))`; the caller

package/dist/sandbox/sandbox-error.js

@@ -26,10 +26,12 @@
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, then
- * `unwrapOrThrow`s each op's `ResultAsync` so the seam re-throws a genuine
- * `SandboxError`. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
+ * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
+ * seam throws the described failure with the variant on `.cause` and on
+ * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
+ * exception — it is already its own DBOS step and throws directly, so the seam
+ * forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
  * non-workflow consumers (`reaper`, `watchdog`,
@@ -37,6 +39,7 @@
  * untouched by this wave.
  */
 import { ResultAsync, err, ok } from "neverthrow";
+import { ZodError } from "zod";
 const _assertDomainError = true;
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
@@ -51,8 +54,62 @@ export function sandboxStatusOf(cause) {
         return e.code;
     return e.statusCode ?? e.response?.statusCode;
 }
-/** A one-line, user-facing description of a `SandboxError` for logs/error bodies. */
+/**
+ * The bound on the appended cause line — the same 200 characters the profile
+ * ledger keeps (`tasks/data-profile.ts`), because a description reaches that
+ * ledger and the run row. A stack trace and an engine response body must stay
+ * out of a row, so the line is cut and marked rather than carried whole.
+ */
+const CAUSE_LINE_MAX = 200;
+/**
+ * The one bounded line that names the reason of a cause, or `undefined` when
+ * the cause carries no reason to name.
+ *
+ * A `ZodError` is special-cased: its `message` is multi-line JSON whose first
+ * line is `[`, which names nothing. Thus a zod cause renders as its first
+ * issue — the path and the message — and the reader sees which field broke.
+ * Any other cause gives the first line of its message.
+ */
+function causeLine(cause) {
+    let text;
+    if (cause instanceof ZodError) {
+        const issue = cause.issues[0];
+        if (!issue)
+            return undefined;
+        const path = issue.path.join(".");
+        text = path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    }
+    else if (cause instanceof Error) {
+        text = cause.message;
+    }
+    else if (typeof cause === "string") {
+        text = cause;
+    }
+    else {
+        return undefined;
+    }
+    const first = text.split("\n", 1)[0].trim();
+    if (first.length === 0)
+        return undefined;
+    return first.length > CAUSE_LINE_MAX ? `${first.slice(0, CAUSE_LINE_MAX - 1)}…` : first;
+}
+/**
+ * A one-line, user-facing description of a `SandboxError` for logs/error
+ * bodies. The variant gives the head. Where the cause names a reason, that
+ * bounded line closes the description, thus the engine or the parser says why
+ * on the operator surfaces.
+ */
 export function describeSandboxError(e) {
+    // `farm_unavailable` is the one variant whose head already carries its
+    // reason, the text of the resolver. A cause line after it would put two
+    // dashes on one row, and the throw of a resolver is in the log with its
+    // stack. Every other variant names its reason only through the cause.
+    const line = e.type === "farm_unavailable" ? undefined : causeLine(e.cause);
+    const head = describeVariant(e);
+    return line === undefined ? head : `${head} — ${line}`;
+}
+/** The head of a description: what failed, at which op, on which subject. */
+function describeVariant(e) {
     switch (e.type) {
         case "container_create_failed":
             return `sandbox create failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
@@ -68,6 +125,23 @@ export function describeSandboxError(e) {
             return `sandbox liveness probe failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
         case "farm_unavailable":
             return `farm unavailable (${e.op}: ${e.analysisId}) — ${e.reason}`;
+        case "farm_unusable":
+            return `farm unusable (${e.op}: ${e.analysisId}, ${e.lockError} at ${e.lockPath})`;
+    }
+}
+/**
+ * The throw of the `SandboxClient` seam. The message is
+ * `describeSandboxError`, thus a surface that renders a message alone still
+ * names the fault and its reason. The variant rides two ways: on `cause`, so
+ * a cause-chain reader keeps working, and on `error`, so a consumer that
+ * matches the class reads the typed fields without a walk.
+ */
+export class SandboxFailure extends Error {
+    error;
+    constructor(error) {
+        super(describeSandboxError(error), { cause: error });
+        this.error = error;
+        this.name = "SandboxFailure";
     }
 }
 /**

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -9,12 +9,10 @@
  * planning surface reads the pool-scope inventory (`readPoolInventory`) —
  * everything the store holds, whether or not a farm links it yet — because
  * the ask flow marks the packages the POOL does not hold, and the farm of a
- * new analysis is empty. The baked image inventory fragment
- * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
- * report when the host can read one. The fragment keeps the section format:
- *
- *     ## System tools (CLI)
- *     samtools, bcftools, ...
+ * new analysis is empty. The image inventory record (`image-packages.json`,
+ * at the root of the package store) merges into either report when the host
+ * can read one: it carries the conda tools and the Node packages the image
+ * owns, which the content-addressed store cannot hold.
  *
  * Each entry renders as `name==version` where the source pins a version, and
  * a targeted `names` lookup also carries the store directory and the full
@@ -23,6 +21,7 @@
  */
 import type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventorySection } from "../../config/environment-stores.js";
 import { type FarmLock } from "../../sandbox/farm.js";
+import { type ImagePackages } from "../../sandbox/image-packages.js";
 /**
  * Group the lock packages into sections, one per track, in a stable order:
  * the known tracks first, then an unknown track at its first occurrence.
@@ -30,9 +29,19 @@ import { type FarmLock } from "../../sandbox/farm.js";
  * targeted `names` path can report the exact store identity.
  */
 export declare function lockSections(lock: FarmLock): Section[];
+/**
+ * Group the image record into its two sections, in the order of the record.
+ * An empty track yields no section, so the report never carries a heading
+ * with nothing under it.
+ *
+ * A `system_tools` row renders its `executable` name where the record gives
+ * one, because an agent invokes the binary rather than the conda package
+ * (the manifest `binaries:` map holds the pairs that differ).
+ */
+export declare function imageSections(record: ImagePackages): Section[];
 /** One package entry of a section, with the store identity where the source records it. */
 export type SectionPackage = PoolInventoryPackage;
-/** One language track of the store, in `packages.txt` section order. The seam shape and the render shape are one. */
+/** One language track of the store, in the section order of its source. The seam shape and the render shape are one. */
 export type Section = PoolInventorySection;
 /** One `names` lookup: present + canonical spelling + track + store identity, or absent. */
 export type CheckedPackage = {
@@ -65,13 +74,6 @@ export type PackagesResult = {
     readonly hasMore: boolean;
     readonly content: string;
 };
-/**
- * Parse `packages.txt` into its sections. `#` lines are the advisory header,
- * `## X` opens a section, and every other non-empty line contributes
- * comma-separated package names to the open section. Unknown section headings
- * are preserved as-is — a downstream image may add its own track.
- */
-export declare function parsePackagesFile(content: string): Section[];
 /** The tool's input, as parsed from `inputSchema`. */
 export interface PackagesQuery {
     readonly names?: readonly string[];
@@ -83,7 +85,7 @@ export interface PackagesQuery {
  * Answer a packages query against a parsed catalog. Pure — the tool's `execute`
  * is only the file read plus this call.
  */
-export declare function queryPackages(sections: readonly Section[], { names, query, language, limit }: PackagesQuery): PackagesResult;
+export declare function queryPackages(rawSections: readonly Section[], { names, query, language, limit }: PackagesQuery): PackagesResult;
 export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory"> & {
     /**
      * True when the composition also attaches the `link_packages` tool. The
@@ -96,7 +98,7 @@ export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "farmLockFil
  * Create the package inventory over the bound source: the pool-scope reader
  * when the embedder binds one (a conversation or planning surface), the
  * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
- * fragment merges into either report.
+ * record merges into either report.
  */
 export declare function createListAvailablePackagesTool(deps?: ListAvailablePackagesDeps): import("../define-tool.js").Tool<{
     names?: string[] | undefined;

package/dist/tools/sandbox/list-available-packages.js

@@ -9,25 +9,23 @@
  * planning surface reads the pool-scope inventory (`readPoolInventory`) —
  * everything the store holds, whether or not a farm links it yet — because
  * the ask flow marks the packages the POOL does not hold, and the farm of a
- * new analysis is empty. The baked image inventory fragment
- * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
- * report when the host can read one. The fragment keeps the section format:
- *
- *     ## System tools (CLI)
- *     samtools, bcftools, ...
+ * new analysis is empty. The image inventory record (`image-packages.json`,
+ * at the root of the package store) merges into either report when the host
+ * can read one: it carries the conda tools and the Node packages the image
+ * owns, which the content-addressed store cannot hold.
  *
  * Each entry renders as `name==version` where the source pins a version, and
  * a targeted `names` lookup also carries the store directory and the full
  * content hash where the source records them. A full listing carries no
  * hashes — a thousand rows of sha256 would bury the signal.
  */
-import { readFile } from "node:fs/promises";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 import { LIBS_CONTAINER_PATH } from "../../sandbox/mount-plan.js";
 import { readFarmLockFile } from "../../sandbox/farm.js";
+import { IMAGE_PACKAGES_FILE, readImagePackagesFile } from "../../sandbox/image-packages.js";
 /**
  * Where the lock lives when the host mounts the farm at the same path the
  * sandbox does. Both farm container paths are tried, because the path keys on
@@ -36,15 +34,30 @@ import { readFarmLockFile } from "../../sandbox/farm.js";
  * reads the farm somewhere else injects its own path instead.
  */
 const DEFAULT_FARM_LOCK_FILES = [`${LIBS_CONTAINER_PATH}/farm/inflexa.lock`, `${LIBS_CONTAINER_PATH}/current/inflexa.lock`];
-/** Where the baked image inventory fragment lives inside the image. */
-const DEFAULT_IMAGE_PACKAGES_FILE = "/opt/inflexa/image-packages.txt";
+/**
+ * Where the image inventory record lives: at the root of the package store,
+ * which the catalog build copied it into. The default names the container
+ * mountpoint of that store, the same rule as {@link DEFAULT_FARM_LOCK_FILES}
+ * — a host whose own process sees the store the way a sandbox does needs no
+ * configuration. A host that reads the store somewhere else injects
+ * `imagePackagesFile`.
+ */
+const DEFAULT_IMAGE_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/${IMAGE_PACKAGES_FILE}`;
+/**
+ * The two headings that a lock track and the image record can both carry.
+ * Declared once, because {@link LANGUAGE_MATCHERS} keys the `language` filter
+ * on the heading text, and {@link foldSections} merges two sources by it: a
+ * second spelling of either would split one track into two headings.
+ */
+const CLI_TITLE = "System tools (CLI)";
+const NODE_TITLE = "Node (npm)";
 /** The section title of each known lock track. An unknown track titles itself. */
 const TRACK_TITLES = {
     python: "Python (pip)",
     cran: "R (CRAN)",
     bioconductor: "R (Bioconductor)",
     github: "R (GitHub)",
-    node: "Node (npm)",
+    node: NODE_TITLE,
 };
 /**
  * Group the lock packages into sections, one per track, in a stable order:
@@ -66,6 +79,56 @@ export function lockSections(lock) {
     }
     return [...byTrack.entries()].filter(([, packages]) => packages.length > 0).map(([track, packages]) => ({ title: TRACK_TITLES[track] ?? track, packages }));
 }
+/**
+ * Group the image record into its two sections, in the order of the record.
+ * An empty track yields no section, so the report never carries a heading
+ * with nothing under it.
+ *
+ * A `system_tools` row renders its `executable` name where the record gives
+ * one, because an agent invokes the binary rather than the conda package
+ * (the manifest `binaries:` map holds the pairs that differ).
+ */
+export function imageSections(record) {
+    const sections = [];
+    if (record.system_tools.length > 0) {
+        sections.push({
+            title: CLI_TITLE,
+            packages: record.system_tools.map((tool) => ({ name: tool.executable ?? tool.name, version: tool.version })),
+        });
+    }
+    if (record.node.length > 0) {
+        sections.push({ title: NODE_TITLE, packages: record.node.map((pkg) => ({ name: pkg.name, version: pkg.version })) });
+    }
+    return sections;
+}
+/**
+ * Merge the sections that share a title, in first-occurrence order, and keep
+ * the first entry of each name inside a merged section.
+ *
+ * Two sources can carry one track: the `node` track of a farm lock and the
+ * `node` track of the image record. Rendered as they arrive, a listing would
+ * print one heading twice and read as two tracks. The fold keeps the first
+ * writer, which is the same rule the `names` index applies, thus the listing
+ * and the presence check agree on which entry a colliding name resolves to.
+ */
+function foldSections(sections) {
+    const byTitle = new Map();
+    for (const section of sections) {
+        let open = byTitle.get(section.title);
+        if (!open) {
+            open = { title: section.title, packages: [], seen: new Set() };
+            byTitle.set(section.title, open);
+        }
+        for (const pkg of section.packages) {
+            const key = pkg.name.toLowerCase();
+            if (open.seen.has(key))
+                continue;
+            open.seen.add(key);
+            open.packages.push(pkg);
+        }
+    }
+    return [...byTitle.values()].map(({ title, packages }) => ({ title, packages }));
+}
 /**
  * Default cap on a listing — high enough that the real store is never truncated.
  * The shipped catalog is ~270 packages (~3 KB, well under a thousand tokens), so
@@ -98,39 +161,10 @@ const LANGUAGE_MATCHERS = {
     // The R triple: `R (CRAN)`, `R (Bioconductor)`, `R (GitHub)`.
     r: (t) => /^r\b/i.test(t),
     python: (t) => /^python\b/i.test(t),
-    // `System tools (CLI)` — the conda-installed bioinformatics executables.
+    // `CLI_TITLE` — the conda-installed bioinformatics executables.
     cli: (t) => /system tools|\bcli\b/i.test(t),
     node: (t) => /^node\b/i.test(t),
 };
-/**
- * Parse `packages.txt` into its sections. `#` lines are the advisory header,
- * `## X` opens a section, and every other non-empty line contributes
- * comma-separated package names to the open section. Unknown section headings
- * are preserved as-is — a downstream image may add its own track.
- */
-export function parsePackagesFile(content) {
-    const sections = [];
-    for (const line of content.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        if (trimmed.startsWith("##")) {
-            sections.push({ title: trimmed.slice(2).trim(), packages: [] });
-            continue;
-        }
-        if (trimmed.startsWith("#"))
-            continue;
-        const open = sections.at(-1);
-        if (!open)
-            continue;
-        for (const name of trimmed.split(",")) {
-            const pkg = name.trim();
-            if (pkg)
-                open.packages.push({ name: pkg });
-        }
-    }
-    return sections;
-}
 /** One entry as the listing renders it: `name==version` where the source pins a version, the bare name otherwise. */
 function renderPackage(entry) {
     return entry.version === undefined ? entry.name : `${entry.name}==${entry.version}`;
@@ -160,15 +194,16 @@ function renderListing(sections, limit) {
  * Answer a packages query against a parsed catalog. Pure — the tool's `execute`
  * is only the file read plus this call.
  */
-export function queryPackages(sections, { names, query, language, limit }) {
+export function queryPackages(rawSections, { names, query, language, limit }) {
+    const sections = foldSections(rawSections);
     // Presence check — the cheap, targeted path. Answers "is X available, and in
     // which track" without returning the catalog.
     if (names && names.length > 0) {
         const index = new Map();
         for (const section of sections) {
             for (const pkg of section.packages) {
-                // First writer wins: `packages.txt` sections are ordered, so a name
-                // colliding across tracks resolves to the earliest one.
+                // First writer wins: the sections arrive in a fixed order, so a
+                // name colliding across tracks resolves to the earliest one.
                 if (!index.has(pkg.name.toLowerCase()))
                     index.set(pkg.name.toLowerCase(), { entry: pkg, section: section.title });
             }
@@ -219,7 +254,7 @@ export function queryPackages(sections, { names, query, language, limit }) {
  * Create the package inventory over the bound source: the pool-scope reader
  * when the embedder binds one (a conversation or planning surface), the
  * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
- * fragment merges into either report.
+ * record merges into either report.
  */
 export function createListAvailablePackagesTool(deps = {}) {
     const lockCandidates = deps.farmLockFile ? [deps.farmLockFile] : DEFAULT_FARM_LOCK_FILES;
@@ -284,12 +319,15 @@ export function createListAvailablePackagesTool(deps = {}) {
             return "full package list";
         },
         execute: async (input) => {
-            // The baked image fragment merges in when the host can read one; a
-            // missing fragment merges nothing, and that is the normal state for
-            // a host that runs outside the image.
-            const fragmentSections = await readFile(imagePackagesFile, "utf-8")
-                .then(parsePackagesFile)
-                .catch(() => []);
+            // The image record merges in when the host can read a valid one.
+            // An absent record and an invalid record both merge nothing, and
+            // neither is an error: the record is an enrichment, and the farm
+            // or pool inventory stays whole without it. A store packed before
+            // the record existed carries none. The tool holds no logger, thus
+            // an invalid record cannot be reported here — the schema of the
+            // harness refuses it, and the report degrades to the tracks it
+            // could read.
+            const recordSections = readImagePackagesFile(imagePackagesFile).map(imageSections).unwrapOr([]);
             // An unreadable inventory is an expected environment state — model it as an
             // `available: false` data variant telling the caller the set is UNKNOWN,
             // WITH the reason: without it, a structural fault (a damaged dependency
@@ -301,7 +339,7 @@ export function createListAvailablePackagesTool(deps = {}) {
                 }));
                 if (pool.kind === "unavailable")
                     return ok({ available: false, content: `${POOL_UNAVAILABLE_NOTE} The reason: ${pool.reason}.` });
-                return ok(queryPackages([...pool.sections, ...fragmentSections], input));
+                return ok(queryPackages([...pool.sections, ...recordSections], input));
             }
             let lock = null;
             for (const candidate of lockCandidates) {
@@ -312,7 +350,7 @@ export function createListAvailablePackagesTool(deps = {}) {
             if (lock === null) {
                 return ok({ available: false, content: UNAVAILABLE_NOTE });
             }
-            return ok(queryPackages([...lockSections(lock), ...fragmentSections], input));
+            return ok(queryPackages([...lockSections(lock), ...recordSections], input));
         },
     });
 }

package/package.json

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