@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/workflows/execute-analysis.js

@@ -50,20 +50,25 @@
  *       the run before any step starts
  *     - a `suspend` error of a synthesis model request suspends the run in
  *       place of the synthesis failure
- *     - the analysis flips to `suspended_insufficient_funds` in
- *       `collectAndComplete`. The paused parent lands in `CANCELLED`, a
+ *     - the run row and the analysis flip to `suspended_insufficient_funds` in
+ *       `collectAndComplete`. The run status is terminal and does not block a
+ *       new run of the plan. The paused parent lands in `CANCELLED`, a
  *       durably reschedulable state; re-driving it is a future enhancement,
  *       not yet wired here. The reason of the host rides to the run row, the
  *       charge close, the metric, and the terminal part, unread.
  *  5. `synthesizeFindings` (single sequential block, no sandbox)
  *  6. `collectAndComplete` (terminal — runs on ALL paths)
  *     - determine final status from completed/cancelled/failed counts
- *     - update `cortex_runs.status` + `error`, and inside that same step record
- *       the run outcome metric plus the outcome of every settled step whose
- *       child never wrote its own terminal row (a cancelled child, or one that
- *       died before `failStep`)
- *     - close running charge with matching reason
- *     - revoke run authorization via the injected `runAuthorizer` seam
+ *     - update `cortex_runs.status` + `error`. When the write changes the row,
+ *       the same step emits `run_completed` before the commit, records the run
+ *       outcome metric plus the outcome of every settled step whose child never
+ *       wrote its own terminal row (a cancelled child, or one that died before
+ *       `failStep`), closes the running charge with the matching outcome, and
+ *       revokes the run authorization through the injected `runAuthorizer`
+ *     - the write retries with backoff on a failed transaction. When the write is
+ *       refused, or fails on each attempt, close and revoke in their own steps, then
+ *       emit `run_completed`. After a failed write the row stays `running`, so the
+ *       body records its run end as a workflow event for the run canceler
  *     - emit terminal stream part
  *     - WRITES NOTHING to the conversation thread (results are pull-only
  *       via `inspectRun`)
@@ -73,18 +78,20 @@ import { err, ok } from "neverthrow";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { forStep } from "../auth/types.js";
+import { RUN_END_EVENT_KEY } from "../execution/run-end-record.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { deliverNotice, passGate } from "../lib/hooks.js";
 import { ATTR_INFLEXA_STEP_ID, stableSpan } from "../lib/otel-spans.js";
 import { recordRunCompleted, recordStepCompleted, stepOutcomeOf } from "../lib/metrics.js";
-import { describeDbError } from "../lib/db-result.js";
+import { describeDbError, withTransaction } from "../lib/db-result.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { countArtifactsForRun, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, queryStepsByRun, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
+import { countArtifactsByRuns, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, queryStepsByRun, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
 import { addChatUsage, hasReportedUsage } from "../loop/metrics.js";
+import { flattenDataPart } from "../contracts/chat-frame.js";
 import { SYNTHESIS_AGENT_ID, loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
-import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing, emptyStepMemory } from "../prompts/briefing.js";
+import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing, emptyStepMemory, } from "../prompts/briefing.js";
 import { SYNTHESIS_STEP_ID, runDir, runStepDir, stepSubdir, stepWritePrefix, toSandboxPath } from "../workspace/paths.js";
-import { isChatDataPart } from "../sandbox/sandbox-step-translate.js";
+import { isChatDataPart, synthesisEmission } from "../sandbox/sandbox-step-translate.js";
 import { synthesizeRun } from "../app/synthesize-run.js";
 import { computeTopologicalLevels, scheduleReady, validatePlanDag } from "./execute-analysis-scheduler.js";
 import { recordCancelledChild } from "./metrics.js";
@@ -181,7 +188,7 @@ function observeRunGuarded(deps, observation) {
  * projection/timeout-propagation tests.
  */
 export function buildChildInput(args) {
-    const { input, stepId, level, runId, workflowId, prompt } = args;
+    const { input, stepId, level, runId, workflowId, prompt, templateBinding } = args;
     const resources = input.resourcesByStepId[stepId];
     if (!resources) {
         throw new Error(`executeAnalysis: step "${stepId}" missing from resourcesByStepId — every step must declare resources`);
@@ -203,6 +210,9 @@ export function buildChildInput(args) {
         // genuinely declared nothing, and it silently deletes every same-run edge
         // the step was entitled to.
         dependsOn: planStep.depends_on,
+        // Composed beside the seed, thus the same checkpoint carries both and a
+        // replay hands the child the binding its briefing describes.
+        ...(templateBinding ? { templateBinding } : {}),
         level,
         prompt,
         parentWorkflowId: workflowId,
@@ -220,13 +230,18 @@ export function buildChildInput(args) {
  * rendered any earlier (at plan submission, say) cannot mention them, and the
  * agent is left to rediscover its own upstream.
  *
- * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed string is
- * checkpointed and a replay returns it verbatim — the DB and disk are not read
- * again and cannot drift the seed under a recovered run. Never call it
- * unwrapped from the workflow body.
+ * The template contract of a grounded step is read with the package, and the
+ * plan settings are bound to it: the seed describes the binding, and the child
+ * input carries it, from one checkpoint. The child fetches nothing.
+ *
+ * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed seed is
+ * checkpointed and a replay returns it verbatim — the DB, the disk, and the
+ * knowledge service are not read again and cannot drift the seed under a
+ * recovered run. Never call it unwrapped from the workflow body.
  */
 export async function composeStepSeed(args) {
-    return composeStepBriefing(await gatherStepPackage(args));
+    const { briefing, templateBinding } = await gatherStepPackage(args);
+    return { prompt: composeStepBriefing(briefing), ...(templateBinding ? { templateBinding } : {}) };
 }
 /**
  * Do every read of one step's package and give the data its seed is rendered
@@ -240,6 +255,9 @@ export async function composeStepSeed(args) {
  * so an edit during a run reaches each later step, and two steps of one run
  * can carry different copies.
  *
+ * The contract of the template a grounded step renders is read here too, from
+ * the knowledge client, and the plan settings are bound to it.
+ *
  * A read failure throws (house rules): a swallowed error would be frozen into
  * the checkpointed seed and served to every replay of this step.
  */
@@ -280,12 +298,151 @@ export async function gatherStepPackage(args) {
         agentByStepId: input.agentByStepId,
         pool: deps.pool,
     });
+    const contract = await resolveTemplateContract(step, deps.knowledge);
+    return {
+        briefing: {
+            step,
+            workspace,
+            profile: profile?.result ?? null,
+            upstream,
+            memory: { goal: memory.goal, constraints: memory.constraints },
+            ...contract.briefing,
+        },
+        ...(contract.binding ? { templateBinding: contract.binding } : {}),
+    };
+}
+/** A served contract carries no `match`; the two refusals do. */
+function isTemplateContract(answer) {
+    return !("match" in answer);
+}
+/**
+ * Fetch the contract of the template a step grounds on, and bind the plan
+ * settings to it. A step without a template has no template part. A step
+ * with one and no way to read it (no client, no answer, or an unknown
+ * template) gets the reason, thus the seed reports the absence rather than
+ * hiding it, and no binding.
+ */
+async function resolveTemplateContract(step, client) {
+    const ref = step.grounding?.template;
+    if (!ref)
+        return { briefing: {} };
+    if (!client)
+        return { briefing: { templateNotRetrieved: "no knowledge client is bound" } };
+    const answer = await client.contract(ref);
+    if (!isTemplateContract(answer)) {
+        const reason = answer.match === "unavailable"
+            ? `the knowledge service did not answer: ${answer.reason}`
+            : `the knowledge service refused the lookup: ${answer.message}`;
+        return { briefing: { templateNotRetrieved: reason } };
+    }
+    return bindTemplateContract(ref, answer, step.grounding?.settings ?? [], {
+        stepId: step.id,
+        claims: step.grounding?.claims ?? [],
+        ...(step.grounding?.snapshot && step.grounding.snapshot !== "none" ? { snapshot: step.grounding.snapshot } : {}),
+    });
+}
+/** The version of a template reference (`tpl-x@1.0.0` gives `1.0.0`), or `undefined` when the reference has none. */
+function versionOfRef(ref) {
+    const at = ref.indexOf("@");
+    return at < 0 ? undefined : ref.slice(at + 1);
+}
+/** Two setting values agree when their JSON agrees: the values are scalars or lists of strings. */
+function sameSettingValue(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Whether a plan value is a value of the slot, and not a policy word. A
+ * procedure parameter and a template slot share a name, but not always a
+ * value domain: `min_samples = smallest_group_size` names a rule the agent
+ * applies, and the slot takes the resulting integer. Only a member of the
+ * enum of the slot, a number for a number slot, or a boolean for a boolean
+ * slot binds. A free-text slot never binds, because the host cannot tell a
+ * policy word from a value there.
+ */
+function fitsSlot(slot, value) {
+    if (slot.enum)
+        return typeof value === "string" && slot.enum.includes(value);
+    if (slot.type === "integer" || slot.type === "number")
+        return typeof value === "number";
+    if (slot.type === "boolean")
+        return typeof value === "boolean";
+    return false;
+}
+function bindTemplateContract(ref, contract, settings, grounding) {
+    const refVersion = versionOfRef(ref);
+    const versionMatches = refVersion === undefined || refVersion === contract.version;
+    const adaptable = contract.parameters.filter((slot) => slot.adaptable);
+    const adaptableNames = new Set(adaptable.map((slot) => slot.name));
+    const pinnedByName = new Map(contract.parameters.filter((slot) => !slot.adaptable).map((slot) => [slot.name, slot]));
+    const bound = [];
+    const unbound = [];
+    const slots = {};
+    const sources = {};
+    for (const setting of settings) {
+        const shown = `\`${setting.name}\` = ${JSON.stringify(setting.value)} (${setting.step})`;
+        if (!versionMatches) {
+            unbound.push(`${shown}: not bound, because the served version differs from the plan`);
+            continue;
+        }
+        if (adaptableNames.has(setting.name)) {
+            const slot = adaptable.find((candidate) => candidate.name === setting.name);
+            if (slot && !fitsSlot(slot, setting.value)) {
+                unbound.push(`${shown}: a policy of the plan, not a value of the \`${setting.name}\` slot (${slot.type}); state the value it gives`);
+                continue;
+            }
+            const prior = slots[setting.name];
+            if (prior !== undefined) {
+                if (!sameSettingValue(prior, setting.value))
+                    unbound.push(`${shown}: differs from the bound value ${JSON.stringify(prior)} of the same slot`);
+                continue;
+            }
+            slots[setting.name] = setting.value;
+            if (setting.source)
+                sources[setting.name] = setting.source;
+            bound.push({ name: setting.name, value: setting.value, source: setting.source ?? "plan" });
+            continue;
+        }
+        const pinned = pinnedByName.get(setting.name);
+        if (pinned) {
+            const pinnedValue = pinned.default === undefined ? "a fixed value" : JSON.stringify(pinned.default);
+            unbound.push(sameSettingValue(pinned.default, setting.value)
+                ? `${shown}: pinned by the template at the same value`
+                : `${shown}: the template pins \`${setting.name}\` at ${pinnedValue}, and the plan value cannot be sent`);
+            continue;
+        }
+        unbound.push(`${shown}: no slot of the template carries it`);
+    }
     return {
-        step,
-        workspace,
-        profile: profile?.result ?? null,
-        upstream,
-        memory: { goal: memory.goal, constraints: memory.constraints },
+        briefing: {
+            template: {
+                ref,
+                version_served: contract.version,
+                slots: adaptable,
+                inputs: (contract.inputs ?? []).map((input) => ({
+                    name: input.name,
+                    path: input.path,
+                    ...(input.description ? { description: input.description } : {}),
+                })),
+                bound,
+                unbound_settings: unbound,
+            },
+        },
+        ...(versionMatches
+            ? {
+                binding: {
+                    template: ref,
+                    slots,
+                    sources,
+                    step: grounding.stepId,
+                    claims: grounding.claims,
+                    ...(grounding.snapshot ? { snapshot: grounding.snapshot } : {}),
+                    // The local slots of the contract, thus the tool binds a path or a column name on the machine
+                    // without a second read of the contract.
+                    local: contract.parameters.filter((slot) => slot.local === true),
+                    adaptable: adaptable.map((slot) => slot.name),
+                },
+            }
+            : {}),
     };
 }
 /**
@@ -359,9 +516,20 @@ export function synthesisRowUpdate(outcome, durationMs) {
  */
 export function synthesizeFindings(args) {
     const { analysisId, runId, completedSteps, session, deps } = args;
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis.synthesis");
+    // Observation is a diagnostic channel: a failed progress write is logged and never fails the synthesis.
+    let progressSeq = 0;
+    const writeProgressAlone = async (part, phase) => {
+        try {
+            await DBOS.writeStream("events", part);
+        }
+        catch (err) {
+            logger.warn("synthesis progress write failed (non-fatal)", { phase, ...logger.errorFields(err) });
+        }
+    };
     const emit = (event) => {
         const part = isChatDataPart(event)
-            ? event
+            ? flattenDataPart(event)
             : {
                 type: "data-loop-event",
                 data: { stepId: "synthesis", event },
@@ -395,14 +563,15 @@ export function synthesizeFindings(args) {
         // call path.
         session: forStep(session, SYNTHESIS_STEP_ID),
         emit,
-        onProgress: (phase, activity, extra = {}) => DBOS.writeStream("events", {
-            type: "data-synthesis-progress",
-            id: `synthesis-progress-${runId}`,
-            runId,
-            phase,
-            activity,
-            ...extra,
-        }),
+        onProgress: async (phase, activity, extra = {}) => {
+            // Synthesis runs inside one `DBOS.runStep`, thus `DBOS.now()` reads the wall clock here, and a rerun of
+            // the step after a crash writes its entries again under the same ids. A reader dedups an entry by id.
+            const seq = progressSeq++;
+            const at = new Date(await DBOS.now()).toISOString();
+            const parts = synthesisEmission(runId, SYNTHESIS_STEP_ID, seq, phase, activity, at, extra);
+            await writeProgressAlone(parts.progress, phase);
+            await writeProgressAlone(parts.entry, phase);
+        },
     });
 }
 // ── Workflow registration ────────────────────────────────────────────
@@ -847,17 +1016,21 @@ async function runSchedulerLoop(args) {
             // can be named. Checkpointed so a replay re-dispatches the child
             // with a byte-identical prompt instead of re-reading the DB/disk.
             const seedStepName = `compose-step-seed:${stepId}`;
-            const prompt = await DBOS.runStep(() => {
+            const checkpointed = await DBOS.runStep(() => {
                 stableSpan(seedStepName, "compose-step-seed", { [ATTR_INFLEXA_STEP_ID]: stepId });
                 return composeStepSeed({ input, stepId, runId, deps });
             }, { name: seedStepName });
+            // A run recovered from a checkpoint written when this step returned the
+            // bare seed string replays that string: it carries no binding.
+            const seed = typeof checkpointed === "string" ? { prompt: checkpointed } : checkpointed;
             const baseChildInput = buildChildInput({
                 input,
                 stepId,
                 level: levels.get(stepId) ?? 0,
                 runId,
                 workflowId,
-                prompt,
+                prompt: seed.prompt,
+                ...(seed.templateBinding ? { templateBinding: seed.templateBinding } : {}),
             });
             const childInput = {
                 ...baseChildInput,
@@ -1038,6 +1211,9 @@ async function cancelInFlight(inFlight, cause, canceledByParent) {
         recordCancelledChild({ cause });
     }
 }
+// ── (6) collectAndComplete ────────────────────────────────────────────
+/** The waits between the attempts are 1, 2, 4, and 8 seconds. */
+const FINAL_STATUS_WRITE_RETRY = { retriesAllowed: true, maxAttempts: 5, intervalSeconds: 1, backoffRate: 2 };
 async function collectAndComplete(args) {
     const { input, runId, workflowId, startedAtMs, completed, failed, canceled, suspension, failureReason, forceFailed, deps } = args;
     // A forced failure is terminal and never a resumable suspension.
@@ -1066,18 +1242,9 @@ async function collectAndComplete(args) {
             : suspended !== null
                 ? "workflow-suspended"
                 : "workflow-canceled";
-    // Terminal clock read + run-completion provenance, emitted BEFORE the `cortex_runs`
-    // status write below — and thus before any of the terminal cleanup steps. The CLI
-    // watches the run by POLLING that row (`run.ts` `waitForRunTerminal`) and shuts down
-    // the instant it leaves `running`, flushing provenance and then `process.exit()`ing;
-    // emitting the record only after the status write races that shutdown and can drop
-    // the run's terminal provenance entirely. Emitting first makes the record dirty
-    // (synchronously, via the bus) before the row can be observed terminal, so the CLI's
-    // flush always captures it. Not step-wrapped — a DBOS recovery replay must re-fire it;
-    // `DBOS.now()` is checkpointed, so the span stays replay-stable (see `RunProvenanceEvent`).
-    // The duration measures from the `run_started` read threaded in as `startedAtMs`.
+    const finalError = failureReason ?? (status === "canceled" ? "external_cancel" : null);
     const terminalAtMs = await DBOS.now();
-    emitProvenanceGuarded(deps, {
+    const emitRunEnd = () => emitProvenanceGuarded(deps, {
         type: "run_completed",
         analysisId: input.analysisId,
         runId,
@@ -1085,12 +1252,58 @@ async function collectAndComplete(args) {
         atMs: terminalAtMs,
         durationMs: terminalAtMs - startedAtMs,
     }, input.runSession);
-    await ledgerStep(logger.with({ status }), "persist-final-status", async () => {
-        const written = await updateRunStatus(deps.pool, runId, status, failureReason ?? (status === "canceled" && suspended === null ? "external_cancel" : null));
-        if (written.isErr())
-            return written;
-        // The outcome metrics ride inside the step that persists the terminal status: DBOS
-        // caches the step, so a recovered body records nothing again. A step's own terminal
+    // Ownership defaults to true for inputs persisted before the field existed (a
+    // workflow recovered across this deploy) — those were always Cortex-owned.
+    const authorization = {
+        runSession: input.runSession,
+        ownsMandate: input.ownsMandate ?? true, // oss-core-managed-ok
+    };
+    const closeCharge = () => deliverNotice(logger.with({ chargeOutcome: chargeOutcome.kind }), "RunCharge.close", deps.runCharge.close({
+        analysisId: input.analysisId,
+        runId,
+        outcome: chargeOutcome,
+        session: input.runSession,
+    }));
+    const revokeAuthorization = () => deliverNotice(logger.with({ revokeReason }), "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, revokeReason));
+    // The writer that wins the row owns the run end: the `run_completed` emit, the charge close,
+    // and the revoke. The step does all three when its write changes the row. An engine cancel
+    // cannot stop a step that started, so a won write is never cut before these acts.
+    //
+    // The emit rides inside the transaction of the write. The update holds the row lock until the
+    // commit, so the run canceler waits and then loses, and no reader sees the terminal row before
+    // the emit. The cli polls the row and flushes the provenance when it leaves `running`; an emit
+    // after the commit can miss that flush. `emitRunEvent` returns `void`, so the emit completes before the commit.
+    //
+    // DBOS retries only a thrown error, so an attempt before the last throws on a failed transaction.
+    // The last attempt returns "failed" instead: the body takes the failed path with no `try`, and a
+    // failure of DBOS to record a won step cannot be mistaken for a failed write. A commit can fail
+    // after the emit, so `emittedInStep` keeps the later attempts from emitting again.
+    let emittedInStep = false;
+    const finalWrite = await DBOS.runStep(async () => {
+        const stepLog = logger.with({ status }).named("persist-final-status");
+        const written = await withTransaction(deps.pool, "runs.persistFinalStatus", (client) => updateRunStatus(client, runId, status, finalError).map((changed) => {
+            if (changed && !emittedInStep) {
+                emitRunEnd();
+                emittedInStep = true;
+            }
+            return changed;
+        }));
+        if (written.isErr()) {
+            const attempt = DBOS.stepStatus;
+            const isLastAttempt = attempt?.currentAttempt === undefined || attempt.maxAttempts === undefined || attempt.currentAttempt >= attempt.maxAttempts;
+            const failure = { error: describeDbError(written.error), ...stepLog.errorFields(written.error.cause) };
+            if (isLastAttempt) {
+                stepLog.error("ledger write failed", failure);
+                return "failed";
+            }
+            stepLog.warn("ledger write failed, the step retries", { ...failure, attempt: attempt.currentAttempt });
+            throw new Error(`ledger write failed: ${describeDbError(written.error)}`, { cause: written.error.cause });
+        }
+        // A refused write means an earlier write already set a terminal status: the run
+        // canceler's, or an earlier run of this step before a crash. That writer owns the run end.
+        if (!written.value)
+            return "refused";
+        // DBOS caches the step, so a recovered body records nothing again. A step's own terminal
         // row already carried its metric; the residue counted here is every settled step
         // without one — a child the cancel cut before `mark-canceled` (the cancel check runs
         // before a step body), or one that died before `failStep`. The ledger read is kept
@@ -1107,8 +1320,41 @@ async function collectAndComplete(args) {
                 recordStepCompleted({ agentId: row.agentId, status: "failed" });
         }
         recordRunCompleted({ workflow: "analysis", status, durationMs: terminalAtMs - startedAtMs });
-        return written;
-    });
+        await closeCharge();
+        await revokeAuthorization();
+        return "won";
+    }, { name: "persist-final-status", ...FINAL_STATUS_WRITE_RETRY });
+    // A refused write leaves two owners. When the canceler won, its engine cancel came before its
+    // write, so `close-running-charge` throws the cancel and the body does no act of the run end.
+    // When a recovery runs the status step again after its own write landed, no cancel occurred and
+    // the body completes the run end here. A failed write leaves the row `running` with no owner,
+    // and the body still closes and revokes.
+    let closed = false;
+    let revoked = false;
+    if (finalWrite !== "won") {
+        closed = await DBOS.runStep(closeCharge, { name: "close-running-charge" });
+        revoked = await DBOS.runStep(revokeAuthorization, { name: "revoke-run-auth" });
+    }
+    // The step emits only in the execution that ran it. A won step that DBOS gives from the cache
+    // did not run, and a refused or failed write did not emit; the body fires the run end here
+    // with the same checkpointed values. It is not step-wrapped, so a recovery replay fires it again.
+    if (!emittedInStep)
+        emitRunEnd();
+    // After a failed write the row is not terminal, so the body records its run end for the run
+    // canceler. The record comes after the acts: a cancel before it stops the body and the canceler
+    // then owns the run end. A cancel is the only error that goes back to DBOS; a failed record must
+    // not undo an otherwise-complete run, like the sibling terminal steps.
+    if (finalWrite === "failed") {
+        const recorded = { status, error: finalError, closed, revoked };
+        try {
+            await DBOS.setEvent(RUN_END_EVENT_KEY, recorded);
+        }
+        catch (error) {
+            if (error instanceof DBOSErrors.DBOSWorkflowCancelledError)
+                throw error;
+            logger.error("run end record failed, the run canceler acts as for a run with no record", { status, ...logger.errorFields(error) });
+        }
+    }
     // Record the run's synthesis outcome AFTER the status write — a reader that
     // sees a terminal status then also sees whether (and why) synthesis ran. A
     // null outcome means synthesis never ran; leave the columns NULL ("unknown").
@@ -1119,39 +1365,21 @@ async function collectAndComplete(args) {
         await ledgerStep(logger.with({ synthesisStatus: outcome.status }), "persist-synthesis-outcome", () => setRunSynthesisOutcome(deps.pool, runId, outcome.status, outcome.reason));
     }
     // Sweep never-started steps to `skipped` — but ONLY on genuinely-terminal
-    // paths. The gate is the BRANCH, not the written run status: the resumable
-    // suspension below also writes "canceled", yet its pending rows must survive
-    // for the resumed workflow to execute. Log-don't-rollback, like every other
-    // finalisation step here.
+    // paths. The gate is the BRANCH, not the written run status: the pending rows
+    // of a suspended run must survive for a later resume. Log-don't-rollback, like
+    // every other finalisation step here.
     if (suspended === null) {
         await ledgerStep(logger, "sweep-pending-steps", () => sweepPendingStepExecutions(deps.pool, runId));
     }
     if (suspended !== null) {
         await ledgerStep(logger, "suspend-analysis", () => suspendAnalysisQuery(deps.pool, input.analysisId));
     }
-    await DBOS.runStep(() => deliverNotice(logger.with({ chargeOutcome: chargeOutcome.kind }), "RunCharge.close", deps.runCharge.close({
-        analysisId: input.analysisId,
-        runId,
-        outcome: chargeOutcome,
-        session: input.runSession,
-    })), { name: "close-running-charge" });
-    // Revoke the run authorization for the terminal run state. Ownership
-    // defaults to true for inputs persisted before the field existed (a
-    // workflow recovered across this deploy) — those were always Cortex-owned.
-    const authorization = {
-        runSession: input.runSession,
-        ownsMandate: input.ownsMandate ?? true, // oss-core-managed-ok
-    };
-    await DBOS.runStep(() => deliverNotice(logger.with({ revokeReason }), "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, revokeReason)), {
-        name: "revoke-run-auth",
-    });
-    // The `run_completed` provenance was already emitted above (before the status write, to
-    // beat the CLI's poll-and-shutdown). These branches only fan out the UI stream part, whose
+    // The run end was emitted above. These branches only fan out the UI stream part, whose
     // completed/failed shapes genuinely differ — the provenance record does not.
     if (status === "completed" || status === "partial") {
-        const artifactCount = await DBOS.runStep(async () => await countArtifactsForRun(deps.pool, input.analysisId, runId).unwrapOr(0), {
-            name: "count-run-artifacts",
-        });
+        const artifactCount = await DBOS.runStep(async () => await countArtifactsByRuns(deps.pool, input.analysisId, [runId])
+            .map((counts) => counts[0]?.count ?? 0)
+            .unwrapOr(0), { name: "count-run-artifacts" });
         await emitStreamPart({
             type: "data-run-completed",
             runId,
@@ -1197,7 +1425,7 @@ async function collectAndComplete(args) {
 function deriveFinalStatus(args) {
     const { totalSteps, completed, failed, canceled, suspended } = args;
     if (suspended)
-        return "canceled";
+        return "suspended_insufficient_funds";
     if (failed.size > 0) {
         return completed.size > 0 ? "partial" : "failed";
     }

package/dist/workflows/plan/graph.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The graph of a stored plan: each step with its agent, its dependencies, and its
+ * level. The levels and the agent fallback are those of `data-dag-state`, so a
+ * host draws the same graph before, during, and after a run.
+ */
+import type { PlanGraphStep } from "../../contracts/chat-parts.js";
+/**
+ * Give the graph of a stored plan document, in the order of the plan. An empty
+ * step list gives an empty graph. A document that fails the stored plan schema, or
+ * whose steps have a duplicate id, a missing dependency, or a cycle, gives `null`
+ * (a plan that no run can execute has no levels).
+ *
+ * The throw of `validatePlanDag` is caught here, at the boundary: the function is a
+ * read for a caller that has no use for the typed error.
+ */
+export declare function planGraphOf(plan: unknown): PlanGraphStep[] | null;

package/dist/workflows/plan/graph.js

@@ -0,0 +1,36 @@
+/**
+ * The graph of a stored plan: each step with its agent, its dependencies, and its
+ * level. The levels and the agent fallback are those of `data-dag-state`, so a
+ * host draws the same graph before, during, and after a run.
+ */
+import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
+import { computeTopologicalLevels, validatePlanDag } from "../execute-analysis-scheduler.js";
+/**
+ * Give the graph of a stored plan document, in the order of the plan. An empty
+ * step list gives an empty graph. A document that fails the stored plan schema, or
+ * whose steps have a duplicate id, a missing dependency, or a cycle, gives `null`
+ * (a plan that no run can execute has no levels).
+ *
+ * The throw of `validatePlanDag` is caught here, at the boundary: the function is a
+ * read for a caller that has no use for the typed error.
+ */
+export function planGraphOf(plan) {
+    const parsed = AnalysisPlanSchema.safeParse(plan);
+    if (!parsed.success)
+        return null;
+    const steps = parsed.data.steps;
+    try {
+        validatePlanDag(steps);
+    }
+    catch {
+        return null;
+    }
+    const levels = computeTopologicalLevels(steps);
+    return steps.map((step) => ({
+        id: step.id,
+        name: step.name,
+        agent: step.agent ?? "unknown",
+        dependsOn: [...step.depends_on],
+        level: levels.get(step.id) ?? 0,
+    }));
+}

package/dist/workflows/sandbox-step.d.ts

@@ -49,6 +49,7 @@ import type { SandboxRef } from "../sandbox/types.js";
 import { ProvenanceCollector } from "../provenance/collector.js";
 import { type BlockerHolder } from "../tools/sandbox/report-blocker.js";
 import { type FileMetadataCell } from "../tools/sandbox/submit-file-metadata.js";
+import type { TemplateBinding } from "../tools/knowledge/template.js";
 /**
  * Input the parent hands the child. Must be JSON-serialisable — DBOS
  * persists this as the workflow's input row.
@@ -70,6 +71,17 @@ export interface SandboxStepInput {
      * rather than admitting unstable ones.
      */
     readonly dependsOn?: readonly string[];
+    /**
+     * The plan settings bound to the template of this step, composed by the
+     * parent at dispatch beside the seed. The agent factory hands it to
+     * `knowledge_template`, which merges the bound slots under the model
+     * values and refuses a silent change of one.
+     *
+     * Optional for the same reason as `dependsOn`: a durable input that
+     * predates the field recovers without it, and a step without a grounded
+     * template has nothing to bind. Absence means the model values ride alone.
+     */
+    readonly templateBinding?: TemplateBinding;
     /** Topological level — persisted on `cortex_step_executions.wave`. */
     readonly level: number;
     /** User-content prompt the agent receives as its initial message. */