@inflexa-ai/harness 0.4.3 → 0.4.5

package/dist/app/synthesize-run.d.ts

@@ -41,7 +41,6 @@ export interface SynthesizeRunDeps {
 /** Optional fields for a progress update, mirroring the wire part. */
 export interface SynthesisProgressExtra {
     readonly delegationCount?: number;
-    readonly validationAttempts?: number;
     readonly reason?: string;
     readonly error?: string;
 }

package/dist/app/synthesize-run.js

@@ -57,12 +57,9 @@ export async function synthesizeRun(deps, params) {
             logger.warn("synthesis skipped — synthesizer reported a blocker", {
                 runId,
                 reason: result.reason,
-                validationRejections: result.validationRejections,
-                rejectedIssuePaths: result.rejectedIssuePaths,
             });
             await onProgress("skipped", "Synthesis skipped — run did not produce synthesizable content", {
                 reason: result.reason,
-                validationAttempts: result.validationRejections,
             });
             return { findings: [], synthesisStatus: "skipped_blocker", synthesisReason: result.reason };
         }

package/dist/contracts/chat-parts.d.ts

@@ -262,8 +262,6 @@ export interface SynthesisProgressPart {
     activity: string;
     /** Number of literature-reviewer delegations started so far. */
     delegationCount?: number;
-    /** Number of times the synthesizer's submit_synthesis call was rejected. */
-    validationAttempts?: number;
     /** Agent-provided reason — set when phase === "skipped". */
     reason?: string;
     /** Error message — set when phase === "failed". */

package/dist/contracts/schemas/chat-parts.d.ts

@@ -298,11 +298,11 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
         low: "low";
     }>;
     noveltyStatus: z.ZodEnum<{
+        expected: "expected";
         novel: "novel";
         confirmed: "confirmed";
         partially_confirmed: "partially_confirmed";
         contradicted: "contradicted";
-        expected: "expected";
     }>;
     literatureInterpretation: z.ZodString;
 }, z.core.$strip>;
@@ -330,11 +330,11 @@ export declare const RunSynthesisPartSchema: z.ZodObject<{
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
+            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
-            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
     }, z.core.$strip>>;
@@ -383,7 +383,6 @@ export declare const SynthesisProgressPartSchema: z.ZodObject<{
     }>;
     activity: z.ZodString;
     delegationCount: z.ZodOptional<z.ZodNumber>;
-    validationAttempts: z.ZodOptional<z.ZodNumber>;
     reason: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -589,11 +588,11 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
+            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
-            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
     }, z.core.$strip>>;
@@ -629,7 +628,6 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     }>;
     activity: z.ZodString;
     delegationCount: z.ZodOptional<z.ZodNumber>;
-    validationAttempts: z.ZodOptional<z.ZodNumber>;
     reason: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{

package/dist/contracts/schemas/chat-parts.js

@@ -243,7 +243,6 @@ export const SynthesisProgressPartSchema = z.object({
     phase: SynthesisPhaseSchema,
     activity: z.string(),
     delegationCount: z.number().int().nonnegative().optional(),
-    validationAttempts: z.number().int().nonnegative().optional(),
     reason: z.string().optional(),
     error: z.string().optional(),
 });

package/dist/execution/run-synthesis.d.ts

@@ -1,9 +1,14 @@
 /**
  * Run synthesizer — a single-shot agent loop driven through `runAgent`:
  *
+ *   - `validate_synthesis` — non-terminal: dry-run schema + semantic validation
+ *                            of a candidate in any shape. Never records.
  *   - `submit_synthesis`  — terminal: schema + semantic validation, captures
- *                            the outcome. Re-callable on rejection.
+ *                            the outcome. Re-callable; a later valid submission
+ *                            supersedes an earlier outcome (last-valid-wins).
  *   - `report_blocker`    — terminal: the run produced nothing synthesizable.
+ *                            Only records when no outcome exists yet, so a
+ *                            blocker can never clobber a real synthesis.
  *   - `literature_reviewer` — research sub-agent exposed as a tool. The tool
  *                            re-uses `createLiteratureReviewerTool`; the
  *                            sub-agent loop's brief is the only context handed
@@ -35,20 +40,6 @@ type SynthesizerOutcome = {
 interface OutcomeHolder {
     outcome: SynthesizerOutcome | null;
 }
-/**
- * Mutable cell the submit tool writes on every rejection from its semantic
- * re-validation — the stepId/theme-ref/PMID checks the arg schema cannot express.
- * A schema-malformed payload is rejected at the agent-loop boundary before the
- * tool runs, so it never reaches here; this counts the semantic-check give-up
- * that this synthesizer is prone to. Read after the loop to diagnose a blocker's
- * cause: zero here points to LLM misjudgment, repeated rejections to a defensive
- * give-up against the semantic checks. The deduped `issuePaths` name which fields
- * the model could not satisfy.
- */
-interface RejectionTelemetry {
-    rejections: number;
-    readonly issuePaths: Set<string>;
-}
 /**
  * Test-only — expose the inner-tool factory so unit tests can assert on
  * validation + outcome capture without driving the whole agent loop.
@@ -57,10 +48,10 @@ export declare function __buildInnerToolsForTest(args: {
     knownStepIds: ReadonlySet<string>;
     runId: string;
 }): {
+    validate: Tool;
     submit: Tool;
     blocker: Tool;
     holder: OutcomeHolder;
-    telemetry: RejectionTelemetry;
 };
 export interface GenerateRunSynthesisInput {
     readonly provider: ChatProvider;
@@ -82,12 +73,9 @@ export interface GenerateRunSynthesisInput {
 export type GenerateRunSynthesisResult = {
     kind: "synthesis";
     synthesis: RunSynthesis;
-    validationRejections: number;
 } | {
     kind: "skipped";
     reason: string;
-    validationRejections: number;
-    rejectedIssuePaths: readonly string[];
 };
 /**
  * Drive the synthesizer agent loop to a terminal outcome — either a

package/dist/execution/run-synthesis.js

@@ -1,9 +1,14 @@
 /**
  * Run synthesizer — a single-shot agent loop driven through `runAgent`:
  *
+ *   - `validate_synthesis` — non-terminal: dry-run schema + semantic validation
+ *                            of a candidate in any shape. Never records.
  *   - `submit_synthesis`  — terminal: schema + semantic validation, captures
- *                            the outcome. Re-callable on rejection.
+ *                            the outcome. Re-callable; a later valid submission
+ *                            supersedes an earlier outcome (last-valid-wins).
  *   - `report_blocker`    — terminal: the run produced nothing synthesizable.
+ *                            Only records when no outcome exists yet, so a
+ *                            blocker can never clobber a real synthesis.
  *   - `literature_reviewer` — research sub-agent exposed as a tool. The tool
  *                            re-uses `createLiteratureReviewerTool`; the
  *                            sub-agent loop's brief is the only context handed
@@ -23,7 +28,8 @@ import { join } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
-import { RunSynthesisSchema } from "../schemas/run-synthesis.js";
+import { hintForZodIssue } from "../lib/zod-issues.js";
+import { BiologicalThemeSchema, KeyReferenceSchema, RunSynthesisSchema, SynthesizedFindingSchema, } from "../schemas/run-synthesis.js";
 import { synthesisAgentPrompt } from "../prompts/synthesis-agent.js";
 import { composeSystemPrompt } from "../agents/system-prompt.js";
 import { runDir } from "../workspace/paths.js";
@@ -40,23 +46,37 @@ const AGENT_ID = "run-synthesizer";
  */
 const SYNTHESIZER_MAX_ITERATIONS = 25;
 // ── Validation ──────────────────────────────────────────────────────
-function zodIssuesToValidationIssues(error, rootPath = "synthesis") {
+function zodIssuesToValidationIssues(error, input, rootPath = "synthesis") {
     return error.issues.map((i) => ({
         path: [rootPath, ...i.path.map((p) => String(p))].join("."),
         code: "schema",
         message: i.message,
+        hint: hintForZodIssue(i, input),
     }));
 }
-function semanticCheck(synthesis, ctx) {
-    const issues = [];
-    if (synthesis.runId !== ctx.runId) {
-        issues.push({
+const PMID_PATTERN = /^\d+$/;
+// ── Semantic checks ─────────────────────────────────────────────────
+//
+// Each check takes only the fields it reads, never the whole synthesis. That is
+// what lets a candidate which failed whole-payload schema validation still be
+// checked: whichever fields parsed on their own get their checks run, and only
+// the checks whose inputs are genuinely missing are deferred. `semanticCheck`
+// composes them for the schema-valid path — it is the one definition of "all
+// semantic checks, in report order".
+function checkRunId(runId, ctx) {
+    if (runId === ctx.runId)
+        return [];
+    return [
+        {
             path: "synthesis.runId",
             code: "semantic",
             message: `runId must be "${ctx.runId}"`,
-        });
-    }
-    for (const [i, f] of synthesis.findings.entries()) {
+        },
+    ];
+}
+function checkFindingStepIds(findings, ctx) {
+    const issues = [];
+    for (const [i, f] of findings.entries()) {
         if (!ctx.knownStepIds.has(f.stepId)) {
             issues.push({
                 path: `synthesis.findings[${i}].stepId`,
@@ -66,8 +86,12 @@ function semanticCheck(synthesis, ctx) {
             });
         }
     }
-    const findingKeys = new Set(synthesis.findings.map((f) => `${f.stepId}::${f.title}`));
-    for (const [ti, t] of synthesis.themes.entries()) {
+    return issues;
+}
+function checkThemeReferences(themes, findings) {
+    const issues = [];
+    const findingKeys = new Set(findings.map((f) => `${f.stepId}::${f.title}`));
+    for (const [ti, t] of themes.entries()) {
         for (const [fi, ref] of t.findings.entries()) {
             if (!findingKeys.has(`${ref.stepId}::${ref.title}`)) {
                 issues.push({
@@ -78,8 +102,12 @@ function semanticCheck(synthesis, ctx) {
             }
         }
     }
-    const citedPmids = new Set(synthesis.findings.flatMap((f) => f.references.map((r) => r.pmid)));
-    for (const [i, r] of synthesis.keyReferences.entries()) {
+    return issues;
+}
+function checkKeyReferencesCited(keyReferences, findings) {
+    const issues = [];
+    const citedPmids = new Set(findings.flatMap((f) => f.references.map((r) => r.pmid)));
+    for (const [i, r] of keyReferences.entries()) {
         if (!citedPmids.has(r.pmid)) {
             issues.push({
                 path: `synthesis.keyReferences[${i}].pmid`,
@@ -89,10 +117,13 @@ function semanticCheck(synthesis, ctx) {
             });
         }
     }
-    const pmidRe = /^\d+$/;
-    for (const [fi, f] of synthesis.findings.entries()) {
+    return issues;
+}
+function checkFindingPmidFormat(findings) {
+    const issues = [];
+    for (const [fi, f] of findings.entries()) {
         for (const [ri, r] of f.references.entries()) {
-            if (!pmidRe.test(r.pmid)) {
+            if (!PMID_PATTERN.test(r.pmid)) {
                 issues.push({
                     path: `synthesis.findings[${fi}].references[${ri}].pmid`,
                     code: "semantic",
@@ -101,8 +132,12 @@ function semanticCheck(synthesis, ctx) {
             }
         }
     }
-    for (const [i, r] of synthesis.keyReferences.entries()) {
-        if (!pmidRe.test(r.pmid)) {
+    return issues;
+}
+function checkKeyReferencePmidFormat(keyReferences) {
+    const issues = [];
+    for (const [i, r] of keyReferences.entries()) {
+        if (!PMID_PATTERN.test(r.pmid)) {
             issues.push({
                 path: `synthesis.keyReferences[${i}].pmid`,
                 code: "semantic",
@@ -112,10 +147,91 @@ function semanticCheck(synthesis, ctx) {
     }
     return issues;
 }
+function semanticCheck(synthesis, ctx) {
+    return [
+        ...checkRunId(synthesis.runId, ctx),
+        ...checkFindingStepIds(synthesis.findings, ctx),
+        ...checkThemeReferences(synthesis.themes, synthesis.findings),
+        ...checkKeyReferencesCited(synthesis.keyReferences, synthesis.findings),
+        ...checkFindingPmidFormat(synthesis.findings),
+        ...checkKeyReferencePmidFormat(synthesis.keyReferences),
+    ];
+}
+function salvageInputs(candidate) {
+    const record = typeof candidate === "object" && candidate !== null ? candidate : {};
+    const runId = z.string().safeParse(record.runId);
+    const findings = z.array(SynthesizedFindingSchema).safeParse(record.findings);
+    const themes = z.array(BiologicalThemeSchema).safeParse(record.themes);
+    const keyReferences = z.array(KeyReferenceSchema).safeParse(record.keyReferences);
+    return {
+        runId: runId.success ? runId.data : undefined,
+        findings: findings.success ? findings.data : undefined,
+        themes: themes.success ? themes.data : undefined,
+        keyReferences: keyReferences.success ? keyReferences.data : undefined,
+    };
+}
+/**
+ * A short issue list must never read as "everything else is fine". When the
+ * payload failed schema validation and some checks could not run, the deferred
+ * ones are named back to the model as an issue of their own.
+ */
+function deferredChecksNotice(deferred) {
+    return {
+        path: "synthesis",
+        code: "semantic",
+        message: `This issue list is INCOMPLETE: ${deferred.length} semantic check(s) could not run because the fields ` +
+            `they read did not survive schema validation — ${deferred.join("; ")}.`,
+        hint: "Fix the schema issues above and call validate_synthesis again; the deferred checks will run then and may report further problems.",
+    };
+}
+/**
+ * Semantic checks over a candidate that failed `RunSynthesisSchema`. Every check
+ * whose own inputs parsed is run; the rest are reported as deferred.
+ */
+function salvagedSemanticCheck(candidate, ctx) {
+    const { runId, findings, themes, keyReferences } = salvageInputs(candidate);
+    const issues = [];
+    const deferred = [];
+    if (runId !== undefined)
+        issues.push(...checkRunId(runId, ctx));
+    else
+        deferred.push("runId matches the run");
+    if (findings !== undefined)
+        issues.push(...checkFindingStepIds(findings, ctx));
+    else
+        deferred.push("finding stepIds are present in the input summaries");
+    if (themes !== undefined && findings !== undefined)
+        issues.push(...checkThemeReferences(themes, findings));
+    else
+        deferred.push("theme references resolve to entries in findings[]");
+    if (keyReferences !== undefined && findings !== undefined)
+        issues.push(...checkKeyReferencesCited(keyReferences, findings));
+    else
+        deferred.push("keyReferences PMIDs are cited by some finding");
+    if (findings !== undefined)
+        issues.push(...checkFindingPmidFormat(findings));
+    else
+        deferred.push("finding reference PMIDs are numeric");
+    if (keyReferences !== undefined)
+        issues.push(...checkKeyReferencePmidFormat(keyReferences));
+    else
+        deferred.push("keyReferences PMIDs are numeric");
+    if (deferred.length > 0)
+        issues.push(deferredChecksNotice(deferred));
+    return issues;
+}
+/**
+ * Validate a candidate in one pass. A schema failure no longer hides the
+ * semantic problems behind it: structure issues come first, then every semantic
+ * check whose inputs survived, then an explicit note of what was deferred.
+ */
 function fullyValidate(candidate, ctx) {
     const parsed = RunSynthesisSchema.safeParse(candidate);
     if (!parsed.success) {
-        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error) };
+        return {
+            valid: false,
+            issues: [...zodIssuesToValidationIssues(parsed.error, candidate), ...salvagedSemanticCheck(candidate, ctx)],
+        };
     }
     const semanticIssues = semanticCheck(parsed.data, ctx);
     if (semanticIssues.length > 0) {
@@ -124,7 +240,37 @@ function fullyValidate(candidate, ctx) {
     return { valid: true, synthesis: parsed.data };
 }
 // ── Inner tools ─────────────────────────────────────────────────────
-function buildSubmitTool(holder, ctx, telemetry) {
+function buildValidateTool(ctx) {
+    return defineTool({
+        id: "validate_synthesis",
+        description: "Dry-run a candidate synthesis and get back everything that is wrong " +
+            "with it. Takes the synthesis in ANY shape: a malformed, partial, or " +
+            "wrong-typed candidate is REPORTED, not rejected. Returns " +
+            "{valid, issues[]} covering both schema problems (missing / " +
+            "wrong-typed fields) and the semantic checks a schema cannot express " +
+            "(unknown stepId refs, theme→finding refs, keyReferences PMIDs not " +
+            "cited by any finding, non-numeric PMIDs) in a SINGLE pass — a " +
+            "schema problem does not hide the semantic problems behind it. If a " +
+            "field is too malformed for a semantic check to read, that check is " +
+            "reported as deferred rather than silently skipped. The authoritative " +
+            "field-by-field synthesis schema is the arg schema of " +
+            "submit_synthesis — this tool deliberately does not restate it. " +
+            "Non-terminal: call as often as needed to iterate toward a clean " +
+            "synthesis, then submit_synthesis.",
+        // Deliberately permissive: a structurally-invalid candidate must reach
+        // `execute` so the model gets a structured {valid:false, issues} result —
+        // including semantic issues — instead of a bare Zod rejection at the loop's
+        // input boundary. `execute` re-parses against RunSynthesisSchema itself.
+        inputSchema: z.object({
+            synthesis: z.unknown().describe("The candidate synthesis, in any shape. Field-by-field schema: see submit_synthesis."),
+        }),
+        execute: async (input) => {
+            const result = fullyValidate(input.synthesis, ctx);
+            return ok(result.valid ? { valid: true, issues: [] } : { valid: false, issues: result.issues });
+        },
+    });
+}
+function buildSubmitTool(holder, ctx) {
     return defineTool({
         id: "submit_synthesis",
         description: "Submit the final synthesis. Re-validates the payload against the " +
@@ -133,29 +279,16 @@ function buildSubmitTool(holder, ctx, telemetry) {
             "success returns {accepted: true} — STOP after this. On rejection " +
             "returns {accepted: false, issues} — fix the specific fields at each " +
             "issue path and call again, or switch to report_blocker if the " +
-            "synthesis cannot be made valid.",
+            "synthesis cannot be made valid. A rejected submission leaves any " +
+            "already-accepted synthesis untouched; a later accepted submission " +
+            "supersedes an earlier one.",
         inputSchema: z.object({ synthesis: RunSynthesisSchema }),
         execute: async (input) => {
-            if (holder.outcome !== null) {
-                return ok({
-                    accepted: false,
-                    issues: [
-                        {
-                            path: "synthesis",
-                            code: "semantic",
-                            message: "A terminal outcome has already been recorded; submit_synthesis " + "can only be called once per invocation.",
-                        },
-                    ],
-                });
-            }
             const result = fullyValidate(input.synthesis, ctx);
             if (!result.valid) {
-                // Count each rejection reaching the tool (the terminal guard above
-                // is not one; a schema-malformed payload is rejected upstream by the
-                // loop before execute and never gets here).
-                telemetry.rejections += 1;
-                for (const issue of result.issues)
-                    telemetry.issuePaths.add(issue.path);
+                // A rejection is not terminal — submission is last-valid-wins, so this
+                // leaves any already-recorded outcome intact and the model may fix the
+                // cited paths and submit again.
                 return ok({ accepted: false, issues: result.issues });
             }
             holder.outcome = { kind: "submitted", synthesis: result.synthesis };
@@ -183,16 +316,15 @@ function buildBlockerTool(holder) {
  */
 export function __buildInnerToolsForTest(args) {
     const holder = { outcome: null };
-    const telemetry = { rejections: 0, issuePaths: new Set() };
     const ctx = {
         knownStepIds: args.knownStepIds,
         runId: args.runId,
     };
     return {
-        submit: buildSubmitTool(holder, ctx, telemetry),
+        validate: buildValidateTool(ctx),
+        submit: buildSubmitTool(holder, ctx),
         blocker: buildBlockerTool(holder),
         holder,
-        telemetry,
     };
 }
 /**
@@ -206,16 +338,16 @@ export async function generateRunSynthesis(input) {
     }
     const knownStepIds = new Set(input.summaries.map((s) => s.stepId));
     const holder = { outcome: null };
-    const telemetry = { rejections: 0, issuePaths: new Set() };
     const innerCtx = { knownStepIds, runId: input.runId };
     const reviewer = createLiteratureReviewerTool({
         provider: input.provider,
         model: input.model,
         bioKeys: input.bioKeys,
     });
-    const submitTool = buildSubmitTool(holder, innerCtx, telemetry);
+    const validateTool = buildValidateTool(innerCtx);
+    const submitTool = buildSubmitTool(holder, innerCtx);
     const blockerTool = buildBlockerTool(holder);
-    const tools = [submitTool, blockerTool, reviewer];
+    const tools = [validateTool, submitTool, blockerTool, reviewer];
     const agent = {
         id: AGENT_ID,
         systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
@@ -241,15 +373,10 @@ export async function generateRunSynthesis(input) {
     });
     const outcome = holder.outcome;
     if (outcome?.kind === "submitted") {
-        return { kind: "synthesis", synthesis: outcome.synthesis, validationRejections: telemetry.rejections };
+        return { kind: "synthesis", synthesis: outcome.synthesis };
     }
     if (outcome?.kind === "blocker") {
-        return {
-            kind: "skipped",
-            reason: outcome.reason,
-            validationRejections: telemetry.rejections,
-            rejectedIssuePaths: [...telemetry.issuePaths].sort(),
-        };
+        return { kind: "skipped", reason: outcome.reason };
     }
     if (signal.aborted) {
         throw new Error("Run synthesis was cancelled.");

package/dist/lib/zod-issues.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Diagnosis and repair of model-authored arguments that failed Zod validation.
+ *
+ * A Zod issue message is accurate but inert: "Invalid input: expected object,
+ * received string" tells a model what the schema wanted, not what it did wrong
+ * or how to change the next call. Two failure modes put a whole, well-formed
+ * JSON value behind that message:
+ *
+ *  - **Double encoding** — the model serialized a nested object or array with
+ *    `JSON.stringify` and passed the resulting string as the argument value.
+ *  - **Wrapper artifacts** — the JSON value arrived intact but with function-call
+ *    markup or a markdown fence stuck to it (`{…}</parameter>\n</invoke>`,
+ *    ` ```json {…}``` `). The payload is complete; only the wrapper makes it a
+ *    string.
+ *
+ * This module owns both halves of the response for the four model-facing
+ * validation sites (`loop/run-agent.ts`'s tool-input boundary,
+ * `execution/run-synthesis.ts`, `tools/research/generate-plan.ts`,
+ * `tools/iterate-report.ts`):
+ *
+ *  - `hintForZodIssue` — a **diagnostic only**. It parses nothing into the
+ *    caller's data; it distinguishes the two modes so the message the model
+ *    reads matches the mistake it actually made. When neither mode explains the
+ *    string it stays silent, because speculative advice to a model that is
+ *    already misdiagnosing is worse than no advice at all.
+ *  - `repairToolInput` — an **issue-guided** repair: only a path where the
+ *    schema wanted an `object` or `array` and found a string is even considered,
+ *    so a tool that legitimately declares a `z.string()` field is never touched.
+ *    It makes validation *reachable*; it never substitutes for it. The caller
+ *    re-runs the full schema over the repaired value, and the tool's own
+ *    semantic checks still run unchanged.
+ *
+ * Neither is used by `tools/lib/api-utils.ts`'s `summarizeZodIssues`, whose
+ * audience is a developer reading a log about a third-party API response shape —
+ * "pass the object directly" is meaningless advice for a payload no one here
+ * constructed.
+ *
+ * Detection walks `issue.path` into the raw input rather than reading the
+ * received type off the issue. Zod 4's `invalid_type` issue exposes `expected`
+ * but carries no `received` field — the received type appears only inside the
+ * human-readable `message`, which is version- and locale-dependent and must
+ * not be pattern-matched.
+ */
+import type { z } from "zod";
+/**
+ * A hint for a single Zod issue, or `undefined` when nothing actionable can be
+ * said. `input` is the raw value that failed validation — the same value handed
+ * to `safeParse` — because the issue alone does not carry the offending value.
+ *
+ * Fires only for an `invalid_type` issue wanting an `object` or an `array` whose
+ * path resolves to a string, and only when that string demonstrably *is* the
+ * expected value:
+ *
+ *  1. it parses in full as JSON of the expected type → double encoding, and
+ *  2. it parses only once a wrapper artifact is stripped → the value is intact
+ *     but surrounded by content that does not belong.
+ *
+ * Anything else — a plain string, a truncated fragment, a stray
+ * `<parameter name=…>` opener — yields `undefined`.
+ *
+ * A path that does not resolve — a mismatched shape, a pruned branch — yields
+ * `undefined` rather than throwing.
+ */
+export declare function hintForZodIssue(issue: z.core.$ZodIssue, input: unknown): string | undefined;
+/**
+ * Repair model-authored tool input whose JSON values arrived as strings behind a
+ * wrapper artifact, or double-encoded. Returns a **new** input value with the
+ * repairs applied, or `undefined` when nothing was repaired.
+ *
+ * The repair is guided entirely by `error`: a path is considered only when the
+ * schema reported an `invalid_type` there wanting an `object` or `array` and the
+ * value sitting at that path is a string. The parsed result is accepted only if
+ * its own type matches what the schema expected, so a string field that happens
+ * to hold JSON-looking text is never rewritten.
+ *
+ * The input object graph is never mutated: the repaired copy shares every
+ * untouched branch and clones only along the paths it patches. Repaired content
+ * is not re-examined — one pass, no recursion — and no input causes a throw.
+ */
+export declare function repairToolInput(input: unknown, error: z.ZodError): unknown | undefined;

package/dist/lib/zod-issues.js

@@ -0,0 +1,227 @@
+/**
+ * Diagnosis and repair of model-authored arguments that failed Zod validation.
+ *
+ * A Zod issue message is accurate but inert: "Invalid input: expected object,
+ * received string" tells a model what the schema wanted, not what it did wrong
+ * or how to change the next call. Two failure modes put a whole, well-formed
+ * JSON value behind that message:
+ *
+ *  - **Double encoding** — the model serialized a nested object or array with
+ *    `JSON.stringify` and passed the resulting string as the argument value.
+ *  - **Wrapper artifacts** — the JSON value arrived intact but with function-call
+ *    markup or a markdown fence stuck to it (`{…}</parameter>\n</invoke>`,
+ *    ` ```json {…}``` `). The payload is complete; only the wrapper makes it a
+ *    string.
+ *
+ * This module owns both halves of the response for the four model-facing
+ * validation sites (`loop/run-agent.ts`'s tool-input boundary,
+ * `execution/run-synthesis.ts`, `tools/research/generate-plan.ts`,
+ * `tools/iterate-report.ts`):
+ *
+ *  - `hintForZodIssue` — a **diagnostic only**. It parses nothing into the
+ *    caller's data; it distinguishes the two modes so the message the model
+ *    reads matches the mistake it actually made. When neither mode explains the
+ *    string it stays silent, because speculative advice to a model that is
+ *    already misdiagnosing is worse than no advice at all.
+ *  - `repairToolInput` — an **issue-guided** repair: only a path where the
+ *    schema wanted an `object` or `array` and found a string is even considered,
+ *    so a tool that legitimately declares a `z.string()` field is never touched.
+ *    It makes validation *reachable*; it never substitutes for it. The caller
+ *    re-runs the full schema over the repaired value, and the tool's own
+ *    semantic checks still run unchanged.
+ *
+ * Neither is used by `tools/lib/api-utils.ts`'s `summarizeZodIssues`, whose
+ * audience is a developer reading a log about a third-party API response shape —
+ * "pass the object directly" is meaningless advice for a payload no one here
+ * constructed.
+ *
+ * Detection walks `issue.path` into the raw input rather than reading the
+ * received type off the issue. Zod 4's `invalid_type` issue exposes `expected`
+ * but carries no `received` field — the received type appears only inside the
+ * human-readable `message`, which is version- and locale-dependent and must
+ * not be pattern-matched.
+ */
+/**
+ * Strings longer than this are neither parsed nor repaired. A real argument
+ * payload is tens of kilobytes; the ceiling exists so a pathological input
+ * cannot turn a failed validation into an expensive parse.
+ */
+const MAX_REPAIRABLE_STRING_LENGTH = 1_000_000;
+/** Longest run of offending wrapper text quoted back to the model in a hint. */
+const HINT_SNIPPET_LENGTH = 40;
+/** A trailing `</parameter>`, optionally followed by `</invoke>`. */
+const TRAILING_CALL_TAGS = /<\/parameter>\s*(?:<\/invoke>\s*)?$/;
+/**
+ * A hint for a single Zod issue, or `undefined` when nothing actionable can be
+ * said. `input` is the raw value that failed validation — the same value handed
+ * to `safeParse` — because the issue alone does not carry the offending value.
+ *
+ * Fires only for an `invalid_type` issue wanting an `object` or an `array` whose
+ * path resolves to a string, and only when that string demonstrably *is* the
+ * expected value:
+ *
+ *  1. it parses in full as JSON of the expected type → double encoding, and
+ *  2. it parses only once a wrapper artifact is stripped → the value is intact
+ *     but surrounded by content that does not belong.
+ *
+ * Anything else — a plain string, a truncated fragment, a stray
+ * `<parameter name=…>` opener — yields `undefined`.
+ *
+ * A path that does not resolve — a mismatched shape, a pruned branch — yields
+ * `undefined` rather than throwing.
+ */
+export function hintForZodIssue(issue, input) {
+    const expected = repairableExpectation(issue);
+    if (expected === undefined)
+        return undefined;
+    const value = resolvePath(input, issue.path);
+    if (typeof value !== "string" || value.length > MAX_REPAIRABLE_STRING_LENGTH)
+        return undefined;
+    if (parseAs(value, expected) !== undefined) {
+        return `This argument arrived as a JSON-encoded string. Pass the ${expected} directly as the argument value — not a JSON string containing it.`;
+    }
+    const { text, removed } = stripWrappers(value);
+    if (removed !== "" && parseAs(text, expected) !== undefined) {
+        return `This argument arrived with extra content wrapped around the JSON ${expected} (${quoteSnippet(removed)}). Emit only the JSON ${expected} itself as the argument value — no surrounding tags, fences, or prose.`;
+    }
+    return undefined;
+}
+/**
+ * Repair model-authored tool input whose JSON values arrived as strings behind a
+ * wrapper artifact, or double-encoded. Returns a **new** input value with the
+ * repairs applied, or `undefined` when nothing was repaired.
+ *
+ * The repair is guided entirely by `error`: a path is considered only when the
+ * schema reported an `invalid_type` there wanting an `object` or `array` and the
+ * value sitting at that path is a string. The parsed result is accepted only if
+ * its own type matches what the schema expected, so a string field that happens
+ * to hold JSON-looking text is never rewritten.
+ *
+ * The input object graph is never mutated: the repaired copy shares every
+ * untouched branch and clones only along the paths it patches. Repaired content
+ * is not re-examined — one pass, no recursion — and no input causes a throw.
+ */
+export function repairToolInput(input, error) {
+    try {
+        let repaired = input;
+        let didRepair = false;
+        for (const issue of error.issues) {
+            const expected = repairableExpectation(issue);
+            if (expected === undefined)
+                continue;
+            const value = resolvePath(repaired, issue.path);
+            if (typeof value !== "string" || value.length > MAX_REPAIRABLE_STRING_LENGTH)
+                continue;
+            const parsed = parseAs(value, expected) ?? parseAs(stripWrappers(value).text, expected);
+            if (parsed === undefined)
+                continue;
+            repaired = setAtPath(repaired, issue.path, parsed.value);
+            didRepair = true;
+        }
+        return didRepair ? repaired : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The `object`/`array` expectation of an `invalid_type` issue, if it has one. */
+function repairableExpectation(issue) {
+    if (issue.code !== "invalid_type")
+        return undefined;
+    if (issue.expected === "object")
+        return "object";
+    if (issue.expected === "array")
+        return "array";
+    return undefined;
+}
+/**
+ * Parse `raw` as JSON and accept it only when the result's own type matches
+ * `expected`. Boxed in a `{ value }` cell so a legitimately parsed `null` or
+ * `undefined` stays distinguishable from "did not parse" — a `null` never
+ * matches either expectation, but the cell keeps the caller's checks honest.
+ */
+function parseAs(raw, expected) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (expected === "array")
+        return Array.isArray(parsed) ? { value: parsed } : undefined;
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? { value: parsed } : undefined;
+}
+/**
+ * Strip the wrapper artifacts a model sticks to an otherwise complete JSON
+ * value: trailing function-call markup and a markdown code fence. `removed`
+ * collects what came off, for the hint to quote back; it is empty when the
+ * string carried no recognized wrapper.
+ *
+ * Deliberately narrow, mirroring `tools/research/generate-analogy-report.ts`'s
+ * `stripFence`: these two shapes and nothing else. Beyond that, no salvaging —
+ * a fragment with a *leading* `<parameter name=…>` opener is not a whole value
+ * with decoration on it, and pretending otherwise would invent content.
+ */
+function stripWrappers(raw) {
+    const removed = [];
+    let text = raw.trim();
+    const tags = TRAILING_CALL_TAGS.exec(text);
+    if (tags !== null) {
+        removed.push(tags[0].trim());
+        text = text.slice(0, tags.index).trim();
+    }
+    if (text.startsWith("```")) {
+        const open = /^```(?:json)?\s*\n/i.exec(text);
+        if (open !== null) {
+            removed.push(open[0].trim());
+            text = text.slice(open[0].length);
+        }
+        const close = /\n```\s*$/.exec(text);
+        if (close !== null) {
+            removed.push("```");
+            text = text.slice(0, close.index);
+        }
+    }
+    return { text: text.trim(), removed: removed.join(" ") };
+}
+/** Quote wrapper text back to the model, bounded so a hint stays a hint. */
+function quoteSnippet(removed) {
+    const snippet = removed.length > HINT_SNIPPET_LENGTH ? `${removed.slice(0, HINT_SNIPPET_LENGTH)}…` : removed;
+    return `found: ${JSON.stringify(snippet)}`;
+}
+/**
+ * Walk a Zod issue path into the raw input. Returns `undefined` for any key
+ * that cannot be traversed, which is indistinguishable from a genuine
+ * `undefined` at that path — acceptable here, since the caller only acts on a
+ * resolved `string`.
+ */
+function resolvePath(input, path) {
+    let current = input;
+    for (const key of path) {
+        if (current === null || (typeof current !== "object" && typeof current !== "function")) {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Return a copy of `root` with `value` at `path`, cloning only the containers
+ * along that path and sharing every other branch. `root` is left untouched.
+ */
+function setAtPath(root, path, value) {
+    if (path.length === 0)
+        return value;
+    const [key, ...rest] = path;
+    if (root === null || typeof root !== "object")
+        return root;
+    const container = root;
+    const child = setAtPath(container[key], rest, value);
+    if (Array.isArray(root)) {
+        const copy = [...root];
+        copy[key] = child;
+        return copy;
+    }
+    return { ...container, [key]: child };
+}

package/dist/loop/run-agent.js

@@ -1,4 +1,5 @@
 import { jsonSchema, tool as aiTool } from "ai";
+import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { classifyProviderError } from "../providers/errors.js";
 import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/prompt-cache.js";
 import { resultStep } from "./run-step.js";
@@ -153,11 +154,21 @@ async function dispatchTool(tu, toolsById, ctx, isFatalLoopError) {
         return errorResult(tu, `unknown tool: ${tu.toolName}`);
     }
     const parsed = tool.inputSchema.safeParse(tu.input);
-    if (!parsed.success) {
-        return errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error)}`);
-    }
+    if (parsed.success)
+        return execute(tu, tool, parsed.data, ctx, isFatalLoopError);
+    // A complete JSON argument can arrive as a string behind function-call
+    // markup or a code fence. Repair only makes the schema reachable — the
+    // repaired value is validated in full, and the tool's own semantic checks
+    // still run, so nothing here weakens validation.
+    const repairedInput = repairToolInput(tu.input, parsed.error);
+    const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
+    if (repaired?.success === true)
+        return execute(tu, tool, repaired.data, ctx, isFatalLoopError);
+    return errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`);
+}
+async function execute(tu, tool, input, ctx, isFatalLoopError) {
     try {
-        const output = await tool.execute(parsed.data, ctx);
+        const output = await tool.execute(input, ctx);
         if (output.isErr())
             return errorResult(tu, toolErrorContent(output.error));
         return successResult(tu, output.value);
@@ -209,11 +220,12 @@ export function finalText(messages) {
         .map((block) => block.text)
         .join("");
 }
-function formatZodIssues(error) {
+function formatZodIssues(error, input) {
     return error.issues
         .map((issue) => {
         const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-        return `${path}: ${issue.message}`;
+        const hint = hintForZodIssue(issue, input);
+        return hint === undefined ? `${path}: ${issue.message}` : `${path}: ${issue.message} — ${hint}`;
     })
         .join("; ");
 }

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 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";
+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### 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. Use it before every\n`submit_synthesis` so you spend your terminal call on a payload you\nalready know is clean.\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). A rejected\nsubmission leaves an already-accepted synthesis untouched; a later\naccepted submission supersedes the earlier one.\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 `validate_synthesis` on the draft. Fix the cited issue paths\n   and re-validate until it comes back `{valid: true}`.\n5. Call `submit_synthesis` with the validated payload. If it is still\n   rejected, fix the cited issue paths and call again. If unfixable,\n   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 (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- 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- Keep calling `submit_synthesis` after `accepted: true`. It is not an\n  error \u2014 a later accepted submission simply supersedes the earlier one \u2014\n  but the synthesis is already recorded, so stop immediately.\n- Use `submit_synthesis` as a validation probe. Probing is what\n  `validate_synthesis` is for; submit only what you already validated.\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- End the session without a terminal tool call. That is a failure mode.\n";

package/dist/prompts/synthesis-agent.js

@@ -61,11 +61,22 @@ Typical usage: 1-3 delegations per run. Multiple small focused briefs
 beat one giant one. 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. Use it before every
+\`submit_synthesis\` so you spend your terminal call on a payload you
+already know is clean.
+
 ### submit_synthesis (terminal — success path)
 Persist the synthesis. Re-validates 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).
+\`report_blocker\` if the synthesis cannot be made valid). A rejected
+submission leaves an already-accepted synthesis untouched; a later
+accepted submission supersedes the earlier one.
 
 ### report_blocker (terminal — cannot produce a synthesis)
 Call ONLY when the run produced no synthesizable content — every summary is
@@ -83,8 +94,11 @@ can always submit a synthesis (overview + conclusions) with an empty
    targeting novel findings, contradictions, and themes that need
    literature grounding.
 3. Draft the synthesis payload with an interpretive focus.
-4. Call \`submit_synthesis\`. If rejected, fix the cited issue paths
-   and call again. If unfixable, call \`report_blocker\`.
+4. Call \`validate_synthesis\` on the draft. Fix the cited issue paths
+   and re-validate until it comes back \`{valid: true}\`.
+5. Call \`submit_synthesis\` with the validated payload. If it is still
+   rejected, fix the cited issue paths and call again. If unfixable,
+   call \`report_blocker\`.
 
 ## Writing the Synthesis
 
@@ -123,7 +137,7 @@ why it matters:
 - "Target druggability not assessed — pathway importance does not imply
   tractability."
 
-## Cross-Field Invariants (enforced at submit_synthesis)
+## Cross-Field Invariants (reported by validate_synthesis, 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
@@ -197,6 +211,12 @@ Example:
   and submit directly, but state that clearly in the overview.)
 - Reference stepIds that aren't in the summaries, or theme-findings that
   aren't in \`findings[]\`.
-- Call \`submit_synthesis\` twice after \`accepted: true\`. Stop immediately.
+- Keep calling \`submit_synthesis\` after \`accepted: true\`. It is not an
+  error — a later accepted submission simply supersedes the earlier one —
+  but the synthesis is already recorded, so stop immediately.
+- Use \`submit_synthesis\` as a validation probe. Probing is what
+  \`validate_synthesis\` is for; submit only what you already validated.
+- Submit a placeholder or stub payload to "see what happens". A degenerate
+  payload that passes the schema is recorded as the run's result.
 - End the session without a terminal tool call. That is a failure mode.
 `;

package/dist/sandbox/docker-client.d.ts

@@ -44,7 +44,12 @@ export interface DockerClientConfig {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Host lib store; bind-mounted read-only at `/mnt/libs` when set. */
     libStorePath?: string;
-    /** Host ref store; bind-mounted read-only at `/mnt/refs` when set. */
+    /**
+     * Host ref store; bind-mounted read-only at `/mnt/refs`. Embedders pass the
+     * configured store location unconditionally — existence is (re-)checked at each
+     * sandbox creation, so a store installed mid-session is mounted into subsequent
+     * sandboxes without a runtime restart.
+     */
     refStorePath?: string;
     /**
      * Force the container platform (e.g. `linux/amd64`). Set by hosts that mount

package/dist/sandbox/docker-client.js

@@ -28,7 +28,7 @@
  * Either way the workload ends as uid 1000 with `no-new-privileges` and no
  * effective capabilities.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, lstatSync, statSync } from "node:fs";
 import { join } from "node:path";
 import Docker from "dockerode";
 import { ResultAsync, err, ok } from "neverthrow";
@@ -80,6 +80,30 @@ function libStoreUsable(libStorePath) {
     }
     return existsSync(join(current, "packages.txt")) && existsSync(join(current, "meta.json"));
 }
+/**
+ * Whether `refStorePath` is, right now, a real directory fit to be a bind authority.
+ * Deliberately shallow — it checks existence-as-a-directory only, never the store's
+ * interior: the harness knows nothing of the ref store's layout, and dataset
+ * completeness/receipts are the embedder's concern, so (unlike `libStoreUsable`, which
+ * validates harness-known `current` layout) there is nothing here to validate beyond
+ * "a directory is present."
+ *
+ * `lstatSync` (not `statSync`) does NOT follow symlinks, so a symlinked path is rejected
+ * even when it resolves to a directory: the bind authority must itself be the store
+ * directory, not an indirection that may later point elsewhere.
+ *
+ * Binding a missing source makes Docker auto-create a root-owned directory at the path —
+ * the same hazard `libStoreUsable` documents — which would also brick the embedder's
+ * later store install (its store tool cannot write into a root-owned dir).
+ */
+function refStoreUsable(refStorePath) {
+    try {
+        return lstatSync(refStorePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 async function pollHealth(fetchImpl, url, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     let lastErr;
@@ -187,9 +211,16 @@ export function createDockerSandboxOps(config) {
                 if (config.libStorePath && !libsMounted) {
                     logger.warn("lib store configured but `current` is missing or incomplete at sandbox creation — mounting no library store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, sandboxId });
                 }
+                // Re-checked here too, so a ref store installed after boot is mounted into
+                // the next sandbox. Unlike libs, a missing ref store is NOT warned: a missing
+                // lib store is a degradation (it was configured and working, then broke),
+                // whereas a missing ref store is the normal cold state — the user simply has
+                // not installed reference data yet — and warning on every create would be
+                // noise. A store that appears mid-session is picked up by the next create.
+                const refsMounted = !!config.refStorePath && refStoreUsable(config.refStorePath);
                 const plan = buildMountPlan(meta, {
                     libs: libsMounted,
-                    refs: !!config.refStorePath,
+                    refs: refsMounted,
                 });
                 const hostTreePath = config.resolveWorkspaceRoot(meta.analysisId);
                 // `stepWritePrefix` (not a raw `join`) so the RW bind source runs through
@@ -200,7 +231,7 @@ export function createDockerSandboxOps(config) {
                     `${hostTreePath}:${plan.readonlyTreePath}:ro`,
                     ...(plan.writableStepPath ? [`${hostStepPath}:${plan.writableStepPath}:rw`] : []),
                     ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
-                    ...(config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
+                    ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
                 ];
                 const createFailed = (status, cause) => ({
                     type: "container_create_failed",

package/dist/schemas/run-synthesis.d.ts

@@ -31,11 +31,11 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
         low: "low";
     }>;
     noveltyStatus: z.ZodEnum<{
+        expected: "expected";
         novel: "novel";
         confirmed: "confirmed";
         partially_confirmed: "partially_confirmed";
         contradicted: "contradicted";
-        expected: "expected";
     }>;
     literatureInterpretation: z.ZodString;
     references: z.ZodArray<z.ZodObject<{
@@ -78,6 +78,11 @@ export declare const BiologicalThemeSchema: z.ZodObject<{
     }, z.core.$strip>>;
     narrative: z.ZodString;
 }, z.core.$strip>;
+export declare const KeyReferenceSchema: z.ZodObject<{
+    pmid: z.ZodString;
+    citation: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
 export declare const RunSynthesisSchema: z.ZodObject<{
     runId: z.ZodString;
     overview: z.ZodString;
@@ -92,11 +97,11 @@ export declare const RunSynthesisSchema: z.ZodObject<{
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
+            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
-            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
         references: z.ZodArray<z.ZodObject<{
@@ -150,3 +155,4 @@ export type RunSynthesis = z.infer<typeof RunSynthesisSchema>;
 export type SynthesizedFinding = z.infer<typeof SynthesizedFindingSchema>;
 export type BiologicalTheme = z.infer<typeof BiologicalThemeSchema>;
 export type LiteratureReference = z.infer<typeof LiteratureReferenceSchema>;
+export type KeyReference = z.infer<typeof KeyReferenceSchema>;

package/dist/schemas/run-synthesis.js

@@ -91,6 +91,11 @@ export const BiologicalThemeSchema = z.object({
         .describe("Findings that contribute to this theme. Each entry must match an entry in findings[] by stepId + title."),
     narrative: z.string().describe("How these findings connect into a coherent biological story — 3-5 sentences connecting them, not restating them."),
 });
+export const KeyReferenceSchema = z.object({
+    pmid: z.string().describe("Numeric PubMed ID. Must already appear in at least one finding's references[]."),
+    citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
+    description: z.string().describe("What the paper establishes and why it is key to this run."),
+});
 export const RunSynthesisSchema = z.object({
     runId: z.string().describe("The run being synthesized. Must equal the runId given in the prompt."),
     overview: z
@@ -114,10 +119,6 @@ export const RunSynthesisSchema = z.object({
         .array(z.string())
         .describe("Concrete methodological and translational caveats — not generic disclaimers. " + "Each names what it affects and why it matters. Target 3-6."),
     keyReferences: z
-        .array(z.object({
-        pmid: z.string().describe("Numeric PubMed ID. Must already appear in at least one finding's references[]."),
-        citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
-        description: z.string().describe("What the paper establishes and why it is key to this run."),
-    }))
+        .array(KeyReferenceSchema)
         .describe("The 5-10 most important papers across all findings. Prioritize those that directly validate, contradict, or extend the findings — do not pad with background citations."),
 });

package/dist/tools/iterate-report.js

@@ -50,6 +50,7 @@ import { previewDir } from "../workspace/paths.js";
 import { runReportIteration } from "../execution/report-runner.js";
 import { formatBytes, stageReportAssets } from "./lib/report-preflight.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { hintForZodIssue } from "../lib/zod-issues.js";
 const REPORT_TOOL_ACCESS_TTL_SECONDS = 3600;
 const PREVIEW_META_FILE = "preview-meta.json";
 async function readPreviewMeta(metaPath) {
@@ -435,6 +436,7 @@ export function createReportSubmitTool(deps) {
                         issues: parsed.error.issues.map((i) => ({
                             path: i.path.join(".") || "(root)",
                             message: i.message,
+                            hint: hintForZodIssue(i, input.report),
                         })),
                         hint: "The `report` brief did not match the schema. Call `plan_report` for the full schema, fix the fields named in `issues`, and resubmit.",
                     });

package/dist/tools/research/generate-plan.js

@@ -41,6 +41,7 @@ import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.
 import { validatePlan } from "../../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
 import { unwrapOrThrow } from "../../lib/result.js";
+import { hintForZodIssue } from "../../lib/zod-issues.js";
 import { insertPlan, loadDataProfileStatus, loadPlan } from "../../state/index.js";
 // ── Tool-level config ──────────────────────────────────────────────
 /** Sub-agent identity for the planner — provenance only. */
@@ -201,11 +202,12 @@ async function persistPlan(plan, ctx, pool) {
     }
 }
 // ── Validation ──────────────────────────────────────────────────────
-function zodIssuesToValidationIssues(error, rootPath = "plan") {
+function zodIssuesToValidationIssues(error, input, rootPath = "plan") {
     return error.issues.map((i) => ({
         path: [rootPath, ...i.path.map((p) => String(p))].join("."),
         code: "schema",
         message: i.message,
+        hint: hintForZodIssue(i, input),
     }));
 }
 /**
@@ -215,7 +217,7 @@ function zodIssuesToValidationIssues(error, rootPath = "plan") {
 function fullyValidate(candidate, resourcePolicy) {
     const parsed = PlannerPlanSchema.safeParse(candidate);
     if (!parsed.success) {
-        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error) };
+        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, candidate) };
     }
     // Semantic checks operate on the AnalysisPlan shape — PlannerPlan omits
     // maxSteps, so inject the execution-time default to satisfy the validator.

package/package.json

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