stageflow 0.8.0 → 0.12.0

package/dist/envelope/cloneForks.js

@@ -1,5 +1,7 @@
 import { parseCloneForks } from "./check.js";
+import { assertCloneAssignmentPayload } from "./payloadSchema.js";
 import { EnvelopeError } from "../types/envelope.js";
+import { CLONE_ACTIONS } from "../types/forkChoice.js";
 function fieldPresent(item, key) {
     return item[key] !== undefined;
 }
@@ -17,40 +19,53 @@ export function assertCloneForks(params, cloneEmitContext) {
     const expectedIds = cloneEmitContext.clonableSuccessors.map((s) => s.successorId);
     const expectedSet = new Set(expectedIds);
     const seen = new Set();
-    for (const item of items) {
+    for (const [i, item] of items.entries()) {
+        const itemPath = `clone_forks[${i}]`;
         if (seen.has(item.successor_id)) {
-            throw new EnvelopeError(`clone_forks contains duplicate successor_id: ${item.successor_id}`);
+            throw new EnvelopeError(`${itemPath} contains duplicate successor_id: ${item.successor_id}`);
         }
         if (!expectedSet.has(item.successor_id)) {
-            throw new EnvelopeError(`clone_forks contains extra successor_id: ${item.successor_id}`);
+            throw new EnvelopeError(`${itemPath} contains extra successor_id: ${item.successor_id}`);
         }
         seen.add(item.successor_id);
         const capEntry = cloneEmitContext.clonableSuccessors.find((s) => s.successorId === item.successor_id);
         const cloneCap = capEntry?.cloneCap;
+        const allowedActions = cloneEmitContext.allowedActions ?? [...CLONE_ACTIONS];
+        if (!allowedActions.includes(item.action)) {
+            throw new EnvelopeError(`${itemPath} action "${item.action}" is not allowed for ${item.successor_id} (allowed: ${allowedActions.join(", ")})`);
+        }
         if (item.action === "skip") {
             if (fieldPresent(item, "envelope") ||
                 fieldPresent(item, "mode") ||
                 fieldPresent(item, "clones")) {
-                throw new EnvelopeError(`clone_forks skip for ${item.successor_id} must not include envelope, mode, or clones`);
+                throw new EnvelopeError(`${itemPath} skip for ${item.successor_id} must not include envelope, mode, or clones`);
             }
         }
         else if (item.action === "once") {
             if (!fieldPresent(item, "envelope")) {
-                throw new EnvelopeError(`clone_forks once for ${item.successor_id} requires envelope`);
+                throw new EnvelopeError(`${itemPath} once for ${item.successor_id} requires envelope`);
             }
             if (fieldPresent(item, "mode") || fieldPresent(item, "clones")) {
-                throw new EnvelopeError(`clone_forks once for ${item.successor_id} must not include mode or clones`);
+                throw new EnvelopeError(`${itemPath} once for ${item.successor_id} must not include mode or clones`);
+            }
+            if (capEntry?.cloneInputSchema !== undefined) {
+                assertCloneAssignmentPayload(item.envelope, capEntry.cloneInputSchema, item.successor_id, `${itemPath}.envelope`);
             }
         }
         else if (item.action === "fanout") {
             if (fieldPresent(item, "envelope")) {
-                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} must not include a top-level envelope`);
+                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} must not include a top-level envelope`);
             }
             if (!fieldPresent(item, "mode") || !fieldPresent(item, "clones") || item.clones === undefined) {
-                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} requires mode and clones`);
+                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} requires mode and clones`);
             }
             if (cloneCap === undefined || item.clones.length < 2 || item.clones.length > cloneCap) {
-                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} must have between 2 and ${cloneCap} clones`);
+                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} must have between 2 and ${cloneCap} clones`);
+            }
+            if (capEntry?.cloneInputSchema !== undefined) {
+                for (const [j, clone] of item.clones.entries()) {
+                    assertCloneAssignmentPayload(clone.envelope, capEntry.cloneInputSchema, item.successor_id, `${itemPath}.clones[${j}].envelope`);
+                }
             }
         }
     }

package/dist/envelope/feedbackLoop.d.ts

@@ -0,0 +1,4 @@
+import { type StageEnvelope } from "../types/envelope.js";
+import type { FeedbackLoopConfig } from "../types/pipeline.js";
+/** Validates an action against the source stage's declared feedback-loop policy. */
+export declare function assertFeedbackLoopAction(envelope: StageEnvelope, context: FeedbackLoopConfig | undefined): void;

package/dist/envelope/feedbackLoop.js

@@ -0,0 +1,31 @@
+import { EnvelopeError } from "../types/envelope.js";
+/** Validates an action against the source stage's declared feedback-loop policy. */
+export function assertFeedbackLoopAction(envelope, context) {
+    if (context === undefined) {
+        if (envelope.feedback_loop !== undefined) {
+            throw new EnvelopeError("feedback_loop is only allowed for a configured feedback-loop stage");
+        }
+        return;
+    }
+    if (envelope.status === "failure") {
+        if (envelope.feedback_loop !== undefined) {
+            throw new EnvelopeError("feedback_loop action is not allowed when status is failure");
+        }
+        return;
+    }
+    const action = envelope.feedback_loop;
+    if (action === undefined) {
+        throw new EnvelopeError("feedback_loop action is required for a successful feedback-loop stage");
+    }
+    if (action.action === "continue")
+        return;
+    if (envelope.fork_choice !== undefined) {
+        throw new EnvelopeError("feedback_loop send_back cannot be combined with fork_choice");
+    }
+    if (envelope.clone_forks !== undefined) {
+        throw new EnvelopeError("feedback_loop send_back cannot be combined with clone_forks");
+    }
+    if (action.target !== context.target) {
+        throw new EnvelopeError(`feedback_loop.target "${action.target}" is not an allowed feedback-loop target`);
+    }
+}

package/dist/envelope/payloadSchema.d.ts

@@ -4,7 +4,13 @@ export type CompiledPayloadSchema = TSchema;
 /**
  * Compile a JSON Schema subset used for stage payload_schema.
  * Supported: type object/string/number/integer/boolean/array,
- * properties, required, items, additionalProperties (boolean).
+ * properties, required, items, additionalProperties (boolean),
+ * minItems, enum, minimum, maximum. String nodes also accept
+ * pattern (a JS RegExp validated with the unicode flag), minLength,
+ * and maxLength (non-negative integers). Nested nodes accept
+ * nullable (boolean), compiling to a union of that type with null;
+ * the root object cannot be nullable. Unknown keywords are ignored.
  */
 export declare function compilePayloadSchema(raw: unknown): CompiledPayloadSchema;
 export declare function assertEnvelopePayload(envelope: StageEnvelope, payloadSchema: unknown | undefined): void;
+export declare function assertCloneAssignmentPayload(envelope: StageEnvelope, cloneInputSchema: unknown, successorId: string, itemPath?: string): void;

package/dist/envelope/payloadSchema.js

@@ -1,6 +1,89 @@
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { EnvelopeError } from "../types/envelope.js";
+function readEnum(schema, path, valueType) {
+    if (schema.enum === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0) {
+        throw new Error(`${path}: enum must be a non-empty array when present`);
+    }
+    if (valueType === "string") {
+        if (!schema.enum.every((value) => typeof value === "string")) {
+            throw new Error(`${path}: enum values must be strings`);
+        }
+        return schema.enum;
+    }
+    if (!schema.enum.every((value) => typeof value === "number" && Number.isInteger(value))) {
+        throw new Error(`${path}: enum values must be integers`);
+    }
+    return schema.enum;
+}
+function readBound(value, path, keyword) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${path}: ${keyword} must be a number when present`);
+    }
+    return value;
+}
+function numericOptions(schema, path) {
+    const minimum = readBound(schema.minimum, path, "minimum");
+    const maximum = readBound(schema.maximum, path, "maximum");
+    if (minimum === undefined && maximum === undefined) {
+        return undefined;
+    }
+    return {
+        ...(minimum !== undefined ? { minimum } : {}),
+        ...(maximum !== undefined ? { maximum } : {}),
+    };
+}
+function readPattern(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${path}: pattern must be a string when present`);
+    }
+    try {
+        // eslint-disable-next-line no-new
+        new RegExp(value, "u");
+    }
+    catch {
+        throw new Error(`${path}: pattern must be a valid regular expression`);
+    }
+    return value;
+}
+function readNonNegativeInt(value, path, keyword) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < 0) {
+        throw new Error(`${path}: ${keyword} must be a non-negative integer when present`);
+    }
+    return value;
+}
+function stringOptions(schema, path) {
+    const pattern = readPattern(schema.pattern, path);
+    const minLength = readNonNegativeInt(schema.minLength, path, "minLength");
+    const maxLength = readNonNegativeInt(schema.maxLength, path, "maxLength");
+    if (minLength !== undefined &&
+        maxLength !== undefined &&
+        minLength > maxLength) {
+        throw new Error(`${path}: minLength must be <= maxLength`);
+    }
+    if (pattern === undefined && minLength === undefined && maxLength === undefined) {
+        return undefined;
+    }
+    return {
+        ...(pattern !== undefined ? { pattern } : {}),
+        ...(minLength !== undefined ? { minLength } : {}),
+        ...(maxLength !== undefined ? { maxLength } : {}),
+    };
+}
 function compileNode(node, path) {
     if (node === null || typeof node !== "object" || Array.isArray(node)) {
         throw new Error(`${path}: schema must be an object`);
@@ -9,20 +92,58 @@ function compileNode(node, path) {
     if (typeof schema.type !== "string") {
         throw new Error(`${path}: type is required`);
     }
+    if (schema.nullable !== undefined && typeof schema.nullable !== "boolean") {
+        throw new Error(`${path}: nullable must be a boolean when present`);
+    }
+    const nullable = schema.nullable === true;
+    let base;
     switch (schema.type) {
-        case "string":
-            return Type.String();
-        case "number":
-            return Type.Number();
-        case "integer":
-            return Type.Integer();
+        case "string": {
+            const enumerated = readEnum(schema, path, "string");
+            const opts = stringOptions(schema, path);
+            base =
+                enumerated !== undefined
+                    ? Type.Enum(enumerated, opts)
+                    : opts !== undefined
+                        ? Type.String(opts)
+                        : Type.String();
+            break;
+        }
+        case "number": {
+            const options = numericOptions(schema, path);
+            base = options !== undefined ? Type.Number(options) : Type.Number();
+            break;
+        }
+        case "integer": {
+            const enumerated = readEnum(schema, path, "integer");
+            const options = numericOptions(schema, path);
+            if (enumerated !== undefined) {
+                base = Type.Enum(enumerated, options);
+            }
+            else {
+                base = options !== undefined ? Type.Integer(options) : Type.Integer();
+            }
+            break;
+        }
         case "boolean":
-            return Type.Boolean();
+            base = Type.Boolean();
+            break;
         case "array": {
             if (schema.items === undefined) {
                 throw new Error(`${path}: array requires items`);
             }
-            return Type.Array(compileNode(schema.items, `${path}.items`));
+            if (schema.minItems !== undefined &&
+                (typeof schema.minItems !== "number" ||
+                    !Number.isInteger(schema.minItems) ||
+                    schema.minItems < 0)) {
+                throw new Error(`${path}: minItems must be a non-negative integer when present`);
+            }
+            const items = compileNode(schema.items, `${path}.items`);
+            base =
+                schema.minItems !== undefined
+                    ? Type.Array(items, { minItems: schema.minItems })
+                    : Type.Array(items);
+            break;
         }
         case "object": {
             const properties = schema.properties ?? {};
@@ -51,24 +172,46 @@ function compileNode(node, path) {
             const options = schema.additionalProperties === false
                 ? { additionalProperties: false }
                 : undefined;
-            return Type.Object(compiledProps, options);
+            base = Type.Object(compiledProps, options);
+            break;
         }
         default:
             throw new Error(`${path}: unsupported type "${schema.type}" (supported: object, string, number, integer, boolean, array)`);
     }
+    return nullable ? Type.Union([base, Type.Null()]) : base;
 }
 /**
  * Compile a JSON Schema subset used for stage payload_schema.
  * Supported: type object/string/number/integer/boolean/array,
- * properties, required, items, additionalProperties (boolean).
+ * properties, required, items, additionalProperties (boolean),
+ * minItems, enum, minimum, maximum. String nodes also accept
+ * pattern (a JS RegExp validated with the unicode flag), minLength,
+ * and maxLength (non-negative integers). Nested nodes accept
+ * nullable (boolean), compiling to a union of that type with null;
+ * the root object cannot be nullable. Unknown keywords are ignored.
  */
 export function compilePayloadSchema(raw) {
+    if (raw !== null &&
+        typeof raw === "object" &&
+        !Array.isArray(raw) &&
+        raw.nullable === true) {
+        throw new Error("payload_schema: root cannot be nullable");
+    }
     const compiled = compileNode(raw, "payload_schema");
     if (!Type.IsObject(compiled)) {
         throw new Error("payload_schema: root type must be object");
     }
     return compiled;
 }
+function formatPayloadInstancePath(instancePath) {
+    const translated = instancePath.replace(/\//g, ".").replace(/^\./, "");
+    return translated ? `payload.${translated}` : "payload";
+}
+function payloadSchemaMismatchDetails(schema, payload) {
+    return [...Value.Errors(schema, payload)]
+        .map((err) => `${formatPayloadInstancePath(err.instancePath)} ${err.message}`)
+        .join("; ");
+}
 export function assertEnvelopePayload(envelope, payloadSchema) {
     if (payloadSchema === undefined) {
         return;
@@ -81,11 +224,25 @@ export function assertEnvelopePayload(envelope, payloadSchema) {
         throw new EnvelopeError("payload is required by stage payload_schema");
     }
     if (!Value.Check(schema, envelope.payload)) {
-        const details = [...Value.Errors(schema, envelope.payload)]
-            .map((err) => `${err.instancePath || "/"} ${err.message}`)
-            .join("; ");
+        const details = payloadSchemaMismatchDetails(schema, envelope.payload);
         throw new EnvelopeError(details
             ? `payload does not match payload_schema: ${details}`
             : "payload does not match payload_schema");
     }
 }
+export function assertCloneAssignmentPayload(envelope, cloneInputSchema, successorId, itemPath = "") {
+    if (envelope.status !== "success") {
+        return;
+    }
+    const schema = compilePayloadSchema(cloneInputSchema);
+    const pathLead = itemPath ? `${itemPath}: ` : "";
+    if (envelope.payload === undefined) {
+        throw new EnvelopeError(`${pathLead}clone assignment payload is required by clone_input_schema for ${successorId}`);
+    }
+    if (!Value.Check(schema, envelope.payload)) {
+        const details = payloadSchemaMismatchDetails(schema, envelope.payload);
+        throw new EnvelopeError(details
+            ? `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}: ${details}`
+            : `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}`);
+    }
+}

package/dist/envelope/preEmitChecks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * In-session runner for `pre_emit_checks` (`src/types/preEmitCheck.ts`).
+ *
+ * Distinct from `completionCheckRunner.ts`'s post-hoc `CompletionCheck`
+ * runner: this runs synchronously inside `emit_stage_envelope`'s own tool
+ * call, before a candidate envelope is even captured, and never touches
+ * disk — `artifact_declared` only checks whether a basename is *listed* in
+ * `envelope.artifacts`, and `gate` only reads the live, attempt-scoped QA
+ * trail via a caller-supplied `readQaTrail`. See the design doc's Q1/Q3 for
+ * why this stays separate from `CompletionCheck`'s `artifact`/`gate` runners.
+ */
+import { type QaExchange } from "../hitl/qaTrail.js";
+import { type StageEnvelope } from "../types/envelope.js";
+import type { PreEmitCheck } from "../types/preEmitCheck.js";
+export type PreEmitCheckOptions = {
+    checks?: PreEmitCheck[];
+    readQaTrail?: () => QaExchange[] | Promise<QaExchange[]>;
+};
+export declare function declaredArtifactIssue(artifacts: readonly string[], check: Extract<PreEmitCheck, {
+    type: "artifact_declared";
+}>): string | undefined;
+/**
+ * Runs `options.checks` in declaration order and throws `EnvelopeError` on
+ * the first failing check, matching the single-message-per-rejected-emit
+ * contract the rest of `emitStageEnvelope.ts`'s `assert*` helpers use. A
+ * `gate` check with no `readQaTrail` fails closed (cannot be verified). No
+ * `checks` (or an empty list) is a no-op.
+ */
+export declare function assertPreEmitChecks(envelope: Pick<StageEnvelope, "artifacts">, options: PreEmitCheckOptions | undefined): Promise<void>;

package/dist/envelope/preEmitChecks.js

@@ -0,0 +1,57 @@
+/**
+ * In-session runner for `pre_emit_checks` (`src/types/preEmitCheck.ts`).
+ *
+ * Distinct from `completionCheckRunner.ts`'s post-hoc `CompletionCheck`
+ * runner: this runs synchronously inside `emit_stage_envelope`'s own tool
+ * call, before a candidate envelope is even captured, and never touches
+ * disk — `artifact_declared` only checks whether a basename is *listed* in
+ * `envelope.artifacts`, and `gate` only reads the live, attempt-scoped QA
+ * trail via a caller-supplied `readQaTrail`. See the design doc's Q1/Q3 for
+ * why this stays separate from `CompletionCheck`'s `artifact`/`gate` runners.
+ */
+import { preEmitGateIssue } from "../hitl/qaTrail.js";
+import { EnvelopeError } from "../types/envelope.js";
+function artifactListsBasename(artifact, basename) {
+    return artifact === basename || artifact.endsWith(`/${basename}`);
+}
+export function declaredArtifactIssue(artifacts, check) {
+    const listed = artifacts.some((artifact) => artifactListsBasename(artifact, check.basename));
+    if (!listed) {
+        return `required artifact "${check.basename}" is missing from envelope.artifacts`;
+    }
+    return undefined;
+}
+/**
+ * Runs `options.checks` in declaration order and throws `EnvelopeError` on
+ * the first failing check, matching the single-message-per-rejected-emit
+ * contract the rest of `emitStageEnvelope.ts`'s `assert*` helpers use. A
+ * `gate` check with no `readQaTrail` fails closed (cannot be verified). No
+ * `checks` (or an empty list) is a no-op.
+ */
+export async function assertPreEmitChecks(envelope, options) {
+    const checks = options?.checks;
+    if (checks === undefined || checks.length === 0) {
+        return;
+    }
+    let exchanges;
+    for (const check of checks) {
+        if (check.type === "artifact_declared") {
+            const issue = declaredArtifactIssue(envelope.artifacts, check);
+            if (issue !== undefined) {
+                throw new EnvelopeError(issue);
+            }
+            continue;
+        }
+        // check.type === "gate"
+        if (options?.readQaTrail === undefined) {
+            throw new EnvelopeError("declared gate kinds cannot be verified without a QA trail reader");
+        }
+        if (exchanges === undefined) {
+            exchanges = await options.readQaTrail();
+        }
+        const issue = preEmitGateIssue(exchanges, check);
+        if (issue !== undefined) {
+            throw new EnvelopeError(issue);
+        }
+    }
+}

package/dist/hitl/qaTrail.d.ts

@@ -7,6 +7,7 @@
 import type { OperatorAnswerActivityEvent, OperatorPromptActivityEvent, StageActivityEvent, StageLogLine } from "../agent/activity.js";
 import type { RunStore, StageLogEvent } from "../runstore/port.js";
 import type { AskOperatorAnswer, AskOperatorPrompt } from "../tools/askOperator.js";
+import type { PreEmitCheck } from "../types/preEmitCheck.js";
 export type { OperatorAnswerActivityEvent, OperatorPromptActivityEvent, } from "../agent/activity.js";
 export type { AskOperatorAnswer, AskOperatorPrompt } from "../tools/askOperator.js";
 export type QaExchange = {
@@ -28,4 +29,28 @@ export declare function appendOperatorAnswer(store: RunStore, runId: string, sta
     attempt?: number;
 }): Promise<void>;
 export declare function listQaExchanges(events: readonly StageLogEvent[]): QaExchange[];
+/**
+ * Builds a reader over the live, attempt-scoped QA trail: `listStageEvents`
+ * for this run/stage/attempt, collapsed via `listQaExchanges`. Read at
+ * `emit_stage_envelope` execute time (not at stage-open/factory time) so it
+ * reflects exchanges recorded during this attempt, including ones recorded
+ * after the reader was constructed.
+ */
+export declare function createAttemptQaTrailReader(store: Pick<RunStore, "listStageEvents">, runId: string, stageId: string, attempt: number): () => Promise<QaExchange[]>;
+/**
+ * Pre-emit `gate`-type check predicate: is the *most recent* exchange of the
+ * check's declared kind, within this attempt's ordered trail, satisfied?
+ * `confirm`/`artifact_backed` require the last such exchange's decision to be
+ * "accept"; `free_text`/`multi_question` are satisfied by any completed
+ * (answered) exchange of that kind. Returns an issue string on failure,
+ * `undefined` on success. Deliberately independent of
+ * `completionCheckRunner.ts`'s `runGateCheck` (see design doc Q2): that
+ * function asks the looser, retrospective "was this kind ever accepted over
+ * the run so far" question via order-erased `GateDecision[]`; this asks the
+ * stricter, attempt-scoped "is the last answer of this kind an accept"
+ * question, which requires the raw, ordered `QaExchange[]`.
+ */
+export declare function preEmitGateIssue(exchanges: readonly QaExchange[], check: Extract<PreEmitCheck, {
+    type: "gate";
+}>): string | undefined;
 export declare function derivePendingPrompt(events: readonly StageLogEvent[]): AskOperatorPrompt | null;

package/dist/hitl/qaTrail.js

@@ -59,6 +59,57 @@ export function listQaExchanges(events) {
     assertAtMostOnePending(exchanges);
     return exchanges;
 }
+const DECISION_GATE_KINDS = new Set([
+    "confirm",
+    "artifact_backed",
+]);
+/**
+ * Builds a reader over the live, attempt-scoped QA trail: `listStageEvents`
+ * for this run/stage/attempt, collapsed via `listQaExchanges`. Read at
+ * `emit_stage_envelope` execute time (not at stage-open/factory time) so it
+ * reflects exchanges recorded during this attempt, including ones recorded
+ * after the reader was constructed.
+ */
+export function createAttemptQaTrailReader(store, runId, stageId, attempt) {
+    return async () => {
+        const events = await store.listStageEvents(runId, stageId, attempt);
+        return listQaExchanges(events);
+    };
+}
+function lastDecisionIsAccept(answer) {
+    return ((answer.kind === "confirm" || answer.kind === "artifact_backed") &&
+        answer.decision === "accept");
+}
+/**
+ * Pre-emit `gate`-type check predicate: is the *most recent* exchange of the
+ * check's declared kind, within this attempt's ordered trail, satisfied?
+ * `confirm`/`artifact_backed` require the last such exchange's decision to be
+ * "accept"; `free_text`/`multi_question` are satisfied by any completed
+ * (answered) exchange of that kind. Returns an issue string on failure,
+ * `undefined` on success. Deliberately independent of
+ * `completionCheckRunner.ts`'s `runGateCheck` (see design doc Q2): that
+ * function asks the looser, retrospective "was this kind ever accepted over
+ * the run so far" question via order-erased `GateDecision[]`; this asks the
+ * stricter, attempt-scoped "is the last answer of this kind an accept"
+ * question, which requires the raw, ordered `QaExchange[]`.
+ */
+export function preEmitGateIssue(exchanges, check) {
+    const ofKind = exchanges.filter((ex) => ex.prompt.kind === check.kind);
+    if (DECISION_GATE_KINDS.has(check.kind)) {
+        const last = ofKind.at(-1);
+        if (last === undefined || last.answer === null) {
+            return `declared gate kind "${check.kind}" has not completed this attempt`;
+        }
+        if (!lastDecisionIsAccept(last.answer)) {
+            return `declared gate kind "${check.kind}" last decision must be "accept"`;
+        }
+        return undefined;
+    }
+    if (!ofKind.some((ex) => ex.answer !== null)) {
+        return `declared gate kind "${check.kind}" has not completed this attempt`;
+    }
+    return undefined;
+}
 export function derivePendingPrompt(events) {
     const pending = listQaExchanges(events).find((ex) => ex.answer === null);
     return pending?.prompt ?? null;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/f
 export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
 export { resolveProjectContext, legacyProjectContext, type ProjectContext, } from "./project/resolveProjectContext.js";
 export { resolveStageflowContext, projectContextFromStageflow, type StageflowContext, type CatalogManifestStatus, } from "./project/resolveStageflowContext.js";
-export { PACKAGE_NAME } from "./package-meta.js";
+export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export type { AgentPort } from "./agent/port.js";

package/dist/index.js

@@ -2,7 +2,7 @@ export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/f
 export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
 export { resolveProjectContext, legacyProjectContext, } from "./project/resolveProjectContext.js";
 export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
-export { PACKAGE_NAME } from "./package-meta.js";
+export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
 export { createRunStore } from "./runstore/createStore.js";

package/dist/mcp/catalogTools.js

@@ -83,7 +83,7 @@ export function registerCatalogTools(server, deps) {
         return textResult({ runId: result.runId });
     });
     server.registerTool("get_run", {
-        description: "Poll a run: status, stage statuses, waiting_* / pending_prompt HITL fields, and envelope summary/payload/artifact paths (no events). Use list_stage_events / get_envelope for timelines and full envelopes.",
+        description: "Poll a run: status, stage statuses, waiting_* / pending_prompt HITL fields, and envelope summary/payload/artifact paths (no events). Use list_stage_events, get_envelope, or get_stage_verification for stage detail.",
         inputSchema: z.object({
             runId: z.string(),
         }),
@@ -165,7 +165,9 @@ export function registerCatalogTools(server, deps) {
             const gateById = new Map(loaded.stages.map((s) => [s.id, s.gate_kinds]));
             const stages = loaded.dag.nodes.map((node) => ({
                 id: node.id,
-                needs: node.needs,
+                needs: node.needsEdges.length > 1
+                    ? node.needsEdges.map((edge) => ({ id: edge.id, on: [...edge.on] }))
+                    : node.needs,
                 ...(node.fork !== undefined ? { fork: node.fork } : {}),
                 ...(node.clonable !== undefined ? { clonable: node.clonable } : {}),
                 ...(node.clone_cap !== undefined ? { clone_cap: node.clone_cap } : {}),