@inflexa-ai/harness 0.13.0 → 0.14.1

package/dist/tools/research/inspect-data-profile.d.ts

@@ -12,11 +12,9 @@
  * and it is why the record is served in full rather than summarized: an agent that
  * cannot pull a fact here has no fallback but to re-derive it from the raw bytes.
  *
- * Bounded by construction. `inspect_run` is the cautionary counter-example — it caps
- * its query at 50 rows with no `limit` parameter and no signal to the caller, so a
- * 51st run is simply invisible. Here the per-file scope is explicitly paged and always
- * reports `total` and `hasMore`: an elided tail is a fact the model can see and act on,
- * never a silent truncation.
+ * Bounded by construction. Like `inspect_run`, the per-file scope is explicitly
+ * paged and always reports `total` and `hasMore`: an elided tail is a fact the
+ * model can see and act on, never a silent truncation.
  *
  * Lifecycle states are data variants, not errors (the `defineTool` contract): a missing,
  * in-flight, failed, or stale profile is an ordinary, expected outcome the model must be
@@ -61,7 +59,17 @@ interface FilesOutput extends ProfileEnvelope {
     readonly hasMore: boolean;
     readonly files: DataProfileFile[];
 }
-/** No profile to serve — the honest lifecycle states, in the ok channel. */
+/**
+ * No profile to serve — the honest lifecycle states, in the ok channel.
+ *
+ * Deliberately carries no staleness verdict. None of this variant's three
+ * producers retains a comparand: an analysis that was never profiled and one
+ * with no input files never had one, and `clearDataProfile` nulls
+ * `seed_input_file_ids` along with every other profile column, so a cleared row
+ * keeps no record of what it once covered. Such a field could only ever be
+ * constant here, and a constant field carries no information while implying
+ * that it does. `FailedOutput` omits one for the same reason — see its note.
+ */
 interface AbsentOutput {
     readonly state: "absent";
     readonly message: string;
@@ -71,9 +79,26 @@ interface PendingOutput {
     readonly status: "pending" | "running";
     readonly message: string;
 }
+/**
+ * A recorded failure with no profile to fall back on.
+ *
+ * Carries no staleness verdict, deliberately. Whether the failed attempt covered
+ * the files the analysis holds NOW is not derivable here: this tool reads one
+ * `cortex_analysis_state` row, the current input set is the embedder's knowledge,
+ * and `seed_input_file_ids` is the most recently seeded set rather than a
+ * per-attempt snapshot (`upsertAnalysis` overwrites it). A field reporting that
+ * verdict could only ever hold one value, which carries no information while
+ * implying that it does — and the tool description, being the whole of what an
+ * agent knows about this tool, must not advertise a distinction it cannot make.
+ *
+ * `failedAt` is reported instead: a fact the row actually holds, and one an agent
+ * that knows when the input set last changed can act on.
+ */
 interface FailedOutput {
     readonly state: "failed";
     readonly error: string | null;
+    /** When the failure was recorded; `null` when the row holds no time. */
+    readonly failedAt: string | null;
     readonly message: string;
 }
 export type InspectDataProfileOutput = OverviewOutput | FilesOutput | AbsentOutput | PendingOutput | FailedOutput;

package/dist/tools/research/inspect-data-profile.js

@@ -12,11 +12,9 @@
  * and it is why the record is served in full rather than summarized: an agent that
  * cannot pull a fact here has no fallback but to re-derive it from the raw bytes.
  *
- * Bounded by construction. `inspect_run` is the cautionary counter-example — it caps
- * its query at 50 rows with no `limit` parameter and no signal to the caller, so a
- * 51st run is simply invisible. Here the per-file scope is explicitly paged and always
- * reports `total` and `hasMore`: an elided tail is a fact the model can see and act on,
- * never a silent truncation.
+ * Bounded by construction. Like `inspect_run`, the per-file scope is explicitly
+ * paged and always reports `total` and `hasMore`: an elided tail is a fact the
+ * model can see and act on, never a silent truncation.
  *
  * Lifecycle states are data variants, not errors (the `defineTool` contract): a missing,
  * in-flight, failed, or stale profile is an ordinary, expected outcome the model must be
@@ -57,6 +55,15 @@ function stalenessReasons(status, result) {
     }
     return reasons;
 }
+/**
+ * The qualification the `failed` message must carry. A bare `failed: <error>`
+ * reads as a verdict on whatever files the agent is currently holding, and
+ * `message` is what an agent quotes back to the user — so the limit of what this
+ * row can establish belongs in the prose channel, not only in the field set.
+ */
+const FAILURE_SCOPE_NOTE = "This records an earlier attempt; this row cannot establish whether it covered the input files the analysis " +
+    "holds now, so do not read it as a verdict on the current data. Compare failedAt against when the input set " +
+    "last changed, and re-profile if they have moved apart.";
 export function createInspectDataProfileTool(pool) {
     return defineTool({
         id: "inspect_data_profile",
@@ -72,7 +79,11 @@ export function createInspectDataProfileTool(pool) {
             "always with the true total and hasMore, so you can see exactly what you have not read yet. " +
             "The state field says what you got: 'ready'; 'stale' (a profile is returned but may not describe the current " +
             "inputs — staleReason says why); 'pending' (profiling is still running); 'failed'; or 'absent' (never profiled, " +
-            "or the analysis has no input files).",
+            "or the analysis has no input files). " +
+            "A 'failed' state reports a PAST attempt, with failedAt naming when it was recorded — it is not a verdict on the " +
+            "input files you are holding now, and this tool cannot tell you whether that attempt covered them. Compare failedAt " +
+            "against when the input set last changed before you conclude anything: if the data moved since, say the profile " +
+            "needs re-running rather than diagnosing the data itself.",
         inputSchema: z.object({
             scope: z
                 .enum(["overview", "files"])
@@ -101,10 +112,15 @@ export function createInspectDataProfileTool(pool) {
             const result = status.result;
             if (!result) {
                 if (status.status === "failed") {
+                    // A failure that DID leave a prior profile on the row never reaches
+                    // here — it is served as `stale`, where `stalenessReasons` names the
+                    // failed re-profile and compares the input sets through the single
+                    // shared predicate. This branch is the case with nothing to compare.
                     return ok({
                         state: "failed",
                         error: status.error,
-                        message: `Data profiling failed and no earlier profile exists: ${status.error ?? "no reason recorded"}.`,
+                        failedAt: status.completedAt,
+                        message: `Data profiling failed and no earlier profile exists: ${status.error ?? "no reason recorded"}. ${FAILURE_SCOPE_NOTE}`,
                     });
                 }
                 if (status.status === "completed") {

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

@@ -1,16 +1,9 @@
 /**
  * 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 type { Pool } from "pg";
 import type { CortexRunRow } from "../../state/schema.js";
@@ -20,7 +13,6 @@ interface FormattedStep {
     agentId: string;
     wave: number;
     status: string;
-    /** Absent for steps that never ran (`pending`/`skipped`) — no output tree exists to point at. */
     summaryPath?: string;
     durationMs?: number | null;
     error?: string | null;
@@ -29,15 +21,34 @@ interface FormattedStep {
     finishReason?: string | null;
     hitMaxSteps?: boolean | null;
 }
+interface WaitMetadata {
+    readonly requestedSeconds: number;
+    readonly cutoffReached: boolean;
+}
 type InspectRunOutput = {
-    message: string;
-} | {
     runs: FormattedRun[];
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+} | {
+    inspectionState: "not_found";
+    message: string;
+    wait?: WaitMetadata;
 } | {
+    inspectionState: "in_progress" | "suspended" | "terminal";
+    message: string;
     run: FormattedRun;
     steps: FormattedStep[];
+    elapsedMs?: number;
+    wait?: WaitMetadata;
+    selfWaitPrevented?: boolean;
 };
-declare function formatRun(r: CortexRunRow, verbose: boolean): {
+interface InspectRunClock {
+    now(): number;
+    wait(ms: number, signal: AbortSignal): Promise<void>;
+}
+declare function formatRun(r: CortexRunRow, verbose: boolean, exposePaths?: boolean): {
     error?: string | null | undefined;
     synthesisReason?: string | undefined;
     runId: string;
@@ -49,8 +60,15 @@ declare function formatRun(r: CortexRunRow, verbose: boolean): {
     synthesisPath: string | null;
     synthesisStatus: "failed" | "produced" | "skipped_no_summaries" | "skipped_blocker" | null;
 };
-export declare function createInspectRunTool(pool: Pool): import("../define-tool.js").Tool<{
+/**
+ * Build the run-inspection tool. The optional clock is an internal testing
+ * seam for deterministic cutoff and transition coverage.
+ */
+export declare function createInspectRunTool(pool: Pool, clock?: InspectRunClock): import("../define-tool.js").Tool<{
     runId?: string | undefined;
+    page?: number | undefined;
+    pageSize?: number | undefined;
+    waitForTerminalSeconds?: number | undefined;
     includeDiagnostics?: boolean | undefined;
 }, InspectRunOutput>;
 export {};

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

@@ -209,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
@@ -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