@inflexa-ai/harness 0.1.1 → 0.2.0

package/dist/tools/sandbox/report-blocker.d.ts

@@ -1,14 +1,19 @@
 /**
- * `report_blocker` — a step agent's honest exit when it cannot fulfil its
- * step (see the harness-sandbox-agents spec). There is no `submit`/`done` tool: a step's deliverable is
- * its persisted files, so a clean end-of-turn after writing them is the
- * implicit success. Calling `report_blocker` is the alternative to
- * improvising an inline result the harness would launder into a green run.
+ * `report_blocker` — an agent's honest exit when it cannot fulfil the loop it
+ * is driving (see the harness-sandbox-agents spec). There is no `submit`/`done`
+ * tool on a sandbox step: a step's deliverable is its persisted files, so a
+ * clean end-of-turn after writing them is the implicit success. Calling
+ * `report_blocker` is the alternative to improvising an inline result the
+ * harness would launder into a green run.
  *
- * Mirrors the synthesizer's blocker (`execution/run-synthesis.ts`): the
- * workflow body owns a per-run `BlockerHolder` and reads `holder.outcome`
- * after `runAgent`. The tool only records the reason and tells the agent to
- * stop — the body decides the terminal status.
+ * This module is the canonical home of the tool. Three loops offer it — the
+ * sandbox step agent, the planner (`tools/research/generate-plan.ts`) and the
+ * run synthesizer (`execution/run-synthesis.ts`) — and all three share one id,
+ * one input schema and one terminal contract via `createReportBlockerToolFor`.
+ * What differs per loop is only what a blocker *means* there, so each call site
+ * injects its own `blockedWhen` prose and its own capture closure. The tool
+ * records the reason and tells the agent to stop; the driving body reads its
+ * own outcome cell after the loop and decides the terminal status.
  */
 import { type Tool } from "../define-tool.js";
 export interface BlockerOutcome {
@@ -20,4 +25,29 @@ export interface BlockerHolder {
     outcome: BlockerOutcome | null;
 }
 export declare function createBlockerHolder(): BlockerHolder;
+export interface ReportBlockerDeps {
+    /**
+     * The calling loop's blocker-capture side effect — writes the outcome into
+     * whatever cell that body reads after its loop. Invoked on every call; the
+     * closure owns the first-call-wins guard, because only the call site knows
+     * what else may already have terminated its loop.
+     */
+    readonly record: (outcome: BlockerOutcome) => void;
+    /**
+     * What a blocker means in THIS loop: which loop the call ends and the
+     * conditions that warrant it. Composed into the shared terminal contract,
+     * so a description can never promise a loop this instance does not end.
+     */
+    readonly blockedWhen: string;
+}
+/**
+ * Build the `report_blocker` tool for one loop. The id, the input schema and
+ * the terminal contract ("pass a reason, then stop") are fixed here; the call
+ * site supplies only the per-loop meaning and the capture closure.
+ */
+export declare function createReportBlockerToolFor(deps: ReportBlockerDeps): Tool;
+/**
+ * The sandbox step agent's `report_blocker`, bound to the step body's holder.
+ * A blocker here ends the step with no deliverables and a blocked reason.
+ */
 export declare function createReportBlockerTool(holder: BlockerHolder): Tool;

package/dist/tools/sandbox/report-blocker.js

@@ -1,14 +1,19 @@
 /**
- * `report_blocker` — a step agent's honest exit when it cannot fulfil its
- * step (see the harness-sandbox-agents spec). There is no `submit`/`done` tool: a step's deliverable is
- * its persisted files, so a clean end-of-turn after writing them is the
- * implicit success. Calling `report_blocker` is the alternative to
- * improvising an inline result the harness would launder into a green run.
+ * `report_blocker` — an agent's honest exit when it cannot fulfil the loop it
+ * is driving (see the harness-sandbox-agents spec). There is no `submit`/`done`
+ * tool on a sandbox step: a step's deliverable is its persisted files, so a
+ * clean end-of-turn after writing them is the implicit success. Calling
+ * `report_blocker` is the alternative to improvising an inline result the
+ * harness would launder into a green run.
  *
- * Mirrors the synthesizer's blocker (`execution/run-synthesis.ts`): the
- * workflow body owns a per-run `BlockerHolder` and reads `holder.outcome`
- * after `runAgent`. The tool only records the reason and tells the agent to
- * stop — the body decides the terminal status.
+ * This module is the canonical home of the tool. Three loops offer it — the
+ * sandbox step agent, the planner (`tools/research/generate-plan.ts`) and the
+ * run synthesizer (`execution/run-synthesis.ts`) — and all three share one id,
+ * one input schema and one terminal contract via `createReportBlockerToolFor`.
+ * What differs per loop is only what a blocker *means* there, so each call site
+ * injects its own `blockedWhen` prose and its own capture closure. The tool
+ * records the reason and tells the agent to stop; the driving body reads its
+ * own outcome cell after the loop and decides the terminal status.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
@@ -16,20 +21,20 @@ import { defineTool } from "../define-tool.js";
 export function createBlockerHolder() {
     return { outcome: null };
 }
-export function createReportBlockerTool(holder) {
+/** The one input every `report_blocker` takes, wherever it is offered. */
+const ReportBlockerInputSchema = z.object({ reason: z.string().min(1) });
+/**
+ * Build the `report_blocker` tool for one loop. The id, the input schema and
+ * the terminal contract ("pass a reason, then stop") are fixed here; the call
+ * site supplies only the per-loop meaning and the capture closure.
+ */
+export function createReportBlockerToolFor(deps) {
     return defineTool({
         id: "report_blocker",
-        description: "Terminal. Call this when you cannot fulfil the step — required inputs " +
-            "are missing or unreadable, the requested analysis is infeasible with " +
-            "the available data/packages, or you cannot produce the persisted " +
-            "deliverables (scripts, output files, figures). Pass a clear reason. Do " +
-            "NOT improvise an inline result and narrate it; if you cannot persist " +
-            "real output files, report a blocker. Stop after calling.",
-        inputSchema: z.object({ reason: z.string().min(1) }),
+        description: `Terminal. ${deps.blockedWhen} Pass a clear reason. Stop immediately after calling — take no further actions.`,
+        inputSchema: ReportBlockerInputSchema,
         execute: async (input) => {
-            if (holder.outcome === null) {
-                holder.outcome = { kind: "blocker", reason: input.reason };
-            }
+            deps.record({ kind: "blocker", reason: input.reason });
             return ok({
                 recorded: true,
                 message: "Blocker recorded. You are done — stop now and do not take further actions.",
@@ -37,3 +42,21 @@ export function createReportBlockerTool(holder) {
         },
     });
 }
+/**
+ * The sandbox step agent's `report_blocker`, bound to the step body's holder.
+ * A blocker here ends the step with no deliverables and a blocked reason.
+ */
+export function createReportBlockerTool(holder) {
+    return createReportBlockerToolFor({
+        record: (outcome) => {
+            if (holder.outcome === null)
+                holder.outcome = outcome;
+        },
+        blockedWhen: "Ends this analysis step with no deliverables. Call it when you cannot " +
+            "fulfil the step — required inputs are missing or unreadable, the " +
+            "requested analysis is infeasible with the available data/packages, or " +
+            "you cannot produce the persisted deliverables (scripts, output files, " +
+            "figures). Do NOT improvise an inline result and narrate it: if you " +
+            "cannot persist real output files, report a blocker.",
+    });
+}

package/dist/tools/workspace/read-file.js

@@ -19,8 +19,7 @@ const ReadFileInputSchema = z.object({
         .min(1)
         .describe("Workspace path. Relative paths resolve against your working directory; " +
         "an absolute '/<analysisId>/...' path is resolved against the analysis " +
-        "root (use absolute to read input data, the data profile, or other " +
-        "steps' outputs)."),
+        "root (use absolute to read input data or other steps' outputs)."),
     headLines: z
         .number()
         .int()
@@ -28,7 +27,7 @@ const ReadFileInputSchema = z.object({
         .max(10_000)
         .optional()
         .describe("Read only the first N lines (head). Use for inspecting CSV/TSV " +
-        "headers, profile summaries, or the top of any large file. Mutually " +
+        "headers, step summaries, or the top of any large file. Mutually " +
         "exclusive with tailLines."),
     tailLines: z
         .number()
@@ -42,8 +41,8 @@ export function createReadFileTool(fs, workingDir) {
     return defineTool({
         id: "read_file",
         description: "Read a workspace file: input data, prior-run outputs, current-run " +
-            "outputs, step summaries, run syntheses, or the data profile. Returns " +
-            "the file content as UTF-8 text. Output is capped at " +
+            "outputs, step summaries, or run syntheses. Returns the file content " +
+            "as UTF-8 text. Output is capped at " +
             `${DEFAULT_MAX_BYTES} bytes; pass headLines or tailLines to read a ` +
             "specific window of a large file (typical for bio CSV/TSV/log files). " +
             "Oversize reads come back truncated with a marker. Missing paths and " +

package/dist/tools/workspace/run-exec.d.ts

@@ -1,10 +1,10 @@
 /**
- * Internal helper used by the three mutate tools to drive one sandbox exec
+ * Internal helper used by dependency-bearing tools to drive one sandbox exec
  * through the `SandboxClient`. Centralises the submit/await pair, exec-id
  * derivation, and intermediate-event forwarding so all three tools share
- * one chokepoint — the contract `execute_command` makes structural is that
- * `write_file` / `edit_file` are layered on top of it, not parallel side
- * paths into sandbox-server.
+ * one chokepoint. `write_file` / `edit_file` are layered on the workspace
+ * mutator and environment introspection tools such as `list_available_refs`
+ * use this same replay-safe submit/await path rather than a parallel protocol.
  *
  * Not a registered tool — `defineTool` is called by the user-facing tools
  * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.

package/dist/tools/workspace/run-exec.js

@@ -1,10 +1,10 @@
 /**
- * Internal helper used by the three mutate tools to drive one sandbox exec
+ * Internal helper used by dependency-bearing tools to drive one sandbox exec
  * through the `SandboxClient`. Centralises the submit/await pair, exec-id
  * derivation, and intermediate-event forwarding so all three tools share
- * one chokepoint — the contract `execute_command` makes structural is that
- * `write_file` / `edit_file` are layered on top of it, not parallel side
- * paths into sandbox-server.
+ * one chokepoint. `write_file` / `edit_file` are layered on the workspace
+ * mutator and environment introspection tools such as `list_available_refs`
+ * use this same replay-safe submit/await path rather than a parallel protocol.
  *
  * Not a registered tool — `defineTool` is called by the user-facing tools
  * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.

package/dist/tools/workspace/show-file.js

@@ -20,19 +20,23 @@ const ShowFileInputSchema = z.object({
     title: z.string().optional().describe("Group heading shown above the card or gallery"),
     files: z
         .array(z.object({
-        path: z.string().describe("Analysis-rooted file path (e.g., 'runs/run-abc/step-1/figures/volcano.png')"),
+        path: z.string().describe("Analysis-rooted file path — no leading slash, no `..` (e.g., 'runs/run-abc/step-1/figures/volcano.png')"),
         caption: z.string().optional().describe("One-sentence context rendered beside this file"),
     }))
         .min(1)
         .max(MAX_FILES)
-        .describe(`1 to ${MAX_FILES} files; multiple files render as a gallery`),
+        .describe(`The related set of files to show together, 1 to ${MAX_FILES} per call; multiple render as ONE gallery card. Pass a related set in a single call — do not make one call per figure.`),
 });
 export const showFileTool = defineTool({
     id: "show_file",
-    description: "Display one or more existing analysis artifacts (images, CSVs, PDFs, notebooks, logs) in chat by path. " +
-        "Paths must be analysis-rooted (no leading slash, no `..`). Up to 10 files per call — multiple render as a gallery. " +
-        "Do NOT read a file and paste its bytes elsewhere; this tool references the file directly. " +
-        "File content is fetched when the user views the card — you do not need to provide it.",
+    description: "Display EXISTING analysis artifacts in chat by path — images, CSVs, PDFs, notebooks, logs. " +
+        "The card references the file directly and its content is fetched when the user views it: you never read, " +
+        "inline, or paste the bytes. Pick this tool by what you are referencing, not by how the output looks: " +
+        "NOT for content you synthesized (a chart, a table, a snippet you invented — use `show_user`), NOT for a stored plan (`show_plan`). " +
+        "Paths are analysis-rooted (no leading slash, no `..`); discover them with `workspace_search` or `list_files`. " +
+        "Up to 10 files per call — pass a related set in ONE call and they render as a gallery, rather than one call per figure. " +
+        "Cards render in call order, so to interleave figures with prose alternate `show_user(markdown)` and `show_file` calls " +
+        "(markdown image syntax pointing at a workspace file does NOT render — this tool is the only way to show one).",
     inputSchema: ShowFileInputSchema,
     execute: async (input, ctx) => {
         const card = buildFileReferenceCardData(input);

package/dist/tools/workspace/show-plan.js

@@ -18,13 +18,19 @@ const PLAN_ID_REGEX = /^pln-[a-f0-9]{8}$/;
 export function createShowPlanTool(pool) {
     return defineTool({
         id: "show_plan",
-        description: "Display a previously generated plan in chat by its planId. " +
-            "Use when the user asks to see a plan again, or to reference a historical plan. " +
-            "Get planIds from `inspect-run` (each run carries its planId) or `generatePlan` (newly created). " +
-            "The plan content is embedded in the chat part so the UI renders it directly.",
+        description: "Display a STORED plan in chat by its planId. The plan is loaded from storage and embedded in the card, " +
+            "so the UI renders it directly. Use it to present the plan `generate_plan` just produced, and when the user " +
+            "asks to see an earlier plan again. " +
+            "Pick this tool by what you are referencing, not by how the output looks: " +
+            "NOT for a plan you are drafting in conversation (that is `generate_plan`), NOT for other synthesized content " +
+            "(`show_user`), NOT for analysis files (`show_file`). Never re-type a plan's steps into a `show_user` markdown " +
+            "card — that renders a second, divergent copy of the same plan.",
         inputSchema: z.object({
-            planId: z.string().regex(PLAN_ID_REGEX, "planId must match pln-<8hex>").describe("Plan ID from generatePlan or inspect-run"),
-            title: z.string().optional().describe("Optional display heading"),
+            planId: z
+                .string()
+                .regex(PLAN_ID_REGEX, "planId must match pln-<8hex>")
+                .describe("Plan ID (`pln-<8hex>`) from `generate_plan` (newly created) or `inspect_run` (each run carries the planId it ran)"),
+            title: z.string().optional().describe("Optional card heading; defaults to the plan's own title"),
         }),
         execute: async ({ planId, title }, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;

package/dist/tools/workspace/workspace-search.d.ts

@@ -15,7 +15,7 @@ import type { EmbeddingProvider } from "../../providers/types.js";
 export declare function createWorkspaceSearchTool(pool: Pool, embedding: EmbeddingProvider): import("../define-tool.js").Tool<{
     query: string;
     limit: number;
-    type?: "output" | "input" | "summary" | "synthesis" | undefined;
+    type?: "output" | "input" | "synthesis" | "summary" | undefined;
 }, {
     results: {
         id: string;

package/dist/tools/workspace/workspace-search.js

@@ -32,13 +32,19 @@ function indexName(analysisId) {
 export function createWorkspaceSearchTool(pool, embedding) {
     return defineTool({
         id: "workspace_search",
-        description: "Semantic search over the analysis workspace — input data, analysis " +
-            "outputs, step summaries, run syntheses, and the data profile. Returns " +
-            "ranked file paths with descriptions and metadata; read a file " +
-            "separately to see its contents. Optionally filter by entry type.",
+        description: "Semantic search over the analysis workspace. Returns ranked file paths " +
+            "with descriptions and metadata; read a file separately to see its " +
+            "contents. Indexed entries are exactly four types, and `type` restricts " +
+            'results to one of them: "input" (staged input data files — their ' +
+            'descriptions come from the data profiler), "output" (files a step ' +
+            'produced), "summary" (a step\'s summary), "synthesis" (a run\'s ' +
+            "literature-grounded synthesis).",
         inputSchema: z.object({
             query: z.string().min(1).describe("What to search for, in natural language"),
-            type: z.enum(["input", "output", "summary", "synthesis"]).optional().describe("Restrict results to one workspace entry type"),
+            type: z
+                .enum(["input", "output", "summary", "synthesis"])
+                .optional()
+                .describe('Restrict results to one entry type: "input", "output", "summary", or "synthesis"'),
             limit: z.number().int().min(1).max(50).default(8).describe("Maximum number of results to return"),
         }),
         execute: async ({ query, type, limit }, ctx) => {

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

@@ -20,6 +20,10 @@
  *     - dispatch every `scheduleReady(plan, completedSet, startedSet)` via
  *       `DBOS.startWorkflow` with deterministic child id
  *       `"${parent.workflowID}-${N}"` (N is the step's stable index)
+ *     - compose each child's seed prompt HERE, at dispatch (`composeStepSeed`,
+ *       inside a durable step): the moment a step is dispatched is the first
+ *       moment its dependencies' results exist, so this is the only place the
+ *       seed can name them
  *     - each child input is `forStep(input.runSession, stepId)` for the
  *       session field
  *     - emit `data-dag-state` (reconciling by id) on every dispatch +
@@ -53,6 +57,7 @@ import type { Pool } from "pg";
 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 { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { RunCharge } from "../billing/run-charge.js";
@@ -76,8 +81,15 @@ export interface ExecuteAnalysisInput {
     readonly steps: readonly PlanStep[];
     /** Optional thread id for cortex_runs.thread_id (UI breadcrumb only). */
     readonly threadId?: string | null;
-    /** Per-step prompt body the child workflow forwards to its agent. */
-    readonly promptByStepId: Readonly<Record<string, string>>;
+    /**
+     * The plan's steps, keyed by id — the instruction DATA each step's seed is
+     * composed FROM, not a pre-rendered prompt string. The seed itself is
+     * composed per step at dispatch (`composeStepSeed`), because that is the
+     * first moment a step's dependencies have produced anything to tell it
+     * about. Snapshotted here at the async edge so the body never re-reads the
+     * plan row (a mid-run plan edit cannot change a running run's instructions).
+     */
+    readonly planStepById: Readonly<Record<string, AnalysisStep>>;
     /** Per-step agent id (sandbox catalog entry). */
     readonly agentByStepId: Readonly<Record<string, string>>;
     /** Per-step planner-estimated sandbox resource request. */
@@ -229,8 +241,9 @@ export interface ExecuteAnalysisDeps {
 }
 /**
  * Project the sandbox-step input handed to each child. The parent owns the
- * level computation; the rest comes from `ExecuteAnalysisInput`. The body
- * fills in `runSession` via `forStep` after this returns. Exported for the
+ * level computation and the seed (`prompt`, composed by `composeStepSeed` at
+ * dispatch); the rest comes from `ExecuteAnalysisInput`. The body fills in
+ * `runSession` via `forStep` after this returns. Exported for the
  * projection/timeout-propagation tests.
  */
 export declare function buildChildInput(args: {
@@ -239,7 +252,33 @@ export declare function buildChildInput(args: {
     level: number;
     runId: string;
     workflowId: string;
+    prompt: string;
 }): Omit<SandboxStepInput, "runSession">;
+/**
+ * Compose one step's seed — the user-content message its agent opens on.
+ *
+ * The composition point is the design: the scheduler calls this at the instant
+ * it dispatches a step, which is the first instant at which every one of that
+ * step's dependencies has *finished* and written its results down. A seed
+ * rendered any earlier (at plan submission, say) cannot mention them, and the
+ * agent is left to rediscover its own upstream.
+ *
+ * Everything read here is durable state written by an already-settled child
+ * (`output/summary.md`, `cortex_artifacts`) or by the profiler
+ * (`cortex_analysis_state`) — never live in-flight state, which would not
+ * reproduce.
+ *
+ * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed string is
+ * checkpointed and a replay returns it verbatim — the DB and disk are not read
+ * again and cannot drift the seed under a recovered run. Never call it
+ * unwrapped from the workflow body.
+ */
+export declare function composeStepSeed(args: {
+    input: ExecuteAnalysisInput;
+    stepId: string;
+    runId: string;
+    deps: ExecuteAnalysisDeps;
+}): Promise<string>;
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is

package/dist/workflows/execute-analysis.js

@@ -20,6 +20,10 @@
  *     - dispatch every `scheduleReady(plan, completedSet, startedSet)` via
  *       `DBOS.startWorkflow` with deterministic child id
  *       `"${parent.workflowID}-${N}"` (N is the step's stable index)
+ *     - compose each child's seed prompt HERE, at dispatch (`composeStepSeed`,
+ *       inside a durable step): the moment a step is dispatched is the first
+ *       moment its dependencies' results exist, so this is the only place the
+ *       seed can name them
  *     - each child input is `forStep(input.runSession, stepId)` for the
  *       session field
  *     - emit `data-dag-state` (reconciling by id) on every dispatch +
@@ -54,9 +58,11 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { forStep } from "../auth/types.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { RunDedupCollisionError, countArtifactsForRun, queryActiveRun, seedStepExecutions, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
+import { RunDedupCollisionError, countArtifactsForRun, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
-import { runDir } from "../workspace/paths.js";
+import { loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
+import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing } from "../prompts/briefing.js";
+import { runDir, runStepDir, stepSubdir, stepWritePrefix, toSandboxPath } from "../workspace/paths.js";
 import { isChatDataPart } from "../sandbox/sandbox-step-translate.js";
 import { synthesizeRun } from "../app/synthesize-run.js";
 import { computeTopologicalLevels, scheduleReady, validatePlanDag } from "./execute-analysis-scheduler.js";
@@ -86,12 +92,13 @@ function emitProvenanceGuarded(deps, event) {
 }
 /**
  * Project the sandbox-step input handed to each child. The parent owns the
- * level computation; the rest comes from `ExecuteAnalysisInput`. The body
- * fills in `runSession` via `forStep` after this returns. Exported for the
+ * level computation and the seed (`prompt`, composed by `composeStepSeed` at
+ * dispatch); the rest comes from `ExecuteAnalysisInput`. The body fills in
+ * `runSession` via `forStep` after this returns. Exported for the
  * projection/timeout-propagation tests.
  */
 export function buildChildInput(args) {
-    const { input, stepId, level, runId, workflowId } = args;
+    const { input, stepId, level, runId, workflowId, prompt } = args;
     const resources = input.resourcesByStepId[stepId];
     if (!resources) {
         throw new Error(`executeAnalysis: step "${stepId}" missing from resourcesByStepId — every step must declare resources`);
@@ -102,12 +109,100 @@ export function buildChildInput(args) {
         stepId,
         agentId: input.agentByStepId[stepId] ?? "scientific-executor",
         level,
-        prompt: input.promptByStepId[stepId] ?? "",
+        prompt,
         parentWorkflowId: workflowId,
         resources,
         timeoutSeconds: input.timeoutByStepId?.[stepId],
     };
 }
+// ── Seed composition (at dispatch, not at plan submission) ────────────
+/**
+ * Compose one step's seed — the user-content message its agent opens on.
+ *
+ * The composition point is the design: the scheduler calls this at the instant
+ * it dispatches a step, which is the first instant at which every one of that
+ * step's dependencies has *finished* and written its results down. A seed
+ * rendered any earlier (at plan submission, say) cannot mention them, and the
+ * agent is left to rediscover its own upstream.
+ *
+ * Everything read here is durable state written by an already-settled child
+ * (`output/summary.md`, `cortex_artifacts`) or by the profiler
+ * (`cortex_analysis_state`) — never live in-flight state, which would not
+ * reproduce.
+ *
+ * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed string is
+ * checkpointed and a replay returns it verbatim — the DB and disk are not read
+ * again and cannot drift the seed under a recovered run. Never call it
+ * unwrapped from the workflow body.
+ */
+export async function composeStepSeed(args) {
+    const { input, stepId, runId, deps } = args;
+    const step = input.planStepById[stepId];
+    if (!step) {
+        throw new Error(`executeAnalysis: step "${stepId}" missing from planStepById — every step must carry its plan data`);
+    }
+    const analysisId = input.analysisId;
+    const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
+    // The paths the agent actually sees: the tree is bind-mounted at
+    // `/{analysisId}`, and the step's writable directory is its cwd. Derived
+    // through the same helpers the sandbox mount and the mutate tools use, so
+    // the seed cannot disagree with the container about where anything is.
+    const workspace = {
+        analysisRoot: `/${analysisId}`,
+        workingDir: toSandboxPath(workspaceRoot, analysisId, stepWritePrefix({ workspaceRoot, runId, stepId })),
+    };
+    // A DB failure here throws (house rules): a swallowed error would be frozen
+    // into the checkpointed seed and served to every replay of this step.
+    const profile = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
+    const upstream = await collectUpstreamHandoffs({
+        analysisId,
+        runId,
+        workspaceRoot,
+        dependsOn: step.depends_on,
+        agentByStepId: input.agentByStepId,
+        pool: deps.pool,
+    });
+    return composeStepBriefing({
+        step,
+        workspace,
+        profile: profile?.result ?? null,
+        upstream,
+    });
+}
+/**
+ * Gather what each completed dependency produced. Dependency order is the
+ * plan's declared `depends_on` order — deterministic, so the seed is stable.
+ *
+ * A dependency that wrote no summary is omitted rather than blocking the
+ * dispatch (`loadStepSummariesFromDisk` skips a missing file): a step that
+ * completed without a summary has nothing to hand off, and waiting for one that
+ * will never arrive would deadlock the run.
+ */
+async function collectUpstreamHandoffs(args) {
+    const { analysisId, runId, workspaceRoot, dependsOn, agentByStepId, pool } = args;
+    if (dependsOn.length === 0)
+        return [];
+    const summaries = await loadStepSummariesFromDisk({
+        workspaceRoot,
+        runId,
+        completedSteps: dependsOn,
+        agentByStepId,
+    });
+    const handoffs = [];
+    for (const summary of summaries) {
+        const outputDir = stepSubdir(runStepDir(runId, summary.stepId), "output");
+        const artifacts = await queryStepArtifactPaths(pool, analysisId, runId, summary.stepId, MAX_UPSTREAM_ARTIFACTS);
+        handoffs.push({
+            stepId: summary.stepId,
+            agentId: summary.agentId,
+            summaryMarkdown: summary.markdown,
+            summaryPath: `/${analysisId}/${outputDir}/summary.md`,
+            outputDir: `/${analysisId}/${outputDir}`,
+            artifacts: artifacts.map((a) => `/${analysisId}/${a.path}`),
+        });
+    }
+    return handoffs;
+}
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is
@@ -416,12 +511,18 @@ async function runSchedulerLoop(args) {
         for (const stepId of admit) {
             const idx = stepIndexById.get(stepId);
             const childWorkflowId = `${workflowId}-${idx}`;
+            // Compose the seed HERE — the dependencies of `stepId` are all in
+            // `completed`, so this is the first (and only) moment their results
+            // can be named. Checkpointed so a replay re-dispatches the child
+            // with a byte-identical prompt instead of re-reading the DB/disk.
+            const prompt = await DBOS.runStep(() => composeStepSeed({ input, stepId, runId, deps }), { name: `compose-step-seed:${stepId}` });
             const baseChildInput = buildChildInput({
                 input,
                 stepId,
                 level: levels.get(stepId) ?? 0,
                 runId,
                 workflowId,
+                prompt,
             });
             const childInput = {
                 ...baseChildInput,

package/dist/workflows/target-assessment/lib/citation-validator.js

@@ -5,11 +5,11 @@
 // was always 0. These patterns match the format the agent actually writes.
 // The block content may include array index notation like `[0]`, so we
 // use a pattern that allows `[digits]` inside the outer brackets.
-const DOSSIER_CITE_BLOCK_RE = /\[dossier:\s*((?:[^[\]]*(?:\[\d+\])?)*)\]/gi;
+const DOSSIER_CITE_BLOCK_RE = /\[dossier:\s*((?:[^[\]]|\[\d+\])*)\]/gi;
 // External citation IDs are plain strings — no array-index notation like `[n]` — so the simple [^\]]+ class suffices here instead of the array-index-aware pattern used by DOSSIER_CITE_BLOCK_RE.
 const EXTERNAL_CITE_BLOCK_RE = /\[external citation:\s*([^\]]+)\]/gi;
 // Assumes at most one `external citation:` segment per dossier block (the recommendation prompt produces at most one); a hypothetical second segment in the same block would be parsed imperfectly.
-const EXTERNAL_SEGMENT_RE = /external citation:\s*((?:[^[\]]*(?:\[\d+\])?)*)/i;
+const EXTERNAL_SEGMENT_RE = /external citation:\s*((?:[^[\]]|\[\d+\])*)/i;
 const NCT_RE = /\bNCT\d{8}\b/g;
 const PMID_RE = /\bPMID[:\s]?(\d{6,9})\b/g;
 // Legacy inline format: `dossier.path.foo` written directly in prose, no

package/dist/workflows/target-assessment/lib/clinical-consequence-annotator.js

@@ -19,6 +19,7 @@ import { z } from "zod";
 import { withHost } from "../../../lib/host-concurrency.js";
 import { tryQuery, tryMutation } from "../../../lib/db-result.js";
 import { offTargetAnnotatorPrompt } from "../../../prompts/target-assessment/off-target-annotator.js";
+import { composeSystemPrompt } from "../../../agents/system-prompt.js";
 import { forSubAgent } from "../../../auth/types.js";
 import { finalText, runAgent } from "../../../loop/run-agent.js";
 import { passthroughStep } from "../../../loop/run-step.js";
@@ -93,7 +94,7 @@ const ANNOTATOR_AGENT_ID = "off-target-annotator";
 function buildAnnotatorAgent(model) {
     return {
         id: ANNOTATOR_AGENT_ID,
-        systemPrompt: offTargetAnnotatorPrompt,
+        systemPrompt: composeSystemPrompt(offTargetAnnotatorPrompt),
         model,
         tools: [],
         maxIterations: 2,

package/dist/workspace/paths.d.ts

@@ -127,8 +127,8 @@ export declare function stepWritePrefix(args: {
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
  * the sandbox path is the resource id plus the root-relative tail — the host
  * location of the root never leaks into the container. Single source of truth
- * for the `execute_command` / `write_file` cwd and the `{{WORKING_DIR}}`
- * prompt substitution (see the harness-workspace-tools spec).
+ * for the `execute_command` / `write_file` cwd and for the working directory
+ * a step briefing names (see the harness-workspace-tools spec).
  */
 export declare function toSandboxPath(workspaceRoot: string, resourceId: string, hostAbsPath: string): string;
 /**

package/dist/workspace/paths.js

@@ -101,8 +101,8 @@ export function stepWritePrefix(args) {
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
  * the sandbox path is the resource id plus the root-relative tail — the host
  * location of the root never leaks into the container. Single source of truth
- * for the `execute_command` / `write_file` cwd and the `{{WORKING_DIR}}`
- * prompt substitution (see the harness-workspace-tools spec).
+ * for the `execute_command` / `write_file` cwd and for the working directory
+ * a step briefing names (see the harness-workspace-tools spec).
  */
 export function toSandboxPath(workspaceRoot, resourceId, hostAbsPath) {
     const tail = relativePath(workspaceRoot, hostAbsPath).split(sep).join("/");