@inflexa-ai/harness 0.1.1

package/dist/schemas/validate-plan.js

@@ -0,0 +1,120 @@
+/**
+ * Plan validation — pure structural checks on an AnalysisPlan.
+ *
+ * Depends only on the plan schema types, the topological sorter, and the
+ * agent id list. No framework dependencies. The `generatePlan` tool imports
+ * this directly.
+ *
+ * Checks:
+ * 1. Topological sort succeeds (no cycles, no missing deps)
+ * 2. Output prefix uniqueness
+ * 3. All agent assignments exist in the agent catalog
+ * 4. All steps have resources defined
+ */
+import { KNOWN_AGENT_IDS } from "../agents/sandbox-catalog.js";
+import { CycleError, DependencyError, topoSortIntoWaves } from "../execution/topo-sort.js";
+import { isSafeId, STEP_SUBDIRS } from "../workspace/paths.js";
+const KNOWN_AGENTS = new Set(KNOWN_AGENT_IDS);
+/**
+ * Reserved step-id names. A step id equal to an artifact subdirectory name
+ * would make its directory (`runs/{runId}/{stepId}`) collide with the
+ * subdirectory convention agents expect inside a step (see the harness-workspace-tools spec).
+ */
+const RESERVED_STEP_IDS = new Set(STEP_SUBDIRS);
+/** Derive a filesystem-safe output prefix from a step ID. */
+export function deriveOutputPrefix(stepId) {
+    return stepId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Validate an analysis plan for structural correctness.
+ *
+ * Returns `valid: true` if the plan passes all checks, or `valid: false`
+ * with a list of human-readable error strings.
+ */
+export function validatePlan(plan, options) {
+    const errors = [];
+    if (plan.steps.length === 0) {
+        return { valid: true, errors: [] };
+    }
+    // 1. Topological sort — catches cycles and missing dependencies
+    try {
+        topoSortIntoWaves(plan.steps);
+    }
+    catch (err) {
+        if (err instanceof CycleError) {
+            errors.push(`Dependency cycle detected involving steps: ${err.involvedSteps.join(", ")}`);
+        }
+        else if (err instanceof DependencyError) {
+            errors.push(`Step "${err.stepId}" depends on "${err.missingDependency}" which does not exist in the plan`);
+        }
+        else {
+            errors.push(`Topological sort failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // 2. Output prefix uniqueness
+    const seen = new Map();
+    for (const step of plan.steps) {
+        const prefix = deriveOutputPrefix(step.id);
+        const ids = seen.get(prefix);
+        if (ids) {
+            ids.push(step.id);
+        }
+        else {
+            seen.set(prefix, [step.id]);
+        }
+    }
+    const duplicates = [...seen.entries()].filter(([, ids]) => ids.length > 1);
+    for (const [prefix, ids] of duplicates) {
+        errors.push(`Duplicate output prefix "${prefix}" used by steps: ${ids.join(", ")}`);
+    }
+    // 3. Agent assignment validation
+    for (const step of plan.steps) {
+        if (!step.agent) {
+            errors.push(`Step "${step.id}" has no agent assigned — every step must specify an agent`);
+        }
+        else if (!KNOWN_AGENTS.has(step.agent)) {
+            errors.push(`Step "${step.id}" assigns unknown agent "${step.agent}" — not found in agent catalog`);
+        }
+    }
+    // 4. Resources validation
+    const ceiling = options?.perStepCeiling;
+    for (const step of plan.steps) {
+        if (!step.resources) {
+            errors.push(`Step "${step.id}" has no resources defined — cpu and memoryGb are required`);
+            continue;
+        }
+        if (!ceiling)
+            continue;
+        if (step.resources.cpu > ceiling.maxCpu) {
+            errors.push(`Step "${step.id}" requests cpu: ${step.resources.cpu} but this host allows at most ` +
+                `${ceiling.maxCpu} per step — reduce cpu or restructure the step`);
+        }
+        if (step.resources.memoryGb > ceiling.maxMemoryGb) {
+            errors.push(`Step "${step.id}" requests memoryGb: ${step.resources.memoryGb} but this host allows at most ` +
+                `${ceiling.maxMemoryGb} per step — reduce memoryGb or restructure the step`);
+        }
+    }
+    // 5. Reserved step-id names (collide with artifact subdirectories)
+    for (const step of plan.steps) {
+        if (RESERVED_STEP_IDS.has(step.id.toLowerCase())) {
+            errors.push(`Step "${step.id}" uses a reserved name — step ids must not be one of: ` +
+                `${STEP_SUBDIRS.join(", ")} (they collide with the artifact subdirectory convention)`);
+        }
+    }
+    // 6. Step-id path safety. The id becomes the `runs/{runId}/{stepId}` directory
+    //    segment and a `/{analysisId}/…` container mount path; an unsafe segment
+    //    (a slash, or `.`/`..`) could traverse or widen the mount. The sandbox
+    //    mount boundary also rejects these (assertSafeId), but catching it here
+    //    turns it into an actionable, retryable planner error instead of a
+    //    durably-failed step at sandbox creation.
+    for (const step of plan.steps) {
+        if (!isSafeId(step.id)) {
+            errors.push(`Step "${step.id}" has an unsafe id — step ids may contain only letters, digits, '.', '_', '-' ` +
+                `and cannot be '.' or '..' (the id becomes a workspace directory and container mount segment)`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

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

@@ -0,0 +1,314 @@
+/**
+ * Workflow state schemas for the omics-analysis workflow.
+ *
+ * Defines Zod schemas for step inputs/outputs, plan structure,
+ * and the completion schemas that validate LLM structured output.
+ */
+import { z } from "zod";
+export declare const AnalysisStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    track: z.ZodString;
+    step_type: z.ZodString;
+    question: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    acceptance_criteria: z.ZodArray<z.ZodString>;
+    caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    depends_on: z.ZodArray<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        skipped: "skipped";
+    }>>;
+    resources: z.ZodOptional<z.ZodObject<{
+        cpu: z.ZodNumber;
+        memoryGb: z.ZodNumber;
+        gpu: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    agent: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    maxSteps: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    artifactIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AnalysisPlanSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    analytical_narrative: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        track: z.ZodString;
+        step_type: z.ZodString;
+        question: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        acceptance_criteria: z.ZodArray<z.ZodString>;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        depends_on: z.ZodArray<z.ZodString>;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            running: "running";
+            completed: "completed";
+            failed: "failed";
+            skipped: "skipped";
+        }>>;
+        resources: z.ZodOptional<z.ZodObject<{
+            cpu: z.ZodNumber;
+            memoryGb: z.ZodNumber;
+            gpu: z.ZodOptional<z.ZodObject<{
+                count: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        agent: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        maxSteps: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        artifactIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    created_at: z.ZodString;
+    omicsType: z.ZodOptional<z.ZodString>;
+    omicsSubtype: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Declarative suspension format — tells the frontend what to render
+ * without requiring per-type components. New suspension types only
+ * need changes on the cortex side.
+ *
+ * The frontend (lumen) renders the payload as:
+ *   1. A severity-themed container (border + background color)
+ *   2. Title + optional message header
+ *   3. Content blocks in order (rich display widgets)
+ *   4. Input fields (collected before any action)
+ *   5. Action buttons
+ *
+ * When the user clicks an action button, the frontend sends
+ * `{ ...action.value, ...filledInputValues }` as `resumeData`
+ * to the workflow resume endpoint.
+ */
+/**
+ * Content blocks — a library of renderable widgets the frontend knows
+ * how to display. New widget types require a frontend change, but each
+ * widget is reusable across all suspension types.
+ *
+ * - "markdown": rendered as prose via react-markdown
+ * - "plan": rich plan view (analytical narrative + step list)
+ * - "json": collapsible JSON preview in a <pre> block
+ * - "text": plain text paragraph
+ */
+export declare const ContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"markdown">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plan">;
+    plan: z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        analytical_narrative: z.ZodString;
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            track: z.ZodString;
+            step_type: z.ZodString;
+            question: z.ZodString;
+            context: z.ZodOptional<z.ZodString>;
+            constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            acceptance_criteria: z.ZodArray<z.ZodString>;
+            caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            depends_on: z.ZodArray<z.ZodString>;
+            status: z.ZodDefault<z.ZodEnum<{
+                pending: "pending";
+                running: "running";
+                completed: "completed";
+                failed: "failed";
+                skipped: "skipped";
+            }>>;
+            resources: z.ZodOptional<z.ZodObject<{
+                cpu: z.ZodNumber;
+                memoryGb: z.ZodNumber;
+                gpu: z.ZodOptional<z.ZodObject<{
+                    count: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            agent: z.ZodOptional<z.ZodString>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            maxSteps: z.ZodNumber;
+            description: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            artifactIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            error: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        created_at: z.ZodString;
+        omicsType: z.ZodOptional<z.ZodString>;
+        omicsSubtype: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"json">;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>], "type">;
+/**
+ * A button the user can click to resume the workflow.
+ *
+ * - `label`: button text (literal string, not an i18n key)
+ * - `value`: key-value pairs merged into resumeData when clicked
+ * - `variant`: button style — "default" (primary), "outline", or "destructive"
+ * - `icon`: optional icon rendered before the label
+ */
+export declare const SuspensionActionSchema: z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    variant: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        outline: "outline";
+        destructive: "destructive";
+    }>>;
+    icon: z.ZodOptional<z.ZodEnum<{
+        check: "check";
+        x: "x";
+        "alert-circle": "alert-circle";
+    }>>;
+}, z.core.$strip>;
+/**
+ * A form field rendered above the action buttons. The user's input
+ * is merged into resumeData under the `key` field when any action
+ * button is clicked. Empty inputs are omitted from resumeData.
+ *
+ * - `key`: the resumeData field name (e.g. "modifications", "answer")
+ * - `type`: "text" (single line), "textarea" (multi-line), or "select" (dropdown)
+ * - `required`: if true, all action buttons are disabled until filled
+ * - `options`: only used for "select" type — dropdown choices
+ */
+export declare const SuspensionInputSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        text: "text";
+        textarea: "textarea";
+        select: "select";
+    }>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Top-level suspension payload stored in `cortex_runs.suspension`.
+ *
+ * - `title`: header text (e.g. "Plan Ready for Review")
+ * - `message`: optional secondary text below the title
+ * - `severity`: controls the visual theme — "info" (blue), "warning" (amber), "error" (red).
+ *   Defaults to "warning" on the frontend if omitted.
+ * - `content`: ordered list of display widgets
+ * - `actions`: at least one button for the user to resume the workflow
+ * - `inputs`: optional form fields collected before any action
+ */
+export declare const SuspensionPayloadSchema: z.ZodObject<{
+    title: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>>;
+    content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"markdown">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"plan">;
+        plan: z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            analytical_narrative: z.ZodString;
+            steps: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                track: z.ZodString;
+                step_type: z.ZodString;
+                question: z.ZodString;
+                context: z.ZodOptional<z.ZodString>;
+                constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                acceptance_criteria: z.ZodArray<z.ZodString>;
+                caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                depends_on: z.ZodArray<z.ZodString>;
+                status: z.ZodDefault<z.ZodEnum<{
+                    pending: "pending";
+                    running: "running";
+                    completed: "completed";
+                    failed: "failed";
+                    skipped: "skipped";
+                }>>;
+                resources: z.ZodOptional<z.ZodObject<{
+                    cpu: z.ZodNumber;
+                    memoryGb: z.ZodNumber;
+                    gpu: z.ZodOptional<z.ZodObject<{
+                        count: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>;
+                agent: z.ZodOptional<z.ZodString>;
+                timeout: z.ZodOptional<z.ZodNumber>;
+                maxSteps: z.ZodNumber;
+                description: z.ZodOptional<z.ZodString>;
+                summary: z.ZodOptional<z.ZodString>;
+                artifactIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                error: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            created_at: z.ZodString;
+            omicsType: z.ZodOptional<z.ZodString>;
+            omicsSubtype: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"json">;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>>;
+    actions: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        variant: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            outline: "outline";
+            destructive: "destructive";
+        }>>;
+        icon: z.ZodOptional<z.ZodEnum<{
+            check: "check";
+            x: "x";
+            "alert-circle": "alert-circle";
+        }>>;
+    }, z.core.$strip>>;
+    inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            text: "text";
+            textarea: "textarea";
+            select: "select";
+        }>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type AnalysisStep = z.infer<typeof AnalysisStepSchema>;
+export type AnalysisPlan = z.infer<typeof AnalysisPlanSchema>;
+export type ContentBlock = z.infer<typeof ContentBlockSchema>;
+export type SuspensionAction = z.infer<typeof SuspensionActionSchema>;
+export type SuspensionInput = z.infer<typeof SuspensionInputSchema>;
+export type SuspensionPayload = z.infer<typeof SuspensionPayloadSchema>;

package/dist/schemas/workflow-state.js

@@ -0,0 +1,139 @@
+/**
+ * Workflow state schemas for the omics-analysis workflow.
+ *
+ * Defines Zod schemas for step inputs/outputs, plan structure,
+ * and the completion schemas that validate LLM structured output.
+ */
+import { z } from "zod";
+// ── Plan structures ─────────────────────────────────────────────────
+export const AnalysisStepSchema = z.object({
+    id: z.string().describe("Step ID in format T{track}S{step}"),
+    name: z.string(),
+    track: z.string(),
+    step_type: z.string(),
+    question: z.string(),
+    context: z.string().optional(),
+    constraints: z.array(z.string()).optional(),
+    acceptance_criteria: z.array(z.string()),
+    caveats: z.array(z.string()).optional(),
+    depends_on: z.array(z.string()),
+    status: z.enum(["pending", "running", "completed", "failed", "skipped"]).default("pending"),
+    // Optional on the persistence schema so historical plans (pre-resources)
+    // still parse on the read side. `PlanStepSchema` re-requires it for planner
+    // output, and the execution path rejects any step that reaches it without
+    // resources (no silent default) and clamps to cluster limits before use.
+    resources: z
+        .object({
+        cpu: z.number(),
+        memoryGb: z.number(),
+        gpu: z.object({ count: z.number() }).optional(),
+    })
+        .optional(),
+    // Execution fields
+    agent: z.string().optional().describe("Assigned sandbox agent name from registry"),
+    timeout: z.number().optional().describe("Execution timeout in seconds (falls back to image default)"),
+    maxSteps: z.number().describe("Max LLM agentic steps for sandbox agent"),
+    description: z.string().optional().describe("Human-readable description of what the step does"),
+    // Step result fields (populated during execution)
+    summary: z.string().optional().describe("Execution result summary"),
+    artifactIds: z.array(z.string()).optional().describe("Artifact IDs produced by this step"),
+    error: z.string().optional().describe("Error message if step failed"),
+});
+export const AnalysisPlanSchema = z.object({
+    // Optional on the persistence schema so historical plans (pre-title) still
+    // parse on the read side. `PlannerPlanSchema` re-requires it for new plans.
+    title: z.string().optional().describe("Concise human-readable plan name"),
+    analytical_narrative: z.string(),
+    steps: z.array(AnalysisStepSchema),
+    created_at: z.string(),
+    omicsType: z.string().optional().describe("Detected omics data type (e.g., transcriptomics, proteomics)"),
+    omicsSubtype: z.string().optional().describe("Detected subtype (e.g., bulk-rna-seq, single-cell)"),
+});
+// ── Suspension Payload ──────────────────────────────────────────────
+/**
+ * Declarative suspension format — tells the frontend what to render
+ * without requiring per-type components. New suspension types only
+ * need changes on the cortex side.
+ *
+ * The frontend (lumen) renders the payload as:
+ *   1. A severity-themed container (border + background color)
+ *   2. Title + optional message header
+ *   3. Content blocks in order (rich display widgets)
+ *   4. Input fields (collected before any action)
+ *   5. Action buttons
+ *
+ * When the user clicks an action button, the frontend sends
+ * `{ ...action.value, ...filledInputValues }` as `resumeData`
+ * to the workflow resume endpoint.
+ */
+/**
+ * Content blocks — a library of renderable widgets the frontend knows
+ * how to display. New widget types require a frontend change, but each
+ * widget is reusable across all suspension types.
+ *
+ * - "markdown": rendered as prose via react-markdown
+ * - "plan": rich plan view (analytical narrative + step list)
+ * - "json": collapsible JSON preview in a <pre> block
+ * - "text": plain text paragraph
+ */
+export const ContentBlockSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("markdown"), text: z.string() }),
+    z.object({ type: z.literal("plan"), plan: AnalysisPlanSchema }),
+    z.object({
+        type: z.literal("json"),
+        data: z.record(z.string(), z.unknown()),
+        label: z.string().optional(),
+    }),
+    z.object({ type: z.literal("text"), text: z.string() }),
+]);
+/**
+ * A button the user can click to resume the workflow.
+ *
+ * - `label`: button text (literal string, not an i18n key)
+ * - `value`: key-value pairs merged into resumeData when clicked
+ * - `variant`: button style — "default" (primary), "outline", or "destructive"
+ * - `icon`: optional icon rendered before the label
+ */
+export const SuspensionActionSchema = z.object({
+    label: z.string(),
+    value: z.record(z.string(), z.unknown()),
+    variant: z.enum(["default", "outline", "destructive"]).optional(),
+    icon: z.enum(["check", "x", "alert-circle"]).optional(),
+});
+/**
+ * A form field rendered above the action buttons. The user's input
+ * is merged into resumeData under the `key` field when any action
+ * button is clicked. Empty inputs are omitted from resumeData.
+ *
+ * - `key`: the resumeData field name (e.g. "modifications", "answer")
+ * - `type`: "text" (single line), "textarea" (multi-line), or "select" (dropdown)
+ * - `required`: if true, all action buttons are disabled until filled
+ * - `options`: only used for "select" type — dropdown choices
+ */
+export const SuspensionInputSchema = z.object({
+    key: z.string(),
+    label: z.string(),
+    type: z.enum(["text", "textarea", "select"]),
+    placeholder: z.string().optional(),
+    required: z.boolean().optional(),
+    options: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
+});
+/**
+ * Top-level suspension payload stored in `cortex_runs.suspension`.
+ *
+ * - `title`: header text (e.g. "Plan Ready for Review")
+ * - `message`: optional secondary text below the title
+ * - `severity`: controls the visual theme — "info" (blue), "warning" (amber), "error" (red).
+ *   Defaults to "warning" on the frontend if omitted.
+ * - `content`: ordered list of display widgets
+ * - `actions`: at least one button for the user to resume the workflow
+ * - `inputs`: optional form fields collected before any action
+ */
+export const SuspensionPayloadSchema = z.object({
+    title: z.string(),
+    message: z.string().optional(),
+    severity: z.enum(["info", "warning", "error"]).optional(),
+    content: z.array(ContentBlockSchema).optional(),
+    actions: z.array(SuspensionActionSchema),
+    inputs: z.array(SuspensionInputSchema).optional(),
+});

package/dist/state/active-sandboxes.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Active-sandbox registry (CONTEXT.md) — the projection over
+ * `cortex_step_executions` rows with a non-null `sandbox_ref` and a running
+ * status. Owns the `sandbox_ref` + `exec_id` columns: written by
+ * `sandbox/create-sandbox.ts` on mint, cleared on teardown, enumerated by
+ * `sandbox/watchdog.ts` for liveness sweeps.
+ */
+import type { ResultAsync } from "neverthrow";
+import { type DbError } from "../lib/db-result.js";
+import type { Querier } from "./db.js";
+import type { PersistedSandboxRef } from "./schema.js";
+/**
+ * Record the live sandbox handle on a step row. Called inside the
+ * `createSandbox` DBOS step after the backend has confirmed the sandbox
+ * is up. The `callbackSecret` is deliberately not part of the persisted
+ * shape (see the harness-sandbox-exec spec) — it lives only in the cached step output.
+ */
+export declare function setSandboxRef(pool: Querier, runId: string, stepId: string, sandboxRef: PersistedSandboxRef, execId: string | null): ResultAsync<void, DbError>;
+/**
+ * Tag the active-sandbox row with the exec currently in flight. Called from
+ * `run-exec.ts` right before `awaitExec` so the liveness watchdog can target
+ * the hung exec when the sandbox dies mid-command. Targets the same
+ * `(run_id, step_id)` row `setSandboxRef` writes and `queryActiveSandboxes`
+ * enumerates. Overwritten by the next exec; cleared on teardown.
+ */
+export declare function setActiveExecId(pool: Querier, runId: string, stepId: string, execId: string): ResultAsync<void, DbError>;
+/**
+ * Clear the sandbox handle. Called inside the `teardown` DBOS step. Safe
+ * to call when no sandbox was ever recorded — the UPDATE simply targets
+ * zero rows.
+ */
+export declare function clearSandboxRef(pool: Querier, runId: string, stepId: string): ResultAsync<void, DbError>;
+/**
+ * Enumerate the active-sandbox registry — every running step with a live
+ * sandbox attached. The liveness watchdog consumes this, shards the
+ * result, and fans out per-shard check workflows.
+ *
+ * Returns the raw row tuple (no Zod parse) so the watchdog can shard
+ * without paying for parse work it doesn't need.
+ */
+export interface ActiveSandboxRow {
+    runId: string;
+    stepId: string;
+    analysisId: string;
+    sandboxRef: PersistedSandboxRef;
+    execId: string | null;
+}
+/**
+ * Reconcile a step row after the reaper deletes its sandbox machine (ADR
+ * 0016). Always clears `sandbox_ref`/`exec_id` (drops the row from the
+ * active-sandbox registry, ending the watchdog churn); a row still stuck at
+ * `status='running'` — a cancellation that never ran its `mark-*` step — is
+ * also flipped to the owning workflow's terminal status so a terminal workflow
+ * never leaves a perpetually-"running" step behind. Returns true if a row
+ * matched. Safe when no row exists (Class A pure orphan): matches zero rows.
+ */
+export declare function reconcileReapedSandbox(pool: Querier, sandboxId: string, terminalStatus: "canceled" | "failed" | "completed"): ResultAsync<boolean, DbError>;
+export declare function queryActiveSandboxes(pool: Querier): ResultAsync<ActiveSandboxRow[], DbError>;