@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/prompts/briefing.js

@@ -30,6 +30,10 @@ export const MAX_UPSTREAM_DEPS = 5;
 export const UPSTREAM_SUMMARY_MAX_CHARS = 500;
 /** Artifact paths listed per dependency; the rest are reachable from its output directory. */
 export const MAX_UPSTREAM_ARTIFACTS = 8;
+/** Adaptable slots rendered in the Template contract section; the tail is counted, not rendered. */
+export const MAX_TEMPLATE_SLOTS = 24;
+/** Characters of one slot description carried in the seed — the constraint, not the manual. */
+export const TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS = 160;
 // ── Field partition (the coverage guard's two halves) ─────────────────
 /** Fields whose content is agent-facing and MUST appear in the rendered task. */
 export const STEP_TASK_FIELDS = [
@@ -40,6 +44,9 @@ export const STEP_TASK_FIELDS = [
     "constraints",
     "acceptance_criteria",
     "caveats",
+    // The step agent reads the template id and the claim identifiers from the
+    // step, not from prose: the grounding renders beside the task fields.
+    "grounding",
 ];
 /**
  * Fields deliberately excluded from the task section: identity/DAG structure
@@ -70,6 +77,11 @@ export const STEP_NON_TASK_FIELDS = [
     // the agent does need to know about them — a dropped entry, or a step that
     // declares none — rides in `caveats`.
     "packages",
+    // Withheld for the same reason as `packages`, one layer up: the phrase is how the router and
+    // the planner name what they routed on, and the launch has already resolved the reference data
+    // it declares. The step agent learns the work from its skill pack, which names each dataset by
+    // what it is. Handing it a routing phrase would invite it to treat that phrase as the method.
+    "capability",
 ];
 // ── Formatting primitives ─────────────────────────────────────────────
 function section(heading, body) {
@@ -95,7 +107,7 @@ function clamp(text, max) {
  * folded in here — otherwise the agent runs against the bare question and
  * improvises the rest.
  */
-export function renderTask(step) {
+export function renderTask(step, contract = {}) {
     const parts = [`# ${step.name}`, section("Task", step.question)];
     if (step.description?.trim()) {
         parts.push(section("What this step produces", step.description.trim()));
@@ -106,14 +118,52 @@ export function renderTask(step) {
     if (step.constraints && step.constraints.length > 0) {
         parts.push(section("Constraints (each one is a requirement of this step)", bullets(step.constraints)));
     }
-    if (step.acceptance_criteria && step.acceptance_criteria.length > 0) {
+    if (step.acceptance_criteria.length > 0) {
         parts.push(section("Acceptance criteria (the result must satisfy all of these)", bullets(step.acceptance_criteria)));
     }
     if (step.caveats && step.caveats.length > 0) {
         parts.push(section("Caveats", bullets(step.caveats)));
     }
+    if (step.grounding) {
+        parts.push(section("Grounding", renderGrounding(step.grounding, contract)));
+    }
     return parts.join("\n\n");
 }
+/**
+ * The grounding as data lines. The template id is the one value the agent
+ * acts on (it names it to `knowledge_template`), thus it renders first after
+ * the status. The claim identifiers and the digest are for the record.
+ *
+ * A grounding that names a template promises a Template contract section.
+ * When the seed carries none, one line says so with the reason, thus the
+ * agent knows the contract was not fetched rather than guessing at slots.
+ *
+ * The settings of the procedure ride here as vetted values, not as
+ * constraints: the agent uses each one unless the data gives a reason for
+ * another value, and then it states the reason. They render only when the
+ * seed carries no template contract, because the bound and the unbound
+ * lists of the contract hold every setting already.
+ */
+function renderGrounding(grounding, contract) {
+    const lines = [`- Status: ${grounding.status}`];
+    if (grounding.template) {
+        lines.push(`- Template: \`${grounding.template}\``);
+        if (!contract.template)
+            lines.push(`- Template contract: not retrieved (${contract.templateNotRetrieved ?? "no contract was fetched for this step"})`);
+    }
+    lines.push(`- Snapshot: ${grounding.snapshot}`);
+    lines.push(`- Claims: ${grounding.claims.length > 0 ? grounding.claims.join(", ") : "none"}`);
+    lines.push(`- Reason: ${grounding.reason}`);
+    const settings = grounding.settings ?? [];
+    if (settings.length > 0 && !contract.template) {
+        lines.push("- Settings (the vetted values of the procedure; another value is permitted when your summary states the reason):");
+        for (const setting of settings) {
+            const value = Array.isArray(setting.value) ? setting.value.join(", ") : String(setting.value);
+            lines.push(`  - ${setting.step}: ${setting.name} = ${value}${setting.source ? ` (${setting.source})` : ""}`);
+        }
+    }
+    return lines.join("\n");
+}
 // ── (1b) Analysis memory ──────────────────────────────────────────────
 /**
  * The heading of the analysis-memory section. The orient core of the sandbox
@@ -155,6 +205,82 @@ export function renderMemory(memory) {
     }
     return section(ANALYSIS_MEMORY_HEADING, parts.join("\n\n"));
 }
+/** A value as the render request carries it: JSON, thus `"apeglm"` and `10` cannot be confused. */
+function slotValue(value) {
+    return JSON.stringify(value);
+}
+/** The version of a template reference (`tpl-x@1.0.0` gives `1.0.0`), or `undefined` when the reference has none. */
+function versionOfRef(ref) {
+    const at = ref.indexOf("@");
+    return at < 0 ? undefined : ref.slice(at + 1);
+}
+/**
+ * One adaptable slot as a bullet: the name, the type, the default with its
+ * source or the required state, the description, and the constraints the
+ * render enforces. A slot without a default is required unless the contract
+ * says otherwise, which is the rule of the renderer.
+ */
+function renderSlot(slot) {
+    const facts = [slot.type];
+    // A local slot is bound on this machine: the agent sends it as any other slot, and the value never leaves.
+    if (slot.local)
+        facts.push("local");
+    if (slot.default !== undefined) {
+        facts.push(`default ${slotValue(slot.default)}${slot.default_source ? ` [${slot.default_source}]` : ""}`);
+    }
+    else {
+        facts.push(slot.required === false ? "optional" : "required");
+    }
+    if (slot.minimum !== undefined)
+        facts.push(`min ${slot.minimum}`);
+    if (slot.maximum !== undefined)
+        facts.push(`max ${slot.maximum}`);
+    const tail = [];
+    if (slot.enum && slot.enum.length > 0)
+        tail.push(`Permitted: ${slot.enum.map(slotValue).join(", ")}.`);
+    if (slot.pattern)
+        tail.push(`Pattern: \`${slot.pattern}\`.`);
+    const description = clamp(slot.description.trim(), TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS);
+    return `\`${slot.name}\` (${facts.join("; ")})${description ? `: ${description}` : ""}${tail.length > 0 ? ` ${tail.join(" ")}` : ""}`;
+}
+/**
+ * The Template contract section. Only the adaptable slots render, bounded by
+ * {@link MAX_TEMPLATE_SLOTS} and the description clamp, so a wide template
+ * cannot blow the seed. A served version that differs from the plan renders
+ * as a caveat: the render refuses the plan version, and the settings are not
+ * bound to a version the plan did not name.
+ */
+export function renderTemplateContract(brief) {
+    if (!brief)
+        return "";
+    const refVersion = versionOfRef(brief.ref);
+    const lead = [
+        `\`${brief.ref}\` (the service serves version ${brief.version_served}). Send only the slots listed here to \`knowledge_template\`; a slot not listed is pinned or unknown, and the render refuses it.`,
+    ];
+    if (refVersion !== undefined && refVersion !== brief.version_served) {
+        lead.push(`Caveat: the plan names version ${refVersion}, and the service serves version ${brief.version_served}. The plan settings are not bound to this render. Render the served version, and state each plan value yourself.`);
+    }
+    const blocks = [lead.join("\n")];
+    const adaptable = brief.slots.filter((slot) => slot.adaptable);
+    if (adaptable.length > 0) {
+        const shown = adaptable.slice(0, MAX_TEMPLATE_SLOTS);
+        const lines = [bullets(shown.map(renderSlot))];
+        const omitted = adaptable.length - shown.length;
+        if (omitted > 0)
+            lines.push(`(+${omitted} more adaptable ${omitted === 1 ? "slot" : "slots"} not listed. The render answer names a required one that is absent.)`);
+        blocks.push(`Slots:\n${lines.join("\n")}`);
+    }
+    if (brief.inputs.length > 0) {
+        blocks.push(`Inputs the script reads:\n${bullets(brief.inputs.map((input) => `${input.name}: \`${input.path}\`${input.description ? ` — ${input.description}` : ""}`))}`);
+    }
+    if (brief.bound.length > 0) {
+        blocks.push(`Bound by the plan (send each value as it is, or add an \`overrides\` entry with the slot and the reason for the change; a changed value without an override is refused):\n${bullets(brief.bound.map((setting) => `\`${setting.name}\` = ${slotValue(setting.value)} (${setting.source})`))}`);
+    }
+    if (brief.unbound_settings.length > 0) {
+        blocks.push(`Unbound settings (the plan states them, and no bound slot carries them):\n${bullets(brief.unbound_settings)}`);
+    }
+    return section("Template contract", blocks.join("\n\n"));
+}
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export function analysisRootOf(frame) {
     return `/${frame.analysisId}`;
@@ -240,7 +366,8 @@ function renderHandoff(handoff) {
  */
 export function composeStepBriefing(briefing) {
     return [
-        renderTask(briefing.step),
+        renderTask(briefing.step, briefing),
+        renderTemplateContract(briefing.template),
         renderMemory(briefing.memory),
         renderWorkspace(briefing.workspace),
         renderResources(briefing.step.resources),

package/dist/prompts/planner.js

@@ -120,7 +120,8 @@ leaves open:
 - An inventory block that reports a failed lookup. Absence in it proves
   nothing, so read that inventory through its tool.
 - A reference census that says it is cut short, where a step needs a
-  collection it does not show.
+  collection it does not show. A bounded listing is not evidence of absence,
+  so confirm through the tool before you call that data missing.
 - A package whose exact spelling or language track the census leaves unclear.
 
 Batch the lookups. \`names\` takes every package you are unsure of in one call,
@@ -212,10 +213,18 @@ ${agentCatalog}
 ### Routing Rules
 - Route by primary data object: if the step works on a count matrix, assign
   the transcriptomics agent; if on a gene list, assign the enrichment agent.
+- A gene list does not settle the assignment by itself. Read what the step
+  asks of the list. A step that builds, labels, or benchmarks a gene set for a
+  safety or tissue-risk question goes to the specialist whose capabilities name
+  that work, not to the enrichment agent.
 - When a step could go to either a modality or cross-cutting agent, prefer
   cross-cutting if the input is already in generic format (CSV/TSV). Prefer
   modality if it needs modality-specific objects (AnnData, SummarizedExperiment).
 - If no agent is an exact fit, pick the closest specialist from the list.
+- Name the capability you routed on. Copy one phrase out of that agent's
+  capabilities into the step's \`capability\` field, spelled exactly as the
+  catalog spells it. The launch resolves what reference data that capability
+  needs before the run starts, so a paraphrase costs the step that check.
 
 ## Grounding
 
@@ -287,7 +296,9 @@ safety, toxicity, or treatment outcomes:
 5. **Route safety data correctly.** If the data includes safety
    biomarkers (ALT, AST, troponin, creatinine, hERG), adverse event
    records, or toxicity classifications, route to the
-   translational-safety-agent.
+   translational-safety-agent. Route a request for matched negative
+   controls, or for a tissue-risk benchmark set, to the same agent even
+   when the only input is a gene list.
 
 6. **Route immune profiling correctly.** If the research question
    involves immune cell composition, tumor microenvironment

package/dist/prompts/synthesis-agent.d.ts

@@ -1 +1 @@
-export declare const synthesisAgentPrompt = "# Run Synthesizer\n\nYou are a cross-step synthesizer for a completed bioinformatics analysis\nrun. You receive the plan's analytical narrative and a block of per-step\nsummaries (markdown). Your job is to distill them into a concise,\nliterature-grounded **interpretation** \u2014 not a catalog of what each step\nproduced.\n\nYou are task-oriented \u2014 you do not interact with the user. You receive\nthe run's context, investigate what you need via your research sub-agent,\nand return a structured synthesis.\n\n## How Your Work Reaches the User\n\nThe orchestrator reads only your tool calls, so text you write reaches no\none. A synthesis reaches the user through `submit_synthesis`, and a\nblocker through `report_blocker`. End the session with an accepted\n`submit_synthesis` or a `report_blocker`.\n\n## Your Mission\n\nThe reader of your synthesis is a scientist who already has the step\nsummaries. They do not need you to repeat what each step found \u2014 they\ncan read that themselves. What they need from you is:\n\n1. **Interpretation** \u2014 what do the results mean taken together?\n2. **Conclusions** \u2014 what can we confidently conclude? What is novel vs\n   confirmatory? What is actionable from a translational perspective?\n3. **Limitations** \u2014 what caveats apply? Where should the reader be\n   skeptical? What confounds exist?\n4. **Evidence** \u2014 key literature references that support, challenge, or\n   contextualize the findings.\n\nThink like a senior reviewer writing the Discussion section of a paper,\nnot like a scribe summarizing the Results section.\n\n## Your Tools\n\n### literature_reviewer (research sub-agent \u2014 delegate focused research)\nA task-oriented sub-agent that holds the bio-lookup and literature tools.\nDelegate to it when you need evidence \u2014 you have no bio-lookup tools of\nyour own.\n\nDelegations must be **focused**:\n- One well-scoped research brief per call (e.g., \"Investigate FOXM1 and\n  MKI67 in the context of proliferation signatures in bulk RNA-seq of\n  breast tumor vs normal. Assess novelty and find supporting PMIDs.\")\n- Include the experimental context the sub-agent needs (conditions, modality,\n  what the computational finding showed).\n- Do NOT send the whole summary block and ask for \"a literature review\".\n  The sub-agent will produce shallow results on diffuse briefs.\n\nYou may delegate again after an initial pass if a\ntheme becomes apparent and needs its own evidence sweep.\n\n### validate_synthesis (non-terminal \u2014 dry run)\nCheck a candidate synthesis without submitting it. Takes the payload in\nANY shape \u2014 a partial, malformed, or wrong-typed draft is reported, not\nrejected \u2014 and returns `{valid, issues}` covering both schema problems\nand the cross-field invariants below. Call it as often as you need: it\nrecords nothing and never ends the session. `submit_synthesis` runs the\nsame checks, so a dry run is optional.\n\n### submit_synthesis (terminal \u2014 success path)\nPersist the synthesis. Re-validates the payload; returns either\n`{accepted: true}` (DONE \u2014 stop) or `{accepted: false, issues}` (fix\nspecific fields per issue path and call again, OR switch to\n`report_blocker` if the synthesis cannot be made valid). An accepted\nsubmission ends the session.\n\n### report_blocker (terminal \u2014 cannot produce a synthesis)\nCall ONLY when the run produced no synthesizable content \u2014 every summary is\nempty, or the summaries are contradictory to the point of incoherence.\n\"No findings worth surfacing\" is NOT a blocker: with non-empty summaries you\ncan always submit a synthesis (overview + conclusions) with an empty\n`findings[]`. Pass a short reason, then stop.\n\n## Canonical Flow\n\nGround the novel findings, the contradictions, and the cross-step themes\nin literature before you draft. Then call `submit_synthesis`. If it is\nrejected, fix the cited issue paths and call again. If it cannot be made\nvalid, call `report_blocker`.\n\n## Writing the Synthesis\n\nThe `submit_synthesis` arg schema defines every field, its enum values,\nand its size expectations \u2014 read it, and follow it. This section is the\ncraft the schema cannot carry.\n\n**An empty `findings[]` is a valid submission.** `findings` is SELECTIVE,\nnot required \u2014 a run whose summaries yield nothing individually notable is\nstill synthesized: write the `overview` and `conclusions` from the\nsummaries and submit with `findings: []`. \"Nothing worth a finding\" is a\nreason to submit a lean synthesis, never a reason to `report_blocker`.\n\n**`conclusions` is the \"Discussion\" of the synthesis** \u2014 the part the\nreader will actually want to read. Be opinionated and interpretive, not\ndescriptive. Say where computational predictions agree or disagree with\nclinical evidence, and be honest about the translational distance: is this\ninteresting biology, or a validated target with a measurable biomarker and\na known drug?\n\n**Assigning `preclinical-validation`** \u2014 cite IMPC mouse-KO phenotypes for\nloss-of-function consequences and cross-species baseline expression for\ntissue-of-action context (both come back from\n`gene_preclinical_profile`), when the literature reviewer's report\nincludes them.\n\n**What a good `limitation` looks like** \u2014 it names what it affects and\nwhy it matters:\n- \"Signatures derive from a single cohort (n=57); cross-validation in\n  independent NASH datasets was not performed.\"\n- \"CMap-style scoring cannot distinguish targeted pathway reversal from\n  non-specific cytotoxic transcriptional disruption.\"\n- \"Biomarker candidates identified computationally; analytical validation\n  (assay performance, reproducibility) and clinical validation (outcome\n  association in independent cohorts) not performed.\"\n- \"Target druggability not assessed \u2014 pathway importance does not imply\n  tractability.\"\n\n## Cross-Field Invariants (reported by validate_synthesis, enforced at submit_synthesis)\n\n- `finding.stepId` must match a stepId present in the input summaries.\n- Every `theme.findings[]` entry must reference a finding that exists\n  in `findings[]` (same stepId + title).\n- Every `keyReferences[].pmid` must appear in at least one\n  `finding.references[]` entry \u2014 the cross-run list summarizes what's\n  already cited per finding.\n\nEvery `pmid` you write comes from a `literature_reviewer` response.\n`validate_synthesis` cannot check this, and nothing after you re-checks a\nPMID, so an invented one reaches the reader as a real citation.\n\n## Investigation Strategy\n\n**Which findings need delegation?**\n- Findings labeled high-confidence in the summary but potentially novel \u2014\n  needs literature check to confirm or challenge novelty.\n- Findings that could map to a known disease or pathway context \u2014 needs\n  a PubMed sweep for the gene+condition combination.\n- Candidate themes spanning 2+ steps \u2014 delegate a theme-level brief to\n  get references that tie the findings together.\n\n**Which findings do NOT need delegation?**\n- Trivial / expected results (QC passed, dimensions as expected).\n- Technical findings with no biological claim (batch effect detected,\n  normalization applied).\n\n**Composing a delegation brief** \u2014 include:\n1. The specific genes/pathways/features to investigate (from the summary).\n2. The experimental context (conditions, modality, organism if known).\n3. What the computational finding showed (one sentence).\n4. What you want back (novelty assessment? supporting PMIDs? pathway\n   context? interaction partners?).\n\nExample:\n> \"Investigate SPP1, TREM2, and APOE in the context of microglia\n> activation in Alzheimer's disease single-cell RNA-seq. Finding:\n> these three genes form a co-expression module enriched in\n> disease-associated microglia. Return: novelty assessment, 3-5 key\n> PMIDs supporting or challenging the DAM signature, and any known\n> interactions among the three.\"\n\n## Do NOT\n\n- **Reiterate step results.** The reader has the step summaries. Do not\n  repeat gene lists, sample counts, table dimensions, method parameters,\n  or per-step results in the synthesis. Refer to findings by their\n  biological meaning, not their technical details.\n- **Create one finding per step.** That is a catalog, not a synthesis.\n  Cross-reference across steps and surface only what matters.\n- **Write a long overview.** The conclusions field is where interpretation goes.\n- **Include methodology findings.** Gene intersection sizes, normalization\n  choices, platform coverage \u2014 these are technical housekeeping, not\n  synthesis findings.\n- **Include expected or confirmatory findings.** Canonical pathway\n  enrichments, QC metrics, and well-established biology do not warrant a\n  finding \u2014 unless the confirmation itself is noteworthy (e.g., a new\n  dataset independently confirming a contested result).\n- **Inflate translational relevance.** A differentially expressed gene is\n  NOT automatically a therapeutic target. A survival association is NOT\n  automatically a predictive biomarker (it may be prognostic only) \u2014\n  predictive requires evidence of treatment x marker interaction,\n  prognostic only requires association with outcome.\n- Force findings into themes. If findings don't converge, return fewer (or zero) themes.\n- Call `submit_synthesis` before delegating at least once when findings need\n  literature grounding. (A run with only technical/QC findings may skip delegation\n  and submit directly, but state that clearly in the overview.)\n- Submit a placeholder or stub payload to \"see what happens\". A degenerate\n  payload that passes the schema is recorded as the run's result.\n";
+export declare const synthesisAgentPrompt = "# Run Synthesizer\n\nYou are a cross-step synthesizer for a completed bioinformatics analysis\nrun. You receive the plan's analytical narrative and a block of per-step\nsummaries (markdown). Your job is to distill them into a concise,\nliterature-grounded **interpretation** \u2014 not a catalog of what each step\nproduced.\n\nYou are task-oriented \u2014 you do not interact with the user. You receive\nthe run's context, investigate what you need via your research sub-agent,\nand return a structured synthesis.\n\n## How Your Work Reaches the User\n\nThe orchestrator reads only your tool calls, so text you write reaches no\none. A synthesis reaches the user through `submit_synthesis`, and a\nblocker through `report_blocker`. End the session with an accepted\n`submit_synthesis` or a `report_blocker`.\n\n## Your Mission\n\nThe reader of your synthesis is a scientist who already has the step\nsummaries. They do not need you to repeat what each step found \u2014 they\ncan read that themselves. What they need from you is:\n\n1. **Interpretation** \u2014 what do the results mean taken together?\n2. **Conclusions** \u2014 what can we confidently conclude? What is novel vs\n   confirmatory? What is actionable from a translational perspective?\n3. **Limitations** \u2014 what caveats apply? Where should the reader be\n   skeptical? What confounds exist?\n4. **Evidence** \u2014 key literature references that support, challenge, or\n   contextualize the findings.\n\nThink like a senior reviewer writing the Discussion section of a paper,\nnot like a scribe summarizing the Results section.\n\n## Your Tools\n\n### literature_reviewer (research sub-agent \u2014 delegate focused research)\nA task-oriented sub-agent that holds the bio-lookup and literature tools.\nDelegate to it when you need evidence \u2014 you have no bio-lookup tools of\nyour own.\n\nDelegations must be **focused**:\n- One well-scoped research brief per call (e.g., \"Investigate FOXM1 and\n  MKI67 in the context of proliferation signatures in bulk RNA-seq of\n  breast tumor vs normal. Assess novelty and find supporting PMIDs.\")\n- Include the experimental context the sub-agent needs (conditions, modality,\n  what the computational finding showed).\n- Do NOT send the whole summary block and ask for \"a literature review\".\n  The sub-agent will produce shallow results on diffuse briefs.\n\nYou may delegate again after an initial pass if a\ntheme becomes apparent and needs its own evidence sweep.\n\n### submit_synthesis (success path)\nSubmit the synthesis. Checks the payload; returns either\n`{accepted: true}` (DONE \u2014 stop) or `{accepted: false, issues}` (fix\nspecific fields per issue path and call again, OR switch to\n`report_blocker` if the synthesis cannot be made valid). The last accepted\nsubmission is the synthesis.\n\n### report_blocker (terminal \u2014 cannot produce a synthesis)\nCall ONLY when the run produced no synthesizable content \u2014 every summary is\nempty, or the summaries are contradictory to the point of incoherence.\n\"No findings worth surfacing\" is NOT a blocker: with non-empty summaries you\ncan always submit a synthesis (overview + conclusions) with an empty\n`findings[]`. Pass a short reason, then stop.\n\n## Canonical Flow\n\nGround the novel findings, the contradictions, and the cross-step themes\nin literature before you draft. Then call `submit_synthesis`. If it is\nrejected, fix the cited issue paths and call again. If it cannot be made\nvalid, call `report_blocker`.\n\n## Writing the Synthesis\n\nThe `submit_synthesis` arg schema defines every field, its enum values,\nand its size expectations \u2014 read it, and follow it. This section is the\ncraft the schema cannot carry.\n\n**An empty `findings[]` is a valid submission.** `findings` is SELECTIVE,\nnot required \u2014 a run whose summaries yield nothing individually notable is\nstill synthesized: write the `overview` and `conclusions` from the\nsummaries and submit with `findings: []`. \"Nothing worth a finding\" is a\nreason to submit a lean synthesis, never a reason to `report_blocker`.\n\n**`conclusions` is the \"Discussion\" of the synthesis** \u2014 the part the\nreader will actually want to read. Be opinionated and interpretive, not\ndescriptive. Say where computational predictions agree or disagree with\nclinical evidence, and be honest about the translational distance: is this\ninteresting biology, or a validated target with a measurable biomarker and\na known drug?\n\n**Assigning `preclinical-validation`** \u2014 cite IMPC mouse-KO phenotypes for\nloss-of-function consequences and cross-species baseline expression for\ntissue-of-action context (both come back from\n`gene_preclinical_profile`), when the literature reviewer's report\nincludes them.\n\n**What a good `limitation` looks like** \u2014 it names what it affects and\nwhy it matters:\n- \"Signatures derive from a single cohort (n=57); cross-validation in\n  independent NASH datasets was not performed.\"\n- \"CMap-style scoring cannot distinguish targeted pathway reversal from\n  non-specific cytotoxic transcriptional disruption.\"\n- \"Biomarker candidates identified computationally; analytical validation\n  (assay performance, reproducibility) and clinical validation (outcome\n  association in independent cohorts) not performed.\"\n- \"Target druggability not assessed \u2014 pathway importance does not imply\n  tractability.\"\n\n## Cross-Field Invariants (enforced at submit_synthesis)\n\n- `finding.stepId` must match a stepId present in the input summaries.\n- Every `theme.findings[]` entry must reference a finding that exists\n  in `findings[]` (same stepId + title).\n- Every `keyReferences[].pmid` must appear in at least one\n  `finding.references[]` entry \u2014 the cross-run list summarizes what's\n  already cited per finding.\n\nEvery `pmid` you write comes from a `literature_reviewer` response.\n`submit_synthesis` cannot check this, and nothing after you re-checks a\nPMID, so an invented one reaches the reader as a real citation.\n\n## Investigation Strategy\n\n**Which findings need delegation?**\n- Findings labeled high-confidence in the summary but potentially novel \u2014\n  needs literature check to confirm or challenge novelty.\n- Findings that could map to a known disease or pathway context \u2014 needs\n  a PubMed sweep for the gene+condition combination.\n- Candidate themes spanning 2+ steps \u2014 delegate a theme-level brief to\n  get references that tie the findings together.\n\n**Which findings do NOT need delegation?**\n- Trivial / expected results (QC passed, dimensions as expected).\n- Technical findings with no biological claim (batch effect detected,\n  normalization applied).\n\n**Composing a delegation brief** \u2014 include:\n1. The specific genes/pathways/features to investigate (from the summary).\n2. The experimental context (conditions, modality, organism if known).\n3. What the computational finding showed (one sentence).\n4. What you want back (novelty assessment? supporting PMIDs? pathway\n   context? interaction partners?).\n\nExample:\n> \"Investigate SPP1, TREM2, and APOE in the context of microglia\n> activation in Alzheimer's disease single-cell RNA-seq. Finding:\n> these three genes form a co-expression module enriched in\n> disease-associated microglia. Return: novelty assessment, 3-5 key\n> PMIDs supporting or challenging the DAM signature, and any known\n> interactions among the three.\"\n\n## Do NOT\n\n- **Reiterate step results.** The reader has the step summaries. Do not\n  repeat gene lists, sample counts, table dimensions, method parameters,\n  or per-step results in the synthesis. Refer to findings by their\n  biological meaning, not their technical details.\n- **Create one finding per step.** That is a catalog, not a synthesis.\n  Cross-reference across steps and surface only what matters.\n- **Write a long overview.** The conclusions field is where interpretation goes.\n- **Include methodology findings.** Gene intersection sizes, normalization\n  choices, platform coverage \u2014 these are technical housekeeping, not\n  synthesis findings.\n- **Include expected or confirmatory findings.** Canonical pathway\n  enrichments, QC metrics, and well-established biology do not warrant a\n  finding \u2014 unless the confirmation itself is noteworthy (e.g., a new\n  dataset independently confirming a contested result).\n- **Inflate translational relevance.** A differentially expressed gene is\n  NOT automatically a therapeutic target. A survival association is NOT\n  automatically a predictive biomarker (it may be prognostic only) \u2014\n  predictive requires evidence of treatment x marker interaction,\n  prognostic only requires association with outcome.\n- Force findings into themes. If findings don't converge, return fewer (or zero) themes.\n- Call `submit_synthesis` before delegating at least once when findings need\n  literature grounding. (A run with only technical/QC findings may skip delegation\n  and submit directly, but state that clearly in the overview.)\n- Submit a placeholder or stub payload to \"see what happens\". A degenerate\n  payload that passes the schema is recorded as the run's result.\n";

package/dist/prompts/synthesis-agent.js

@@ -53,20 +53,12 @@ Delegations must be **focused**:
 You may delegate again after an initial pass if a
 theme becomes apparent and needs its own evidence sweep.
 
-### validate_synthesis (non-terminal — dry run)
-Check a candidate synthesis without submitting it. Takes the payload in
-ANY shape — a partial, malformed, or wrong-typed draft is reported, not
-rejected — and returns \`{valid, issues}\` covering both schema problems
-and the cross-field invariants below. Call it as often as you need: it
-records nothing and never ends the session. \`submit_synthesis\` runs the
-same checks, so a dry run is optional.
-
-### submit_synthesis (terminal — success path)
-Persist the synthesis. Re-validates the payload; returns either
+### submit_synthesis (success path)
+Submit the synthesis. Checks the payload; returns either
 \`{accepted: true}\` (DONE — stop) or \`{accepted: false, issues}\` (fix
 specific fields per issue path and call again, OR switch to
-\`report_blocker\` if the synthesis cannot be made valid). An accepted
-submission ends the session.
+\`report_blocker\` if the synthesis cannot be made valid). The last accepted
+submission is the synthesis.
 
 ### report_blocker (terminal — cannot produce a synthesis)
 Call ONLY when the run produced no synthesizable content — every summary is
@@ -119,7 +111,7 @@ why it matters:
 - "Target druggability not assessed — pathway importance does not imply
   tractability."
 
-## Cross-Field Invariants (reported by validate_synthesis, enforced at submit_synthesis)
+## Cross-Field Invariants (enforced at submit_synthesis)
 
 - \`finding.stepId\` must match a stepId present in the input summaries.
 - Every \`theme.findings[]\` entry must reference a finding that exists
@@ -129,7 +121,7 @@ why it matters:
   already cited per finding.
 
 Every \`pmid\` you write comes from a \`literature_reviewer\` response.
-\`validate_synthesis\` cannot check this, and nothing after you re-checks a
+\`submit_synthesis\` cannot check this, and nothing after you re-checks a
 PMID, so an invented one reaches the reader as a real citation.
 
 ## Investigation Strategy

package/dist/provenance/collector.d.ts

@@ -23,22 +23,22 @@ import type { ProvenanceRecord, InputRef, InputSource } from "./types.js";
  * and stable (e.g., `recordFileToolWrite` for in-process agent tool
  * writes) may pass a non-empty hash directly.
  */
-export interface ObservedWrite {
+export type ObservedWrite = {
     /** Analysis-relative path (e.g., "runs/run-001/step-de/output/results.csv") */
     path: string;
     /** SHA-256 hash of the file content. Empty string when deferred to reconcile. */
     hash: string;
     /** File size in bytes. */
     size: number;
-}
+};
 /** Explicit classification context for a file read. Callers build this
  *  from the step's own coordinates (stepId/runId/dependsOn) instead of the
  *  collector parsing paths. */
-export interface InputClassificationContext {
+export type InputClassificationContext = {
     source: InputSource;
     stepId?: string;
     runId?: string;
-}
+};
 /**
  * The outcome of classifying one read: an input edge the step may assert, or
  * an explicit refusal naming the producing step it would have pointed at.
@@ -70,12 +70,12 @@ export type ReadClassification = {
  * prior-run branch below for why.
  */
 export declare function classifyReadPath(relativePath: string, ownStepId: string, ownRunId: string, dependsOn?: string[]): ReadClassification;
-export interface ProvenanceCollectorOptions {
+export type ProvenanceCollectorOptions = {
     stepId: string;
     runId: string;
     /** Step IDs this step depends on (for upstream mount enumeration). */
     dependsOn?: string[];
-}
+};
 export declare class ProvenanceCollector {
     readonly stepId: string;
     readonly runId: string;

package/dist/provenance/collector.js

@@ -11,21 +11,28 @@
  * tool reads are not tracked here — they're exploratory and would
  * pollute the lineage graph.
  */
+import { presentFirst } from "../lib/present.js";
+import { collapseWhitespace, hasWhitespace } from "../lib/text.js";
 // ── Script path inference ───────────────────────────────────────────
-/** Known interpreter prefixes for script path extraction. */
-const SCRIPT_PATTERNS = [/^python3?\s+(\S.*)$/, /^Rscript\s+(\S.*)$/, /^bash\s+(\S.*)$/, /^sh\s+(\S.*)$/];
+/** Known interpreter prefixes for script path extraction. The two python spellings sit first, so the longer prefix wins. */
+const INTERPRETER_PREFIXES = ["python3", "python", "Rscript", "bash", "sh"];
 /**
  * Attempt to extract the script path from a command string.
  * Returns the first argument that looks like a file path for known interpreters.
  */
 function inferScriptPath(command, args) {
     const fullCommand = args?.length ? `${command} ${args.join(" ")}` : command;
-    for (const pattern of SCRIPT_PATTERNS) {
-        const match = fullCommand.match(pattern);
-        if (match?.[1]) {
-            // Take the first token (the script path), ignoring further args
-            return match[1].split(/\s+/)[0];
-        }
+    for (const prefix of INTERPRETER_PREFIXES) {
+        if (!fullCommand.startsWith(prefix))
+            continue;
+        const rest = fullCommand.slice(prefix.length);
+        if (!hasWhitespace(rest.charAt(0)))
+            continue;
+        const argumentsText = collapseWhitespace(rest);
+        if (argumentsText === "")
+            continue;
+        // Take the first token (the script path), ignoring further args
+        return presentFirst(argumentsText.split(" "), "the script path");
     }
     return null;
 }

package/dist/provenance/exec-frame.d.ts

@@ -32,7 +32,7 @@ import { type ProvenanceCollector } from "./collector.js";
  * verbatim (see `trackInputAccess`).
  */
 export declare function stripMountPrefix(mountRoot: string, absPath: string): string;
-export interface FeedExecFrameArgs {
+export type FeedExecFrameArgs = {
     readonly collector: ProvenanceCollector;
     /** Analysis resource mount root, e.g. `/{resourceId}`. */
     readonly mountRoot: string;
@@ -44,7 +44,7 @@ export interface FeedExecFrameArgs {
     readonly provenance?: ProvenanceFrame;
     /** Diagnostics seam. Left unwired, refusals still happen but go unnarrated. */
     readonly logger?: Logger;
-}
+};
 /**
  * Translate one exec's frame into a collector record. Per-command input
  * scoping: only the reads observed for THIS exec are attached to its

package/dist/provenance/exec-frame.js

@@ -32,7 +32,12 @@ import { classifyReadPath } from "./collector.js";
  */
 export function stripMountPrefix(mountRoot, absPath) {
     const prefix = mountRoot.endsWith("/") ? mountRoot : `${mountRoot}/`;
-    return absPath.startsWith(prefix) ? absPath.slice(prefix.length).replace(/^\/+/, "") : absPath;
+    if (!absPath.startsWith(prefix))
+        return absPath;
+    let start = prefix.length;
+    while (start < absPath.length && absPath.charAt(start) === "/")
+        start++;
+    return absPath.slice(start);
 }
 /**
  * Translate one exec's frame into a collector record. Per-command input

package/dist/provenance/seam.d.ts

@@ -8,14 +8,16 @@
  *
  * One surface carries the three, and each member is optional alone. Thus a composition binds the members
  * that it records, and the harness reads an absent member as absence and never as an error. The run emit
- * takes the `RunSession` of the run, because a durable run carries one and a persisting realization needs
- * its credential. A session act carries no session, thus the session emit takes the event alone.
+ * takes an `AgentSession`, because a persisting realization needs the credential of the actor. The
+ * workflow body passes the `RunSession` of its durable input, and the run canceler passes the session of
+ * the cancel. A session act carries no session, thus the session emit takes the event alone.
  *
- * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. A site emits
- * after its act lands, thus a refused act and a failed act each emit nothing and the record states what
- * happened.
+ * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. The writer
+ * that wins the conditional terminal write of the run row emits `run_completed`. The body emits it before
+ * its status write commits, or after a refused or failed write. The canceler emits it only when its write
+ * changes the row, thus a refused cancel emits nothing.
  */
-import type { RunSession } from "../auth/types.js";
+import type { AgentSession } from "../auth/types.js";
 import type { Logger } from "../lib/logger.js";
 import type { ProvenanceExport } from "../report-render/provenance-data.js";
 import type { AuthoringBlock } from "../report-model/authoring-grammar.js";
@@ -26,14 +28,19 @@ export type { ProvenanceExport } from "../report-render/provenance-data.js";
  * Harness-owned plain union — the harness stays tsprov-free and bus-free; the
  * host maps these execution facts onto its own ledger vocabulary.
  *
- * Every `atMs` is epoch milliseconds read via `await DBOS.now()`, a checkpointed
- * step: a body re-executed by DBOS recovery reads the recorded value, so a
+ * In the workflow body, every `atMs` is epoch milliseconds read via `await DBOS.now()`, a
+ * checkpointed step: a body re-executed by DBOS recovery reads the recorded value, so a
  * re-emitted event carries the identical timestamp and merges on the host's
- * ledger without a value conflict. Never source these from a wall clock
+ * ledger without a value conflict. The body never sources these from a wall clock
  * (`Date.now()`) — that would diverge across replays and defeat the merge.
  *
- * `run_completed.durationMs` is the terminal `atMs` minus the `run_started`
- * `atMs` (both `DBOS.now()` reads) — the true workflow-observed run span.
+ * The run canceler is the second emit site of `step_completed` and `run_completed`, and it emits only
+ * when its write of the run row changes the row. It is not a workflow, thus no replay fires its emits,
+ * and it reads the wall clock one time for all of them.
+ *
+ * In the body, `run_completed.durationMs` is the terminal `atMs` minus the `run_started`
+ * `atMs` (both `DBOS.now()` reads) — the true workflow-observed run span. The canceler holds no
+ * `run_started` time, thus it measures from the `started_at` of the run row.
  *
  * `step_completed` fires once at EVERY scheduler-loop settlement — the only site
  * that observes every executed step (registration sees only artifact-producing
@@ -67,10 +74,7 @@ export type RunProvenanceEvent = {
     type: "run_completed";
     analysisId: string;
     runId: string;
-    /**
-     * The body's terminal status, resolved through `deriveFinalStatus`. A suspension is
-     * `"suspended_insufficient_funds"`.
-     */
+    /** The body's terminal status, resolved through `deriveFinalStatus`. */
     status: Exclude<ExecuteAnalysisFinalStatus, "running">;
     atMs: number;
     /** `atMs − run_started.atMs`: the workflow-observed run span in ms. */
@@ -192,11 +196,12 @@ export type ProvenanceSeam = {
      * The run engine emits the facts of one run here.
      *
      * Synchronous by signature (`void`, never a promise): a host that needs input and output dispatches
-     * the work rather than making a workflow body wait behind it. The `RunSession` rides from the durable
-     * workflow input, because a persisting realization needs the credential, the scope, and the identity
-     * of the run. A realization can ignore the parameter.
+     * the work rather than making a workflow body wait behind it. The session rides beside the event,
+     * because a persisting realization needs the credential, the scope, and the identity of the actor.
+     * The body passes the `RunSession` of its durable workflow input. The run canceler passes the
+     * session of the cancel, because it holds no `RunSession`. A realization can ignore the parameter.
      */
-    readonly emitRunEvent?: (event: RunProvenanceEvent, session: RunSession) => void;
+    readonly emitRunEvent?: (event: RunProvenanceEvent, session: AgentSession) => void;
     /**
      * A session emits one act here. A session act runs under no authorized run, thus this member takes
      * the event alone. It is synchronous by signature for the same reason as the run emit.

package/dist/provenance/seam.js

@@ -8,12 +8,14 @@
  *
  * One surface carries the three, and each member is optional alone. Thus a composition binds the members
  * that it records, and the harness reads an absent member as absence and never as an error. The run emit
- * takes the `RunSession` of the run, because a durable run carries one and a persisting realization needs
- * its credential. A session act carries no session, thus the session emit takes the event alone.
+ * takes an `AgentSession`, because a persisting realization needs the credential of the actor. The
+ * workflow body passes the `RunSession` of its durable input, and the run canceler passes the session of
+ * the cancel. A session act carries no session, thus the session emit takes the event alone.
  *
- * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. A site emits
- * after its act lands, thus a refused act and a failed act each emit nothing and the record states what
- * happened.
+ * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. The writer
+ * that wins the conditional terminal write of the run row emits `run_completed`. The body emits it before
+ * its status write commits, or after a refused or failed write. The canceler emits it only when its write
+ * changes the row, thus a refused cancel emits nothing.
  */
 /**
  * Bind the optional session emit and the logger of one site into a total emit.

package/dist/provenance/types.d.ts

@@ -42,10 +42,10 @@ export declare const ProducerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export type Producer = z.infer<typeof ProducerSchema>;
 /** Classification of an input source based on mount semantics. */
 export declare const InputSourceSchema: z.ZodEnum<{
+    artifacts: "artifacts";
     data: "data";
-    upstream: "upstream";
     prior: "prior";
-    artifacts: "artifacts";
+    upstream: "upstream";
 }>;
 export type InputSource = z.infer<typeof InputSourceSchema>;
 /** A single input reference in a lineage chain. */
@@ -53,10 +53,10 @@ export declare const InputRefSchema: z.ZodObject<{
     path: z.ZodString;
     hash: z.ZodString;
     source: z.ZodEnum<{
+        artifacts: "artifacts";
         data: "data";
-        upstream: "upstream";
         prior: "prior";
-        artifacts: "artifacts";
+        upstream: "upstream";
     }>;
     stepId: z.ZodOptional<z.ZodString>;
     runId: z.ZodOptional<z.ZodString>;
@@ -84,10 +84,10 @@ export declare const ProvenanceRecordSchema: z.ZodObject<{
         path: z.ZodString;
         hash: z.ZodString;
         source: z.ZodEnum<{
+            artifacts: "artifacts";
             data: "data";
-            upstream: "upstream";
             prior: "prior";
-            artifacts: "artifacts";
+            upstream: "upstream";
         }>;
         stepId: z.ZodOptional<z.ZodString>;
         runId: z.ZodOptional<z.ZodString>;