@inflexa-ai/harness 0.36.4 → 0.38.0

package/dist/tasks/derive-table-exec.d.ts

@@ -18,8 +18,10 @@
  * callback unroutable and it lands as a `400`. The pull backstop still settles such an exec, but it pays
  * the quiet interval first.
  */
+import { type Result } from "neverthrow";
 import type { Logger } from "../lib/logger.js";
 import type { SandboxClient } from "../sandbox/client.js";
+import { type Suspension } from "../workflows/suspension.js";
 import type { ExecResult } from "../sandbox/types.js";
 import { type DeriveTableExecInput } from "../tools/report-session/derive-table.js";
 /** The construction-time deps of the body. The registration closes over them, thus the trigger holds none. */
@@ -35,15 +37,17 @@ export interface DeriveTableExecDeps {
 /**
  * The body, exported so a test drives it without a registered workflow.
  *
- * A fault of any seam call throws. The tool reads a rejection as one short detail, thus the caller needs no
- * result type here.
+ * A fault of any seam call throws. The tool reads a rejection as one short detail. A chat turn awaits this
+ * workflow, thus a suspension is the `err` of the result, and the workflow does not cancel
+ * (workflow-suspension spec). The body does not mark the analysis: the tool reports the suspension to the
+ * conversation agent.
  */
-export declare function runDeriveTableExecBody(input: DeriveTableExecInput, deps: DeriveTableExecDeps): Promise<ExecResult>;
+export declare function runDeriveTableExecBody(input: DeriveTableExecInput, deps: DeriveTableExecDeps): Promise<Result<ExecResult, Suspension>>;
 /**
  * Register the derivation workflow with DBOS. It gives back the registered callable, thus a trigger
  * dispatches with `DBOS.startWorkflow`.
  */
-export declare function registerDeriveTableExecWorkflow(deps: DeriveTableExecDeps): (input: DeriveTableExecInput) => Promise<ExecResult>;
+export declare function registerDeriveTableExecWorkflow(deps: DeriveTableExecDeps): (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>;
 /**
  * The workflow id of one derivation.
  *
@@ -55,6 +59,6 @@ export declare function deriveTableExecWorkflowId(executionId: string): string;
  * The async edge. It starts the registered workflow and it awaits the terminal result.
  *
  * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
- * lifecycle of its own. A workflow fault rejects the returned promise.
+ * lifecycle of its own. A workflow fault rejects the returned promise, and a suspension is the `err`.
  */
-export declare function triggerDeriveTableExec(workflow: (input: DeriveTableExecInput) => Promise<ExecResult>, input: DeriveTableExecInput): Promise<ExecResult>;
+export declare function triggerDeriveTableExec(workflow: (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>, input: DeriveTableExecInput): Promise<Result<ExecResult, Suspension>>;

package/dist/tasks/derive-table-exec.js

@@ -19,16 +19,22 @@
  * the quiet interval first.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { err, ok } from "neverthrow";
+import { forStep } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
+import { suspensionOfSpawnRefusal } from "../workflows/suspension.js";
 import { buildDerivationExec, DERIVATION_DEADLINE_MS, DERIVATION_RESOURCES, DERIVE_RUN_LITERAL, DERIVE_STEP_LITERAL, } from "../tools/report-session/derive-table.js";
 /** The awaitExec callback. A derivation reports no live activity, thus the callback drops each event. */
 const noopEmit = () => { };
 /**
  * The body, exported so a test drives it without a registered workflow.
  *
- * A fault of any seam call throws. The tool reads a rejection as one short detail, thus the caller needs no
- * result type here.
+ * A fault of any seam call throws. The tool reads a rejection as one short detail. A chat turn awaits this
+ * workflow, thus a suspension is the `err` of the result, and the workflow does not cancel
+ * (workflow-suspension spec). The body does not mark the analysis: the tool reports the suspension to the
+ * conversation agent.
  */
 export async function runDeriveTableExecBody(input, deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("derive-table-exec").with({ analysisId: input.analysisId });
@@ -36,14 +42,13 @@ export async function runDeriveTableExecBody(input, deps) {
     // One workflow submits one exec, thus the function id is a constant. The three segments are what a
     // callback host parses to find the workflow that awaits this exec.
     const execId = `${workflowId}:${DERIVE_STEP_LITERAL}:fn-0`;
-    const sandbox = await deps.sandboxClient.createSandbox({
-        runId: DERIVE_RUN_LITERAL,
-        stepId: DERIVE_STEP_LITERAL,
-        analysisId: input.analysisId,
-        childWorkflowId: workflowId,
-        resources: DERIVATION_RESOURCES,
-        writableTail: input.writableTail,
-    }, mintSandboxIdentity(DERIVE_RUN_LITERAL));
+    const spawned = keepSuspendingRefusal(await deps.sandboxClient.createSandbox(forStep(input.runSession, DERIVE_STEP_LITERAL), { childWorkflowId: workflowId, resources: DERIVATION_RESOURCES, writableTail: input.writableTail }, mintSandboxIdentity(DERIVE_RUN_LITERAL)));
+    if (spawned.isErr()) {
+        const suspension = suspensionOfSpawnRefusal(spawned.error);
+        logger.warn("derivation suspended", { reason: suspension.reason });
+        return err(suspension);
+    }
+    const sandbox = spawned.value;
     try {
         // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
         // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
@@ -55,7 +60,7 @@ export async function runDeriveTableExecBody(input, deps) {
             inputs: input.inputs,
             output: input.output,
         }));
-        return await deps.sandboxClient.awaitExec(sandbox, execId, noopEmit, deadline);
+        return ok(await deps.sandboxClient.awaitExec(sandbox, execId, noopEmit, deadline));
     }
     finally {
         try {
@@ -86,7 +91,7 @@ export function deriveTableExecWorkflowId(executionId) {
  * The async edge. It starts the registered workflow and it awaits the terminal result.
  *
  * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
- * lifecycle of its own. A workflow fault rejects the returned promise.
+ * lifecycle of its own. A workflow fault rejects the returned promise, and a suspension is the `err`.
  */
 export async function triggerDeriveTableExec(workflow, input) {
     const handle = (await DBOS.startWorkflow(workflow, {

package/dist/tasks/extract-values.d.ts

@@ -11,11 +11,13 @@
  * authorization on every terminal path. The container is ephemeral, and it goes away with the work, thus no
  * standing machine exists.
  */
-import type { AuthContext, RunSession } from "../auth/types.js";
+import { type Result } from "neverthrow";
+import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { Logger } from "../lib/logger.js";
 import type { ExtractionArm, ExtractionArtifact, ExtractionRequest } from "../report-model/production-resolver.js";
 import type { SandboxClient } from "../sandbox/client.js";
+import { type Suspension } from "../workflows/suspension.js";
 import type { ExecResult, SubmitExecBody } from "../sandbox/types.js";
 import { type ExtractValuesResult } from "./extract-values-script.js";
 export type { ExtractValuesResult } from "./extract-values-script.js";
@@ -71,13 +73,16 @@ export declare function parseExtractionOutput(result: ExecResult): ExtractValues
  * The body, extracted so a test drives it without a registered workflow. It creates the ephemeral
  * container, submits one exec, awaits the result durably, and gives the value map back. It revokes the run
  * authorization on every terminal path, and it tears the container down on both paths.
+ *
+ * A chat turn awaits this workflow, thus a suspension is the `err` of the result, and the workflow does not
+ * cancel (workflow-suspension spec). The body does not mark the analysis: the caller reports the suspension.
  */
-export declare function runExtractValuesBody(input: ExtractValuesWorkflowInput, deps: ExtractValuesDeps): Promise<ExtractValuesResult>;
+export declare function runExtractValuesBody(input: ExtractValuesWorkflowInput, deps: ExtractValuesDeps): Promise<Result<ExtractValuesResult, Suspension>>;
 /**
  * Register the extraction workflow with DBOS. It gives back the registered callable, thus a trigger
  * dispatches with `DBOS.startWorkflow`.
  */
-export declare function registerExtractValuesWorkflow(deps: ExtractValuesDeps): (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
+export declare function registerExtractValuesWorkflow(deps: ExtractValuesDeps): (input: ExtractValuesWorkflowInput) => Promise<Result<ExtractValuesResult, Suspension>>;
 /** The per-attempt workflow id. A fresh nonce keeps each pass under a distinct id. */
 export declare function extractValuesWorkflowId(analysisId: string, nonce: string): string;
 /**
@@ -86,7 +91,7 @@ export declare function extractValuesWorkflowId(analysisId: string, nonce: strin
  */
 export interface ExtractValuesTriggerDeps {
     readonly runAuthorizer: RunAuthorizer;
-    readonly workflow: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
+    readonly workflow: (input: ExtractValuesWorkflowInput) => Promise<Result<ExtractValuesResult, Suspension>>;
 }
 /** The identity and the requests for one extraction pass. */
 export interface ExtractValuesTriggerParams {
@@ -96,12 +101,13 @@ export interface ExtractValuesTriggerParams {
 }
 /**
  * The async edge. It authorizes through the `RunAuthorizer`, starts the workflow, and awaits the outcome.
- * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault rejects the returned
- * promise.
+ * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault and a refused
+ * authorization reject the returned promise. A suspension is the `err` of the result: of the workflow, or of
+ * an authorization that the host refused with the suspend flag.
  */
-export declare function triggerExtractValues(deps: ExtractValuesTriggerDeps, params: ExtractValuesTriggerParams): Promise<ExtractValuesResult>;
-/** Runs one extraction pass for the bound analysis, and gives the raw value map back. */
-export type ExtractionRunner = (requests: readonly ExtractionRequest[]) => Promise<ExtractValuesResult>;
+export declare function triggerExtractValues(deps: ExtractValuesTriggerDeps, params: ExtractValuesTriggerParams): Promise<Result<ExtractValuesResult, Suspension>>;
+/** Runs one extraction pass for the bound analysis, and gives the raw value map back, or the suspension. */
+export type ExtractionRunner = (requests: readonly ExtractionRequest[]) => Promise<Result<ExtractValuesResult, Suspension>>;
 /**
  * Bind the trigger to one analysis and one auth context. The result runs one pass with every request in it.
  */
@@ -119,6 +125,6 @@ export declare function extractionArtifactsFromResult(result: ExtractValuesResul
 /**
  * Make the extraction arm over a runner. One `extract` call makes one run with every request in it, and it
  * gives the value map. A run fault rejects the promise, and the resolver turns the rejection into a failed
- * reference.
+ * reference. A suspension is the `err`, and the resolver reports its reason on each reference.
  */
 export declare function createExtractionArm(run: ExtractionRunner): ExtractionArm;

package/dist/tasks/extract-values.js

@@ -12,10 +12,15 @@
  * standing machine exists.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { err, ok } from "neverthrow";
 import { randomUUID } from "node:crypto";
+import { forStep } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice, passGate } from "../lib/hooks.js";
 import { generateExecutionId } from "../sandbox/execution-id.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
+import { suspensionOfRefusal, suspensionOfSpawnRefusal } from "../workflows/suspension.js";
 import { EXTRACTION_INPUT_ENV, EXTRACTION_SCRIPT, ExtractValuesResultSchema } from "./extract-values-script.js";
 /** The synthetic run id and step id of the extraction pass. Both are constants shared by every analysis. */
 const EXTRACT_VALUES_RUN_LITERAL = "extract-values";
@@ -85,24 +90,28 @@ export function parseExtractionOutput(result) {
  * The body, extracted so a test drives it without a registered workflow. It creates the ephemeral
  * container, submits one exec, awaits the result durably, and gives the value map back. It revokes the run
  * authorization on every terminal path, and it tears the container down on both paths.
+ *
+ * A chat turn awaits this workflow, thus a suspension is the `err` of the result, and the workflow does not
+ * cancel (workflow-suspension spec). The body does not mark the analysis: the caller reports the suspension.
  */
 export async function runExtractValuesBody(input, deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("extract-values").with({ analysisId: input.analysisId });
     const { analysisId, runSession, requests, ownsMandate = true } = input; // oss-core-managed-ok
     const authorization = { runSession, ownsMandate }; // oss-core-managed-ok
+    const revoke = (reason) => deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, reason));
     try {
         const executionId = generateExecutionId(EXTRACT_VALUES_AGENT_ID);
         const workflowId = DBOS.workflowID ?? `${EXTRACT_VALUES_RUN_LITERAL}:${executionId}`;
         // The container mounts the analysis tree read-only. The extraction pass only reads, thus it needs
         // no writable step mount.
-        const sandbox = await deps.sandboxClient.createSandbox({
-            runId: EXTRACT_VALUES_RUN_LITERAL,
-            stepId: EXTRACT_VALUES_STEP_LITERAL,
-            analysisId,
-            childWorkflowId: workflowId,
-            resources: EXTRACTION_RESOURCES,
-            readOnly: true,
-        }, mintSandboxIdentity(EXTRACT_VALUES_RUN_LITERAL));
+        const spawned = keepSuspendingRefusal(await deps.sandboxClient.createSandbox(forStep(runSession, EXTRACT_VALUES_STEP_LITERAL), { childWorkflowId: workflowId, resources: EXTRACTION_RESOURCES, readOnly: true }, mintSandboxIdentity(EXTRACT_VALUES_RUN_LITERAL)));
+        if (spawned.isErr()) {
+            const suspension = suspensionOfSpawnRefusal(spawned.error);
+            logger.warn("extraction suspended", { reason: suspension.reason });
+            await revoke("extract-values-suspended");
+            return err(suspension);
+        }
+        const sandbox = spawned.value;
         try {
             // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
             // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
@@ -110,8 +119,8 @@ export async function runExtractValuesBody(input, deps) {
             await deps.sandboxClient.submitExec(sandbox, buildExtractionExec(analysisId, requests, executionId));
             const result = await deps.sandboxClient.awaitExec(sandbox, executionId, noopEmit, deadlineAbs);
             const map = parseExtractionOutput(result);
-            await deps.runAuthorizer.revoke(authorization, "extract-values-completed");
-            return map;
+            await revoke("extract-values-completed");
+            return ok(map);
         }
         finally {
             try {
@@ -124,7 +133,7 @@ export async function runExtractValuesBody(input, deps) {
     }
     catch (err) {
         logger.error("extraction failed", logger.errorFields(err));
-        await deps.runAuthorizer.revoke(authorization, "extract-values-failed");
+        await revoke("extract-values-failed");
         throw err;
     }
 }
@@ -141,18 +150,25 @@ export function extractValuesWorkflowId(analysisId, nonce) {
 }
 /**
  * The async edge. It authorizes through the `RunAuthorizer`, starts the workflow, and awaits the outcome.
- * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault rejects the returned
- * promise.
+ * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault and a refused
+ * authorization reject the returned promise. A suspension is the `err` of the result: of the workflow, or of
+ * an authorization that the host refused with the suspend flag.
  */
 export async function triggerExtractValues(deps, params) {
     const { auth, analysisId, requests } = params;
-    const { runSession, ownsMandate } = await deps.runAuthorizer.authorize({
-        // oss-core-managed-ok
+    const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
         auth,
         scope: { kind: "analysis", analysisId },
         provenance: { agentId: EXTRACT_VALUES_AGENT_ID, callPath: [EXTRACT_VALUES_AGENT_ID] },
         frame: { runId: EXTRACT_VALUES_RUN_LITERAL, stepId: EXTRACT_VALUES_STEP_LITERAL },
-    });
+    }));
+    if (authorized.isErr()) {
+        const suspension = suspensionOfRefusal(authorized.error);
+        if (suspension !== undefined)
+            return err(suspension);
+        throw new Error(`the extraction was not authorized: ${authorized.error.reason}`);
+    }
+    const { runSession, ownsMandate } = authorized.value; // oss-core-managed-ok
     const handle = (await DBOS.startWorkflow(deps.workflow, {
         workflowID: extractValuesWorkflowId(analysisId, randomUUID()),
     })({ analysisId, runSession, requests: [...requests], ownsMandate })); // oss-core-managed-ok
@@ -182,12 +198,12 @@ export function extractionArtifactsFromResult(result) {
 /**
  * Make the extraction arm over a runner. One `extract` call makes one run with every request in it, and it
  * gives the value map. A run fault rejects the promise, and the resolver turns the rejection into a failed
- * reference.
+ * reference. A suspension is the `err`, and the resolver reports its reason on each reference.
  */
 export function createExtractionArm(run) {
     return {
         async extract(requests) {
-            return extractionArtifactsFromResult(await run(requests));
+            return (await run(requests)).map(extractionArtifactsFromResult);
         },
     };
 }

package/dist/tools/execute-analysis.js

@@ -3,17 +3,18 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import { randomUUID } from "node:crypto";
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { DEFAULT_SANDBOX_MAX_STEPS } from "../config/resource-limits.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice, passGate } from "../lib/hooks.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { buildRunCardData } from "../memory/card-builders.js";
 import { formatQuery, parseQuery } from "../sandbox/package-identity.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
 import { validatePlan } from "../schemas/validate-plan.js";
-import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, updateRunStatus, upsertPlan } from "../state/index.js";
+import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, suspendAnalysis, updateRunStatus, upsertPlan } from "../state/index.js";
 import { routeAdHocRequest } from "./ad-hoc-router.js";
 import { adHocPlanId, adHocRunId } from "./analysis-invocation.js";
 import { defineTool } from "./define-tool.js";
@@ -383,19 +384,25 @@ export function createExecuteAnalysisTool(deps) {
                     return ok({ runId: reservation.row.runId, status: "in_progress" });
                 }
             }
-            let authorization;
-            try {
-                authorization = await deps.runAuthorizer.authorize({
-                    auth: ctx.session.auth,
-                    scope: ctx.session.scope,
-                    provenance: ctx.session.provenance,
-                    frame: { runId },
-                });
-            }
-            catch (error) {
-                await updateRunStatus(deps.pool, runId, "failed", "run authorization failed").match(() => { }, () => { });
-                throw error;
+            const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
+                auth: ctx.session.auth,
+                scope: ctx.session.scope,
+                provenance: ctx.session.provenance,
+                frame: { runId },
+            }));
+            if (authorized.isErr()) {
+                // The refusal ends the run before a workflow exists, thus the
+                // reserved row must not stay `running`.
+                const { kind, reason } = authorized.error;
+                if (kind === "suspended") {
+                    await updateRunStatus(deps.pool, runId, "canceled", reason).match(() => { }, () => { });
+                    unwrapOrThrow(await suspendAnalysis(deps.pool, analysisId));
+                    return err({ error: `The analysis is suspended: ${reason}`, retryable: false });
+                }
+                await updateRunStatus(deps.pool, runId, "failed", reason).match(() => { }, () => { });
+                return err({ error: `The run was not authorized: ${reason}`, retryable: false });
             }
+            const authorization = authorized.value;
             const wfInput = workflowInput(planId, plan, {
                 analysisId,
                 threadId,
@@ -408,7 +415,7 @@ export function createExecuteAnalysisTool(deps) {
                 await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
             }
             catch (error) {
-                await deps.runAuthorizer.revoke(authorization, "workflow-start-failed").catch(() => { });
+                await deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, "workflow-start-failed"));
                 await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
                 throw error;
             }

package/dist/tools/report-session/derive-table.d.ts

@@ -33,7 +33,10 @@
  * under the callback transport, and a report turn is not a body. Thus the tool takes an injected runner,
  * and a registered workflow owns the container. The tool holds no sandbox client, and it imports no DBOS.
  */
+import { type Result } from "neverthrow";
 import { z } from "zod";
+import type { RunSession } from "../../auth/types.js";
+import type { Suspension } from "../../workflows/suspension.js";
 import type { RunAuthorizer } from "../../execution/run-authorizer.js";
 import { type Logger } from "../../lib/logger.js";
 import type { ResourceSpec } from "../../config/resource-limits.js";
@@ -90,6 +93,10 @@ export type DeriveTableResult = {
 } | {
     outcome: "exec-failed";
     detail: string;
+} | {
+    outcome: "suspended";
+    reason: string;
+    detail: string;
 } | {
     outcome: "no-output";
     detail: string;
@@ -172,6 +179,7 @@ export declare function describeExecFailure(result: ExecResult): string | undefi
  */
 export interface DeriveTableExecInput {
     readonly analysisId: string;
+    readonly runSession: RunSession;
     readonly executionId: string;
     readonly script: string;
     readonly writableTail: string;
@@ -186,7 +194,7 @@ export interface DeriveTableExecInput {
  * and the await is legal under each transport. A fault of the sandbox rejects the promise, and the tool
  * turns that rejection into one short detail.
  */
-export type DeriveTableRunner = (input: DeriveTableExecInput) => Promise<ExecResult>;
+export type DeriveTableRunner = (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>;
 /**
  * Make the derivation tool over the session-state gateway, the derivation ledger, and the sandbox rails.
  *

package/dist/tools/report-session/derive-table.js

@@ -38,6 +38,7 @@ import { unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { z } from "zod";
 import { createNoopLogger } from "../../lib/console-logger.js";
+import { deliverNotice, passGate } from "../../lib/hooks.js";
 import { classifyWithinRoot, computeSha256, computeSha256File } from "../../lib/fs-helpers.js";
 import { defaultErrorFields } from "../../lib/logger.js";
 import { snapshotEntry } from "../../report-model/reference-resolver.js";
@@ -223,19 +224,20 @@ export function createDeriveTableTool(deps) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "unavailable", detail: "the workspace root did not resolve, thus the derived table has no place to land" });
             }
-            let authorization;
-            try {
-                authorization = await runAuthorizer.authorize({
-                    auth: ctx.session.auth,
-                    scope: { kind: "analysis", analysisId },
-                    provenance: { agentId: DERIVE_AGENT_ID, callPath: [DERIVE_AGENT_ID] },
-                    frame: { runId: DERIVE_RUN_LITERAL, stepId: DERIVE_STEP_LITERAL },
-                });
-            }
-            catch (cause) {
-                logger.error("the derivation was not authorized", { threadId, analysisId, ...defaultErrorFields(cause) });
-                return ok({ outcome: "unavailable", detail: "the derivation was not authorized" });
+            const authorized = await passGate("RunAuthorizer.authorize", runAuthorizer.authorize({
+                auth: ctx.session.auth,
+                scope: { kind: "analysis", analysisId },
+                provenance: { agentId: DERIVE_AGENT_ID, callPath: [DERIVE_AGENT_ID] },
+                frame: { runId: DERIVE_RUN_LITERAL, stepId: DERIVE_STEP_LITERAL },
+            }));
+            if (authorized.isErr()) {
+                const { kind, reason } = authorized.error;
+                logger.error("the derivation was not authorized", { threadId, analysisId, reason, suspend: kind === "suspended" });
+                if (kind === "suspended")
+                    return ok({ outcome: "suspended", reason, detail: `the analysis is suspended (${reason}), thus the derivation did not run` });
+                return ok({ outcome: "unavailable", detail: `the derivation was not authorized: ${reason}` });
             }
+            const authorization = authorized.value;
             // The work sits inside the `try`, and the revoke sits in the `finally`. Thus the authorization
             // revokes on every terminal path, the thrown one included: a path builder refuses a hostile
             // stored path with a throw, and that throw must not leave an authorization standing.
@@ -247,6 +249,7 @@ export function createDeriveTableTool(deps) {
                     root,
                     threadId,
                     analysisId,
+                    runSession: authorization.runSession,
                     script: input.script,
                     sources,
                     writableTail,
@@ -270,14 +273,9 @@ export function createDeriveTableTool(deps) {
                 return ok(result);
             }
             finally {
-                // A revoke fault changes no outcome of the call, thus it reaches the log alone. An absent
-                // result means that the work threw, and a throw is a failed derivation.
-                try {
-                    await runAuthorizer.revoke(authorization, result?.outcome === "derived" ? "derive-table-completed" : "derive-table-failed");
-                }
-                catch (cause) {
-                    logger.warn("the derivation authorization did not revoke", { threadId, analysisId, ...defaultErrorFields(cause) });
-                }
+                // The revoke is a notice: its failure changes no outcome of the call, thus it reaches the log
+                // alone. An absent result means that the work threw, and a throw is a failed derivation.
+                await deliverNotice(logger.with({ threadId, analysisId }), "RunAuthorizer.revoke", runAuthorizer.revoke(authorization, result?.outcome === "derived" ? "derive-table-completed" : "derive-table-failed"));
             }
         },
     });
@@ -318,6 +316,7 @@ async function derive(args) {
     // thus that refusal stays a throw and it never reads as a fault of the container.
     const execInput = {
         analysisId: args.analysisId,
+        runSession: args.runSession,
         executionId,
         script: args.script,
         writableTail: args.writableTail,
@@ -325,14 +324,18 @@ async function derive(args) {
         inputs: args.sources.map((source) => ({ path: toSandboxPath(args.root, args.analysisId, join(args.root, source.path)), hash: source.hash })),
         output: toSandboxPath(args.root, args.analysisId, absolute),
     };
-    let executed;
+    let ran;
     try {
-        executed = await args.runDerivation(execInput);
+        ran = await args.runDerivation(execInput);
     }
     catch (cause) {
         args.logger.error("the derivation exec did not complete", { threadId: args.threadId, ...defaultErrorFields(cause) });
         return { outcome: "exec-failed", detail: "the derivation exec did not complete" };
     }
+    if (ran.isErr()) {
+        return { outcome: "suspended", reason: ran.error.reason, detail: `the analysis is suspended (${ran.error.reason}), thus the derivation did not run` };
+    }
+    const executed = ran.value;
     const failure = describeExecFailure(executed);
     if (failure !== undefined) {
         return { outcome: "exec-failed", detail: failure };

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

@@ -53,7 +53,7 @@ declare function formatRun(r: CortexRunRow, verbose: boolean, exposePaths?: bool
     synthesisReason?: string | undefined;
     runId: string;
     workflowName: string;
-    status: "running" | "completed" | "failed" | "partial" | "canceled" | "suspended_insufficient_funds";
+    status: "failed" | "running" | "completed" | "partial" | "canceled" | "suspended_insufficient_funds";
     startedAt: string;
     completedAt: string | null;
     planId: string | null;

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

@@ -31,23 +31,30 @@
  *     - await child results via `getResult` (these are themselves cached
  *       in DBOS, so parent recovery does NOT re-run completed children)
  *  3. Failure isolation
- *     - a child settling `failed`/`blocked` (or throwing for a non-budget
- *       cause) dooms only its transitive dependents: they can never become
- *       dependency-satisfied, are marked `skipped` on the dag-state part, and
- *       are never dispatched. In-flight siblings and independent ready steps
- *       continue; the loop drains and the run finalises (typically `partial`).
+ *     - a child settling `failed`/`blocked` (or throwing for a cause that is
+ *       not a suspension) dooms only its transitive dependents: they can never
+ *       become dependency-satisfied, are marked `skipped` on the dag-state
+ *       part, and are never dispatched. In-flight siblings and independent
+ *       ready steps continue; the loop drains and the run finalises (typically
+ *       `partial`).
  *     - the halt cascade (cancel in-flight via
  *       `Promise.allSettled(handles.map(h => DBOS.cancelWorkflow(h.workflowID)))`,
- *       stop scheduling) survives only for the budget paths: a
- *       `budget_exceeded` settlement and the `neverFits` plan-validation guard.
- *  4. Pause cascade (402)
- *     - on a child cancelling itself with `budget_exceeded`: cancel siblings
- *       then self-cancel the parent to `CANCELLED` (NOT `ERROR` — ERROR
- *       isn't resumable; NOTES #3)
+ *       stop scheduling) survives only for a suspension of a child and the
+ *       `neverFits` plan-validation guard.
+ *  4. Suspension cascade (workflow-suspension spec)
+ *     - a child that suspends sends a typed message on `CHILD_SUSPENDED_TOPIC`
+ *       and cancels itself. The parent reads the kind of the message, never a
+ *       reason string: it cancels the siblings, then self-cancels to
+ *       `CANCELLED` (NOT `ERROR` — ERROR isn't resumable; NOTES #3)
+ *     - a refusal of the `RunCharge.open` gate with the suspend flag suspends
+ *       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
- *       durably reschedulable state; re-driving it after a top-up is a
- *       future enhancement, not yet wired here.
+ *       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
@@ -77,6 +84,7 @@ import type { RunCharge } from "../billing/run-charge.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type PlanStep } from "./execute-analysis-scheduler.js";
 import { type SandboxStepInput, type SandboxStepResult } from "./sandbox-step.js";
+import { type Suspension } from "./suspension.js";
 /** Registered child sandbox-step callable the parent's child-dispatch closes over. */
 type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /** Quick-display finding on the run-completed card. Mirrors the wire schema's RunCompletedFinding. */
@@ -320,13 +328,14 @@ export declare function composeStepSeed(args: {
  * 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).
+ * two ledgers cannot disagree about why synthesis died. A suspension is not an
+ * outcome: the row is canceled, as the row of a suspended step. Exported for
+ * the projection tests (the `buildChildInput` pattern).
  */
 export declare function synthesisRowUpdate(outcome: {
     status: SynthesisStatus;
     reason: string | null;
-}, durationMs: number): UpdateStepExecutionInput;
+} | Suspension, durationMs: number): UpdateStepExecutionInput;
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is