@inflexa-ai/harness 0.37.0 → 0.39.0

package/dist/sandbox/sandbox-error.js

@@ -25,21 +25,21 @@
  *    propagate untouched. `await-exec.ts` is NOT converted; `trySandbox` only
  *    ever wraps the single SDK/HTTP call handed to it.
  *
- * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
- * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
- * seam throws the described failure with the variant on `.cause` and on
- * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
- * exception — it is already its own DBOS step and throws directly, so the seam
- * forwards its `Promise<void>` as-is.)
- * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
- * `DBOS.runStep`, so the re-thrown error records the step as failed;
- * non-workflow consumers (`reaper`, `watchdog`,
- * `data-profile`, `run-exec`) already handle a thrown failure. They are
- * untouched by this wave.
+ * `createSandbox` of the public `SandboxClient` gives each `SandboxError` as
+ * an `err` value, because a refusal of the label hook must reach the spawn path
+ * as a value. A spawn path splits the result with `keepSuspendingRefusal`: a
+ * refusal with the suspend flag stays a value, and each other failure throws
+ * as a `SandboxFailure`.
+ * Each other op keeps a `Promise<T>` signature. `create-sandbox.ts` is the
+ * composition seam: it builds the backend ops, maps each `err` of such an op to
+ * a `SandboxFailure`, and `unwrapOrThrow`s it, so the seam throws the described
+ * failure with the variant on `.cause` and on `.error`. A `catch` never sees
+ * the raw variant. (`submitExec` is the exception — it is already its own DBOS
+ * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
  */
 import { ResultAsync, err, ok } from "neverthrow";
 import { ZodError } from "zod";
+import { unwrapOrThrow } from "../lib/result.js";
 const _assertDomainError = true;
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
@@ -100,11 +100,11 @@ function causeLine(cause) {
  * on the operator surfaces.
  */
 export function describeSandboxError(e) {
-    // `farm_unavailable` is the one variant whose head already carries its
-    // reason, the text of the resolver. A cause line after it would put two
-    // dashes on one row, and the throw of a resolver is in the log with its
-    // stack. Every other variant names its reason only through the cause.
-    const line = e.type === "farm_unavailable" ? undefined : causeLine(e.cause);
+    // `farm_unavailable` and `labels_refused` are the two variants whose head
+    // already carries its reason, the text of the resolver or of the host. A
+    // cause line after it would put two dashes on one row. Every other variant
+    // names its reason only through the cause.
+    const line = e.type === "farm_unavailable" || e.type === "labels_refused" ? undefined : causeLine(e.cause);
     const head = describeVariant(e);
     return line === undefined ? head : `${head} — ${line}`;
 }
@@ -123,6 +123,8 @@ function describeVariant(e) {
             return `sandbox teardown failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
         case "liveness_failed":
             return `sandbox liveness probe failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
+        case "labels_refused":
+            return `the label hook refused the spawn (${e.op}) — ${e.reason}`;
         case "farm_unavailable":
             return `farm unavailable (${e.op}: ${e.analysisId}) — ${e.reason}`;
         case "farm_unusable":
@@ -144,6 +146,19 @@ export class SandboxFailure extends Error {
         this.name = "SandboxFailure";
     }
 }
+function isSuspendingRefusal(e) {
+    return e.type === "labels_refused" && e.suspend;
+}
+/**
+ * Split the result of a spawn at a DBOS boundary. Call it inside the step of
+ * the spawn, before the checkpoint: the cause of a backend failure does not
+ * survive the serialization of a `Result`.
+ */
+export function keepSuspendingRefusal(result) {
+    if (result.isErr() && isSuspendingRefusal(result.error))
+        return err(result.error);
+    return ok(unwrapOrThrow(result.mapErr((e) => new SandboxFailure(e))));
+}
 /**
  * Wrap a single sandbox backend call (Docker SDK op, K8s API op, or the
  * `/exec` POST). A throw becomes `err(toError(status, cause))`; the caller

package/dist/sandbox/types.d.ts

@@ -8,8 +8,11 @@
  * — that one OMITS the secret, which lives only in the cached
  * `createSandbox` DBOS step output.
  */
+import type { ResultAsync } from "neverthrow";
 import { z } from "zod";
+import type { RunSession } from "../auth/types.js";
 import type { ResourceSpec } from "../config/resource-limits.js";
+import type { GateFailure } from "../lib/hooks.js";
 import type { PackageQuery } from "./package-identity.js";
 export declare const SandboxBackend: z.ZodEnum<{
     docker: "docker";
@@ -141,8 +144,12 @@ export type PackageRequestOutcome = {
  *
  * The seam speaks the query of the `package-identity` capability, thus the
  * host resolves the identity and the harness never folds a name.
+ *
+ * A failure of one package is an outcome. An `err` means that the whole
+ * call gave no answer, and the harness reads it as `unavailable` for each
+ * query.
  */
-export type ExtendAnalysisFarm = (analysisId: string, queries: readonly PackageQuery[]) => Promise<readonly PackageRequestOutcome[]>;
+export type ExtendAnalysisFarm = (analysisId: string, queries: readonly PackageQuery[]) => ResultAsync<readonly PackageRequestOutcome[], GateFailure>;
 /**
  * Per-sandbox-machine liveness verdict. `oomKilled` is meaningful only when
  * `alive` is false: true when the backend reports the machine was killed for
@@ -380,11 +387,8 @@ export interface SubmitExecBody {
     stdoutByteCap?: number;
     stderrByteCap?: number;
 }
-/** Step-meta passed to `createSandbox` — what the registry row needs. */
-export interface CreateSandboxMeta {
-    runId: string;
-    stepId: string;
-    analysisId: string;
+/** What a spawn needs beside its session. */
+export interface SandboxSpec {
     /** The first `execId` that will fire against this sandbox; nullable for
      *  early-create flows where the workflow mints the first execId later. */
     execId?: string | null;
@@ -408,11 +412,15 @@ export interface CreateSandboxMeta {
      *  mount, thus a run provisions exactly as before. A tail beside `readOnly` is
      *  a contradiction, and the mount builders refuse it. */
     writableTail?: string;
-    /** Host-supplied labels stamped onto the sandbox pod, verbatim. Opaque here:
-     *  the harness reads no key and no value, it only sanitizes each value into a
-     *  valid label. Absent ⇒ the pod carries the harness's own labels only. */
-    podLabels?: Record<string, string>;
 }
+/** The labels that the host adds to a sandbox. The harness stamps each one as the host gives it. */
+export type SandboxLabels = Readonly<Record<string, string>>;
+/**
+ * The sandbox label hook of the host: a gate (`lib/hooks.ts`). The sandbox
+ * client calls it at each spawn, on both backends, before it makes the step
+ * tree and before it calls a backend.
+ */
+export type ResolveSandboxLabels = (session: RunSession) => ResultAsync<SandboxLabels, GateFailure>;
 /**
  * The identity minted for a sandbox machine *before* it is spawned — the
  * durable half of the two-step create (see the harness-sandbox-exec spec). Step 1 checkpoints this so a

package/dist/schemas/validate-plan.js

@@ -14,6 +14,7 @@
 import { KNOWN_AGENT_IDS } from "../agents/sandbox-catalog.js";
 import { CycleError, DependencyError, topoSortIntoWaves } from "../execution/topo-sort.js";
 import { parseQuery } from "../sandbox/package-identity.js";
+import { isLabelValue } from "../sandbox/labels.js";
 import { isSafeId, STEP_SUBDIRS, SYNTHESIS_STEP_ID } from "../workspace/paths.js";
 const KNOWN_AGENTS = new Set(KNOWN_AGENT_IDS);
 /**
@@ -157,5 +158,17 @@ export function validatePlan(plan, options) {
                 `and cannot be '.' or '..' (the id becomes a workspace directory and container mount segment)`);
         }
     }
+    // 8. Step-id label safety. The id also becomes the value of the sandbox
+    //    label `cortex/step-id`, and the harness stamps a label value with no
+    //    change (sandbox-labels spec). A safe id can be too long for a label
+    //    value, or it can start or end with a separator. Refused here, the
+    //    planner makes the plan again; left alone, the K8s API server refuses
+    //    the spawn of the step.
+    for (const step of plan.steps) {
+        if (isSafeId(step.id) && !isLabelValue(step.id)) {
+            errors.push(`Step "${step.id}" is not a valid label value — a step id has 1 to 63 characters, and it starts and ends ` +
+                `with a letter or a digit (the id becomes the value of the sandbox label cortex/step-id)`);
+        }
+    }
     return { valid: errors.length === 0, errors };
 }

package/dist/schemas/workflow-state.d.ts

@@ -24,10 +24,10 @@ export declare const AnalysisStepSchema: z.ZodObject<{
     packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
     depends_on: z.ZodArray<z.ZodString>;
     status: z.ZodDefault<z.ZodEnum<{
+        failed: "failed";
         pending: "pending";
         running: "running";
         completed: "completed";
-        failed: "failed";
         skipped: "skipped";
     }>>;
     resources: z.ZodOptional<z.ZodObject<{
@@ -61,10 +61,10 @@ export declare const AnalysisPlanSchema: z.ZodObject<{
         packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
         depends_on: z.ZodArray<z.ZodString>;
         status: z.ZodDefault<z.ZodEnum<{
+            failed: "failed";
             pending: "pending";
             running: "running";
             completed: "completed";
-            failed: "failed";
             skipped: "skipped";
         }>>;
         resources: z.ZodOptional<z.ZodObject<{
@@ -133,10 +133,10 @@ export declare const ContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
             depends_on: z.ZodArray<z.ZodString>;
             status: z.ZodDefault<z.ZodEnum<{
+                failed: "failed";
                 pending: "pending";
                 running: "running";
                 completed: "completed";
-                failed: "failed";
                 skipped: "skipped";
             }>>;
             resources: z.ZodOptional<z.ZodObject<{
@@ -253,10 +253,10 @@ export declare const SuspensionPayloadSchema: z.ZodObject<{
                 packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 depends_on: z.ZodArray<z.ZodString>;
                 status: z.ZodDefault<z.ZodEnum<{
+                    failed: "failed";
                     pending: "pending";
                     running: "running";
                     completed: "completed";
-                    failed: "failed";
                     skipped: "skipped";
                 }>>;
                 resources: z.ZodOptional<z.ZodObject<{

package/dist/state/analyses.d.ts

@@ -20,12 +20,12 @@ export declare function loadAnalysisStatus(pool: Querier, resourceId: string): R
     context: string | null;
 } | null, DbError>;
 /**
- * Suspend an analysis due to a 402 `budget_exceeded` error.
+ * Mark an analysis as suspended.
  * Idempotent — no-op if already suspended.
  *
- * The only cause of suspension today is budget exhaustion; no reason is
- * persisted. If a second cause arises, add a column rather than a param so
- * history is queryable.
+ * `suspended_insufficient_funds` is the name of the one suspended state, for
+ * each reason of the host, thus no reason is persisted. A chat turn never calls
+ * it.
  */
 export declare function suspendAnalysis(pool: Querier, analysisId: string): ResultAsync<void, DbError>;
 /**

package/dist/state/analyses.js

@@ -41,12 +41,12 @@ export function loadAnalysisStatus(pool, resourceId) {
     });
 }
 /**
- * Suspend an analysis due to a 402 `budget_exceeded` error.
+ * Mark an analysis as suspended.
  * Idempotent — no-op if already suspended.
  *
- * The only cause of suspension today is budget exhaustion; no reason is
- * persisted. If a second cause arises, add a column rather than a param so
- * history is queryable.
+ * `suspended_insufficient_funds` is the name of the one suspended state, for
+ * each reason of the host, thus no reason is persisted. A chat turn never calls
+ * it.
  */
 export function suspendAnalysis(pool, analysisId) {
     return tryMutation("analyses.suspendAnalysis", async () => {

package/dist/state/schema.d.ts

@@ -10,10 +10,10 @@ export declare const AnalysisStateRowSchema: z.ZodObject<{
     status: z.ZodString;
     context: z.ZodNullable<z.ZodString>;
     dataProfileStatus: z.ZodEnum<{
+        failed: "failed";
         pending: "pending";
         running: "running";
         completed: "completed";
-        failed: "failed";
     }>;
     dataProfileError: z.ZodNullable<z.ZodString>;
     dataProfileStartedAt: z.ZodNullable<z.ZodString>;
@@ -46,19 +46,19 @@ export declare const ArtifactRowSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ArtifactRow = z.infer<typeof ArtifactRowSchema>;
 export declare const RunStatus: z.ZodEnum<{
+    failed: "failed";
     running: "running";
     completed: "completed";
-    failed: "failed";
     partial: "partial";
     canceled: "canceled";
     suspended_insufficient_funds: "suspended_insufficient_funds";
 }>;
 export type RunStatus = z.infer<typeof RunStatus>;
 export declare const StepExecutionStatus: z.ZodEnum<{
+    failed: "failed";
     pending: "pending";
     running: "running";
     completed: "completed";
-    failed: "failed";
     canceled: "canceled";
     skipped: "skipped";
     blocked: "blocked";
@@ -77,9 +77,9 @@ export declare const CortexRunRowSchema: z.ZodObject<{
     threadId: z.ZodNullable<z.ZodString>;
     workflowName: z.ZodString;
     status: z.ZodEnum<{
+        failed: "failed";
         running: "running";
         completed: "completed";
-        failed: "failed";
         partial: "partial";
         canceled: "canceled";
         suspended_insufficient_funds: "suspended_insufficient_funds";
@@ -124,10 +124,10 @@ export declare const StepExecutionRowSchema: z.ZodObject<{
     wave: z.ZodNumber;
     agentId: z.ZodString;
     status: z.ZodEnum<{
+        failed: "failed";
         pending: "pending";
         running: "running";
         completed: "completed";
-        failed: "failed";
         canceled: "canceled";
         skipped: "skipped";
         blocked: "blocked";

package/dist/tasks/data-profile.d.ts

@@ -17,6 +17,7 @@
  * triggers dedup via the ledger CAS (only one `tryStart/tryRerun/tryRetry`
  * UPDATE wins); each winning attempt starts a workflow under a per-attempt id.
  */
+import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
@@ -25,6 +26,7 @@ import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorize
 import type { StagedInput } from "../execution/staged-input.js";
 import type { SandboxAgentDeps } from "../agents/sandbox/shared.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import { type GateRefusal } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
@@ -60,13 +62,6 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
     readonly skillsDir: string;
     /** LLM usage-accounting seam for the profiler agent loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
-    /**
-     * Host-supplied labels for the profiler's sandbox pod, resolved under the
-     * profiling session. The map is opaque to the harness: it stamps each entry
-     * and interprets none of it. Absent in a wiring that attributes nothing —
-     * the pod then carries the harness's own labels only.
-     */
-    readonly resolvePodLabels?: (session: RunSession) => Promise<Record<string, string>>;
     /**
      * The farm-extension seam of the embedder. Bound, it rides into the
      * profiler agent deps, and the substrate attaches `link_packages`. Thus
@@ -187,7 +182,7 @@ export interface DataProfileTriggerParams {
  * `RunAuthorizer` seam from the opaque auth; this passes that auth straight
  * through and never inspects it.
  */
-export declare function authorizeDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<RunAuthorization>;
+export declare function authorizeDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): ResultAsync<RunAuthorization, GateRefusal>;
 /**
  * Per-attempt DBOS workflow id. The `nonce` is fresh per attempt (a bare
  * `randomUUID()` minted at the trigger), so each (re-)profile of the same
@@ -227,5 +222,7 @@ export declare function triggerDataProfile(deps: DataProfileTriggerDeps, params:
  * await the workflow's completion, but a start that rejects compensates the
  * ledger (see {@link compensateStartFailure}) before re-throwing, so a caller's
  * own `.catch` still observes the error and the row never wedges at `running`.
+ * A refused authorization fails the row with the reason of the host, and the
+ * promise resolves: the row is where a caller reads the outcome.
  */
 export declare function runDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<void>;

package/dist/tasks/data-profile.js

@@ -17,18 +17,21 @@
  * triggers dedup via the ledger CAS (only one `tryStart/tryRerun/tryRetry`
  * UPDATE wins); each winning attempt starts a workflow under a per-attempt id.
  */
-import { DBOS } from "@dbos-inc/dbos-sdk";
+import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { randomUUID } from "node:crypto";
-import { ok } from "neverthrow";
-import { forSubAgent } from "../auth/types.js";
+import { err, ok } from "neverthrow";
+import { forStep, forSubAgent } from "../auth/types.js";
 import { createDataProfilerAgent } from "../agents/sandbox/data-profiler.js";
 import { runToTerminal } from "../loop/run-to-terminal.js";
 import { durableStep } from "../loop/run-step.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice, passGate } from "../lib/hooks.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { defineTool } from "../tools/define-tool.js";
 import { createDetailResolver } from "../tools/detail-resolver.js";
 import { renderWorkspace } from "../prompts/briefing.js";
+import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
+import { cancelSelf, suspensionOfFailure, suspensionOfRefusal, suspensionOfSpawnRefusal } from "../workflows/suspension.js";
 import { toSandboxPath } from "../workspace/paths.js";
 import { estimateDataProfileResources } from "../sandbox/estimate-data-profile-resources.js";
 import { generateExecutionId } from "../sandbox/execution-id.js";
@@ -44,7 +47,7 @@ import { scanInputTree } from "../input-scan/scan.js";
 import { PROFILE_INDEX_TYPES, buildProfileIndexEntries } from "./data-profile-index.js";
 import { absorbRecipe, renderAbsorbDelta } from "./data-profile-absorb.js";
 import { formatResolutionErrors, resolveProfileSubmission } from "./data-profile-resolve.js";
-import { completeDataProfile, completeEmptyDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
+import { completeDataProfile, completeEmptyDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, suspendAnalysis, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
 import { elapsedSinceIso, recordRunCompleted } from "../lib/metrics.js";
 import { createProfileActivityEmitter } from "./data-profile-activity.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
@@ -139,6 +142,8 @@ async function readSetHeaders(args) {
         });
     }
     catch (err) {
+        if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+            throw err;
         logger.warn("input-scan header readout failed (non-fatal)", logger.errorFields(err));
         return new Map();
     }
@@ -285,6 +290,21 @@ export async function runDataProfileBody(input, deps) {
     // Cortex-owned and must be revoked here.
     const { analysisId, runSession, ownsMandate = true, stagedInputs } = 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));
+    let selfCancelled = false;
+    // A suspension fails the row with the reason of the host, because the profile
+    // ledger has no suspended state and the retry path takes a `failed` row again.
+    const suspendProfile = async (suspension) => {
+        logger.warn("profile suspended", { reason: suspension.reason });
+        settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, suspension.reason)), "failed");
+        await revoke("data-profile-suspended");
+        unwrapOrThrow(await suspendAnalysis(deps.pool, analysisId));
+        await activity.failed(suspension.reason);
+        if (DBOS.workflowID === undefined)
+            return;
+        selfCancelled = true;
+        await cancelSelf("self-cancel-suspended");
+    };
     // The profile's activity channel. `DBOS.writeStream` is body-only, so the write is bound here
     // while every phase and phrase lives in the emitter — the phrases are the observable contract of
     // this capability, and a body that composed its own strings is a body they can drift from.
@@ -318,7 +338,7 @@ export async function runDataProfileBody(input, deps) {
             // empty-manifest path invisible to the same monitoring that watches every other.
             logProfileMonitoring(logger, { dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
             settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)), "completed");
-            await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
+            await revoke("data-profile-completed");
             // This is a terminal completion like any other, so it reports one — a consumer watching
             // an empty-manifest profile sees it settle rather than seeing the stream simply stop.
             await activity.complete();
@@ -371,7 +391,7 @@ export async function runDataProfileBody(input, deps) {
             await indexProfile({ deps, analysisId, session: runSession, record, scan, logger });
             logProfileMonitoring(logger, { resolution, dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
             settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, record)), "completed");
-            await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
+            await revoke("data-profile-completed");
             await activity.complete();
             return;
         }
@@ -397,7 +417,7 @@ export async function runDataProfileBody(input, deps) {
                 absorb: absorb.kind,
             });
             settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, absorbed)), "completed");
-            await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
+            await revoke("data-profile-completed");
             await activity.complete();
             return;
         }
@@ -408,27 +428,10 @@ export async function runDataProfileBody(input, deps) {
         // from the agent loop would leave the longest wait of all unreported — the same defect the
         // run panel's activity readout was built to remove.
         await activity.sandboxInit();
-        let podLabels;
-        if (deps.resolvePodLabels) {
-            try {
-                podLabels = await deps.resolvePodLabels(childSession);
-            }
-            catch (err) {
-                logger.warn("pod-label resolution failed", logger.errorFields(err));
-            }
-            // A wired resolver that yields nothing is the one loud case: the host
-            // asked for attribution and the pod spawns without it.
-            if (!podLabels || Object.keys(podLabels).length === 0)
-                logger.warn("sandbox spawned with no pod labels");
-        }
-        const sandbox = await deps.sandboxClient.createSandbox({
-            runId: DATA_PROFILE_RUN_LITERAL,
-            stepId: DATA_PROFILE_STEP_LITERAL,
-            analysisId,
-            childWorkflowId: workflowId,
-            resources: estimateDataProfileResources(stagedInputs),
-            podLabels,
-        }, mintSandboxIdentity(DATA_PROFILE_RUN_LITERAL));
+        const spawned = keepSuspendingRefusal(await deps.sandboxClient.createSandbox(forStep(runSession, DATA_PROFILE_STEP_LITERAL), { childWorkflowId: workflowId, resources: estimateDataProfileResources(stagedInputs) }, mintSandboxIdentity(DATA_PROFILE_RUN_LITERAL)));
+        if (spawned.isErr())
+            return await suspendProfile(suspensionOfSpawnRefusal(spawned.error));
+        const sandbox = spawned.value;
         try {
             // Checkpointed clock, not `Date.now()`: `awaitExec` gates on this absolute
             // deadline and its recovery-pull is a durable step, so a wall-clock deadline
@@ -545,6 +548,7 @@ export async function runDataProfileBody(input, deps) {
                 runStep: durableStep,
                 resolved: () => accepted !== null,
                 usageRecorder: deps.usageRecorder,
+                isFatalLoopError: (err) => err instanceof DBOSErrors.DBOSWorkflowCancelledError,
             }, {
                 tools: [submitProfileTool],
                 nudge: "You stopped without calling submit_profile, so no profile was " +
@@ -574,7 +578,7 @@ export async function runDataProfileBody(input, deps) {
             // 6. Complete — store the FULL profiler finding plus the input signature for
             // staleness detection. The scratch tree is gone; this row is all that survives.
             settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord)), "completed");
-            await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
+            await revoke("data-profile-completed");
             // LAST statement of the success path, and that placement is the guarantee that exactly
             // one terminal activity is ever emitted. Everything that could still throw — the ledger
             // write above, the revoke — is already behind us, so any failure on the way here reaches
@@ -593,10 +597,15 @@ export async function runDataProfileBody(input, deps) {
         }
     }
     catch (err) {
+        if (selfCancelled || err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+            throw err;
+        const suspension = suspensionOfFailure(err);
+        if (suspension !== undefined)
+            return await suspendProfile(suspension);
         logger.error("profile failed", logger.errorFields(err));
         const reason = profileFailureReason(err);
         settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)), "failed");
-        await deps.runAuthorizer.revoke(authorization, "data-profile-failed");
+        await revoke("data-profile-failed");
         // The same bounded, user-safe line the ledger receives — never the raw error, whose paths and
         // stack frames stay in the log record above. This is the only other terminal emission, so
         // reaching it means the success path did not emit one.
@@ -633,14 +642,14 @@ function settleTerminalWrite(logger, analysisId, write, status) {
  * `RunAuthorizer` seam from the opaque auth; this passes that auth straight
  * through and never inspects it.
  */
-export async function authorizeDataProfile(deps, params) {
+export function authorizeDataProfile(deps, params) {
     const { auth, analysisId } = params;
-    return deps.runAuthorizer.authorize({
+    return passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
         auth,
         scope: { kind: "analysis", analysisId },
         provenance: { agentId: DATA_PROFILE_AGENT_ID, callPath: [DATA_PROFILE_AGENT_ID] },
         frame: { runId: DATA_PROFILE_RUN_LITERAL, stepId: DATA_PROFILE_STEP_LITERAL },
-    });
+    }));
 }
 /**
  * Per-attempt DBOS workflow id. The `nonce` is fresh per attempt (a bare
@@ -666,7 +675,10 @@ export function dataProfileWorkflowId(analysisId, nonce) {
  * not awaited.
  */
 async function startDataProfileWorkflow(deps, params) {
-    const { runSession, ownsMandate } = await authorizeDataProfile(deps, params); // oss-core-managed-ok
+    const authorized = await authorizeDataProfile(deps, params);
+    if (authorized.isErr())
+        return err(authorized.error);
+    const { runSession, ownsMandate } = authorized.value; // oss-core-managed-ok
     const attemptNonce = randomUUID();
     await DBOS.startWorkflow(deps.workflow, {
         workflowID: dataProfileWorkflowId(params.analysisId, attemptNonce),
@@ -676,6 +688,20 @@ async function startDataProfileWorkflow(deps, params) {
         ownsMandate, // oss-core-managed-ok
         stagedInputs: params.stagedInputs,
     });
+    return ok(undefined);
+}
+/**
+ * Dispatch a claimed profile, fire-and-forget. The claim already flipped the
+ * row to `running`, thus a refused authorization and a rejected start each
+ * settle the row as `failed`, and it never wedges at `running`.
+ */
+async function dispatchClaimedProfile(deps, params, phase) {
+    const started = await startDataProfileWorkflow(deps, params).catch(async (cause) => {
+        await compensateStartFailure(deps, params.analysisId, phase, cause);
+        return undefined;
+    });
+    if (started?.isErr())
+        await refuseClaimedProfile(deps, params.analysisId, phase, started.error);
 }
 /**
  * Attempt to claim and run data profiling for an analysis, then start the workflow
@@ -738,12 +764,12 @@ export async function triggerDataProfile(deps, params) {
         }
         const started = unwrapOrThrow(await tryStartDataProfile(deps.pool, analysisId));
         if (started) {
-            startDataProfileWorkflow(deps, params).catch((err) => compensateStartFailure(deps, analysisId, "Run", err));
+            void dispatchClaimedProfile(deps, params, "Run");
             return "started";
         }
         const restarted = unwrapOrThrow(await tryRerunDataProfile(deps.pool, analysisId));
         if (restarted) {
-            startDataProfileWorkflow(deps, params).catch((err) => compensateStartFailure(deps, analysisId, "Re-run", err));
+            void dispatchClaimedProfile(deps, params, "Re-run");
             return "restarted";
         }
         const status = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
@@ -765,10 +791,24 @@ export async function triggerDataProfile(deps, params) {
  * Best-effort — a compensation write that itself fails is only logged, since
  * there is no further channel to report it on.
  */
-async function compensateStartFailure(deps, analysisId, phase, err) {
+async function compensateStartFailure(deps, analysisId, phase, cause) {
+    const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId });
+    logger.error("start failed", { phase, ...logger.errorFields(cause) });
+    await failClaimedProfile(deps, analysisId, phase, profileFailureReason(cause));
+}
+async function refuseClaimedProfile(deps, analysisId, phase, refusal) {
     const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId });
-    logger.error("start failed", { phase, ...logger.errorFields(err) });
-    const failed = await failDataProfile(deps.pool, analysisId, profileFailureReason(err));
+    logger.error("the profile was not authorized", { phase, reason: refusal.reason, suspend: refusal.kind === "suspended" });
+    await failClaimedProfile(deps, analysisId, phase, refusal.reason);
+    if (suspensionOfRefusal(refusal) === undefined)
+        return;
+    const marked = await suspendAnalysis(deps.pool, analysisId);
+    if (marked.isErr())
+        logger.error("the analysis was not marked as suspended", { phase, err: marked.error });
+}
+async function failClaimedProfile(deps, analysisId, phase, reason) {
+    const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId });
+    const failed = await failDataProfile(deps.pool, analysisId, reason);
     if (failed.isErr()) {
         logger.error("failed to mark failed after a start error", { phase, err: failed.error });
     }
@@ -790,15 +830,20 @@ async function compensateStartFailure(deps, analysisId, phase, err) {
  * await the workflow's completion, but a start that rejects compensates the
  * ledger (see {@link compensateStartFailure}) before re-throwing, so a caller's
  * own `.catch` still observes the error and the row never wedges at `running`.
+ * A refused authorization fails the row with the reason of the host, and the
+ * promise resolves: the row is where a caller reads the outcome.
  */
 export async function runDataProfile(deps, params) {
+    let started;
     try {
-        await startDataProfileWorkflow(deps, params);
+        started = await startDataProfileWorkflow(deps, params);
     }
-    catch (err) {
-        await compensateStartFailure(deps, params.analysisId, "Retry", err);
-        throw err;
+    catch (cause) {
+        await compensateStartFailure(deps, params.analysisId, "Retry", cause);
+        throw cause;
     }
+    if (started.isErr())
+        await refuseClaimedProfile(deps, params.analysisId, "Retry", started.error);
 }
 /**
  * Concise, UI-safe failure reason. `data_profile_error` is surfaced verbatim