@inflexa-ai/harness 0.8.0 → 0.10.0

package/dist/tools/report/preview-publisher.js

@@ -10,6 +10,26 @@
  * returns not-ok, so `preview_snapshot` short-circuits before touching
  * Chrome and the report still builds (submit_report is the only gate).
  */
+/**
+ * Renders a failed mint as the line an agent reads back from a preview tool.
+ *
+ * The failure shape is sparse by design: a realization with no HTTP transport
+ * behind it supplies neither a status nor, necessarily, a message. Naming a
+ * field the seam left unset would put the literal `status=undefined` in front
+ * of the model, so the message carries only what actually arrived. This lives
+ * beside the type because its whole job is to honour that type's optionality —
+ * every tool holding the seam owes the same message, and one of them owning
+ * the wording would make the others depend on a peer for a seam-wide concern.
+ */
+export function describeMintFailure(failure) {
+    const detail = [];
+    if (failure.status !== undefined)
+        detail.push(`status=${failure.status}`);
+    const message = failure.error.message?.trim();
+    if (message)
+        detail.push(message);
+    return detail.length > 0 ? `preview-access mint failed: ${detail.join(" ")}` : "preview-access mint failed";
+}
 /**
  * Local default — no hosted preview surface. Returns not-ok so the preview
  * tools surface a clear "unavailable" message and short-circuit before any

package/dist/tools/report/preview-snapshot.d.ts

@@ -10,10 +10,16 @@
  * Returned screenshot is base64-encoded PNG bytes; the agent can inspect
  * console errors / failed requests to decide whether to fix the template
  * or move on to submit_report.
+ *
+ * A seam that cannot mint is also reported through the injected `Logger`:
+ * this tool is the build's only visual verification, so an unavailable seam
+ * means that verification silently did not happen — a condition an operator
+ * has to be able to see without reading the model transcript.
  */
 import { type Tool } from "../define-tool.js";
 import { type ChromeConfig } from "../../lib/chrome.js";
-import type { PreviewPublisher } from "./preview-publisher.js";
+import type { Logger } from "../../lib/logger.js";
+import { type PreviewPublisher } from "./preview-publisher.js";
 import type { PreviewUrlCell } from "./mint-preview-url.js";
 export interface PreviewSnapshotToolState {
     readonly resourceId: string;
@@ -22,5 +28,7 @@ export interface PreviewSnapshotToolState {
     readonly previews: PreviewPublisher;
     readonly urlCell: PreviewUrlCell;
     readonly chrome: ChromeConfig;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
 }
 export declare function createPreviewSnapshotTool(state: PreviewSnapshotToolState): Tool;

package/dist/tools/report/preview-snapshot.js

@@ -10,15 +10,23 @@
  * Returned screenshot is base64-encoded PNG bytes; the agent can inspect
  * console errors / failed requests to decide whether to fix the template
  * or move on to submit_report.
+ *
+ * A seam that cannot mint is also reported through the injected `Logger`:
+ * this tool is the build's only visual verification, so an unavailable seam
+ * means that verification silently did not happen — a condition an operator
+ * has to be able to see without reading the model transcript.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { withPage } from "../../lib/chrome.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { describeMintFailure } from "./preview-publisher.js";
 const NAV_TIMEOUT_MS = 20_000;
 const READY_TIMEOUT_MS = 8_000;
 const WAIT_MS_CAP = 30_000;
 export function createPreviewSnapshotTool(state) {
+    const logger = (state.logger ?? createNoopLogger()).named("preview-snapshot").with({ previewId: state.previewId });
     return defineTool({
         id: "preview_snapshot",
         description: "Render the report in a real headless browser and report what you " +
@@ -48,11 +56,17 @@ export function createPreviewSnapshotTool(state) {
             if (!url) {
                 const result = await state.previews.mintPreviewAccess(state.resourceId, state.previewId);
                 if (!result.ok) {
+                    const reason = result.error.message?.trim();
+                    logger.warn("preview access unavailable — visual verification did not run", {
+                        version: state.currentVersion,
+                        ...(result.status !== undefined ? { status: result.status } : {}),
+                        ...(reason ? { reason } : {}),
+                    });
                     return ok({
                         ok: false,
                         consoleErrors: [],
                         failedRequests: [],
-                        error: `preview-access mint failed: status=${result.status} ${result.error.message ?? ""}`.trim(),
+                        error: describeMintFailure(result),
                     });
                 }
                 url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${state.currentVersion}/index.html?t=${result.data.token}`;

package/dist/tools/report/submit-report.d.ts

@@ -3,6 +3,7 @@
  * `data-report-preview` until this tool writes the success outcome.
  *
  * Checks:
+ *   - report.html.j2 exists at versionDir/ — the report itself
  *   - index.html exists at versionDir/ with size > 0
  *   - no unrendered `{{ … }}` or `{% … %}` left in the output
  *   - all referenced asset paths resolve to files on disk

package/dist/tools/report/submit-report.js

@@ -3,6 +3,7 @@
  * `data-report-preview` until this tool writes the success outcome.
  *
  * Checks:
+ *   - report.html.j2 exists at versionDir/ — the report itself
  *   - index.html exists at versionDir/ with size > 0
  *   - no unrendered `{{ … }}` or `{% … %}` left in the output
  *   - all referenced asset paths resolve to files on disk
@@ -23,26 +24,46 @@ const UNRENDERED_JINJA = /\{\{[^{}]*\}\}|\{%-?\s*\w/;
 export function createSubmitReportTool(state) {
     return defineTool({
         id: "submit_report",
-        description: "Declare the report ready. Validates index.html exists, has no " +
-            "unrendered Jinja, and that all referenced asset paths resolve. " +
+        description: "Declare the report ready. Validates report.html.j2 and index.html " +
+            "exist, that the output has no unrendered Jinja, and that all " +
+            "referenced asset paths resolve. " +
             "You MUST call this to finish — the runner ignores any other claim " +
             "of success. Returns problems[] when checks fail; fix and re-submit. " +
-            "Use `notes` to surface caveats to the caller (e.g. files skipped due " +
-            "to the 50MB asset size limit, sections rendered with partial data, " +
-            "missing inputs that forced a fallback) — these reach the conversation " +
-            "agent and the user in the iteration result.",
+            "Use `notes` to surface caveats to the caller (e.g. sections rendered " +
+            "with partial data, missing inputs that forced a fallback) — these " +
+            "reach the conversation agent and the user in the iteration result.",
         inputSchema: z.object({
             notes: z
                 .array(z.string())
                 .optional()
                 .describe("Caveats / issues to surface to the caller. One short sentence " +
-                "per item. Examples: 'skipped raw_counts.h5ad (1.2GB > 50MB cap)', " +
-                "'pathway-enrichment section omitted — no GSEA output found'. " +
+                "per item. Examples: 'pathway-enrichment section omitted — no " +
+                "GSEA output found', 'cohort table rendered from 8 of 12 " +
+                "samples — the rest had no QC row'. " +
                 "Leave empty when the report shipped cleanly."),
         }),
         execute: async (input) => {
             const problems = [];
-            // 1. index.html exists and is non-empty
+            // 1. report.html.j2 exists — the report itself, as opposed to the
+            // artifact rendered from it. Nothing downstream re-derives this: a
+            // version that is finalized without a template persists as one, and
+            // the next iteration copies a template that isn't there, then tells
+            // the builder to edit it in place. Checked first because an absent
+            // template is the cause the checks below can only report symptoms of.
+            const templatePath = join(state.versionDir, "report.html.j2");
+            let hasTemplate;
+            try {
+                hasTemplate = (await stat(templatePath)).isFile();
+            }
+            catch {
+                hasTemplate = false;
+            }
+            if (!hasTemplate) {
+                problems.push("report.html.j2 is missing — a report is authored as report.html.j2 and " +
+                    "rendered into index.html by build_report; a hand-written index.html is " +
+                    "not a report. Write the template, then call build_report.");
+            }
+            // 2. index.html exists and is non-empty
             const indexPath = join(state.versionDir, "index.html");
             let html;
             try {
@@ -57,13 +78,13 @@ export function createSubmitReportTool(state) {
                 problems.push("index.html does not exist — call build_report first");
                 return ok({ ok: false, problems });
             }
-            // 2. No unrendered Jinja markers
+            // 3. No unrendered Jinja markers
             if (UNRENDERED_JINJA.test(html)) {
                 const match = html.match(UNRENDERED_JINJA);
                 problems.push(`unrendered Jinja in output (e.g. ${JSON.stringify(match?.[0] ?? "")}); ` +
                     "build_report likely failed silently or report.html.j2 was edited after build");
             }
-            // 3. Asset reference resolution
+            // 4. Asset reference resolution
             const refs = extractLocalRefs(html);
             for (const ref of refs) {
                 const resolved = resolveLocalRef(ref, state.versionDir, state.assetsDir);

package/dist/tools/report/version-fs.d.ts

@@ -2,10 +2,10 @@
  * In-process workspace surface for the report-builder agent.
  *
  * Tight read/write/mkdir surface scoped to the version directory.
- * Agent-supplied paths are resolved against `versionDir`; any path that
- * escapes is rejected as `out_of_scope`. Constructed inside the
- * iterate-report runner so it always shares the same `versionDir` as the
- * rest of the report tools.
+ * Agent-supplied paths are relative to `versionDir`; an absolute path, or one
+ * that escapes the directory, is rejected as `out_of_scope`. Constructed
+ * inside the iterate-report runner so it always shares the same `versionDir`
+ * as the rest of the report tools.
  */
 import { type Tool } from "../define-tool.js";
 export interface VersionFsToolsState {

package/dist/tools/report/version-fs.js

@@ -2,10 +2,10 @@
  * In-process workspace surface for the report-builder agent.
  *
  * Tight read/write/mkdir surface scoped to the version directory.
- * Agent-supplied paths are resolved against `versionDir`; any path that
- * escapes is rejected as `out_of_scope`. Constructed inside the
- * iterate-report runner so it always shares the same `versionDir` as the
- * rest of the report tools.
+ * Agent-supplied paths are relative to `versionDir`; an absolute path, or one
+ * that escapes the directory, is rejected as `out_of_scope`. Constructed
+ * inside the iterate-report runner so it always shares the same `versionDir`
+ * as the rest of the report tools.
  */
 import { mkdir as fsMkdir, readFile as fsReadFile, stat as fsStat, writeFile as fsWriteFile } from "node:fs/promises";
 import { dirname, resolve as resolvePath, sep } from "node:path";
@@ -19,13 +19,15 @@ function resolveAgentPath(agentPath, versionDir) {
     if (agentPath.length === 0 || agentPath.includes("\0")) {
         return { kind: "out_of_scope", reason: "empty or null-byte path" };
     }
-    // Strip a leading slash so an agent typing "/index.html" is treated as
-    // "index.html" relative to versionDir (the version dir is the root).
-    const stripped = agentPath.replace(/^\/+/, "");
-    if (!stripped) {
-        return { kind: "out_of_scope", reason: "path resolves to the version dir itself" };
+    // A leading slash is refused rather than trimmed. Trimming it makes the
+    // containment check below unreachable for absolute paths: a deep one such
+    // as "/previews/abc/v1/report.html.j2" would land a real file several
+    // directories below versionDir and report success, and the builder — which
+    // has no directory-listing tool — cannot find where its template went.
+    if (agentPath.startsWith("/")) {
+        return { kind: "out_of_scope", reason: `absolute path rejected, use one relative to the version dir: ${agentPath}` };
     }
-    const absolute = resolvePath(versionDir, stripped);
+    const absolute = resolvePath(versionDir, agentPath);
     if (absolute !== versionDir && !absolute.startsWith(versionDir + sep)) {
         return { kind: "out_of_scope", reason: `path escapes version dir: ${agentPath}` };
     }
@@ -34,9 +36,10 @@ function resolveAgentPath(agentPath, versionDir) {
 export function createVersionFsTools(state) {
     const writeFile = defineTool({
         id: "write_file",
-        description: "Write a UTF-8 text file under the report's version directory. Use " +
-            "relative paths (e.g. `report.html.j2`, `assets/foo.csv`). Returns " +
-            "`out_of_scope` for any path that escapes the version dir.",
+        description: "Write a UTF-8 text file under the report's version directory. Paths " +
+            "are relative to it (e.g. `report.html.j2`, `assets/foo.csv`); an " +
+            "absolute path, or one that escapes the version dir, returns " +
+            "`out_of_scope` and writes nothing.",
         inputSchema: z.object({
             path: z.string().min(1),
             content: z.string(),
@@ -62,8 +65,9 @@ export function createVersionFsTools(state) {
         id: "edit_file",
         description: "Surgical edit of an existing UTF-8 file inside the report's version " +
             "directory: replace the first occurrence of `oldText` with `newText`. " +
-            "Returns `not_found` if the file doesn't exist, `no_match` if " +
-            "`oldText` isn't present.",
+            "Paths are relative to that directory; an absolute or escaping path " +
+            "returns `out_of_scope`. Returns `not_found` if the file doesn't " +
+            "exist, `no_match` if `oldText` isn't present.",
         inputSchema: z.object({
             path: z.string().min(1),
             oldText: z.string().min(1),
@@ -102,7 +106,9 @@ export function createVersionFsTools(state) {
     });
     const readFile = defineTool({
         id: "read_file",
-        description: "Read a UTF-8 file inside the report's version directory. Returns " + "truncated content (capped at 256 KiB) for large files.",
+        description: "Read a UTF-8 file inside the report's version directory. Paths are " +
+            "relative to it; an absolute or escaping path returns `out_of_scope`. " +
+            "Returns truncated content (capped at 256 KiB) for large files.",
         inputSchema: z.object({
             path: z.string().min(1),
         }),
@@ -137,7 +143,8 @@ export function createVersionFsTools(state) {
     });
     const mkdir = defineTool({
         id: "mkdir",
-        description: "Create a directory (recursive) inside the report's version directory.",
+        description: "Create a directory (recursive) inside the report's version directory. " +
+            "Paths are relative to it; an absolute or escaping path returns `out_of_scope`.",
         inputSchema: z.object({
             path: z.string().min(1),
         }),

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

@@ -16,6 +16,7 @@ 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 { defineTool } from "../define-tool.js";
 function formatRun(r, verbose) {
@@ -73,9 +74,15 @@ export function createInspectRunTool(pool) {
                 agentId: s.agentId,
                 wave: s.wave,
                 status: s.status,
-                // Seeded rows exist before a step ever runs; a summary path for one
-                // would point the agent at a file that cannot exist yet (or ever).
-                ...(s.status === "pending" || s.status === "skipped" ? {} : { summaryPath: `runs/${input.runId}/${s.stepId}/output/summary.md` }),
+                // 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,

package/dist/tools/workspace/read-file.d.ts

@@ -30,6 +30,11 @@ type ReadFileOutput = {
 } | {
     status: "out_of_scope";
     path: string;
+} | {
+    status: "binary";
+    path: string;
+    mode: "head" | "tail" | "full";
+    totalSize?: number;
 };
 export declare function createReadFileTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
     path: string;

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

@@ -13,6 +13,18 @@ import { defineTool } from "../define-tool.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 /** Default cap — large enough for typical CSV/MD/JSON, small enough to keep tool results out of context-blowing territory. */
 const DEFAULT_MAX_BYTES = 256 * 1024;
+/**
+ * Treat returned content as binary when it contains a NUL byte — `grep`'s
+ * `looksBinary` heuristic, applied here to the whole returned window rather than
+ * a 1 KiB probe. These exact bytes are what would be UTF-8-decoded into the
+ * transcript, and a NUL both renders that decode as lossy garbage (useless to
+ * the model) and cannot be persisted into the JSONB message store — Postgres
+ * rejects U+0000 with 22P05, failing the whole turn's append. Reporting the
+ * read as `binary` keeps a NUL out of both.
+ */
+function looksBinary(content) {
+    return content.includes(0);
+}
 const ReadFileInputSchema = z.object({
     path: z
         .string()
@@ -45,8 +57,10 @@ export function createReadFileTool(fs, workingDir) {
             "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 " +
-            "paths outside the analysis tree return a data variant — not an error.",
+            "Oversize reads come back truncated with a marker. This tool is for " +
+            "text; a binary file (one holding NUL bytes, e.g. a .gz or image) comes " +
+            "back as a `binary` data variant rather than decoded garbage. Missing " +
+            "paths and paths outside the analysis tree return a data variant — not an error.",
         inputSchema: ReadFileInputSchema,
         execute: async ({ path, headLines, tailLines }, ctx) => {
             if (headLines !== undefined && tailLines !== undefined) {
@@ -67,6 +81,8 @@ export function createReadFileTool(fs, workingDir) {
             const mode = headLines !== undefined ? "head" : tailLines !== undefined ? "tail" : "full";
             switch (result.kind) {
                 case "ok":
+                    if (looksBinary(result.content))
+                        return ok({ status: "binary", path, mode });
                     return ok({
                         status: "ok",
                         path,
@@ -74,6 +90,8 @@ export function createReadFileTool(fs, workingDir) {
                         content: result.content.toString("utf8"),
                     });
                 case "truncated":
+                    if (looksBinary(result.content))
+                        return ok({ status: "binary", path, mode, totalSize: result.totalSize });
                     return ok({
                         status: "truncated",
                         path,

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

@@ -63,7 +63,7 @@ import type { MachineBudget, ResourceSpec } from "../config/resource-limits.js";
 import type { RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { Logger } from "../lib/logger.js";
-import type { SynthesisStatus } from "../state/index.js";
+import type { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
@@ -288,6 +288,19 @@ export declare function composeStepSeed(args: {
     runId: string;
     deps: ExecuteAnalysisDeps;
 }): Promise<string>;
+/**
+ * Project a classified synthesis outcome onto the run-phase `synthesis` ledger
+ * row's terminal update (see the run-synthesis-outcome spec). The blocker keeps
+ * its reason in `blockedReason` — an honest agent-declared blocker, not an
+ * error — and a failure carries the same reason string
+ * `persist-synthesis-outcome` writes to `cortex_runs.synthesis_reason`, so the
+ * two ledgers cannot disagree about why synthesis died. Exported for the
+ * projection tests (the `buildChildInput` pattern).
+ */
+export declare function synthesisRowUpdate(outcome: {
+    status: SynthesisStatus;
+    reason: string | null;
+}, durationMs: number): UpdateStepExecutionInput;
 /**
  * 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

@@ -58,17 +58,17 @@
  *     - WRITES NOTHING to the conversation thread (results are pull-only
  *       via `inspectRun`)
  */
-import { DBOS } from "@dbos-inc/dbos-sdk";
+import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { forStep } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { RunDedupCollisionError, countArtifactsForRun, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
+import { RunDedupCollisionError, countArtifactsForRun, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
-import { loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
+import { SYNTHESIS_AGENT_ID, 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 { SYNTHESIS_STEP_ID, 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";
@@ -222,6 +222,31 @@ async function collectUpstreamHandoffs(args) {
     }
     return handoffs;
 }
+/**
+ * Project a classified synthesis outcome onto the run-phase `synthesis` ledger
+ * row's terminal update (see the run-synthesis-outcome spec). The blocker keeps
+ * its reason in `blockedReason` — an honest agent-declared blocker, not an
+ * error — and a failure carries the same reason string
+ * `persist-synthesis-outcome` writes to `cortex_runs.synthesis_reason`, so the
+ * two ledgers cannot disagree about why synthesis died. Exported for the
+ * projection tests (the `buildChildInput` pattern).
+ */
+export function synthesisRowUpdate(outcome, durationMs) {
+    switch (outcome.status) {
+        case "produced":
+            return { status: "completed", durationMs };
+        case "skipped_no_summaries":
+            return { status: "skipped", durationMs };
+        case "skipped_blocker":
+            return { status: "blocked", durationMs, blockedReason: outcome.reason };
+        case "failed":
+            return { status: "failed", durationMs, error: outcome.reason };
+        default: {
+            const _exhaustive = outcome.status;
+            throw new Error(`unhandled synthesis status: ${String(_exhaustive)}`);
+        }
+    }
+}
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is
@@ -309,14 +334,32 @@ export async function runExecuteAnalysisBody(input, deps) {
     // The seed's DO NOTHING conflict action makes this replay-safe; the agent
     // fallback mirrors `buildChildInput` so seed and mark-running agree on the
     // row a step's child later upserts.
+    //
+    // The run-phase `synthesis` row is seeded alongside the DAG — gated on
+    // enablement ONLY, because the other half of the run gate for actually
+    // executing synthesis (`final.completed.size > 0`) is unknowable until the
+    // scheduler returns. A seeded row whose gate later fails simply stays
+    // `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 synthesisWave = Math.max(-1, ...levels.values()) + 1;
     await DBOS.runStep(async () => {
-        unwrapOrThrow(await seedStepExecutions(deps.pool, input.steps.map((step) => ({
+        const dagRows = input.steps.map((step) => ({
             runId,
             stepId: step.id,
             analysisId: input.analysisId,
             wave: levels.get(step.id) ?? 0,
             agentId: input.agentByStepId[step.id] ?? "scientific-executor",
-        }))));
+        }));
+        const synthesisRow = {
+            runId,
+            stepId: SYNTHESIS_STEP_ID,
+            analysisId: input.analysisId,
+            wave: synthesisWave,
+            agentId: SYNTHESIS_AGENT_ID,
+        };
+        unwrapOrThrow(await seedStepExecutions(deps.pool, synthesisEnabled ? [...dagRows, synthesisRow] : dagRows));
     }, { name: "seed-step-executions" });
     // One checkpointed clock read stamps the run's start; the terminal read in
     // `collectAndComplete` subtracts it for the true run span. Checkpointed →
@@ -352,10 +395,37 @@ export async function runExecuteAnalysisBody(input, deps) {
     let synthesisError = null;
     let synthesisFindings = [];
     // Null when synthesis never ran (disabled or no completed steps): the ledger
-    // columns stay NULL — "unknown", not a recorded skip.
+    // columns stay NULL — "unknown", not a recorded skip — and the seeded
+    // `synthesis` row (if any) stays `pending` for the terminal sweep.
     let synthesisOutcome = null;
-    const synthesisEnabled = deps.synthesisEnabled ?? true;
     if (synthesisEnabled && final.completed.size > 0) {
+        // Bracketing clock reads for the row's duration_ms — checkpointed, so a
+        // 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
+        // otherwise-healthy run. Cancellation still re-propagates — it is not a
+        // write failure, and swallowing it here would only defer it one operation.
+        try {
+            await DBOS.runStep(async () => {
+                unwrapOrThrow(await insertStepExecution(deps.pool, {
+                    runId,
+                    stepId: SYNTHESIS_STEP_ID,
+                    analysisId: input.analysisId,
+                    wave: synthesisWave,
+                    agentId: SYNTHESIS_AGENT_ID,
+                    childWorkflowId: null,
+                }));
+            }, { name: "mark-synthesis-running" });
+        }
+        catch (err) {
+            if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+                throw err;
+            logger.error("mark-synthesis-running failed", { runId, ...logger.errorFields(err) });
+        }
         try {
             const synthOut = await DBOS.runStep(() => synthesizeFindings({
                 analysisId: input.analysisId,
@@ -368,10 +438,37 @@ export async function runExecuteAnalysisBody(input, deps) {
             synthesisOutcome = { status: synthOut.synthesisStatus, reason: synthOut.synthesisReason };
         }
         catch (err) {
+            // Cancellation is not a synthesis outcome: re-propagate unchanged (the
+            // sandbox-step rule), so a cancelled workflow is never recorded as a
+            // synthesis failure — neither on the row nor in cortex_runs. The row is
+            // deliberately left `running`: `collectAndComplete` never executes on
+            // this path either, so the run row is equally non-terminal and the pair
+            // stays consistent — the pre-existing cancelled-mid-flight wedge shape
+            // `inflexa run` already detects via its DBOS-status cross-check.
+            if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+                throw err;
             synthesisError = err;
             synthesisOutcome = { status: "failed", reason: err instanceof Error ? err.message : String(err) };
             logger.error("synthesizeFindings failed — failing the run", { runId, ...logger.errorFields(err) });
         }
+        // Terminal stamp for the `synthesis` row — deliberately BEFORE
+        // `collectAndComplete` writes the run row's terminal status, so no reader
+        // can observe a terminal run beside a still-`running` synthesis row. Both
+        // branches above set `synthesisOutcome` (or threw), so it is non-null here
+        // and the compiler narrows it — no guard needed. Log-don't-fail, like the
+        // sibling finalisation writes.
+        const rowOutcome = synthesisOutcome;
+        try {
+            const synthEndedAtMs = await DBOS.now();
+            await DBOS.runStep(async () => {
+                unwrapOrThrow(await updateStepExecution(deps.pool, runId, SYNTHESIS_STEP_ID, synthesisRowUpdate(rowOutcome, synthEndedAtMs - synthStartedAtMs)));
+            }, { name: "persist-synthesis-step" });
+        }
+        catch (err) {
+            if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+                throw err;
+            logger.error("persist-synthesis-step failed", { runId, ...logger.errorFields(err) });
+        }
     }
     // (6) collectAndComplete — terminal block. Runs on EVERY path. When synthesis
     // failed, force a failed terminal status so the charge/run-authorization close correctly

package/dist/workspace/paths.d.ts

@@ -181,5 +181,15 @@ export declare function stepSubdir(stepBase: string, type: StepSubdirType): stri
 export declare function reportDir(reportId: string): string;
 /** All standard subdirectory types for a step. */
 export declare const STEP_SUBDIRS: readonly StepSubdirType[];
+/**
+ * Reserved id of the run-phase synthesis row in `cortex_step_executions` — the
+ * ledger row `executeAnalysis` writes for run-level synthesis so progress
+ * readers see the phase. Reserved here beside {@link STEP_SUBDIRS} because the
+ * reservation is a layout fact as much as a ledger one: a plan step with this
+ * id would collide with the row's primary key AND put its step directory
+ * `runs/{runId}/synthesis/` beside the run-level `runs/{runId}/synthesis.json`.
+ * Plan validation rejects it (see validate-plan).
+ */
+export declare const SYNTHESIS_STEP_ID = "synthesis";
 /** Get all subdirectory paths for a step. */
 export declare function allStepSubdirs(stepBase: string): string[];

package/dist/workspace/paths.js

@@ -213,6 +213,16 @@ export function reportDir(reportId) {
 }
 /** All standard subdirectory types for a step. */
 export const STEP_SUBDIRS = ["scripts", "output", "figures", "logs", "notebooks"];
+/**
+ * Reserved id of the run-phase synthesis row in `cortex_step_executions` — the
+ * ledger row `executeAnalysis` writes for run-level synthesis so progress
+ * readers see the phase. Reserved here beside {@link STEP_SUBDIRS} because the
+ * reservation is a layout fact as much as a ledger one: a plan step with this
+ * id would collide with the row's primary key AND put its step directory
+ * `runs/{runId}/synthesis/` beside the run-level `runs/{runId}/synthesis.json`.
+ * Plan validation rejects it (see validate-plan).
+ */
+export const SYNTHESIS_STEP_ID = "synthesis";
 /** Get all subdirectory paths for a step. */
 export function allStepSubdirs(stepBase) {
     return STEP_SUBDIRS.map((type) => stepSubdir(stepBase, type));

package/package.json

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