@inflexa-ai/harness 0.4.1 → 0.4.3

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## CRITICAL \u2014 Read This First\n\n**You communicate results EXCLUSIVELY by calling tools. This is not optional.**\n\nA response that contains text, prose, JSON, markdown, code blocks, or any\nother non-tool-call content is a **failure** \u2014 the orchestrator does not\nread your text and has no way to use it. The only way a synthesis reaches\nthe user is via `submit_synthesis`. The only way a blocker reaches the\nuser is via `report_blocker`.\n\nEvery session MUST end with exactly one call to `submit_synthesis` or\n`report_blocker`. Do NOT respond with text before any tool call.\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 with access to bio-lookup tools (search_gene,\nsearch_pathway, lookup_go_term, search_interactions, pubmed,\nsearch_bgee_expression, get_impc_ko_profile). Delegate to it when you need\nevidence \u2014 you have no bio-lookup tools of your 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\nTypical usage: 1-3 delegations per run. Multiple small focused briefs\nbeat one giant one. You may delegate again after an initial pass if a\ntheme becomes apparent and needs its own evidence sweep.\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).\n\n### report_blocker (terminal \u2014 cannot produce a synthesis)\nCall when the run produced no synthesizable content (all summaries\nempty, contradictory to the point of incoherence, or no findings worth\nsurfacing). Pass a short reason. STOP after calling.\n\n## Canonical Flow\n\n1. Read the analytical narrative + all step summaries end-to-end.\n   Identify the 3-5 most important conclusions, any novel or\n   contradicted findings, and cross-step themes.\n2. Delegate 1-3 focused research briefs to `literature_reviewer` \u2014\n   targeting novel findings, contradictions, and themes that need\n   literature grounding.\n3. Draft the synthesis payload with an interpretive focus.\n4. Call `submit_synthesis`. If rejected, fix the cited issue paths\n   and call again. If unfixable, 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**`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\n(`get_impc_ko_profile`) for loss-of-function consequences and\ncross-species baseline expression (`search_bgee_expression`) for\ntissue-of-action context, when the literature reviewer's report includes\nthem.\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- Every `pmid` you write must come from a `literature_reviewer` response.\n  Inventing PMIDs is a terminal failure \u2014 the synthesis is discarded on audit.\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- Respond with plain text (even to explain your reasoning \u2014 nothing is read).\n- Invent PMIDs, citations, or gene facts. Only report what the reviewer returned.\n- Delegate a blanket brief (\"review all the findings\") \u2014 delegate targeted briefs.\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- Reference stepIds that aren't in the summaries, or theme-findings that\n  aren't in `findings[]`.\n- Call `submit_synthesis` twice after `accepted: true`. Stop immediately.\n- End the session without a terminal tool call. That is a failure mode.\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## CRITICAL \u2014 Read This First\n\n**You communicate results EXCLUSIVELY by calling tools. This is not optional.**\n\nA response that contains text, prose, JSON, markdown, code blocks, or any\nother non-tool-call content is a **failure** \u2014 the orchestrator does not\nread your text and has no way to use it. The only way a synthesis reaches\nthe user is via `submit_synthesis`. The only way a blocker reaches the\nuser is via `report_blocker`.\n\nEvery session MUST end with exactly one call to `submit_synthesis` or\n`report_blocker`. Do NOT respond with text before any tool call.\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 with access to bio-lookup tools (search_gene,\nsearch_pathway, lookup_go_term, search_interactions, pubmed,\nsearch_bgee_expression, get_impc_ko_profile). Delegate to it when you need\nevidence \u2014 you have no bio-lookup tools of your 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\nTypical usage: 1-3 delegations per run. Multiple small focused briefs\nbeat one giant one. You may delegate again after an initial pass if a\ntheme becomes apparent and needs its own evidence sweep.\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).\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. STOP after calling.\n\n## Canonical Flow\n\n1. Read the analytical narrative + all step summaries end-to-end.\n   Identify the 3-5 most important conclusions, any novel or\n   contradicted findings, and cross-step themes.\n2. Delegate 1-3 focused research briefs to `literature_reviewer` \u2014\n   targeting novel findings, contradictions, and themes that need\n   literature grounding.\n3. Draft the synthesis payload with an interpretive focus.\n4. Call `submit_synthesis`. If rejected, fix the cited issue paths\n   and call again. If unfixable, 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\n(`get_impc_ko_profile`) for loss-of-function consequences and\ncross-species baseline expression (`search_bgee_expression`) for\ntissue-of-action context, when the literature reviewer's report includes\nthem.\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- Every `pmid` you write must come from a `literature_reviewer` response.\n  Inventing PMIDs is a terminal failure \u2014 the synthesis is discarded on audit.\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- Respond with plain text (even to explain your reasoning \u2014 nothing is read).\n- Invent PMIDs, citations, or gene facts. Only report what the reviewer returned.\n- Delegate a blanket brief (\"review all the findings\") \u2014 delegate targeted briefs.\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 `report_blocker` because no finding seems worth surfacing.** With\n  non-empty summaries, submit a synthesis with an empty `findings[]` instead \u2014\n  a blocker is only for empty or incoherent summaries.\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- Reference stepIds that aren't in the summaries, or theme-findings that\n  aren't in `findings[]`.\n- Call `submit_synthesis` twice after `accepted: true`. Stop immediately.\n- End the session without a terminal tool call. That is a failure mode.\n";

package/dist/prompts/synthesis-agent.js

@@ -68,9 +68,11 @@ specific fields per issue path and call again, OR switch to
 \`report_blocker\` if the synthesis cannot be made valid).
 
 ### report_blocker (terminal — cannot produce a synthesis)
-Call when the run produced no synthesizable content (all summaries
-empty, contradictory to the point of incoherence, or no findings worth
-surfacing). Pass a short reason. STOP after calling.
+Call ONLY when the run produced no synthesizable content — every summary is
+empty, or the summaries are contradictory to the point of incoherence.
+"No findings worth surfacing" is NOT a blocker: with non-empty summaries you
+can always submit a synthesis (overview + conclusions) with an empty
+\`findings[]\`. Pass a short reason. STOP after calling.
 
 ## Canonical Flow
 
@@ -90,6 +92,12 @@ The \`submit_synthesis\` arg schema defines every field, its enum values,
 and its size expectations — read it, and follow it. This section is the
 craft the schema cannot carry.
 
+**An empty \`findings[]\` is a valid submission.** \`findings\` is SELECTIVE,
+not required — a run whose summaries yield nothing individually notable is
+still synthesized: write the \`overview\` and \`conclusions\` from the
+summaries and submit with \`findings: []\`. "Nothing worth a finding" is a
+reason to submit a lean synthesis, never a reason to \`report_blocker\`.
+
 **\`conclusions\` is the "Discussion" of the synthesis** — the part the
 reader will actually want to read. Be opinionated and interpretive, not
 descriptive. Say where computational predictions agree or disagree with
@@ -181,6 +189,9 @@ Example:
   predictive requires evidence of treatment x marker interaction,
   prognostic only requires association with outcome.
 - Force findings into themes. If findings don't converge, return fewer (or zero) themes.
+- **Call \`report_blocker\` because no finding seems worth surfacing.** With
+  non-empty summaries, submit a synthesis with an empty \`findings[]\` instead —
+  a blocker is only for empty or incoherent summaries.
 - Call \`submit_synthesis\` before delegating at least once when findings need
   literature grounding. (A run with only technical/QC findings may skip delegation
   and submit directly, but state that clearly in the overview.)

package/dist/provenance/collector.d.ts

@@ -86,7 +86,9 @@ export declare class ProvenanceCollector {
      * Called by sandbox exec provenance frame processing.
      *
      * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
-     * @param relativePath - Path relative to the mount root
+     * @param relativePath - Path relative to the mount root; or, for a frame
+     *   report naming somewhere outside the mount, the verbatim absolute path
+     *   (see `stripMountPrefix`)
      * @param hash - SHA-256 hash of the file content, or null if file no longer exists
      * @param context - Explicit classification context from the caller. When provided,
      *   the collector uses it directly instead of classifying from the path.
@@ -124,10 +126,11 @@ export declare class ProvenanceCollector {
      * Drop an input ref from lineage entirely — removes it from the tracked-input
      * map and from every record's `inputs` array (identity match, since the refs
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
-     * resolves to a directory (e.g. an `ls` / `list.files` of a mount): the
-     * inotify frame tracks the open, but a directory is not a content-attestable
-     * file artifact and must never reach registration. Mirrors the output-side
-     * non-file drop.
+     * is not a content-attestable file of this analysis: one resolving to a
+     * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
+     * tracks as an open), or one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root). Neither may reach registration.
+     * Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref: InputRef): void;
     /**

package/dist/provenance/collector.js

@@ -121,7 +121,9 @@ export class ProvenanceCollector {
      * Called by sandbox exec provenance frame processing.
      *
      * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
-     * @param relativePath - Path relative to the mount root
+     * @param relativePath - Path relative to the mount root; or, for a frame
+     *   report naming somewhere outside the mount, the verbatim absolute path
+     *   (see `stripMountPrefix`)
      * @param hash - SHA-256 hash of the file content, or null if file no longer exists
      * @param context - Explicit classification context from the caller. When provided,
      *   the collector uses it directly instead of classifying from the path.
@@ -133,7 +135,12 @@ export class ProvenanceCollector {
             return existing;
         // Use explicit context if provided, otherwise fall back to path classification
         const classification = context ?? classifyReadPath(relativePath, this.stepId, this.runId, this.dependsOn);
-        const fullPath = `${mountPath}/${relativePath}`;
+        // A still-absolute `relativePath` is a report the caller could not
+        // relativize — it names somewhere outside the mount. It rides verbatim:
+        // prepending the mount root would forge an in-tree name for a foreign
+        // path, and reconcile would then see phantom drift (a missing file,
+        // which fails the step) instead of an out-of-tree read (which it drops).
+        const fullPath = relativePath.startsWith("/") ? relativePath : `${mountPath}/${relativePath}`;
         // Resolve fileId for data-source inputs via materialized file metadata map
         let fileId;
         if (classification.source === "data" && this.inputFileIdMap) {
@@ -240,10 +247,11 @@ export class ProvenanceCollector {
      * Drop an input ref from lineage entirely — removes it from the tracked-input
      * map and from every record's `inputs` array (identity match, since the refs
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
-     * resolves to a directory (e.g. an `ls` / `list.files` of a mount): the
-     * inotify frame tracks the open, but a directory is not a content-attestable
-     * file artifact and must never reach registration. Mirrors the output-side
-     * non-file drop.
+     * is not a content-attestable file of this analysis: one resolving to a
+     * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
+     * tracks as an open), or one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root). Neither may reach registration.
+     * Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref) {
         for (const [key, val] of this.inputAccesses) {

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

@@ -14,7 +14,13 @@
  */
 import type { ProvenanceFrame } from "../sandbox/types.js";
 import { type ProvenanceCollector } from "./collector.js";
-/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+/**
+ * Strip the `/{resourceId}/` mount prefix from an absolute frame path.
+ * Separators doubled at the boundary collapse (`/{rid}//a` → `a`) so an
+ * in-mount name lands on its canonical relative form. A path not under the
+ * mount comes back unchanged — still absolute — and the collector carries it
+ * verbatim (see `trackInputAccess`).
+ */
 export declare function stripMountPrefix(mountRoot: string, absPath: string): string;
 export interface FeedExecFrameArgs {
     readonly collector: ProvenanceCollector;

package/dist/provenance/exec-frame.js

@@ -13,10 +13,16 @@
  * It never throws — provenance is best-effort and must not fail an exec.
  */
 import { classifyReadPath } from "./collector.js";
-/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+/**
+ * Strip the `/{resourceId}/` mount prefix from an absolute frame path.
+ * Separators doubled at the boundary collapse (`/{rid}//a` → `a`) so an
+ * in-mount name lands on its canonical relative form. A path not under the
+ * mount comes back unchanged — still absolute — and the collector carries it
+ * verbatim (see `trackInputAccess`).
+ */
 export function stripMountPrefix(mountRoot, absPath) {
     const prefix = mountRoot.endsWith("/") ? mountRoot : `${mountRoot}/`;
-    return absPath.startsWith(prefix) ? absPath.slice(prefix.length) : absPath;
+    return absPath.startsWith(prefix) ? absPath.slice(prefix.length).replace(/^\/+/, "") : absPath;
 }
 /**
  * Translate one exec's frame into a collector record. Per-command input

package/dist/providers/errors.d.ts

@@ -10,9 +10,12 @@
  * is required to disambiguate): the gateway emits `402` exclusively for
  * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
  * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all.
+ * network error with no status at all. A `401` is `auth`: the credential the
+ * host put behind the call is expired, revoked, or absent, and only a human
+ * re-authenticating fixes it — which is a different remedy from every other
+ * non-retryable 4xx, so it is a different kind.
  */
-export type ProviderErrorKind = "budget" | "tenant-blocked" | "provider";
+export type ProviderErrorKind = "auth" | "budget" | "tenant-blocked" | "provider";
 /**
  * The provider error value channel — a `DomainError`-conforming
  * discriminated union mirroring `ProviderErrorKind`. `chat` / `embed` return
@@ -23,6 +26,11 @@ export type ProviderErrorKind = "budget" | "tenant-blocked" | "provider";
  * step boundary.
  */
 export type ProviderError = {
+    readonly type: "auth";
+    readonly retryable: false;
+    readonly message: string;
+    readonly cause?: unknown;
+} | {
     readonly type: "budget";
     readonly retryable: false;
     readonly message: string;
@@ -72,6 +80,7 @@ export interface ProviderErrorClassification {
 /**
  * Classify a provider failure by origin.
  *
+ * - Provider `401` → `auth`, not retryable.
  * - Billing-gateway `402` → `budget`, not retryable.
  * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.

package/dist/providers/errors.js

@@ -10,7 +10,10 @@
  * is required to disambiguate): the gateway emits `402` exclusively for
  * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
  * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all.
+ * network error with no status at all. A `401` is `auth`: the credential the
+ * host put behind the call is expired, revoked, or absent, and only a human
+ * re-authenticating fixes it — which is a different remedy from every other
+ * non-retryable 4xx, so it is a different kind.
  */
 /**
  * Structural guard for an already-constructed `ProviderError` value. A
@@ -22,7 +25,9 @@ export function isProviderError(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const v = value;
-    return (v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") && typeof v.retryable === "boolean" && typeof v.message === "string";
+    return ((v.type === "auth" || v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") &&
+        typeof v.retryable === "boolean" &&
+        typeof v.message === "string");
 }
 /**
  * Turn a caught SDK throwable into a `ProviderError` value. Routes through
@@ -42,6 +47,14 @@ export function toProviderError(e, workload) {
         return e;
     const { kind, retryable } = classifyProviderError(e);
     const detail = e instanceof Error ? e.message : String(e);
+    if (kind === "auth") {
+        return {
+            type: "auth",
+            retryable: false,
+            message: `Provider rejected the credential for ${workload} — it is expired, revoked, or absent: ${detail}`,
+            cause: e,
+        };
+    }
     if (kind === "budget") {
         return {
             type: "budget",
@@ -109,6 +122,7 @@ function looksLikeConnectionError(err) {
 /**
  * Classify a provider failure by origin.
  *
+ * - Provider `401` → `auth`, not retryable.
  * - Billing-gateway `402` → `budget`, not retryable.
  * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.
@@ -116,6 +130,13 @@ function looksLikeConnectionError(err) {
  */
 export function classifyProviderError(e) {
     const status = extractStatus(e);
+    // `auth` is its own kind rather than a plain non-retryable 4xx because the
+    // remedy is categorically different: the request was well-formed and the
+    // credential behind it is not, so no amount of re-issuing or rephrasing
+    // helps — a human has to re-authenticate. Callers surface that; the generic
+    // 4xx branch below would tell them the request was wrong, which is false.
+    if (status === 401)
+        return { kind: "auth", retryable: false };
     if (status === 402)
         return { kind: "budget", retryable: false };
     if (status === 403)

package/dist/state/index.d.ts

@@ -12,7 +12,7 @@ export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis
 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)
-queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export type { InsertRunInput } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
@@ -23,7 +23,7 @@ export type { InsertPlanInput } 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";
-export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
+export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";
 export type { TargetAssessmentStatus, TargetAssessmentRow, TargetAssessmentError, InsertAssessmentInput, ListAssessmentsOptions, } from "./target-assessments.js";

package/dist/state/index.js

@@ -10,11 +10,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)
-queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+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 { 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, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
+export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/init.js

@@ -61,6 +61,10 @@ CREATE TABLE IF NOT EXISTS cortex_runs (
   started_at          TEXT NOT NULL,
   completed_at        TEXT,
   error               TEXT,
+  -- Run-level synthesis outcome. NULL means "unknown": a legacy row written
+  -- before these columns existed, or a run whose synthesis never recorded a result.
+  synthesis_status    TEXT,
+  synthesis_reason    TEXT,
   parts               JSONB,
   mandate_jti         TEXT, -- oss-core-managed-ok run-mandate ledger, nullable, OSS leaves null
   mandate_expires_at  TEXT -- oss-core-managed-ok run-mandate ledger, nullable, OSS leaves null
@@ -318,6 +322,8 @@ export async function initCortexState(pool, injected) {
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS parts JSONB",
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS mandate_jti TEXT", // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS mandate_expires_at TEXT", // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+                "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS synthesis_status TEXT",
+                "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS synthesis_reason TEXT",
                 "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS data_profile_result JSONB",
                 "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS billing_context JSONB",
                 // Sandbox reliability telemetry (from sandbox-reliability change on main).

package/dist/state/runs.d.ts

@@ -12,7 +12,7 @@
 import type { ResultAsync } from "neverthrow";
 import type { DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
-import type { CortexRunRow } from "./schema.js";
+import type { CortexRunRow, SynthesisStatus } from "./schema.js";
 export interface InsertRunInput {
     runId: string;
     analysisId: string;
@@ -67,3 +67,9 @@ export declare function queryRunsByThread(pool: Querier, analysisId: string, thr
  * The JWT itself is NOT persisted — it rides in DBOS workflow input.
  */
 export declare function setRunMandate(pool: Querier, runId: string, jti: string, expiresAt: string): ResultAsync<void, DbError>;
+/**
+ * Record the run-level synthesis outcome on the run ledger. `synthesisReason`
+ * carries operator-facing detail for a skipped/failed outcome; it stays null
+ * for the "produced" case.
+ */
+export declare function setRunSynthesisOutcome(pool: Querier, runId: string, synthesisStatus: SynthesisStatus, synthesisReason?: string | null): ResultAsync<void, DbError>;

package/dist/state/runs.js

@@ -80,7 +80,7 @@ export function queryActiveRun(pool, analysisId, planId) {
     return tryQuery("runs.queryActiveRun", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1
@@ -118,7 +118,7 @@ export function queryRun(pool, runId) {
     return tryQuery("runs.queryRun", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE run_id = $1`,
@@ -132,7 +132,7 @@ export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0 }
     return tryQuery("runs.queryRunsByAnalysis", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1
@@ -146,7 +146,7 @@ export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offs
     return tryQuery("runs.queryRunsByThread", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1 AND thread_id = $2
@@ -174,6 +174,21 @@ export function setRunMandate(pool, runId, jti, expiresAt) {
         });
     });
 }
+/**
+ * Record the run-level synthesis outcome on the run ledger. `synthesisReason`
+ * carries operator-facing detail for a skipped/failed outcome; it stays null
+ * for the "produced" case.
+ */
+export function setRunSynthesisOutcome(pool, runId, synthesisStatus, synthesisReason) {
+    return tryMutation("runs.setRunSynthesisOutcome", async () => {
+        await pool.query({
+            text: `UPDATE cortex_runs
+            SET synthesis_status = $1, synthesis_reason = $2
+            WHERE run_id = $3`,
+            values: [synthesisStatus, synthesisReason ?? null, runId],
+        });
+    });
+}
 function mapRunRow(row) {
     // JSONB is parsed by `pg` into native arrays/objects. Treat legacy TEXT
     // rows (if anything slipped through) as strings and parse them.
@@ -198,6 +213,8 @@ function mapRunRow(row) {
         startedAt: row.started_at,
         completedAt: row.completed_at ?? null,
         error: row.error ?? null,
+        synthesisStatus: row.synthesis_status ?? null,
+        synthesisReason: row.synthesis_reason ?? null,
         parts,
         mandateJti: row.mandate_jti ?? null, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
         mandateExpiresAt: row.mandate_expires_at ?? null, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)

package/dist/state/schema.d.ts

@@ -64,6 +64,13 @@ export declare const StepExecutionStatus: z.ZodEnum<{
     blocked: "blocked";
 }>;
 export type StepExecutionStatus = z.infer<typeof StepExecutionStatus>;
+export declare const SynthesisStatus: z.ZodEnum<{
+    failed: "failed";
+    produced: "produced";
+    skipped_no_summaries: "skipped_no_summaries";
+    skipped_blocker: "skipped_blocker";
+}>;
+export type SynthesisStatus = z.infer<typeof SynthesisStatus>;
 export declare const CortexRunRowSchema: z.ZodObject<{
     runId: z.ZodString;
     analysisId: z.ZodString;
@@ -80,6 +87,13 @@ export declare const CortexRunRowSchema: z.ZodObject<{
     startedAt: z.ZodString;
     completedAt: z.ZodNullable<z.ZodString>;
     error: z.ZodNullable<z.ZodString>;
+    synthesisStatus: z.ZodNullable<z.ZodEnum<{
+        failed: "failed";
+        produced: "produced";
+        skipped_no_summaries: "skipped_no_summaries";
+        skipped_blocker: "skipped_blocker";
+    }>>;
+    synthesisReason: z.ZodNullable<z.ZodString>;
     parts: z.ZodNullable<z.ZodArray<z.ZodAny>>;
     mandateJti: z.ZodNullable<z.ZodString>;
     mandateExpiresAt: z.ZodNullable<z.ZodString>;

package/dist/state/schema.js

@@ -35,6 +35,11 @@ export const ArtifactRowSchema = z.object({
 // ── Run & Step Execution Schemas ─────────────────────────────────────
 export const RunStatus = z.enum(["running", "completed", "partial", "failed", "canceled", "suspended_insufficient_funds"]);
 export const StepExecutionStatus = z.enum(["pending", "running", "completed", "failed", "skipped", "canceled", "blocked"]);
+// Run-level synthesis outcome, distinct from RunStatus: a run can reach
+// status="completed" while synthesis produced nothing. "produced" is the only
+// outcome that wrote a synthesis result; the two "skipped_*" variants and
+// "failed" record why none exists.
+export const SynthesisStatus = z.enum(["produced", "skipped_no_summaries", "skipped_blocker", "failed"]);
 export const CortexRunRowSchema = z.object({
     runId: z.string(),
     analysisId: z.string(),
@@ -44,6 +49,10 @@ export const CortexRunRowSchema = z.object({
     startedAt: z.string(),
     completedAt: z.string().nullable(),
     error: z.string().nullable(),
+    // NULL synthesisStatus means "unknown" — a legacy row, or a run whose
+    // synthesis never recorded an outcome.
+    synthesisStatus: SynthesisStatus.nullable(),
+    synthesisReason: z.string().nullable(),
     parts: z.array(z.any()).nullable(),
     mandateJti: z.string().nullable(), // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
     mandateExpiresAt: z.string().nullable(), // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)

package/dist/tools/research/inspect-run.d.ts

@@ -9,8 +9,8 @@
  * conversation thread on completion. The retired `run-result-writer` push
  * payload (run status, step summaries, run synthesis, artifact paths) is
  * surfaced here on demand: the run row + step `summaryPath` references +
- * the `synthesisPath` for completed runs let the conversation agent
- * `read_file` the artefacts it needs.
+ * the `synthesisPath` for runs whose synthesis was produced let the
+ * conversation agent `read_file` the artefacts it needs.
  */
 import type { Pool } from "pg";
 import type { CortexRunRow } from "../../state/schema.js";
@@ -39,6 +39,7 @@ type InspectRunOutput = {
 };
 declare function formatRun(r: CortexRunRow, verbose: boolean): {
     error?: string | null | undefined;
+    synthesisReason?: string | undefined;
     runId: string;
     workflowName: string;
     status: "running" | "completed" | "failed" | "partial" | "canceled" | "suspended_insufficient_funds";
@@ -46,6 +47,7 @@ declare function formatRun(r: CortexRunRow, verbose: boolean): {
     completedAt: string | null;
     planId: string | null;
     synthesisPath: string | null;
+    synthesisStatus: "failed" | "produced" | "skipped_no_summaries" | "skipped_blocker" | null;
 };
 export declare function createInspectRunTool(pool: Pool): import("../define-tool.js").Tool<{
     runId?: string | undefined;

package/dist/tools/research/inspect-run.js

@@ -9,8 +9,8 @@
  * conversation thread on completion. The retired `run-result-writer` push
  * payload (run status, step summaries, run synthesis, artifact paths) is
  * surfaced here on demand: the run row + step `summaryPath` references +
- * the `synthesisPath` for completed runs let the conversation agent
- * `read_file` the artefacts it needs.
+ * the `synthesisPath` for runs whose synthesis was produced let the
+ * conversation agent `read_file` the artefacts it needs.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
@@ -26,7 +26,15 @@ function formatRun(r, verbose) {
         startedAt: r.startedAt,
         completedAt: r.completedAt,
         planId: r.planId,
-        synthesisPath: r.status === "completed" ? `runs/${r.runId}/synthesis.json` : null,
+        // synthesis.json is written only when synthesis actually produced a
+        // result; a skipped/failed synthesis leaves no file, so pointing at a
+        // path would send the agent to a stale or absent artifact. The recorded
+        // outcome — surfaced as synthesisStatus (and synthesisReason when set) —
+        // lets a consumer tell "produced" from "skipped/failed/unknown" without
+        // reading a file.
+        synthesisPath: r.synthesisStatus === "produced" ? `runs/${r.runId}/synthesis.json` : null,
+        synthesisStatus: r.synthesisStatus,
+        ...(r.synthesisReason !== null ? { synthesisReason: r.synthesisReason } : {}),
         ...(verbose ? { error: r.error } : {}),
     };
 }
@@ -35,7 +43,7 @@ export function createInspectRunTool(pool) {
         id: "inspect_run",
         description: "Inspect workflow runs for this analysis. " +
             "Without a runId: lists all runs. " +
-            "With a runId: returns step-level details with paths to summary.md (and synthesis.json on completed runs). " +
+            "With a runId: returns step-level details with paths to summary.md, plus each run's synthesisStatus and a synthesisPath to synthesis.json only when synthesis was produced. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry. " +
             "Read summary.md or synthesis.json for findings, or use workspace search with type:summary or type:synthesis.",
         inputSchema: z.object({

package/dist/workflows/execute-analysis.d.ts

@@ -58,6 +58,7 @@ import type { MachineBudget, ResourceSpec } from "../config/resource-limits.js";
 import type { RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { Logger } from "../lib/logger.js";
+import type { SynthesisStatus } from "../state/index.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
@@ -297,6 +298,8 @@ export declare function synthesizeFindings(args: {
     deps: ExecuteAnalysisDeps;
 }): Promise<{
     findings: readonly RunFinding[];
+    synthesisStatus: Exclude<SynthesisStatus, "failed">;
+    synthesisReason: string | null;
 }>;
 /**
  * Register the executeAnalysis parent workflow with DBOS. Caller is