@inflexa-ai/harness 0.12.0 → 0.14.0

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

@@ -1,25 +1,28 @@
 /**
  * inspectRun — inspect workflow runs for the current analysis.
  *
- * Dependency-bearing: the database `Pool` is captured by the factory
- * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`,
- * not an ambient request context.
- *
- * Results are pull-only via this tool — the workflow does NOT write to the
- * conversation thread on completion. The retired `run-result-writer` push
- * payload (run status, step summaries, run synthesis, artifact paths) is
- * surfaced here on demand: the run row + step `summaryPath` references +
- * the `synthesisPath` for runs whose synthesis was produced let the
- * conversation agent `read_file` the artefacts it needs.
+ * Results are pull-only: workflows never append completion messages to a
+ * conversation. List mode is active-first and paged. Targeted mode makes
+ * readiness explicit and can perform one bounded, abort-aware wait.
  */
+import { setTimeout as sleep } from "node:timers/promises";
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { queryRun, queryRunsByAnalysis, queryStepsByRun } from "../../state/index.js";
 import { scopeResource } from "../../auth/types.js";
-import { SYNTHESIS_STEP_ID } from "../../workspace/paths.js";
 import { unwrapOrThrow } from "../../lib/result.js";
+import { queryRun, queryRunsForInspection, queryStepsByRun } from "../../state/index.js";
+import { SYNTHESIS_STEP_ID } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
-function formatRun(r, verbose) {
+const DEFAULT_PAGE_SIZE = 50;
+const POLL_INTERVAL_MS = 1_000;
+const systemClock = {
+    now: Date.now,
+    wait: (ms, signal) => sleep(ms, undefined, { signal }),
+};
+function isTerminal(status) {
+    return status === "completed" || status === "partial" || status === "failed" || status === "canceled";
+}
+function formatRun(r, verbose, exposePaths = isTerminal(r.status)) {
     return {
         runId: r.runId,
         workflowName: r.workflowName,
@@ -27,74 +30,160 @@ function formatRun(r, verbose) {
         startedAt: r.startedAt,
         completedAt: r.completedAt,
         planId: r.planId,
-        // synthesis.json is written only when synthesis actually produced a
-        // result; a skipped/failed synthesis leaves no file, so pointing at a
-        // path would send the agent to a stale or absent artifact. The recorded
-        // outcome — surfaced as synthesisStatus (and synthesisReason when set) —
-        // lets a consumer tell "produced" from "skipped/failed/unknown" without
-        // reading a file.
-        synthesisPath: r.synthesisStatus === "produced" ? `runs/${r.runId}/synthesis.json` : null,
+        synthesisPath: exposePaths && r.synthesisStatus === "produced" ? `runs/${r.runId}/synthesis.json` : null,
         synthesisStatus: r.synthesisStatus,
         ...(r.synthesisReason !== null ? { synthesisReason: r.synthesisReason } : {}),
         ...(verbose ? { error: r.error } : {}),
     };
 }
-export function createInspectRunTool(pool) {
+function formatSteps(runId, stepRows, verbose, exposePaths) {
+    return stepRows.map((s) => ({
+        stepId: s.stepId,
+        agentId: s.agentId,
+        wave: s.wave,
+        status: s.status,
+        ...(exposePaths && s.status !== "pending" && s.status !== "skipped" && s.stepId !== SYNTHESIS_STEP_ID
+            ? { summaryPath: `runs/${runId}/${s.stepId}/output/summary.md` }
+            : {}),
+        ...(verbose
+            ? {
+                durationMs: s.durationMs,
+                error: s.error,
+                attempts: s.attempts,
+                lastErrorClass: s.lastErrorClass,
+                finishReason: s.finishReason,
+                hitMaxSteps: s.hitMaxSteps,
+            }
+            : {}),
+    }));
+}
+const inputSchema = z
+    .object({
+    runId: z.string().optional().describe("Specific run to inspect. Omit to list runs."),
+    page: z.number().int().min(1).optional().describe("List page, starting at 1. Valid only without runId."),
+    pageSize: z.number().int().min(1).max(100).optional().describe("Rows per list page (1-100). Valid only without runId."),
+    waitForTerminalSeconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(30)
+        .optional()
+        .describe("Wait up to this many seconds for a targeted running run to leave running state."),
+    includeDiagnostics: z
+        .boolean()
+        .optional()
+        .describe("Include failure/retry telemetry: run.error and step.{durationMs,error,attempts,lastErrorClass,finishReason,hitMaxSteps}. Default false."),
+})
+    .superRefine((input, refinement) => {
+    if (input.runId && (input.page !== undefined || input.pageSize !== undefined)) {
+        refinement.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "page and pageSize are valid only when runId is omitted",
+            path: input.page !== undefined ? ["page"] : ["pageSize"],
+        });
+    }
+    if (!input.runId && input.waitForTerminalSeconds !== undefined) {
+        refinement.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "waitForTerminalSeconds requires runId",
+            path: ["waitForTerminalSeconds"],
+        });
+    }
+});
+/**
+ * Build the run-inspection tool. The optional clock is an internal testing
+ * seam for deterministic cutoff and transition coverage.
+ */
+export function createInspectRunTool(pool, clock = systemClock) {
     return defineTool({
         id: "inspect_run",
-        description: "Inspect workflow runs for this analysis. " +
-            "Without a runId: lists all runs. " +
-            "With a runId: returns step-level details with paths to summary.md, plus each run's synthesisStatus and a synthesisPath to synthesis.json only when synthesis was produced. " +
-            "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry. " +
-            "Read summary.md or synthesis.json for findings, or use workspace search with type:summary or type:synthesis.",
-        inputSchema: z.object({
-            runId: z.string().optional().describe("Specific run to inspect. Omit to list all runs."),
-            includeDiagnostics: z
-                .boolean()
-                .optional()
-                .describe("Include failure/retry telemetry: run.error and step.{durationMs,error,attempts,lastErrorClass,finishReason,hitMaxSteps}. Default false."),
-        }),
+        description: "Inspect workflow runs for this analysis. Without a runId, returns an active-first paged list (running, suspended, then terminal history). " +
+            "With a runId, returns an explicit inspectionState and advertises output paths only after the run is terminal. " +
+            "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
+            "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
+        inputSchema,
         execute: async (input, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;
             const verbose = input.includeDiagnostics === true;
             if (!input.runId) {
-                const runs = unwrapOrThrow(await queryRunsByAnalysis(pool, resourceId));
-                if (runs.length === 0) {
-                    return ok({ message: "No runs found for this analysis." });
-                }
-                return ok({ runs: runs.map((r) => formatRun(r, verbose)) });
+                const page = input.page ?? 1;
+                const pageSize = input.pageSize ?? DEFAULT_PAGE_SIZE;
+                const offset = (page - 1) * pageSize;
+                const result = unwrapOrThrow(await queryRunsForInspection(pool, resourceId, { limit: pageSize, offset }));
+                return ok({
+                    runs: result.runs.map((run) => formatRun(run, verbose)),
+                    total: result.total,
+                    page,
+                    pageSize,
+                    hasMore: offset + result.runs.length < result.total,
+                });
             }
-            const run = unwrapOrThrow(await queryRun(pool, input.runId));
+            const waitSeconds = input.waitForTerminalSeconds;
+            let run = unwrapOrThrow(await queryRun(pool, input.runId));
             if (!run || run.analysisId !== resourceId) {
-                return ok({ message: `Run ${input.runId} not found.` });
+                return ok({
+                    inspectionState: "not_found",
+                    message: `Run ${input.runId} was not found in this analysis.`,
+                    ...(waitSeconds === undefined ? {} : { wait: { requestedSeconds: waitSeconds, cutoffReached: false } }),
+                });
             }
-            const stepRows = unwrapOrThrow(await queryStepsByRun(pool, input.runId));
-            const steps = stepRows.map((s) => ({
-                stepId: s.stepId,
-                agentId: s.agentId,
-                wave: s.wave,
-                status: s.status,
-                // No per-step `summaryPath` when the file cannot exist: a seeded row
-                // (`pending`/`skipped`) never produced output, and the reserved
-                // `synthesis` phase is not a sandbox step — it writes the run-level
-                // `synthesis.json`, surfaced as the run's `synthesisPath`, not a
-                // `{stepId}/output/summary.md`. Emitting the per-step path for it would
-                // point the agent at a file that never exists.
-                ...(s.status === "pending" || s.status === "skipped" || s.stepId === SYNTHESIS_STEP_ID
-                    ? {}
-                    : { summaryPath: `runs/${input.runId}/${s.stepId}/output/summary.md` }),
-                ...(verbose
-                    ? {
-                        durationMs: s.durationMs,
-                        error: s.error,
-                        attempts: s.attempts,
-                        lastErrorClass: s.lastErrorClass,
-                        finishReason: s.finishReason,
-                        hitMaxSteps: s.hitMaxSteps,
+            const selfWait = waitSeconds !== undefined && ctx.session.runFrame?.runId === input.runId;
+            let cutoffReached = false;
+            if (waitSeconds !== undefined && run.status === "running" && !selfWait) {
+                const deadline = clock.now() + waitSeconds * 1_000;
+                while (run.status === "running") {
+                    const remaining = deadline - clock.now();
+                    if (remaining <= 0) {
+                        cutoffReached = true;
+                        break;
                     }
-                    : {}),
-            }));
-            return ok({ run: formatRun(run, verbose), steps });
+                    await clock.wait(Math.min(POLL_INTERVAL_MS, remaining), ctx.signal);
+                    run = unwrapOrThrow(await queryRun(pool, input.runId));
+                    if (!run || run.analysisId !== resourceId) {
+                        return ok({
+                            inspectionState: "not_found",
+                            message: `Run ${input.runId} was not found in this analysis.`,
+                            wait: { requestedSeconds: waitSeconds, cutoffReached: false },
+                        });
+                    }
+                }
+            }
+            const terminal = isTerminal(run.status);
+            const stepRows = unwrapOrThrow(await queryStepsByRun(pool, input.runId));
+            const steps = formatSteps(input.runId, stepRows, verbose, terminal);
+            const wait = waitSeconds === undefined ? {} : { wait: { requestedSeconds: waitSeconds, cutoffReached } };
+            if (run.status === "running") {
+                const message = selfWait
+                    ? "This run is still in progress. Results are not ready, and the enclosing workflow cannot finish while its current step waits for itself."
+                    : cutoffReached
+                        ? "This run is still in progress after the requested wait cutoff. Results are not ready; stop polling for this turn."
+                        : "This run is in progress. Results are not ready.";
+                return ok({
+                    inspectionState: "in_progress",
+                    message,
+                    run: formatRun(run, verbose, false),
+                    steps,
+                    elapsedMs: Math.max(0, clock.now() - Date.parse(run.startedAt)),
+                    ...wait,
+                    ...(selfWait ? { selfWaitPrevented: true } : {}),
+                });
+            }
+            if (run.status === "suspended_insufficient_funds") {
+                return ok({
+                    inspectionState: "suspended",
+                    message: "This run is suspended and will not progress until it is resumed.",
+                    run: formatRun(run, verbose, false),
+                    steps,
+                    ...wait,
+                });
+            }
+            return ok({
+                inspectionState: "terminal",
+                message: `This run is terminal with status ${run.status}.`,
+                run: formatRun(run, verbose, true),
+                steps,
+                ...wait,
+            });
         },
     });
 }

package/dist/tools/research/literature-reviewer.js

@@ -22,14 +22,11 @@ import { literatureReviewerPrompt } from "../../prompts/literature-reviewer.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { forSubAgent } from "../../auth/types.js";
 import { defineTool } from "../define-tool.js";
-import { createNcbiTools } from "../bio/keys.js";
-import { getImpcKoProfileTool } from "../bio/get-impc-ko-profile.js";
-import { lookupGoTermTool } from "../bio/lookup-go-term.js";
-import { searchBgeeExpressionTool } from "../bio/search-bgee-expression.js";
-import { createSearchDgidbTool } from "../bio/search-dgidb.js";
+import { createChemDbTools, createNcbiTools } from "../bio/keys.js";
+import { genePreclinicalProfileTool } from "../bio/gene-preclinical-profile.js";
+import { lookupAnnotationTool } from "../bio/lookup-annotation.js";
 import { searchGeneTool } from "../bio/search-gene.js";
 import { searchInteractionsTool } from "../bio/search-interactions.js";
-import { searchPathwayTool } from "../bio/search-pathway.js";
 /** Sub-agent identity — appended to `callPath`, set as `agentId`. */
 const AGENT_ID = "literature-reviewer";
 /** Multi-tool research budget — search → read → synthesize over many genes. */
@@ -37,15 +34,14 @@ const REVIEWER_MAX_ITERATIONS = 30;
 /** Build the `literature_reviewer` delegation tool bound to its provider. */
 export function createLiteratureReviewerTool(deps) {
     const ncbi = createNcbiTools(deps.bioKeys);
+    const chemDb = createChemDbTools(deps.bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
     const reviewerTools = [
         searchGeneTool,
-        searchPathwayTool,
-        lookupGoTermTool,
+        lookupAnnotationTool,
         searchInteractionsTool,
         ncbi.pubmed,
-        createSearchDgidbTool({ ...(deps.logger ? { logger: deps.logger } : {}) }),
-        searchBgeeExpressionTool,
-        getImpcKoProfileTool,
+        chemDb.drugGeneInteractions,
+        genePreclinicalProfileTool,
     ];
     const agent = {
         id: AGENT_ID,

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

@@ -115,6 +115,11 @@ export interface ExecuteAnalysisInput {
      * dependency-satisfied step starts immediately — the legacy fan-out.
      */
     readonly budget?: MachineBudget;
+    /**
+     * Replay-stable run-level synthesis decision. Absent preserves the legacy
+     * behavior for workflows persisted before this field existed.
+     */
+    readonly synthesisEnabled?: boolean;
     /**
      * Durable `RunSession` minted at the async edge by `executePlan`.
      * Carries the run-authorization credential, identity, scope, and `runFrame.runId`.
@@ -204,6 +209,49 @@ export type RunProvenanceEvent = {
     /** `atMs − run_started.atMs`: the workflow-observed run span in ms. */
     durationMs: number;
 };
+/**
+ * A step's in-run display state. Wider than the ledger's `StepExecutionStatus`: `queued` is a
+ * scheduler-only condition (dependency-satisfied but held for budget capacity) that never reaches a
+ * database row, and `skipped` is asserted mid-run for a doomed dependent whose ledger row stays
+ * `pending` until the terminal sweep.
+ */
+export type StepRuntimeStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+/**
+ * One step's state inside a {@link RunObservation}. `id` is the plan slug the ledger and the
+ * dependency edges use; `name` is the human phrase the plan author wrote, which is the only field
+ * that says what the step is FOR. `durationMs` and `error` appear only once the step has settled
+ * in a way that produced them.
+ */
+export interface RunStepObservation {
+    readonly id: string;
+    readonly name: string;
+    readonly agent: string;
+    readonly status: StepRuntimeStatus;
+    readonly durationMs?: number;
+    readonly error?: string;
+}
+/**
+ * A whole-run snapshot handed to {@link ExecuteAnalysisDeps.observeRun}.
+ *
+ * Deliberately a SNAPSHOT rather than a transition event. The observer is invoked from the
+ * workflow body, so DBOS re-execution on recovery re-fires the whole sequence; a re-fired snapshot
+ * is idempotent for any consumer that renders from the newest one it has seen, whereas re-fired
+ * granular events would force every consumer to rebuild ordering and dedupe by identity. A
+ * consumer that misses an invocation loses nothing permanent — the next transition restates the
+ * full truth.
+ *
+ * Derived aggregates (completion counts, run duration) are deliberately ABSENT. They are
+ * computable from `steps` and recorded authoritatively on the run's ledger row; carrying them here
+ * would mint a second source that can disagree with the ledger a host also reads.
+ */
+export interface RunObservation {
+    readonly runId: string;
+    readonly analysisId: string;
+    /** `running` for every mid-flight snapshot; the derived terminal status on the last one. */
+    readonly status: ExecuteAnalysisFinalStatus;
+    /** Every plan step, including ones that have not started — never a delta. */
+    readonly steps: readonly RunStepObservation[];
+}
 /**
  * Construction-time deps for the parent workflow. The order-of-operations is
  * the body's own: it brackets the run, dispatches children, and synthesizes
@@ -230,11 +278,6 @@ export interface ExecuteAnalysisDeps {
     readonly bioKeys: BioToolKeys;
     /** Run-level billing-bracket seam (managed: external bracket; OSS: no-op). */
     readonly runCharge: RunCharge;
-    /**
-     * When false, skip run-level synthesis entirely (findings stay empty).
-     * Config, not a seam. Defaults to true.
-     */
-    readonly synthesisEnabled?: boolean;
     /** Run-authorization seam — the terminal path revokes through `revoke`. */
     readonly runAuthorizer: RunAuthorizer;
     /**
@@ -247,6 +290,26 @@ export interface ExecuteAnalysisDeps {
      * guarded so a throwing observer never fails the run.
      */
     readonly emitProvenance?: (event: RunProvenanceEvent) => void;
+    /**
+     * Optional, fire-and-forget observation of the run's live shape, for a host driving a UI.
+     *
+     * Independent of {@link emitProvenance} in every direction: neither is implemented in terms of
+     * the other, they share no payload, and supplying one does not imply the other. They exist
+     * separately because provenance closes a signed, hash-chained record under a single-writer
+     * lock, while this is a lossy-tolerant display channel — coupling them would put a UI repaint
+     * behind the chain's write discipline and force provenance to carry step names and agent ids it
+     * has no reason to record.
+     *
+     * Invoked directly in the workflow body (NOT wrapped in `DBOS.runStep`) for the same reason
+     * `emitProvenance` is: body re-execution on recovery must re-fire it, and a cached step would
+     * suppress that. Idempotency comes free for rendering because the payload is a whole-run
+     * snapshot; a host taking a DURABLE side effect on one must key it by run id and status itself.
+     *
+     * Synchronous by signature (`void`, never a promise) so a host needing I/O has to dispatch it
+     * rather than await it inside the body's critical path. Every call site is guarded, so a
+     * throwing observer never fails the run.
+     */
+    readonly observeRun?: (observation: RunObservation) => void;
 }
 /**
  * Project the sandbox-step input handed to each child. The parent owns the

package/dist/workflows/execute-analysis.js

@@ -97,6 +97,52 @@ function emitProvenanceGuarded(deps, event) {
         logger.error("emitProvenance threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
     }
 }
+/**
+ * Build the whole-run snapshot from the workflow input and the scheduler's live step state.
+ *
+ * Pure, so every emission point produces an identically-shaped payload from one place — a second
+ * construction path is exactly how "a transition happened" acquires two definitions that drift.
+ * The human `name` joins through `input.planStepById` because `input.steps` is the scheduler's
+ * narrow `{id, depends_on}` projection and carries no plan vocabulary.
+ */
+function buildRunObservation(args) {
+    const { input, runId, status, stepStates } = args;
+    return {
+        runId,
+        analysisId: input.analysisId,
+        status,
+        steps: input.steps.map((s) => {
+            const rt = stepStates.get(s.id);
+            return {
+                id: s.id,
+                name: input.planStepById[s.id]?.name ?? s.id,
+                agent: input.agentByStepId[s.id] ?? "unknown",
+                // A step absent from the map has not been reached yet; `pending` is its honest state.
+                status: rt?.status ?? "pending",
+                ...(rt?.durationMs !== undefined ? { durationMs: rt.durationMs } : {}),
+                ...(rt?.error !== undefined ? { error: rt.error } : {}),
+            };
+        }),
+    };
+}
+/**
+ * Fire the optional run observer, isolating a throwing host callback from the workflow.
+ *
+ * Deliberately a sibling of {@link emitProvenanceGuarded} rather than a shared helper: the two
+ * seams carry unrelated payloads and must stay independently removable, and one shared guard would
+ * have to pick a single logger namespace, making it lie about whichever seam it is not named for.
+ */
+function observeRunGuarded(deps, observation) {
+    if (!deps.observeRun)
+        return;
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis.observe");
+    try {
+        deps.observeRun(observation);
+    }
+    catch (err) {
+        logger.error("observeRun threw", { runId: observation.runId, status: observation.status, ...logger.errorFields(err) });
+    }
+}
 /**
  * Project the sandbox-step input handed to each child. The parent owns the
  * level computation and the seed (`prompt`, composed by `composeStepSeed` at
@@ -342,7 +388,7 @@ export async function runExecuteAnalysisBody(input, deps) {
     // `pending` and the terminal sweep finalizes it to `skipped` — honest
     // ("never ran, never will"), like any never-dispatched DAG step. Its wave
     // sits after every DAG level so ledger-ordered readers render it last.
-    const synthesisEnabled = deps.synthesisEnabled ?? true;
+    const synthesisEnabled = input.synthesisEnabled ?? true;
     const synthesisWave = Math.max(-1, ...levels.values()) + 1;
     await DBOS.runStep(async () => {
         const dagRows = input.steps.map((step) => ({
@@ -379,6 +425,10 @@ export async function runExecuteAnalysisBody(input, deps) {
         stepCount: input.steps.length,
         atMs: startedAtMs,
     });
+    // Opening snapshot: every step pending. The scheduler's own map does not exist yet, and an
+    // empty one yields exactly that — so a host has the run's full shape before the first dispatch
+    // rather than learning the step list from whichever transition happens to land first.
+    observeRunGuarded(deps, buildRunObservation({ input, runId, status: "running", stepStates: new Map() }));
     // (2-4) Scheduler loop + failure isolation + pause cascade.
     const final = await runSchedulerLoop({
         input,
@@ -403,10 +453,8 @@ export async function runExecuteAnalysisBody(input, deps) {
         // recovered replay reuses the original instants (same rule as `startedAtMs`).
         const synthStartedAtMs = await DBOS.now();
         // Mark the seeded `synthesis` row running. The same upsert the DAG children
-        // use: it stamps started_at, and it CREATES the row outright when the seed
-        // never carried it (synthesisEnabled flipped true across a recovery
-        // redeploy) — the mark self-heals rather than trusting the seed's snapshot
-        // of the config. Log-don't-fail: a progress row must never fail an
+        // use: it stamps started_at, and it creates the row outright if a legacy
+        // persisted input did not seed it. Log-don't-fail: a progress row must never fail an
         // otherwise-healthy run. Cancellation still re-propagates — it is not a
         // write failure, and swallowing it here would only defer it one operation.
         try {
@@ -492,6 +540,11 @@ export async function runExecuteAnalysisBody(input, deps) {
         synthesisOutcome,
         deps,
     });
+    // Terminal snapshot, fired here rather than inside `collectAndComplete` because this is the
+    // first point where BOTH the derived final status and the scheduler's final step map are in
+    // hand. It precedes the budget self-cancel below on purpose: that branch raises out of the
+    // body, so an observer placed after it would never see a budget-paused run's last state.
+    observeRunGuarded(deps, buildRunObservation({ input, runId, status: result.status, stepStates: final.stepStates }));
     // Synthesis failure takes priority over the budget-exceeded cascade: a run
     // whose synthesis threw is definitively failed (ERROR), not a resumable
     // budget pause. Only self-cancel when synthesis succeeded.
@@ -604,7 +657,14 @@ async function runSchedulerLoop(args) {
                 const rt = stepRuntime.get(s.id);
                 const entry = {
                     id: s.id,
-                    name: s.id,
+                    // `input.steps` is the SCHEDULER's projection — `{id, depends_on}` and nothing
+                    // else — so the human name has to be joined from the snapshotted plan step. A
+                    // consumer reading `name` is reading it to say what the step is FOR, which the
+                    // id (a `T{track}S{step}` slug) cannot answer. Falling back to the id keeps the
+                    // field populated for a step missing from the snapshot rather than emitting an
+                    // empty label; `planStepById` is complete by contract (dispatch throws on a
+                    // miss), so the fallback is unreachable in practice.
+                    name: input.planStepById[s.id]?.name ?? s.id,
                     agent: input.agentByStepId[s.id] ?? "unknown",
                     status: rt.status,
                     level: levels.get(s.id) ?? 0,
@@ -614,9 +674,18 @@ async function runSchedulerLoop(args) {
                     entry.durationMs = rt.durationMs;
                 if (rt.error !== undefined)
                     entry.error = rt.error;
+                // `artifactCount` and `summary` are declared on `DagStepState` and deliberately not
+                // set: the parent holds neither at snapshot time, and a placeholder would make a
+                // consumer's rendering confidently wrong rather than honestly incomplete.
                 return entry;
             }),
         });
+        // The host observer rides the DAG emission rather than getting its own instrumentation
+        // points: these call sites already ARE the complete set of run-state transitions, and a
+        // second set would drift from this one. Status is `running` here by construction — the
+        // scheduler loop only emits while it is still scheduling; the terminal snapshot is fired by
+        // the body once `collectAndComplete` has derived the final status.
+        observeRunGuarded(deps, buildRunObservation({ input, runId, status: "running", stepStates: stepRuntime }));
     };
     const dbosParentId = DBOS.workflowID ?? workflowId;
     const dispatchReady = async () => {
@@ -843,7 +912,7 @@ async function runSchedulerLoop(args) {
         });
     }
     await drainBudgetExceededNotifications(budgetExceededChildIds);
-    return { completed, failed, canceled, budgetExceeded, failureReason };
+    return { completed, failed, canceled, budgetExceeded, failureReason, stepStates: stepRuntime };
 }
 async function drainBudgetExceededNotifications(childIds) {
     while (true) {

package/dist/workflows/sandbox-step.js

@@ -33,7 +33,7 @@ import { unwrapOrThrow } from "../lib/result.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
 import { runAgent } from "../loop/run-agent.js";
 import { durableStep } from "../loop/run-step.js";
-import { activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta } from "../sandbox/sandbox-step-translate.js";
+import { activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, stepPartId } from "../sandbox/sandbox-step-translate.js";
 import { forSubAgent } from "../auth/types.js";
 import { walkStepArtifacts } from "../execution/post-step.js";
 import { collectStepOutputs, generateStepFileMetadata, generateStepSummaryAndWrite, reconcileAndRegisterStepArtifacts, vectorIndexStepOutputs, } from "../execution/post-step-pipeline.js";
@@ -61,16 +61,6 @@ function nextFunctionIdFactory() {
     let n = 0;
     return () => `fn-${(n++).toString(36)}`;
 }
-/**
- * Stable reconciliation id for a step's reconciling parts
- * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
- * so the run-stream fold collapses every phase transition latest-wins onto
- * a single frame. The client keys these by `stepId`, but the server fold
- * keys by part `id`, so the id MUST be unique per step within the run.
- */
-function stepPartId(kind, runId, stepId) {
-    return `${kind}-${runId}-${stepId}`;
-}
 /**
  * Map an internal step failure to a user-safe string. Internal detail (file
  * paths, content hashes, managed-root rejection reasons, stack traces) stays in the pod

package/dist/workflows/target-assessment/decisions/index.d.ts

@@ -43,9 +43,9 @@ export declare const DrugsInClassOutputSchema: z.ZodObject<{
         firstApproval: z.ZodNullable<z.ZodNumber>;
         moleculeType: z.ZodNullable<z.ZodString>;
         sources: z.ZodArray<z.ZodEnum<{
-            chembl: "chembl";
             dgidb: "dgidb";
             drugbank: "drugbank";
+            chembl: "chembl";
         }>>;
     }, z.core.$strip>>;
     total: z.ZodNumber;

package/dist/workflows/target-assessment/phase4-assemble.d.ts

@@ -1707,8 +1707,8 @@ export declare const Phase4OutputSchema: z.ZodObject<{
                                 medium: "medium";
                                 low: "low";
                                 absent: "absent";
-                                not_loaded: "not_loaded";
                                 no_data: "no_data";
+                                not_loaded: "not_loaded";
                             }>;
                         }, z.core.$strip>>;
                         per_species_coverage: z.ZodRecord<z.ZodString, z.ZodEnum<{

package/dist/workflows/target-assessment/steps/phase2-aggregate.d.ts

@@ -53,9 +53,9 @@ export declare const Phase2AggregateInputSchema: z.ZodObject<{
                 firstApproval: z.ZodNullable<z.ZodNumber>;
                 moleculeType: z.ZodNullable<z.ZodString>;
                 sources: z.ZodArray<z.ZodEnum<{
-                    chembl: "chembl";
                     dgidb: "dgidb";
                     drugbank: "drugbank";
+                    chembl: "chembl";
                 }>>;
             }, z.core.$strip>>;
             total: z.ZodNumber;
@@ -672,9 +672,9 @@ export declare const Phase2BundleSchema: z.ZodObject<{
                     firstApproval: z.ZodNullable<z.ZodNumber>;
                     moleculeType: z.ZodNullable<z.ZodString>;
                     sources: z.ZodArray<z.ZodEnum<{
-                        chembl: "chembl";
                         dgidb: "dgidb";
                         drugbank: "drugbank";
+                        chembl: "chembl";
                     }>>;
                 }, z.core.$strip>>;
                 total: z.ZodNumber;

package/dist/workflows/target-assessment/steps/phase3-aggregate.d.ts

@@ -757,9 +757,9 @@ export declare const Phase3BundleSchema: z.ZodObject<{
                         firstApproval: z.ZodNullable<z.ZodNumber>;
                         moleculeType: z.ZodNullable<z.ZodString>;
                         sources: z.ZodArray<z.ZodEnum<{
-                            chembl: "chembl";
                             dgidb: "dgidb";
                             drugbank: "drugbank";
+                            chembl: "chembl";
                         }>>;
                     }, z.core.$strip>>;
                     total: z.ZodNumber;

package/package.json

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

package/dist/agents/sandbox/ephemeral-executor.d.ts

@@ -1,9 +0,0 @@
-/**
- * Ephemeral Executor — read-only sandbox agent for quick computations.
- * Cannot create files; step conventions don't apply.
- */
-import type { AgentDefinition } from "../../loop/types.js";
-import { type SandboxAgentDeps } from "./shared.js";
-import type { AgentMeta } from "./types.js";
-export declare const meta: AgentMeta;
-export declare function createEphemeralExecutorAgent(deps: SandboxAgentDeps): AgentDefinition;