@inflexa-ai/harness 0.31.0 → 0.31.1

package/dist/prompts/briefing.d.ts

@@ -36,7 +36,9 @@ export declare const STEP_TASK_FIELDS: readonly ["name", "question", "descriptio
  * threaded separately through the workflow input, execution knobs, and result
  * fields populated after the step runs. `depends_on` is not rendered here
  * because the dependencies appear as {@link renderUpstream} blocks — with their
- * results — rather than as bare ids.
+ * results — rather than as bare ids. `resources` renders as its own
+ * {@link renderResources} section, because the budget is an execution bound,
+ * not a task instruction.
  */
 export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error"];
 /**
@@ -66,6 +68,15 @@ export interface WorkspaceFrame {
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export declare function analysisRootOf(frame: WorkspaceFrame): string;
 export declare function renderWorkspace(frame: WorkspaceFrame): string;
+/**
+ * The cpu and memory budget of the step, with the one rule that keeps a
+ * parallel workload inside it. The mounted cpu files make `detectCores()` and
+ * `os.cpu_count()` report the quota, thus the fork count is right by default.
+ * The thread pools default to one thread (see `sandbox/thread-env.ts`), and
+ * only the agent knows when a step is thread-parallel. Thus the briefing names
+ * the budget and the rule, and the agent raises a pool per command.
+ */
+export declare function renderResources(resources: AnalysisStep["resources"]): string;
 /**
  * What dataset the analysis is holding, projected from the persisted profile.
  * Absent or not-yet-profiled → `""`, and the agent falls back to its always-on

package/dist/prompts/briefing.js

@@ -45,7 +45,9 @@ export const STEP_TASK_FIELDS = [
  * threaded separately through the workflow input, execution knobs, and result
  * fields populated after the step runs. `depends_on` is not rendered here
  * because the dependencies appear as {@link renderUpstream} blocks — with their
- * results — rather than as bare ids.
+ * results — rather than as bare ids. `resources` renders as its own
+ * {@link renderResources} section, because the budget is an execution bound,
+ * not a task instruction.
  */
 export const STEP_NON_TASK_FIELDS = [
     "id",
@@ -117,6 +119,29 @@ export function renderWorkspace(frame) {
         `Analysis root (read-only): \`${analysisRoot}\` — inputs at \`${analysisRoot}/data/inputs/\`, prior runs at \`${analysisRoot}/runs/\`.`,
     ]));
 }
+// ── (2b) Resources ────────────────────────────────────────────────────
+/**
+ * The cpu and memory budget of the step, with the one rule that keeps a
+ * parallel workload inside it. The mounted cpu files make `detectCores()` and
+ * `os.cpu_count()` report the quota, thus the fork count is right by default.
+ * The thread pools default to one thread (see `sandbox/thread-env.ts`), and
+ * only the agent knows when a step is thread-parallel. Thus the briefing names
+ * the budget and the rule, and the agent raises a pool per command.
+ */
+export function renderResources(resources) {
+    if (!resources)
+        return "";
+    const cores = Math.max(1, Math.floor(resources.cpu));
+    const items = [
+        `CPU: ${resources.cpu} ${resources.cpu === 1 ? "core" : "cores"} (hard quota). Memory: ${resources.memoryGb} GB (hard limit — exceeding it kills the process).`,
+        `Core-count calls (\`parallel::detectCores()\`, \`os.cpu_count()\`) report this quota — worker counts sized from them are already right, nothing to raise.`,
+        `BLAS/OpenMP thread pools default to **1 thread** (\`OMP_NUM_THREADS\` etc.). For a thread-parallel single-process step, raise them per command via \`execute_command\`'s \`env\`, up to ${cores}.`,
+        `The one rule: workers × threads-per-worker must stay ≤ ${cores}. A mix is fine while the product holds.`,
+    ];
+    if (resources.gpu)
+        items.push(`GPU: ${resources.gpu.count}.`);
+    return section("Resources (hard limits)", bullets(items));
+}
 // ── (3) Data orientation ──────────────────────────────────────────────
 /**
  * What dataset the analysis is holding, projected from the persisted profile.
@@ -168,6 +193,7 @@ export function composeStepBriefing(briefing) {
     return [
         renderTask(briefing.step),
         renderWorkspace(briefing.workspace),
+        renderResources(briefing.step.resources),
         renderOrientation(briefing.profile, briefing.workspace.analysisId),
         renderUpstream(briefing.upstream),
     ]

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

@@ -22,5 +22,5 @@
  * `prompts/briefing.ts`), which is composed per dispatch and where per-step
  * content belongs.
  */
-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## 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";
+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";
 export declare const sandboxAnalysisStepStandardsPrompt = "# Sandbox Analysis-Step Conventions\n\nThese apply to plannable analysis steps \u2014 agents that produce reproducible\nscript + output + figure artifacts. They do NOT apply to data profiling or\nreport building (those agents opt out via\n`appendAnalysisStepStandards: false`).\n\n## Language Policy\n\nPython is the DEFAULT language. Use R when:\n(a) No adequate Python equivalent (e.g. minfi, ANCOM-BC2, ChAMP).\n(b) The R implementation is significantly more mature.\n(c) The task explicitly requires an R-only package.\n\nChoose native R or rpy2 based on scope:\n- **Isolated R calls** in a Python pipeline \u2192 rpy2 bridge.\n  Example: DESeq2 for one DE step, fgsea for enrichment.\n- **R-dominant pipeline** where most steps use R packages \u2192 write\n  **native R scripts**. Do not wrap an entire R pipeline in rpy2.\n  Examples: microbiome (DADA2 \u2192 phyloseq \u2192 vegan \u2192 ANCOM-BC2),\n  DNA methylation (minfi \u2192 ChAMP \u2192 DMRcate), untargeted metabolomics\n  (XCMS \u2192 CAMERA).\n\nNative R scripts follow the same standards as Python: structured logging\n(`message()`), named constants, documented functions. Save final outputs\nas CSV (and optionally AnnData) for cross-agent consumption.\n\n## Data Format Standards\n\n- **AnnData (.h5ad)** is the UNIVERSAL container for sample-by-feature\n  data across ALL modalities \u2014 bulk RNA-seq, proteomics, metabolomics,\n  microarray, methylation, single-cell. Samples in `.obs`, features in\n  `.var`, values in `.X`, layers in `.layers`, embeddings in `.obsm`,\n  unstructured results in `.uns`.\n- **MuData (.h5mu)** for multi-modal data (CITE-seq, Multiome,\n  multi-omics integration).\n- Store sample metadata in `.obs`, feature annotations in `.var`. Do\n  NOT write separate metadata CSV files unless explicitly needed.\n- **Intermediate analysis objects**: save as `.h5ad` or `.h5mu`. Do\n  NOT save as `.rds` or `.pkl`. When R packages produce R objects\n  (DESeqDataSet, phyloseq, SingleCellExperiment), convert key results\n  back to AnnData or pandas.\n- **Tabular results**: CSV with human-readable column names\n  (`log2_fold_change`, `adjusted_pvalue`, not `lfc`/`padj`).\n- **Genomic data**: VCF/BED/BAM are acceptable primary containers.\n  Derived summary statistics go in AnnData or CSV.\n- **Dual-format output**: when producing modality-specific results,\n  also output a generic CSV for downstream cross-cutting agents.\n\n## Figure Standards\n\n- **PNG at 300 DPI** for preview AND **PDF (vector)** for publication,\n  same base filename with different extensions.\n- **Colorblind-safe palettes** \u2014 viridis family as default. Never use\n  red-green as the sole distinguishing feature.\n- **Clean minimal themes**: matplotlib `seaborn-v0_8-whitegrid` or\n  equivalent; ggplot2 `theme_classic()` or `theme_minimal()`.\n- **Complete labels**: title, axis labels with units, legend.\n- **Statistical annotations** where applicable (p-values, significance\n  brackets, effect sizes).\n- No default matplotlib/ggplot styling, no cut-off labels, no\n  overlapping text.\n\n## Directory Structure\n\nYour working directory has five subdirectories \u2014 write each kind of artifact\nto its own (paths are relative to your working directory):\n\n```\nscripts/    Analysis scripts (.py, .R)\noutput/     Results: CSV, AnnData (.h5ad), MuData (.h5mu), JSON\nfigures/    Visualizations: PNG (300 DPI) + PDF (vector), same base name\nlogs/       Execution logs from long-running commands\nnotebooks/  Reserved (currently unused)\n```\n\nPut data results in `output/`, not at the working-directory root. For\nlong-running commands, redirect stdout/stderr to a file in `logs/`:\n```python\nsubprocess.run(cmd, stdout=open(\"logs/deseq2_run.log\", \"w\"), stderr=subprocess.STDOUT)\n```\n\n## Code Quality\n\n**Functions** for any non-trivial logic. Each logical operation\n(load, QC, fit, plot) gets its own function with a docstring. Top-level\nscript flow should read like an outline \u2014 call functions, not inline\nlogic.\n\n```python\n# %% [markdown]\n# ## Differential Expression\n\n# %%\ndef run_deseq2(counts: pd.DataFrame, metadata: pd.DataFrame, design: str) -> pd.DataFrame:\n    \"\"\"Run DESeq2 via rpy2 and return results as a DataFrame.\"\"\"\n    ...\n\nde_results = run_deseq2(counts, metadata, \"~ condition + batch\")\n```\n\n**Structured logging**, not `print()`:\n\n- Python \u2014 `logging.getLogger()`:\n  `logger.info(\"Loaded %d samples, %d genes\", n_samples, n_genes)`\n- R \u2014 `message()` / `warning()`:\n  `message(sprintf(\"Loaded %d samples\", n_samples))`\n\nReserve `print()` / `cat()` for intentional data display in notebook\ncells only.\n\n**Validate at function boundaries**. Fail fast with clear messages.\nUse `try/except` only when recovery is meaningful.\n\n**Type hints** on Python function signatures. Add them \u2014 they document\nintent and catch mistakes early.\n\n**Named constants** for thresholds, cutoffs, parameters in the first\ncode cell:\n```python\n# %% Parameters\nRANDOM_SEED = 42\nFDR_THRESHOLD = 0.05\nMIN_LOG2FC = 1.0\n```\n\n**R specifics**: load packages at the top (never inside functions).\nUse `<-` for assignment. Use `message()` / `warning()` not `cat()` /\n`print()`.\n\n## Scripts\n\n- Start with a header comment (title + description).\n- Parameters go in the first code block.\n- Set random seeds for reproducibility.\n- Scripts must be independently re-runnable.\n- **Lint Python scripts with `ruff check <script.py>`** via\n  `execute_command` before executing. `ruff` is pre-installed. This\n  catches import errors, undefined names, and common bugs early.\n\n## Cleanup\n\nWhen a script fails, delete the failed script from `scripts/` and any\npartial output files before writing a corrected version. Only final\nworking scripts should remain. Use `list_files` to verify.\n\n## Interpretation & Literature Grounding\n\nGround findings in the research literature as you work \u2014 not as a\nfinal step:\n\n1. When you identify a significant finding (DE genes, enriched\n   pathways, hub genes, quality issues), search PubMed with\n   `pubmed({action:\"search\"})`.\n2. For relevant hits, call `pubmed({action:\"details\"})` for abstracts and\n   PMIDs. Note short citations (e.g. \"Smith et al., Nature 2023\").\n3. Assess novelty per finding: **novel** (searched, nothing found),\n   **confirmed** (directly supported), **partially confirmed**,\n   **contradicted**, **expected** (domain knowledge, no citation\n   needed).\n4. Document the search even when no references are found. \"Novel\"\n   means you looked and found nothing \u2014 not that you didn't look.\n\nYour structured output captures this interpretation. It is your\nscientific assessment of what the results mean.\n\n## Analysis-Step Anti-Patterns\n\n- **Ignoring script errors.** Read the error, diagnose the root\n  cause, fix the script. Do not move on.\n- **Placeholder or dummy output.** If an analysis cannot produce\n  meaningful results, report the reason clearly instead of faking\n  results.\n- **Monolithic scripts.** Keep scripts under 300 lines. Split into\n  logical sections with markdown annotations.\n- **`print()` for logging.** Use `logging` (Python) or `message()`\n  (R). `print()` is for intentional data display only.\n- **Inline logic without functions.** Wrap non-trivial operations in\n  functions with docstrings and typed parameters.\n- **Magic numbers.** Define thresholds and cutoffs as named constants.\n";

package/dist/prompts/sandbox-standards.js

@@ -135,6 +135,33 @@ up front.
   \`AnnotationHub\` — they all reach for the network and will fail. Load from an
   inventory path instead. Do NOT download data or install packages at runtime.
 
+## CPU Budget and Parallelism
+
+Your briefing names this step's CPU quota and memory limit. The container's
+core-count calls (\`parallel::detectCores()\`, \`os.cpu_count()\`) report the
+quota, so worker counts sized from them are safe.
+
+BLAS/OpenMP thread pools default to **1 thread** (\`OMP_NUM_THREADS\`,
+\`OPENBLAS_NUM_THREADS\`, \`MKL_NUM_THREADS\`, …). A forked worker inherits its
+parent's pool size, so this default is what keeps \`mclapply\` /
+\`multiprocessing\` from running workers × threads on a quota sized for one of
+them. The rule: **workers × threads-per-worker must not exceed the quota.** A
+mix is fine while the product stays inside it.
+
+- **Fork/worker parallelism** (\`mclapply\`, \`BiocParallel\`, \`joblib\`,
+  \`multiprocessing\`): size the workers from the reported core count and leave
+  the thread defaults alone — there is nothing to raise. \`joblib\` also
+  divides its own thread budget across its workers; do not manage it.
+- **Thread parallelism** (one process: xgboost, WGCNA, data.table, polars, a
+  single large BLAS fit): raise the thread variables for that command through
+  \`execute_command\`'s \`env\`, e.g.
+  \`env: { "OMP_NUM_THREADS": "4", "OPENBLAS_NUM_THREADS": "4" }\` on a 4-CPU
+  quota.
+
+Exceeding the quota does not kill the step — the cgroup throttles it — but an
+oversubscribed step runs slower and can starve the exec server that runs your
+commands.
+
 ## Output Contract — Persisted Files Are the Deliverable
 
 This is a hard requirement, not a convention. **Your deliverable is persisted

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

@@ -2,26 +2,32 @@
  * Thread-count env for a sandbox container.
  *
  * Each backend turns the `ResourceSpec` of a step into a hard cgroup limit:
- * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s. A
- * cgroup quota is invisible to most runtimes inside it. `parallel::detectCores()`
- * greps `/proc/cpuinfo`, and `os.cpu_count()` reads
- * `/sys/devices/system/cpu/online`. Both files describe the host. Thus a step
- * with 2 CPUs on a host of 12 cores forks 12 workers into a cgroup of 2 CPUs,
- * and each fork copies its working set until the memory limit stops it.
+ * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s.
+ * The mounted cpu files show the quota to `parallel::detectCores()` and to
+ * `os.cpu_count()`. Thus the fork count of a step follows the quota by default.
  *
- * The env below publishes the quota to each library that reads a thread count
- * from the environment. `parallelly::availableCores()` and `joblib.cpu_count()`
- * read the cgroup quota on their own, thus they need no value here.
+ * The thread pools get a different default. A fork copies the pool size of its
+ * parent, and no R runtime divides it. Thus a pool at the quota turns into
+ * `workers * quota` threads inside one cgroup. The env below pins each pool to
+ * one thread, which is the convention of Snakemake and of the HPC sites. A
+ * thread-parallel step raises the value per command, through the `env`
+ * parameter of `execute_command`. The rule for the agent is one line: workers
+ * times threads must not go above the quota.
+ *
+ * The two worker-count names stay at the quota. They cap process workers, not
+ * threads, and a worker with one thread is safe at each count up to the quota.
+ * joblib divides its own budget by its worker count, and a value of one in
+ * `OMP_NUM_THREADS` gives each of its workers one thread as well.
  *
  * `MC_CORES` is absent on purpose. R defaults `mclapply` to 2 workers, not to
  * the core count. A value there raises the fork count instead of a decrease.
  */
 import type { ResourceSpec } from "../config/resource-limits.js";
 /**
- * Env that binds each parallel library in the container to `spec.cpu`.
+ * Env that makes each parallel library in the container safe under `spec.cpu`.
  *
- * A fractional CPU request floors to one thread. A pool of zero is not
- * representable, and two threads on half a core only add context switches.
+ * A fractional CPU request floors to one worker. A pool of zero is not
+ * representable, and two workers on half a core only add context switches.
  *
  * The caller puts these before `plan.env` and before the `extraEnv` of the
  * embedder, thus a host that knows more about a step keeps the last word.

package/dist/sandbox/thread-env.js

@@ -2,48 +2,59 @@
  * Thread-count env for a sandbox container.
  *
  * Each backend turns the `ResourceSpec` of a step into a hard cgroup limit:
- * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s. A
- * cgroup quota is invisible to most runtimes inside it. `parallel::detectCores()`
- * greps `/proc/cpuinfo`, and `os.cpu_count()` reads
- * `/sys/devices/system/cpu/online`. Both files describe the host. Thus a step
- * with 2 CPUs on a host of 12 cores forks 12 workers into a cgroup of 2 CPUs,
- * and each fork copies its working set until the memory limit stops it.
+ * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s.
+ * The mounted cpu files show the quota to `parallel::detectCores()` and to
+ * `os.cpu_count()`. Thus the fork count of a step follows the quota by default.
  *
- * The env below publishes the quota to each library that reads a thread count
- * from the environment. `parallelly::availableCores()` and `joblib.cpu_count()`
- * read the cgroup quota on their own, thus they need no value here.
+ * The thread pools get a different default. A fork copies the pool size of its
+ * parent, and no R runtime divides it. Thus a pool at the quota turns into
+ * `workers * quota` threads inside one cgroup. The env below pins each pool to
+ * one thread, which is the convention of Snakemake and of the HPC sites. A
+ * thread-parallel step raises the value per command, through the `env`
+ * parameter of `execute_command`. The rule for the agent is one line: workers
+ * times threads must not go above the quota.
+ *
+ * The two worker-count names stay at the quota. They cap process workers, not
+ * threads, and a worker with one thread is safe at each count up to the quota.
+ * joblib divides its own budget by its worker count, and a value of one in
+ * `OMP_NUM_THREADS` gives each of its workers one thread as well.
  *
  * `MC_CORES` is absent on purpose. R defaults `mclapply` to 2 workers, not to
  * the core count. A value there raises the fork count instead of a decrease.
  */
 /**
- * Env that binds each parallel library in the container to `spec.cpu`.
+ * Env that makes each parallel library in the container safe under `spec.cpu`.
  *
- * A fractional CPU request floors to one thread. A pool of zero is not
- * representable, and two threads on half a core only add context switches.
+ * A fractional CPU request floors to one worker. A pool of zero is not
+ * representable, and two workers on half a core only add context switches.
  *
  * The caller puts these before `plan.env` and before the `extraEnv` of the
  * embedder, thus a host that knows more about a step keeps the last word.
  */
 export function threadLimitEnv(spec) {
-    const threads = String(Math.max(1, Math.floor(spec.cpu)));
+    const workers = String(Math.max(1, Math.floor(spec.cpu)));
     return {
+        // Thread pools: one thread each. The agent raises a value per command.
         // OpenMP: the compiled code of R and Python packages.
-        OMP_NUM_THREADS: threads,
+        OMP_NUM_THREADS: "1",
         // OpenBLAS keeps a private pool. A pthread build reads this name first.
-        OPENBLAS_NUM_THREADS: threads,
+        OPENBLAS_NUM_THREADS: "1",
         // MKL reads this name before OMP_NUM_THREADS.
-        MKL_NUM_THREADS: threads,
+        MKL_NUM_THREADS: "1",
+        // data.table defaults to half of the visible cores.
+        R_DATATABLE_NUM_THREADS: "1",
+        // The Python numerical stack.
+        NUMBA_NUM_THREADS: "1",
+        NUMEXPR_MAX_THREADS: "1",
+        POLARS_MAX_THREADS: "1",
+        RAYON_NUM_THREADS: "1",
+        // Worker counts: the quota.
         // BiocParallel sizes `bpparam()` from this name. DESeq2 `parallel=TRUE`
         // and the other Bioconductor packages size their workers from `bpparam()`.
-        BIOCPARALLEL_WORKER_NUMBER: threads,
-        // data.table defaults to half of the host cores.
-        R_DATATABLE_NUM_THREADS: threads,
-        // The Python numerical stack.
-        NUMBA_NUM_THREADS: threads,
-        NUMEXPR_MAX_THREADS: threads,
-        LOKY_MAX_CPU_COUNT: threads,
-        POLARS_MAX_THREADS: threads,
-        RAYON_NUM_THREADS: threads,
+        // `parallelly::availableCores()` reads it too, and under gVisor, where no
+        // cgroup is visible, it is the only bound that library sees.
+        BIOCPARALLEL_WORKER_NUMBER: workers,
+        // loky caps its worker default at this name.
+        LOKY_MAX_CPU_COUNT: workers,
     };
 }

package/package.json

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