@inflexa-ai/harness 0.45.1 → 0.46.2

package/dist/memory/working-memory.js

@@ -30,6 +30,7 @@
 import { err, ok, okAsync } from "neverthrow";
 import { z } from "zod";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { presentGet } from "../lib/present.js";
 /**
  * The write-time bounds on working memory. `updateSection` enforces them, the
  * `update_working_memory` input schema declares them to the model (importing
@@ -140,7 +141,7 @@ function countFindings(findings) {
 }
 /** The run a finding id hangs under, or `undefined` if no run holds it. */
 function runOfFinding(findings, id) {
-    return Object.keys(findings).find((runId) => findings[runId].some((f) => f.id === id));
+    return Object.keys(findings).find((runId) => presentGet(findings, runId, "the run's findings").some((f) => f.id === id));
 }
 function applyFindingOp(findings, op) {
     switch (op.op) {
@@ -159,59 +160,51 @@ function applyFindingOp(findings, op) {
                 return rejectUnknownId("finding", op.id);
             return checkEntryText("finding", op.text).map((text) => ({
                 ...findings,
-                [runId]: findings[runId].map((f) => (f.id === op.id ? { ...f, text } : f)),
+                [runId]: presentGet(findings, runId, "the run's findings").map((f) => (f.id === op.id ? { ...f, text } : f)),
             }));
         }
         case "retire": {
             const runId = runOfFinding(findings, op.id);
             if (runId === undefined)
                 return rejectUnknownId("finding", op.id);
-            const kept = findings[runId].filter((f) => f.id !== op.id);
+            const kept = presentGet(findings, runId, "the run's findings").filter((f) => f.id !== op.id);
             const next = { ...findings };
             // An emptied run bucket is dropped whole: memory references a run only
             // for as long as it holds a finding from it.
             if (kept.length === 0)
-                delete next[runId];
+                Reflect.deleteProperty(next, runId);
             else
                 next[runId] = kept;
             return ok(next);
         }
     }
 }
-/**
- * Pure section-addressable amendment. Sibling sections are never touched; a
- * refused write returns `err` and the caller writes nothing.
- */
-function applySectionUpdate(wm, section, value) {
-    switch (section) {
-        case "goal": {
-            const text = value.text.trim();
-            if (text.length > WORKING_MEMORY_LIMITS.goalChars) {
-                return reject(`the goal is ${text.length} characters — the cap is ${WORKING_MEMORY_LIMITS.goalChars}. It was NOT ` +
-                    `recorded. State the objective in a sentence or two; the supporting detail belongs in ` +
-                    `constraints and findings, not in the goal.`);
-            }
-            return ok({ ...wm, goal: text });
+const sectionWriters = {
+    goal: (wm, value) => {
+        const text = value.text.trim();
+        if (text.length > WORKING_MEMORY_LIMITS.goalChars) {
+            return reject(`the goal is ${text.length} characters — the cap is ${WORKING_MEMORY_LIMITS.goalChars}. It was NOT ` +
+                `recorded. State the objective in a sentence or two; the supporting detail belongs in ` +
+                `constraints and findings, not in the goal.`);
         }
-        case "constraint": {
-            const op = value;
-            const origin = op.op === "add" ? op.origin : "agent";
-            return applyEntryOp(wm.constraints, op, "constraints", WORKING_MEMORY_LIMITS.constraints, (text) => ({
-                id: newId(),
-                text,
-                origin,
-            })).map((constraints) => ({ ...wm, constraints }));
-        }
-        case "hypothesis":
-            return applyEntryOp(wm.hypotheses, value, "hypotheses", WORKING_MEMORY_LIMITS.hypotheses, (text) => ({
-                id: newId(),
-                text,
-            })).map((hypotheses) => ({ ...wm, hypotheses }));
-        case "finding":
-            return applyFindingOp(wm.findings, value).map((findings) => ({ ...wm, findings }));
-    }
-    // Unreachable — `section` is exhaustively a `Section`.
-    return ok(wm);
+        return ok({ ...wm, goal: text });
+    },
+    constraint: (wm, op) => {
+        const origin = op.op === "add" ? op.origin : "agent";
+        return applyEntryOp(wm.constraints, op, "constraints", WORKING_MEMORY_LIMITS.constraints, (text) => ({
+            id: newId(),
+            text,
+            origin,
+        })).map((constraints) => ({ ...wm, constraints }));
+    },
+    hypothesis: (wm, op) => applyEntryOp(wm.hypotheses, op, "hypotheses", WORKING_MEMORY_LIMITS.hypotheses, (text) => ({
+        id: newId(),
+        text,
+    })).map((hypotheses) => ({ ...wm, hypotheses })),
+    finding: (wm, op) => applyFindingOp(wm.findings, op).map((findings) => ({ ...wm, findings })),
+};
+function applySectionUpdate(wm, section, value) {
+    return sectionWriters[section](wm, value);
 }
 /** Every finding, in insertion order, each carrying its run reference. */
 function flattenFindings(findings) {
@@ -283,33 +276,51 @@ export function createWorkingMemory(pool) {
         // The driver read is the only thing wrapped; `workingMemorySchema.parse`
         // runs in `.map` so a schema-validation throw propagates verbatim rather
         // than being miscaptured as a `DbError`.
-        return tryQuery("working-memory.load", () => pool.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId])).map(({ rows }) => (rows.length === 0 ? emptyWorkingMemory() : workingMemorySchema.parse(rows[0].data)));
+        return tryQuery("working-memory.load", () => pool.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId])).map(({ rows }) => {
+            const [stored] = rows;
+            return stored === undefined ? emptyWorkingMemory() : workingMemorySchema.parse(stored.data);
+        });
     }
-    function updateSection(analysisId, section, value) {
-        return withTransaction(pool, "working-memory.updateSection", (client) => 
-        // Serialize concurrent read-modify-write on this analysis — the lock
-        // covers the not-yet-existing-row case an `SELECT ... FOR UPDATE`
-        // would miss. Released automatically at COMMIT/ROLLBACK. The cap check
-        // runs under it too, so two racing adds cannot both slip past a full
-        // section.
-        tryQuery("working-memory.updateSection.lock", () => client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [analysisId]))
-            .andThen(() => tryQuery("working-memory.updateSection.read", () => client.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId])))
-            .map(({ rows }) => {
-            // Schema parse stays outside the driver wrapper — a validation throw
-            // propagates verbatim (and `withTransaction` still rolls back).
-            const current = rows.length === 0 ? emptyWorkingMemory() : workingMemorySchema.parse(rows[0].data);
-            return applySectionUpdate(current, section, value);
-        })
-            .andThen((amended) => 
-        // A rejection rides the transaction's ok channel: it is a decision, not a
-        // storage failure. The transaction commits having written nothing, and the
-        // rejection is lifted back into the error channel below.
-        amended.isErr()
-            ? okAsync(err(amended.error))
-            : tryMutation("working-memory.updateSection.upsert", () => client.query(`INSERT INTO cortex_working_memory (analysis_id, data, updated_at)
+    function updateSection(analysisId, section, value, callKey) {
+        const written = ok(undefined);
+        return withTransaction(pool, "working-memory.updateSection", (client) => {
+            // The key is read under the analysis lock, thus a second run of one call
+            // waits for the first and then finds its key.
+            const alreadyApplied = () => callKey === undefined
+                ? okAsync(false)
+                : tryQuery("working-memory.updateSection.appliedKey", () => client.query("SELECT 1 FROM cortex_applied_memory_edits WHERE call_key = $1", [callKey])).map(({ rows }) => rows.length > 0);
+            const recordKey = () => callKey === undefined
+                ? okAsync(undefined)
+                : tryMutation("working-memory.updateSection.recordKey", () => client.query("INSERT INTO cortex_applied_memory_edits (call_key, analysis_id) VALUES ($1, $2)", [callKey, analysisId])).map(() => undefined);
+            const amend = () => tryQuery("working-memory.updateSection.read", () => client.query("SELECT data FROM cortex_working_memory WHERE analysis_id = $1", [analysisId]))
+                .map(({ rows }) => {
+                // Schema parse stays outside the driver wrapper — a validation throw
+                // propagates verbatim (and `withTransaction` still rolls back).
+                const [stored] = rows;
+                const current = stored === undefined ? emptyWorkingMemory() : workingMemorySchema.parse(stored.data);
+                return applySectionUpdate(current, section, value);
+            })
+                .andThen((amended) => 
+            // A rejection rides the transaction's ok channel: it is a decision, not a
+            // storage failure. The transaction commits having written nothing, and the
+            // rejection is lifted back into the error channel below.
+            amended.isErr()
+                ? okAsync(err(amended.error))
+                : tryMutation("working-memory.updateSection.upsert", () => client.query(`INSERT INTO cortex_working_memory (analysis_id, data, updated_at)
                VALUES ($1, $2::jsonb, NOW())
                ON CONFLICT (analysis_id)
-               DO UPDATE SET data = EXCLUDED.data, updated_at = NOW()`, [analysisId, JSON.stringify(amended.value)])).map(() => ok(undefined)))).andThen((written) => written);
+               DO UPDATE SET data = EXCLUDED.data, updated_at = NOW()`, [analysisId, JSON.stringify(amended.value)]))
+                    .andThen(recordKey)
+                    .map(() => written));
+            // Serialize concurrent read-modify-write on this analysis — the lock
+            // covers the not-yet-existing-row case an `SELECT ... FOR UPDATE`
+            // would miss. Released automatically at COMMIT/ROLLBACK. The cap check
+            // runs under it too, so two racing adds cannot both slip past a full
+            // section.
+            return tryQuery("working-memory.updateSection.lock", () => client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [analysisId]))
+                .andThen(alreadyApplied)
+                .andThen((done) => (done ? okAsync(written) : amend()));
+        }).andThen((result) => result);
     }
     function render(analysisId) {
         return load(analysisId).map(renderWorkingMemory);

package/dist/prompts/briefing.d.ts

@@ -82,25 +82,25 @@ export declare function emptyStepMemory(): StepMemory;
  */
 export declare function renderMemory(memory: StepMemory): string;
 /** A file the script of the template reads. `path` names the slot that gives it, for example `{{counts_path}}`. */
-export interface TemplateBriefInput {
+export type TemplateBriefInput = {
     readonly name: string;
     readonly path: string;
     readonly description?: string;
-}
+};
 /** One plan setting bound to an adaptable slot of the template. */
-export interface TemplateBoundSetting {
+export type TemplateBoundSetting = {
     readonly name: string;
     readonly value: TemplateBindingValue;
     /** The source of the value (a doi or a document), or `plan` when the procedure names none. */
     readonly source: string;
-}
+};
 /**
  * The contract of the template a step renders, projected for the seed. The
  * parent fetches it at dispatch and binds the plan settings to it; the
  * section is what lets an agent that has never seen the template make one
  * valid render call.
  */
-export interface TemplateBrief {
+export type TemplateBrief = {
     /** The template reference of the plan step, with its version when the plan names one. */
     readonly ref: string;
     /** The version the service serves. Differs from the version of `ref` when the snapshot moved on. */
@@ -112,7 +112,7 @@ export interface TemplateBrief {
     readonly bound: readonly TemplateBoundSetting[];
     /** The plan settings no bound slot carries, one line each with the reason. */
     readonly unbound_settings: readonly string[];
-}
+};
 /**
  * The Template contract section. Only the adaptable slots render, bounded by
  * {@link MAX_TEMPLATE_SLOTS} and the description clamp, so a wide template
@@ -130,12 +130,12 @@ export declare function renderTemplateContract(brief: TemplateBrief | undefined)
  * every other path in the briefing is rooted with, thus one field serves the
  * workspace section and the orientation alike.
  */
-export interface WorkspaceFrame {
+export type WorkspaceFrame = {
     /** The analysis id. The sandbox mounts the read-only analysis tree at `/{analysisId}`. */
     readonly analysisId: string;
     /** In-sandbox working directory — this step's writable artifact directory, and its cwd. */
     readonly workingDir: string;
-}
+};
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export declare function analysisRootOf(frame: WorkspaceFrame): string;
 export declare function renderWorkspace(frame: WorkspaceFrame): string;
@@ -159,7 +159,7 @@ export declare function renderOrientation(profile: DataProfileResult | null | un
  * to the rest — an agent that needs more than the excerpt reads the summary at
  * `summaryPath` rather than having the whole document pushed into its context.
  */
-export interface UpstreamHandoff {
+export type UpstreamHandoff = {
     readonly stepId: string;
     readonly agentId: string;
     /** The dependency's step summary. Clamped to {@link UPSTREAM_SUMMARY_MAX_CHARS} here, not by the caller. */
@@ -170,10 +170,10 @@ export interface UpstreamHandoff {
     readonly outputDir: string;
     /** In-sandbox absolute paths of the artifacts the dependency registered. */
     readonly artifacts: readonly string[];
-}
+};
 export declare function renderUpstream(handoffs: readonly UpstreamHandoff[]): string;
 /** Everything one step's seed is composed from — all of it known at dispatch time. */
-export interface StepBriefing {
+export type StepBriefing = {
     readonly step: AnalysisStep;
     readonly workspace: WorkspaceFrame;
     /** The analysis's persisted data profile; `null` when never profiled or still pending. */
@@ -190,7 +190,7 @@ export interface StepBriefing {
      * service does not hold the template. Read only when `template` is absent.
      */
     readonly templateNotRetrieved?: string;
-}
+};
 /**
  * Compose the seed. Absent sections collapse out entirely — an independent step
  * with no profile and an empty memory yields exactly the task and workspace sections, byte-identical

package/dist/prompts/briefing.js

@@ -118,7 +118,7 @@ export function renderTask(step, contract = {}) {
     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) {

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

@@ -74,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. */

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>;