stageflow 0.9.0 → 0.12.0

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/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 } : {}),

package/dist/mcp/controlTools.js

@@ -3,6 +3,7 @@ import { mapRetryStageFailure, mapStartFailure, } from "../server/operatorResult
 import { parseAskOperatorAnswer } from "../tools/askOperator.js";
 import { textResult } from "./toolResults.js";
 import { projectWaitingGates } from "./waitingGates.js";
+import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 export function registerControlTools(server, deps) {
     const { manager, store } = deps;
     server.registerTool("list_waiting", {
@@ -36,6 +37,30 @@ export function registerControlTools(server, deps) {
         }
         return textResult({ ok: true });
     });
+    server.registerTool("decide_feedback_loop", {
+        description: "Resolve a feedback-loop wait_for_human decision (extend, continue, or abandon). Same semantics as POST /api/runs/:id/stages/:stageId/feedback-decision.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+            decision: z.enum(["extend", "continue", "abandon"]),
+            loopId: z.string().optional(),
+            reason: z.string().optional(),
+        }),
+    }, async ({ runId, stageId, decision, loopId, reason }) => {
+        const result = await manager.decideFeedbackLoop(runId, stageId, {
+            decision,
+            ...(loopId !== undefined ? { loopId } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+        });
+        if (!result.ok) {
+            return textResult({ error: result.reason, status: result.status }, true);
+        }
+        return textResult({
+            ok: true,
+            effect: result.effect,
+            loopId: result.loopId,
+        });
+    });
     server.registerTool("list_stage_events", {
         description: "List persisted stage log events for a run stage (optional attempt filter). Prefer over bloating get_run.",
         inputSchema: z.object({
@@ -66,6 +91,53 @@ export function registerControlTools(server, deps) {
             return textResult({ error: message, status: notFound ? 404 : 500 }, true);
         }
     });
+    server.registerTool("get_stage_verification", {
+        description: "Read every execution attempt for a stage, including durable completion-check results and their evidence. Use this to understand an automatic repair or a failed verification.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        try {
+            return textResult(await readStageVerificationHistory(store, runId, stageId));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = /not found|no such/i.test(message);
+            return textResult({ error: message, status: notFound ? 404 : 500 }, true);
+        }
+    });
+    server.registerTool("recover_manual_stage", {
+        description: "Explicitly approve one fresh attempt for a manual-recovery stage after a completion verification failure. Optional guidance is recorded and supplied to the agent with the failed-check evidence.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+            guidance: z.string().max(4_000).optional(),
+        }),
+    }, async ({ runId, stageId, guidance }) => {
+        const result = await manager.recoverManualStage(runId, stageId, guidance);
+        if (!result.ok) {
+            return textResult({ ...mapRetryStageFailure(result), status: result.status }, true);
+        }
+        return textResult({
+            runId: result.runId,
+            stageId: result.stageId,
+            attemptIndex: result.attemptIndex,
+        });
+    });
+    server.registerTool("stop_manual_recovery", {
+        description: "Record the operator's decision to leave a manual-recovery stage failed. This is terminal for that stage; start a fresh run to try again later.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        const result = await manager.stopManualRecovery(runId, stageId);
+        if (!result.ok) {
+            return textResult({ error: result.reason, status: result.status }, true);
+        }
+        return textResult(result);
+    });
     server.registerTool("get_envelope", {
         description: "Read the full StageEnvelope for a run stage (latest attempt). Returns 404 when absent.",
         inputSchema: z.object({

package/dist/mcp/waitingGates.d.ts

@@ -1,10 +1,11 @@
-import type { RunStore, RunSummary, StageSnapshot } from "../runstore/port.js";
+import type { RunDetail, RunStore, RunSummary, StageSnapshot } from "../runstore/port.js";
 type WaitingSummarySource = Pick<RunSummary, "run_id" | "waiting_stage_id" | "waiting_stage_ids" | "waiting_kind" | "waiting_summary" | "waiting_prompt_id" | "waiting_artifacts" | "waiting_questions">;
 export declare function projectWaitingGate(opts: {
     runId: string;
     stageId: string;
     stage: StageSnapshot;
     summary: WaitingSummarySource;
+    activeFeedbackLoop?: RunDetail["active_feedback_loop"];
 }): Record<string, unknown>;
 export declare function projectWaitingGates(store: RunStore, opts?: {
     runId?: string;

package/dist/mcp/waitingGates.js

@@ -1,5 +1,5 @@
 export function projectWaitingGate(opts) {
-    const { runId, stageId, stage, summary } = opts;
+    const { runId, stageId, stage, summary, activeFeedbackLoop } = opts;
     const prompt = stage.pending_prompt;
     const item = {
         runId,
@@ -36,6 +36,21 @@ export function projectWaitingGate(opts) {
             item.waiting_questions = summary.waiting_questions;
         }
     }
+    if ((item.waiting_kind === "feedback_loop_decision" ||
+        activeFeedbackLoop?.state === "waiting_for_human") &&
+        activeFeedbackLoop !== undefined) {
+        item.feedback_loop_id = activeFeedbackLoop.loop_id;
+        if (activeFeedbackLoop.deferred_send_back?.target !== undefined) {
+            item.deferred_target = activeFeedbackLoop.deferred_send_back.target;
+        }
+        if (item.waiting_kind === undefined) {
+            item.waiting_kind = "feedback_loop_decision";
+        }
+        if (item.waiting_summary === undefined) {
+            item.waiting_summary =
+                "Feedback loop limit reached — extend, continue, or abandon";
+        }
+    }
     return item;
 }
 function projectGatesForRun(detail, summary) {
@@ -51,6 +66,7 @@ function projectGatesForRun(detail, summary) {
             stageId,
             stage,
             summary,
+            activeFeedbackLoop: detail.active_feedback_loop,
         }));
     }
     return items;

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.9.0";
+export declare const PACKAGE_VERSION = "0.12.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.9.0";
+export const PACKAGE_VERSION = "0.12.0";

package/dist/projection/projectRun.d.ts

@@ -1,4 +1,4 @@
-import type { RunDetail, StageSnapshot } from "../runstore/port.js";
+import type { FeedbackLoopHistory, FeedbackLoopRecord, RunDetail, StageSnapshot } from "../runstore/port.js";
 import type { PipelineTrackProjection, RunSummary } from "../runstore/port.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
@@ -13,6 +13,7 @@ export type StageProjection = {
         payload?: Record<string, unknown>;
         fork_choice?: string[];
         clone_forks?: CloneForkItem[];
+        feedback_loop?: StageEnvelope["feedback_loop"];
     } | null;
     artifacts: string[];
     last_at?: string;
@@ -39,6 +40,8 @@ export type RunProjection = {
     waiting_questions?: RunSummary["waiting_questions"];
     failed_stage_id?: RunSummary["failed_stage_id"];
     failed_reason?: RunSummary["failed_reason"];
+    active_feedback_loop?: FeedbackLoopRecord;
+    feedback_loops: FeedbackLoopHistory[];
 };
 export declare function projectRun(detail: RunDetail): RunProjection;
 export { projectRun as projectRunForMcp };

package/dist/projection/projectRun.js

@@ -41,6 +41,10 @@ export function projectRun(detail) {
         ...(detail.failed_reason !== undefined
             ? { failed_reason: detail.failed_reason }
             : {}),
+        ...(detail.active_feedback_loop !== undefined
+            ? { active_feedback_loop: detail.active_feedback_loop }
+            : {}),
+        feedback_loops: detail.feedback_loops ?? [],
         stages: detail.stages.map((stage) => ({
             stage_id: stage.stage_id,
             status: stage.status,
@@ -58,6 +62,9 @@ export function projectRun(detail) {
                     ...(stage.envelope.clone_forks !== undefined
                         ? { clone_forks: stage.envelope.clone_forks }
                         : {}),
+                    ...(stage.envelope.feedback_loop !== undefined
+                        ? { feedback_loop: stage.envelope.feedback_loop }
+                        : {}),
                 }
                 : null,
             artifacts: stage.artifacts,

package/dist/prompt/feedbackLoopContext.d.ts

@@ -0,0 +1,2 @@
+import type { FeedbackLoopContext, StageSessionMode } from "../agent/port.js";
+export declare function formatFeedbackLoopContext(ctx: FeedbackLoopContext, sessionMode?: StageSessionMode): string;

package/dist/prompt/feedbackLoopContext.js

@@ -0,0 +1,17 @@
+function resolveFeedbackSessionMode(ctx, sessionMode) {
+    if (sessionMode === "new_session" || sessionMode === "feedback_resume") {
+        return sessionMode;
+    }
+    return ctx.replay_session === "new_session" ? "new_session" : "feedback_resume";
+}
+export function formatFeedbackLoopContext(ctx, sessionMode) {
+    const mode = resolveFeedbackSessionMode(ctx, sessionMode);
+    const continuity = mode === "new_session"
+        ? "starting a fresh agent session"
+        : "continuing the prior agent session";
+    return [
+        "Feedback Loop Context:",
+        `Session mode: ${mode} (${continuity})`,
+        JSON.stringify(ctx, null, 2),
+    ].join("\n");
+}

package/dist/prompt/priorEnvelope.d.ts

@@ -1,2 +1,2 @@
-import type { StageEnvelope } from "../types/envelope.js";
-export declare function formatPriorEnvelope(priorEnvelope: StageEnvelope | null, priorEnvelopes?: StageEnvelope[]): string;
+import type { StageEnvelope, TerminalEnvelope } from "../types/envelope.js";
+export declare function formatPriorEnvelope(priorEnvelope: StageEnvelope | null, priorEnvelopes?: StageEnvelope[], priorEnvelopesByStage?: Record<string, TerminalEnvelope | TerminalEnvelope[]>): string;

package/dist/prompt/priorEnvelope.js

@@ -1,4 +1,7 @@
-export function formatPriorEnvelope(priorEnvelope, priorEnvelopes) {
+export function formatPriorEnvelope(priorEnvelope, priorEnvelopes, priorEnvelopesByStage) {
+    if (priorEnvelopesByStage !== undefined) {
+        return `Prior envelopes by stage (declaration order):\n${JSON.stringify(priorEnvelopesByStage, null, 2)}`;
+    }
     if (priorEnvelopes !== undefined && priorEnvelopes.length > 0) {
         return `Prior envelopes (${priorEnvelopes.length} clones, clone-list order):\n${JSON.stringify(priorEnvelopes, null, 2)}`;
     }

package/dist/runstore/pipelineDagSnapshot.d.ts

@@ -8,6 +8,7 @@ export declare function appendCloneInstances(snapshot: RunPipelineDagSnapshot, i
     catalogId: string;
     predecessorId: string;
     count: number;
+    startAt?: number;
 }): {
     snapshot: RunPipelineDagSnapshot;
     instanceIds: string[];

package/dist/runstore/pipelineDagSnapshot.js

@@ -1,10 +1,15 @@
+import { hydrateResolvedNeeds } from "../config/pipelineNeeds.js";
 import { mintCloneInstanceIds } from "./stageInstanceId.js";
 export function buildPipelineDagSnapshotFromLoaded(loaded) {
     const gate_kinds = {};
+    const clone_input_schema = {};
     for (const stage of loaded.stages) {
-        if (stage.gate_kinds?.length) {
+        if (stage.gate_kinds !== undefined) {
             gate_kinds[stage.id] = stage.gate_kinds;
         }
+        if (stage.clone_input_schema !== undefined) {
+            clone_input_schema[stage.id] = stage.clone_input_schema;
+        }
     }
     return {
         stage_ids: [...loaded.pipeline.stages],
@@ -15,12 +20,16 @@ export function buildPipelineDagSnapshotFromLoaded(loaded) {
         roots: loaded.dag.roots,
         childrenOf: loaded.dag.childrenOf,
         ...(Object.keys(gate_kinds).length > 0 ? { gate_kinds } : {}),
+        ...(Object.keys(clone_input_schema).length > 0
+            ? { clone_input_schema }
+            : {}),
     };
 }
 export function linearCompatDagSnapshot(stageIds) {
     const nodes = stageIds.map((id, index) => ({
         id,
         needs: index === 0 ? null : stageIds[index - 1],
+        needsEdges: index === 0 ? [] : [{ id: stageIds[index - 1], on: ["succeeded"] }],
         ancestors: index === 0 ? [] : stageIds.slice(0, index),
         stageIndex: index,
         definition_id: id,
@@ -44,7 +53,14 @@ export function parsePipelineDagSnapshot(raw) {
     const value = raw;
     if (!Array.isArray(value.stage_ids) || !Array.isArray(value.nodes))
         return null;
-    return raw;
+    const nodes = value.nodes.map((node) => {
+        if (!node || typeof node !== "object")
+            return node;
+        const record = node;
+        const hydrated = hydrateResolvedNeeds(record);
+        return { ...record, ...hydrated };
+    });
+    return { ...raw, nodes };
 }
 export function instancesOfDefinition(snapshot, catalogId) {
     const nodeById = new Map(snapshot.nodes.map((n) => [n.id, n]));
@@ -54,15 +70,24 @@ export function instancesOfDefinition(snapshot, catalogId) {
     });
 }
 export function appendCloneInstances(snapshot, input) {
-    const { catalogId, predecessorId, count } = input;
-    if (!snapshot.stage_ids.includes(catalogId)) {
+    const { catalogId, predecessorId, count, startAt } = input;
+    // A catalog id that's already been fanned out once is no longer present as
+    // its own stage_ids entry — it was replaced by its instances. Minting
+    // *more* instances for it (a retried fanout requesting a larger clone
+    // count) is still valid as long as those instances exist.
+    const existingInstanceIdxs = snapshot.stage_ids
+        .map((id, i) => [id, i])
+        .filter(([id]) => id !== catalogId && id.startsWith(`${catalogId}~`))
+        .map(([, i]) => i);
+    const catalogIdx = snapshot.stage_ids.indexOf(catalogId);
+    if (catalogIdx === -1 && existingInstanceIdxs.length === 0) {
         throw new Error(`catalog stage "${catalogId}" is not in the run DAG snapshot`);
     }
     const predNode = snapshot.nodes.find((n) => n.id === predecessorId);
     if (!predNode) {
         throw new Error(`predecessor "${predecessorId}" is not in the run DAG snapshot`);
     }
-    const instanceIds = mintCloneInstanceIds(catalogId, count);
+    const instanceIds = mintCloneInstanceIds(catalogId, count, startAt);
     for (const id of instanceIds) {
         if (snapshot.stage_ids.includes(id) ||
             snapshot.nodes.some((n) => n.id === id)) {
@@ -70,22 +95,37 @@ export function appendCloneInstances(snapshot, input) {
         }
     }
     const catalogNode = snapshot.nodes.find((n) => n.id === catalogId);
-    if (!catalogNode) {
+    const templateNode = catalogNode ?? snapshot.nodes.find((n) => n.definition_id === catalogId);
+    if (!templateNode) {
         throw new Error(`catalog stage "${catalogId}" is not in the run DAG snapshot`);
     }
-    const catalogIdx = snapshot.stage_ids.indexOf(catalogId);
+    const insertAt = catalogIdx !== -1 ? catalogIdx : Math.max(...existingInstanceIdxs) + 1;
+    const removeAt = catalogIdx !== -1 ? catalogIdx + 1 : insertAt;
     const stage_ids = [
-        ...snapshot.stage_ids.slice(0, catalogIdx),
+        ...snapshot.stage_ids.slice(0, insertAt),
         ...instanceIds,
-        ...snapshot.stage_ids.slice(catalogIdx + 1),
+        ...snapshot.stage_ids.slice(removeAt),
     ];
     const instanceNodes = instanceIds.map((id) => ({
         id,
         definition_id: catalogId,
         needs: predecessorId,
+        needsEdges: [{ id: predecessorId, on: ["succeeded"] }],
         ancestors: [...predNode.ancestors, predecessorId],
         stageIndex: 0,
-        ...(catalogNode.fork !== undefined ? { fork: catalogNode.fork } : {}),
+        ...(templateNode.fork !== undefined ? { fork: templateNode.fork } : {}),
+        ...(templateNode.completion !== undefined
+            ? { completion: templateNode.completion }
+            : {}),
+        ...(templateNode.recovery !== undefined
+            ? { recovery: templateNode.recovery }
+            : {}),
+        ...(templateNode.feedback_loop !== undefined
+            ? { feedback_loop: templateNode.feedback_loop }
+            : {}),
+        ...(templateNode.replay_safe !== undefined
+            ? { replay_safe: templateNode.replay_safe }
+            : {}),
     }));
     const remaining = new Map(snapshot.nodes
         .filter((n) => n.id !== catalogId)
@@ -112,7 +152,7 @@ export function appendCloneInstances(snapshot, input) {
                 ...instanceIds,
                 ...predChildren.slice(predIdx + 1),
             ];
-    const definitionParent = catalogNode.needs;
+    const definitionParent = catalogNode?.needs;
     if (definitionParent && definitionParent !== predecessorId) {
         const parentChildren = childrenOf[definitionParent] ?? [];
         childrenOf[definitionParent] = parentChildren.filter((id) => id !== catalogId);