@inflexa-ai/harness 0.11.0 → 0.13.0

package/dist/prompts/conversation.js

@@ -10,7 +10,9 @@ conversational — from simple lookups to multi-step scientific exploration.
 1. **Answer directly** — data questions, bio-lookups, file exploration,
    general bioinformatics questions. Use your tools.
 2. **Plan and execute analyses** — orient in the workspace, generate plans
-   via \`generate_plan\`, present plans via \`show_plan\`, execute via \`execute_plan\`.
+   via \`generate_plan\`, present plans via \`show_plan\`, execute via
+   \`execute_analysis\`. For an explicitly requested targeted computation, use
+   \`execute_analysis\` in ad hoc mode without generating a plan.
 3. **Interpret results** — after runs complete, read summaries and artifacts,
    synthesize findings, grade evidence, flag novelty.
 4. **Explore hypotheses** — investigate data, cross-reference with biology,
@@ -79,16 +81,31 @@ When the user wants to run an analysis:
    passing the prior \`planId\` as \`parentPlanId\` and the user's feedback
    as \`userConstraints\`. This produces a new \`planId\` linked to the
    previous one.
-5. **Execute** — on approval, call \`execute_plan({ planId })\` with the
+5. **Execute** — on approval, call
+   \`execute_analysis({ mode: "plan", planId })\` with the
    approved \`planId\`. The tool resolves the plan server-side and starts
    the workflow. On validation failure, regenerate via \`generate_plan\`.
-6. **Plan stale / invalid?** If \`execute_plan\` returns \`status: not_found\`
+6. **Plan stale / invalid?** If \`execute_analysis\` returns \`status: not_found\`
    (or \`invalid_plan\`), or \`show_plan\` returns \`error: plan_not_found\`,
    the \`planId\` is no longer valid — regenerate via \`generate_plan\` and
    present the new plan for approval. Do NOT retry the same \`planId\`.
 
 The workflow runs autonomously — you do not monitor or evaluate it.
 
+## Ad Hoc Analysis
+
+When the user explicitly asks you to run, compute, test, compare, or otherwise
+execute one targeted computation, call
+\`execute_analysis({ mode: "adhoc", request })\` with their exact request. Their
+explicit computational instruction is consent: do not generate or present a
+synthetic plan and do not ask for a second approval. The tool automatically
+selects the sandbox specialist and resources; never add or invent an agent id.
+
+If computation is only your suggestion — the user asked a conceptual question
+and did not ask you to execute anything — ask for consent before calling the
+tool. Ad hoc runs are asynchronous, writable, durable analysis runs. Retrieve
+their results later with \`inspect_run\`; do not wait or poll inside the turn.
+
 ## Interpreting Results
 
 After a run completes, the workflow automatically produces two types of output:
@@ -276,7 +293,7 @@ automatically. Your job is to STEER, not re-present:
 - End with one concrete steering question. Examples: "Want me to draft
   a plan around the DNB index?" / "Should we dig into the percolation
   framing or pursue the bet-hedging entropy angle?"
-- Never embed analogies into \`generate_plan\`, \`execute_plan\`, or any
+- Never embed analogies into \`generate_plan\`, \`execute_analysis\`, or any
   workflow input. The planner and sandbox agents are unaware of
   analogy reports by design — they're for conversation only.
 - Never call \`show_user\` to re-present the report. The card is the
@@ -337,8 +354,9 @@ Instead:
   reference specific results you verified by reading files.
 - **Write just-so stories.** Hypotheses must make testable predictions.
   If a claim fits any outcome, it is not a hypothesis — sharpen or drop it.
-- **Trigger workflows without user approval.** Always present the plan
-  and get explicit approval before starting execution.
+- **Trigger unrequested computation.** Planned analyses require an approved plan.
+  A targeted ad hoc analysis requires the user's explicit computational intent;
+  if execution is merely your suggestion, ask first.
 - **Silently violate a constraint.** A constraint in working memory is
   binding for the rest of the analysis. If a plan or analysis choice would
   break one — a different FDR threshold, an unpaired test on paired data —
@@ -347,10 +365,9 @@ Instead:
   has inputs — at init, and again when inputs are added or removed during the
   conversation. Never propose "explore data structure" or "initial
   assessment" steps.
-- **Call \`run_ephemeral\` multiple times for related data questions.** Each
-  call spins up a sandbox pod (~30-60s of overhead). Combine related data
-  questions into a single multi-part prompt — one call is far faster than
-  two sequential ones.
+- **Split one targeted request into multiple ad hoc runs.** Keep one explicit
+  computational request in one ad hoc call. Use a user-approved plan when the
+  work genuinely requires multiple dependent steps.
 - **Report an environment gap as permanent without checking.** "That package
   is not installed" and "that reference dataset is not here" are facts about
   right now, not verdicts. Before telling the user something cannot be had,

package/dist/prompts/planner.d.ts

@@ -1,2 +1,5 @@
 import type { ResourcePolicy } from "../config/resource-limits.js";
+/** The Resource Estimation planning rules — concrete host limits when a
+ *  policy is supplied, the historical default guidance otherwise. */
+export declare function resourceEstimationSection(policy?: ResourcePolicy): string;
 export declare function plannerPrompt(agentCatalog: string, resourcePolicy?: ResourcePolicy): string;

package/dist/prompts/planner.js

@@ -1,6 +1,6 @@
 /** The Resource Estimation planning rules — concrete host limits when a
  *  policy is supplied, the historical default guidance otherwise. */
-function resourceEstimationSection(policy) {
+export function resourceEstimationSection(policy) {
     const base = `Use the data context to estimate cpu and memoryGb for each step. Consider
 total file size, per-file sizes, feature x sample dimensions, and what the
 step actually does in memory. Be conservative — a 14 MB dataset does not

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

@@ -2,15 +2,15 @@
  * Sandbox prompts — split into two layers, both STATIC.
  *
  * - `sandboxOrientCorePrompt` — universal guidance for any agent that talks to
- *   a sandbox (plannable steps, the data profiler, the read-only ephemeral
- *   executor). Covers the workspace path model, the environment's hard limits,
+ *   a sandbox (plannable steps and the data profiler). Covers the workspace
+ *   path model, the environment's hard limits,
  *   the output contract, and tool-use discipline. Always appended by
  *   `createSandboxAgent`.
  *
  * - `sandboxAnalysisStepStandardsPrompt` — conventions for plannable analysis
  *   steps that produce reproducible script + output + figure artifacts in their
  *   working directory. Opt out via `appendAnalysisStepStandards: false` for
- *   agents that don't fit this mold (data-profiler, ephemeral-executor).
+ *   agents that don't fit this mold (for example data-profiler).
  *
  * Neither layer names a concrete path, id, or any other per-step value, and
  * neither carries a placeholder for one. That is load-bearing rather than
@@ -23,4 +23,4 @@
  * 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 (per-file metrics, warnings,\n  the profiler's narrative), paged. It is the ONLY record of what the input data\n  IS; no file on disk carries it. Use it when the briefing's orientation is not\n  enough, or when it 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` | `output` | `summary` |\n  `synthesis`) and `limit` (1-50, default 8). Returns paths, descriptions, and\n  metadata \u2014 not file contents.\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## 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`, `bedtools`, `fastqc`, version\n  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 read-only ephemeral\nexecution, data profiling, or report 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";
+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

@@ -2,15 +2,15 @@
  * Sandbox prompts — split into two layers, both STATIC.
  *
  * - `sandboxOrientCorePrompt` — universal guidance for any agent that talks to
- *   a sandbox (plannable steps, the data profiler, the read-only ephemeral
- *   executor). Covers the workspace path model, the environment's hard limits,
+ *   a sandbox (plannable steps and the data profiler). Covers the workspace
+ *   path model, the environment's hard limits,
  *   the output contract, and tool-use discipline. Always appended by
  *   `createSandboxAgent`.
  *
  * - `sandboxAnalysisStepStandardsPrompt` — conventions for plannable analysis
  *   steps that produce reproducible script + output + figure artifacts in their
  *   working directory. Opt out via `appendAnalysisStepStandards: false` for
- *   agents that don't fit this mold (data-profiler, ephemeral-executor).
+ *   agents that don't fit this mold (for example data-profiler).
  *
  * Neither layer names a concrete path, id, or any other per-step value, and
  * neither carries a placeholder for one. That is load-bearing rather than
@@ -211,8 +211,8 @@ occur exactly once — include surrounding context to make it unique.
 export const sandboxAnalysisStepStandardsPrompt = `# Sandbox Analysis-Step Conventions
 
 These apply to plannable analysis steps — agents that produce reproducible
-script + output + figure artifacts. They do NOT apply to read-only ephemeral
-execution, data profiling, or report building (those agents opt out via
+script + output + figure artifacts. They do NOT apply to data profiling or
+report building (those agents opt out via
 \`appendAnalysisStepStandards: false\`).
 
 ## Language Policy

package/dist/runtime/assemble.d.ts

@@ -21,11 +21,10 @@ import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalys
 import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
 import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, type ExecuteTargetAssessmentResult } from "../workflows/execute-target-assessment.js";
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
-import { type EphemeralDeps, type EphemeralResult, type EphemeralWorkflowInput } from "../execution/ephemeral-runner.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /**
- * Deps bundles for the five durable workflows. `executeAnalysis` is a builder
+ * Deps bundles for the durable workflows. `executeAnalysis` is a builder
  * because its `sandboxStepCallable` is the registered sandbox-step callable,
  * which does not exist until registration runs inside `assembleCoreRuntime`.
  */
@@ -34,7 +33,6 @@ export interface CoreWorkflowDeps {
     readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => ExecuteAnalysisDeps;
     readonly executeTargetAssessment: ExecuteTargetAssessmentDeps;
     readonly dataProfile: DataProfileDeps;
-    readonly ephemeral: Omit<EphemeralDeps, "resourcePolicy">;
 }
 /** The registered, callable workflow handles. */
 export interface RegisteredWorkflows {
@@ -42,22 +40,19 @@ export interface RegisteredWorkflows {
     readonly sandboxStep: SandboxStepCallable;
     readonly executeTargetAssessment: (input: ExecuteTargetAssessmentInput) => Promise<ExecuteTargetAssessmentResult>;
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
-    readonly ephemeral: (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
 }
 /**
- * Conversation-agent deps minus the two workflow callables and the resource
+ * Conversation-agent deps minus the workflow callable and the resource
  * policy — `assembleCoreRuntime` supplies those itself so a caller cannot wire
  * a stale callable or a policy that diverges from the one the workflows see.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "ephemeralWorkflow" | "resourcePolicy">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy">;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
     /**
-     * Host resource policy — per-step ceilings, machine budget, ephemeral
-     * sizing. One supply point: assembly distributes it to the planner tools,
-     * `execute_plan` (budget snapshot into workflow input), and the ephemeral
-     * runner. Absent, every consumer keeps its legacy behavior.
+     * Host resource policy — per-step ceilings and machine budget. One supply
+     * point for planner/routing guidance and workflow-input budget snapshots.
      */
     readonly resourcePolicy?: ResourcePolicy;
 }

package/dist/runtime/assemble.js

@@ -19,18 +19,15 @@ import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
-import { registerEphemeralWorkflow } from "../execution/ephemeral-runner.js";
 export function assembleCoreRuntime(deps) {
     const { conversation, workflows: wf, resourcePolicy } = deps;
     const sandboxStep = registerSandboxStep(wf.sandboxStep);
     const executeAnalysis = registerExecuteAnalysis(wf.buildExecuteAnalysis(sandboxStep));
     const executeTargetAssessment = registerExecuteTargetAssessment(wf.executeTargetAssessment);
     const dataProfile = registerDataProfileWorkflow(wf.dataProfile);
-    const ephemeral = registerEphemeralWorkflow({ ...wf.ephemeral, resourcePolicy });
     const conversationAgent = createConversationAgent({
         ...conversation,
         executeAnalysisWorkflow: executeAnalysis,
-        ephemeralWorkflow: ephemeral,
         resourcePolicy,
     });
     return {
@@ -40,7 +37,6 @@ export function assembleCoreRuntime(deps) {
             sandboxStep,
             executeTargetAssessment,
             dataProfile,
-            ephemeral,
         },
     };
 }

package/dist/runtime/boot.d.ts

@@ -22,7 +22,7 @@
  *      builds the conversation agent (register-before-launch invariant).
  *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
  *      must attach before DBOS launch re-emits events (scheduled sweeps, an
- *      ephemeral-workflow reap, an agent-switch install). Runs after registration
+ *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
  *   7. `launchDbos(...)` — the last registration-dependent step.
  *
@@ -49,7 +49,7 @@ export interface BootHarnessDeps {
     readonly logger: Logger;
     /**
      * Host-specific work that must run AFTER workflow registration and BEFORE
-     * DBOS launch (scheduled sweeps, ephemeral reap, agent-switch install). The
+     * DBOS launch (scheduled sweeps, legacy-row reap, agent-switch install). The
      * booted runtime is not returned until after launch, so this hook captures
      * whatever it needs from the embedder's own composition root.
      */

package/dist/runtime/boot.js

@@ -22,7 +22,7 @@
  *      builds the conversation agent (register-before-launch invariant).
  *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
  *      must attach before DBOS launch re-emits events (scheduled sweeps, an
- *      ephemeral-workflow reap, an agent-switch install). Runs after registration
+ *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
  *   7. `launchDbos(...)` — the last registration-dependent step.
  *

package/dist/runtime/dbos.d.ts

@@ -67,11 +67,10 @@ export declare function shutdownDbos({ logger: injected }: {
     logger: Logger;
 }): Promise<void>;
 /**
- * Cancel any `ephemeral:`-prefixed PENDING workflow this executor owns —
- * called BEFORE `launchDbos`, whose recovery would otherwise re-dispatch them.
- *
- * Ephemeral runs are turn-scoped: a run whose pod died mid-flight has no live
- * awaiter and must never re-execute. DBOS has no "zero recovery" knob, and
+ * Cancel any legacy `ephemeral:`-prefixed PENDING workflow this executor owns
+ * before `launchDbos`, whose recovery would otherwise re-dispatch rows created
+ * by older releases. No current workflow creates this prefix. DBOS has no
+ * "zero recovery" knob, and
  * `launch()` starts recovery itself, so there is no post-launch window to
  * cancel from — the only race-free point is a direct system-DB UPDATE before
  * launch. A CANCELLED row is excluded from the recovery query (which selects

package/dist/runtime/dbos.js

@@ -109,11 +109,10 @@ export async function shutdownDbos({ logger: injected }) {
     }
 }
 /**
- * Cancel any `ephemeral:`-prefixed PENDING workflow this executor owns —
- * called BEFORE `launchDbos`, whose recovery would otherwise re-dispatch them.
- *
- * Ephemeral runs are turn-scoped: a run whose pod died mid-flight has no live
- * awaiter and must never re-execute. DBOS has no "zero recovery" knob, and
+ * Cancel any legacy `ephemeral:`-prefixed PENDING workflow this executor owns
+ * before `launchDbos`, whose recovery would otherwise re-dispatch rows created
+ * by older releases. No current workflow creates this prefix. DBOS has no
+ * "zero recovery" knob, and
  * `launch()` starts recovery itself, so there is no post-launch window to
  * cancel from — the only race-free point is a direct system-DB UPDATE before
  * launch. A CANCELLED row is excluded from the recovery query (which selects
@@ -134,7 +133,7 @@ export async function sweepEphemeralWorkflows({ pool, logger: injectedLogger, ex
             values: [Date.now(), executorID],
         });
         if (rowCount && rowCount > 0) {
-            logger.info("swept orphaned ephemeral workflows", { executorID, swept: rowCount });
+            logger.info("swept legacy ephemeral workflow rows", { executorID, swept: rowCount });
         }
     }
     catch (err) {
@@ -142,7 +141,7 @@ export async function sweepEphemeralWorkflows({ pool, logger: injectedLogger, ex
         if (err && typeof err === "object" && "code" in err && err.code === "42P01") {
             return;
         }
-        logger.error("ephemeral sweep failed", { executorID, ...logger.errorFields(err) });
+        logger.error("legacy ephemeral-row sweep failed", { executorID, ...logger.errorFields(err) });
     }
 }
 /** Snapshot of DBOS lifecycle state — read by the readiness probe. */

package/dist/sandbox/mount-plan.d.ts

@@ -24,7 +24,7 @@ export interface MountPlanCoords {
     /**
      * Enforced read-only: emit no read-write step mount. The container sees only
      * the read-only analysis tree (plus container-local `/tmp`). Used by the
-     * ephemeral executor, whose prompt promises it physically cannot write files.
+     * a generic read-only agent that must not mutate analysis files.
      */
     readOnly?: boolean;
 }

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

@@ -32,7 +32,7 @@
  * 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`, `ephemeral-runner`,
+ * non-workflow consumers (`reaper`, `watchdog`,
  * `data-profile`, `run-exec`) already handle a thrown failure. They are
  * untouched by this wave.
  */

package/dist/sandbox/sandbox-error.js

@@ -32,7 +32,7 @@
  * 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`, `ephemeral-runner`,
+ * non-workflow consumers (`reaper`, `watchdog`,
  * `data-profile`, `run-exec`) already handle a thrown failure. They are
  * untouched by this wave.
  */

package/dist/sandbox/types.d.ts

@@ -241,7 +241,7 @@ export interface CreateSandboxMeta {
      *  a sandbox with none. */
     resources: ResourceSpec;
     /** Enforced read-only: provision with no read-write step mount, only the
-     *  read-only analysis tree. Used by the ephemeral executor. */
+     *  read-only analysis tree for generic read-only agents. */
     readOnly?: boolean;
 }
 /**

package/dist/schemas/validate-plan.d.ts

@@ -22,7 +22,7 @@ export interface ValidatePlanOptions {
      * Host per-step resource ceilings. When present, a step whose declared
      * `resources` exceed them is an error — the planner gets actionable
      * feedback at plan time instead of a silent clamp at sandbox creation.
-     * The plan-generation path passes this; `execute_plan` deliberately does
+     * The plan-generation path passes this; `execute_analysis` plan mode deliberately does
      * not, so stored plans that predate the policy keep running (the
      * sandbox-creation clamp remains their backstop).
      */

package/dist/state/index.d.ts

@@ -11,15 +11,15 @@ export type { Querier } from "./db.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
 export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef } from "./artifacts.js";
-export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
-export type { InsertRunInput } from "./runs.js";
+export type { InsertRunInput, RunReservation } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
 export type { ActiveSandboxRow } from "./active-sandboxes.js";
-export { insertPlan, loadPlan } from "./plans.js";
-export type { InsertPlanInput } from "./plans.js";
+export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
+export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";

package/dist/state/index.js

@@ -9,11 +9,11 @@
 export { initCortexState } from "./init.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
-export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
-export { insertPlan, loadPlan } from "./plans.js";
+export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";

package/dist/state/plans.js

@@ -6,7 +6,7 @@ import { randomUUID } from "node:crypto";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 /**
  * `cortex_plans.plan_id` shape contract — `pln-` followed by 8 lowercase hex
- * chars. The chat trigger (`tools/execute-plan.ts`) enforces the same regex on
+ * chars. The chat trigger (`tools/execute-analysis.ts`) enforces the same regex on
  * its tool input; `upsertPlan` re-asserts it because it accepts a caller-derived
  * id rather than minting one.
  */

package/dist/state/runs.d.ts

@@ -22,6 +22,14 @@ export interface InsertRunInput {
     mandateJti?: string | null;
     mandateExpiresAt?: string | null;
 }
+export interface RunReservation {
+    readonly row: CortexRunRow;
+    readonly inserted: boolean;
+}
+export declare class RunIdentityCollisionError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
 /**
  * Raised when `insertRun` collides with the partial-unique index
  * `idx_cortex_runs_active_plan` — i.e., an active run already exists for
@@ -43,6 +51,8 @@ export declare class RunDedupCollisionError extends Error {
  * the err channel as a `DbError`.
  */
 export declare function insertRun(pool: Querier, input: InsertRunInput): ResultAsync<void, DbError>;
+/** Reserve a deterministic run id, treating same-analysis PK conflict as redelivery. */
+export declare function reserveRunById(pool: Querier, input: InsertRunInput): ResultAsync<RunReservation, DbError>;
 /**
  * Recover the active run row for `(analysisId, planId)` after `insertRun`
  * raises `RunDedupCollisionError`. The partial-unique index guarantees at

package/dist/state/runs.js

@@ -10,6 +10,14 @@
  * `err(constraint_violation)` via `tryMutation`.
  */
 import { tryMutation, tryQuery } from "../lib/db-result.js";
+export class RunIdentityCollisionError extends Error {
+    runId;
+    constructor(runId) {
+        super(`run id ${runId} already belongs to another analysis`);
+        this.runId = runId;
+        this.name = "RunIdentityCollisionError";
+    }
+}
 /**
  * Raised when `insertRun` collides with the partial-unique index
  * `idx_cortex_runs_active_plan` — i.e., an active run already exists for
@@ -65,6 +73,45 @@ export function insertRun(pool, input) {
         return e;
     });
 }
+/** Reserve a deterministic run id, treating same-analysis PK conflict as redelivery. */
+export function reserveRunById(pool, input) {
+    const now = new Date().toISOString();
+    return tryMutation("runs.reserveRunById", async () => {
+        const result = await pool.query({
+            text: `INSERT INTO cortex_runs
+            (run_id, analysis_id, thread_id, workflow_name,
+             status, started_at, plan_id, mandate_jti, mandate_expires_at)
+            VALUES ($1, $2, $3, $4, 'running', $5, $6, $7, $8)
+            ON CONFLICT (run_id) DO NOTHING
+            RETURNING run_id`,
+            values: [
+                input.runId,
+                input.analysisId,
+                input.threadId ?? null,
+                input.workflowName,
+                now,
+                input.planId ?? null,
+                input.mandateJti ?? null,
+                input.mandateExpiresAt ?? null,
+            ],
+        });
+        return (result.rowCount ?? 0) > 0;
+    }).andThen((inserted) => tryQuery("runs.reserveRunById.reload", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id, analysis_id, thread_id, workflow_name,
+                       status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
+                       mandate_jti, mandate_expires_at, plan_id
+                FROM cortex_runs
+                WHERE run_id = $1`,
+            values: [input.runId],
+        });
+        return result.rows[0] ?? null;
+    }).map((row) => {
+        if (!row || row.analysis_id !== input.analysisId)
+            throw new RunIdentityCollisionError(input.runId);
+        return { row: mapRunRow(row), inserted };
+    }));
+}
 function isPartialUniqueViolation(err) {
     if (err === null || typeof err !== "object")
         return false;

package/dist/tools/__fixtures__/tool-context.js

@@ -9,6 +9,7 @@ export function makeToolContext(signal) {
     const emitted = [];
     const deny = new UnavailableAsk();
     const ctx = {
+        invocationId: "test-tool-call",
         session: makeSession(),
         signal: signal ?? new AbortController().signal,
         emit: (event) => {

package/dist/tools/ad-hoc-router.d.ts

@@ -0,0 +1,31 @@
+import type { Pool } from "pg";
+import { type AgentSession } from "../auth/types.js";
+import type { ResourcePolicy, ResourceSpec } from "../config/resource-limits.js";
+import type { Logger } from "../lib/logger.js";
+import type { ChatProvider } from "../providers/types.js";
+export declare const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
+export declare const AD_HOC_ROUTER_TIMEOUT_MS = 10000;
+export declare const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
+export interface AdHocRoute {
+    readonly agentId: string;
+    readonly resources: ResourceSpec;
+    readonly rationale: string;
+    readonly fallbackClass?: "timeout" | "provider_error" | "malformed" | "no_match" | "invalid_agent" | "invalid_resources";
+}
+export interface AdHocRouterDeps {
+    readonly provider: ChatProvider;
+    readonly model: string;
+    readonly pool: Pool;
+    readonly resourcePolicy?: ResourcePolicy;
+    readonly logger?: Logger;
+    /** Test seam; production always uses {@link AD_HOC_ROUTER_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
+export declare function defaultAdHocResources(policy?: ResourcePolicy): ResourceSpec;
+export declare function validAdHocResources(value: unknown, policy?: ResourcePolicy): ResourceSpec | null;
+export declare function routeAdHocRequest(deps: AdHocRouterDeps, input: {
+    analysisId: string;
+    request: string;
+    session: AgentSession;
+    signal: AbortSignal;
+}): Promise<AdHocRoute>;