stageflow 0.15.0 → 0.18.0

package/dist/envelope/payloadSchema.js

@@ -179,10 +179,21 @@ function compileNode(node, path, ctx) {
                     schema.minItems < 0)) {
                 throw new Error(`${path}: minItems must be a non-negative integer when present`);
             }
+            if (schema.maxItems !== undefined &&
+                (typeof schema.maxItems !== "number" ||
+                    !Number.isInteger(schema.maxItems) ||
+                    schema.maxItems < 0)) {
+                throw new Error(`${path}: maxItems must be a non-negative integer when present`);
+            }
             const items = compileNode(schema.items, `${path}.items`, childCtx);
+            const arrayOpts = {};
+            if (schema.minItems !== undefined)
+                arrayOpts.minItems = schema.minItems;
+            if (schema.maxItems !== undefined)
+                arrayOpts.maxItems = schema.maxItems;
             base =
-                schema.minItems !== undefined
-                    ? Type.Array(items, { minItems: schema.minItems })
+                Object.keys(arrayOpts).length > 0
+                    ? Type.Array(items, arrayOpts)
                     : Type.Array(items);
             break;
         }
@@ -420,6 +431,61 @@ export function expandPayloadSchemaRefs(raw, options) {
         stack: [],
     });
 }
+const INDEX_SEGMENT = /^\d+$/;
+function schemaNodeType(schema) {
+    return typeof schema?.type === "string" ? schema.type : undefined;
+}
+function tryExpandSchema(node, options) {
+    try {
+        return expandPayloadSchemaRefs(node, options);
+    }
+    catch {
+        return node;
+    }
+}
+export function resolvePayloadSchemaFieldPath(schema, field, options) {
+    const segments = field.split(".");
+    if (segments.length === 0 || segments.some((segment) => segment === "")) {
+        return { ok: false, issue: "empty_segment" };
+    }
+    if (segments.some((segment) => INDEX_SEGMENT.test(segment))) {
+        return { ok: false, issue: "array_index" };
+    }
+    let current = tryExpandSchema(schema, options);
+    for (const segment of segments) {
+        if (!isPlainSchemaObject(current)) {
+            return { ok: false, issue: "missing" };
+        }
+        const node = current;
+        if (node.$ref !== undefined && node.properties === undefined) {
+            return { ok: false, issue: "missing" };
+        }
+        const typeName = schemaNodeType(node);
+        if (typeName === "array" ||
+            (node.items !== undefined && typeName !== "object")) {
+            return { ok: false, issue: "array_index" };
+        }
+        const properties = readProperties(node);
+        if (!Object.prototype.hasOwnProperty.call(properties, segment)) {
+            return { ok: false, issue: "missing" };
+        }
+        if (!readRequiredKeys(node).includes(segment)) {
+            return { ok: false, issue: "optional" };
+        }
+        current = properties[segment];
+    }
+    const leaf = isPlainSchemaObject(current)
+        ? tryExpandSchema(current, options)
+        : undefined;
+    if (leaf?.$ref !== undefined && leaf.properties === undefined) {
+        return { ok: false, issue: "untyped" };
+    }
+    const fieldType = schemaNodeType(leaf);
+    if (fieldType === undefined) {
+        return { ok: false, issue: "untyped" };
+    }
+    return { ok: true, type: fieldType };
+}
 function expandSchemaNode(node, path, ctx) {
     const { schema, stack } = derefSchemaNode(node, path, ctx);
     const childCtx = { schemas: ctx.schemas, stack };
@@ -496,3 +562,22 @@ export function assertCloneAssignmentPayload(envelope, cloneInputSchema, success
             : `${pathLead}clone assignment payload does not match io.input.schema for ${successorId}`);
     }
 }
+/**
+ * Validate a predecessor success payload against the child's IR
+ * `clone_input_schema` (YAML: `io.input.schema`) on a normal pipeline edge.
+ */
+export function assertPriorInputPayload(envelope, cloneInputSchema, childId, options) {
+    if (envelope.status !== "success") {
+        return;
+    }
+    const schema = compilePayloadSchema(cloneInputSchema, options);
+    if (envelope.payload === undefined) {
+        throw new EnvelopeError(`prior payload is required by io.input.schema for ${childId}`);
+    }
+    if (!Value.Check(schema, envelope.payload)) {
+        const details = payloadSchemaMismatchDetails(schema, envelope.payload);
+        throw new EnvelopeError(details
+            ? `prior payload does not match io.input.schema for ${childId}: ${details}`
+            : `prior payload does not match io.input.schema for ${childId}`);
+    }
+}

package/dist/mcp/catalogTools.js

@@ -153,7 +153,7 @@ export function registerCatalogTools(server, deps) {
         }
     });
     server.registerTool("describe_pipeline", {
-        description: "Describe a pipeline DAG: stages with needs, fork, clonable, clone_cap, and gate_kinds. Input is a filesystem pipeline path (same as start_run).",
+        description: "Describe a pipeline DAG: stages with needs, fork, and gate_kinds. Input is a filesystem pipeline path (same as start_run).",
         inputSchema: z.object({
             pipeline: z.string(),
         }),
@@ -170,7 +170,6 @@ export function registerCatalogTools(server, deps) {
                     ? 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 } : {}),
                 ...(gateById.get(node.id) !== undefined
                     ? { gate_kinds: gateById.get(node.id) }

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.15.0";
+export declare const PACKAGE_VERSION = "0.18.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.15.0";
+export const PACKAGE_VERSION = "0.18.0";

package/dist/projection/projectRun.d.ts

@@ -2,7 +2,6 @@ import type { FeedbackLoopHistory, FeedbackLoopRecord, RunDetail, StageSnapshot
 import type { PipelineTrackProjection, RunSummary } from "../runstore/port.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { CloneForkItem } from "../types/forkChoice.js";
 export type StageProjection = {
     stage_id: string;
     status: StageSnapshot["status"];
@@ -12,7 +11,6 @@ export type StageProjection = {
         artifacts: string[];
         payload?: Record<string, unknown>;
         fork_choice?: string[];
-        clone_forks?: CloneForkItem[];
         feedback_loop?: StageEnvelope["feedback_loop"];
     } | null;
     artifacts: string[];

package/dist/projection/projectRun.js

@@ -59,9 +59,6 @@ export function projectRun(detail) {
                     ...(stage.envelope.fork_choice !== undefined
                         ? { fork_choice: stage.envelope.fork_choice }
                         : {}),
-                    ...(stage.envelope.clone_forks !== undefined
-                        ? { clone_forks: stage.envelope.clone_forks }
-                        : {}),
                     ...(stage.envelope.feedback_loop !== undefined
                         ? { feedback_loop: stage.envelope.feedback_loop }
                         : {}),

package/dist/prompt/priorEnvelope.js

@@ -3,7 +3,7 @@ export function formatPriorEnvelope(priorEnvelope, priorEnvelopes, priorEnvelope
         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)}`;
+        return `Prior envelopes (${priorEnvelopes.length}):\n${JSON.stringify(priorEnvelopes, null, 2)}`;
     }
     return priorEnvelope === null
         ? "No prior envelope (first stage)."

package/dist/runstore/port.d.ts

@@ -4,6 +4,7 @@ import type { StageEnvelope } from "../types/envelope.js";
 import type { FeedbackLoopConfig, ResolvedPipelineDag } from "../types/pipeline.js";
 import type { CompletionCheck } from "../types/completion.js";
 import type { StageGateKind } from "../types/stage.js";
+import type { StageUsage } from "../types/usage.js";
 export type RunStatus = "created" | "running" | "succeeded" | "failed";
 export type RunPipelineDagSnapshot = ResolvedPipelineDag & {
     stage_ids: string[];
@@ -70,6 +71,8 @@ export type StageSnapshot = {
     last_at?: string;
     pending_prompt?: AskOperatorPrompt;
     attempt_count: number;
+    /** Total $ spent on this stage across every attempt; omitted when no attempt reported usage. */
+    cost_usd?: number;
 };
 export type StageExecution = {
     run_id: string;
@@ -80,6 +83,8 @@ export type StageExecution = {
     started_at?: string;
     finished_at?: string;
     envelope: StageEnvelope | null;
+    cost_usd?: number;
+    usage?: StageUsage;
 };
 export type StageExecutionPatch = {
     status?: StageSnapshot["status"];
@@ -87,6 +92,8 @@ export type StageExecutionPatch = {
     started_at?: string;
     finished_at?: string;
     envelope?: StageEnvelope | null;
+    cost_usd?: number;
+    usage?: StageUsage;
 };
 /** The durable disposition of completion verification for one stage attempt. */
 export type VerificationOutcome = "not_run" | "passed" | "failed" | "error";
@@ -220,6 +227,7 @@ export type CompactStage = {
     status: StageSnapshot["status"];
     attempt_count: number;
     definition_id?: string;
+    cost_usd?: number;
 };
 export type RunSummary = {
     run_id: string;
@@ -246,6 +254,8 @@ export type RunSummary = {
     failed_reason?: string;
     /** The active loop, when a run is currently replaying or awaiting a decision. */
     active_feedback_loop?: FeedbackLoopRecord;
+    /** Sum of every stage's cost_usd; omitted when no stage reported usage. */
+    total_cost_usd?: number;
 };
 export type RunDetail = Omit<RunSummary, "stages"> & {
     task_yaml: string;

package/dist/runstore/runProjection.js

@@ -26,8 +26,15 @@ function compactStages(stages) {
         status: s.status,
         attempt_count: s.attempt_count,
         ...(s.definition_id !== undefined ? { definition_id: s.definition_id } : {}),
+        ...(s.cost_usd !== undefined ? { cost_usd: s.cost_usd } : {}),
     }));
 }
+function totalCostUsd(stages) {
+    const costs = stages.map((s) => s.cost_usd).filter((c) => c !== undefined);
+    if (costs.length === 0)
+        return undefined;
+    return costs.reduce((sum, c) => sum + c, 0);
+}
 function waitingSummaryFromPrompt(prompt) {
     if (!prompt)
         return "Waiting for input";
@@ -89,6 +96,7 @@ function resolveListedStatus(stages, meta, dag) {
 export function projectRunSummary(meta, stages, feedback) {
     const dag = meta.pipeline_dag;
     const waiting = waitingFieldsFromStages(stages);
+    const cost = totalCostUsd(stages);
     if (feedback?.active_feedback_loop?.state === "waiting_for_human" &&
         waiting.waiting_stage_id !== undefined &&
         waiting.waiting_kind === undefined) {
@@ -114,6 +122,7 @@ export function projectRunSummary(meta, stages, feedback) {
         ...(feedback?.active_feedback_loop !== undefined
             ? { active_feedback_loop: feedback.active_feedback_loop }
             : {}),
+        ...(cost !== undefined ? { total_cost_usd: cost } : {}),
     };
 }
 export function projectRunDetail(meta, stages, task_yaml, dagSnapshot, feedback) {

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -78,6 +78,18 @@ function ensureStageExecutionVerificationOutcomeColumn(db) {
         db.exec(`ALTER TABLE stage_executions ADD COLUMN verification_outcome TEXT NOT NULL DEFAULT 'not_run'`);
     }
 }
+function ensureStageExecutionCostColumns(db) {
+    const cols = db
+        .prepare(`PRAGMA table_info(stage_executions)`)
+        .all();
+    const names = new Set(cols.map((c) => c.name));
+    if (!names.has("cost_usd")) {
+        db.exec(`ALTER TABLE stage_executions ADD COLUMN cost_usd REAL`);
+    }
+    if (!names.has("usage_json")) {
+        db.exec(`ALTER TABLE stage_executions ADD COLUMN usage_json TEXT`);
+    }
+}
 function backfillVerificationOutcomes(db) {
     db.exec(`
 UPDATE stage_executions
@@ -184,6 +196,8 @@ function executionFromRow(row) {
         envelope: row.envelope_json
             ? JSON.parse(row.envelope_json)
             : null,
+        ...(row.cost_usd != null ? { cost_usd: row.cost_usd } : {}),
+        ...(row.usage_json != null ? { usage: JSON.parse(row.usage_json) } : {}),
     };
 }
 function verificationCheckResultFromRow(row) {
@@ -292,6 +306,7 @@ export class SqliteRunStore {
         ensureRunLocatorColumns(this.db);
         ensureStageExecutionsTable(this.db);
         ensureStageExecutionVerificationOutcomeColumn(this.db);
+        ensureStageExecutionCostColumns(this.db);
         ensureStageEventsAttemptColumn(this.db);
         ensureVerificationCheckResultsTable(this.db);
         ensureFeedbackReplayStagePassEnvelopeColumn(this.db);
@@ -432,7 +447,7 @@ export class SqliteRunStore {
                 verification_outcome: "not_run",
             });
             const row = this.db
-                .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+                .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
            FROM stage_executions
            WHERE run_id = ? AND stage_id = ? AND attempt = ?`)
                 .get(runId, stageId, attempt);
@@ -442,7 +457,7 @@ export class SqliteRunStore {
     async listStageExecutions(runId, stageId) {
         await this.ready();
         const rows = this.db
-            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
          FROM stage_executions
          WHERE run_id = ? AND stage_id = ?
          ORDER BY attempt ASC`)
@@ -452,7 +467,7 @@ export class SqliteRunStore {
     async getLatestStageExecution(runId, stageId) {
         await this.ready();
         const row = this.db
-            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
          FROM stage_executions
          WHERE run_id = ? AND stage_id = ?
          ORDER BY attempt DESC
@@ -471,7 +486,7 @@ export class SqliteRunStore {
     async getStageExecution(runId, stageId, attempt) {
         await this.ready();
         const row = this.db
-            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
          FROM stage_executions
          WHERE run_id = ? AND stage_id = ? AND attempt = ?`)
             .get(runId, stageId, attempt);
@@ -509,6 +524,14 @@ export class SqliteRunStore {
             params.envelope_json =
                 patch.envelope != null ? JSON.stringify(patch.envelope) : null;
         }
+        if (patch.cost_usd !== undefined) {
+            sets.push("cost_usd = @cost_usd");
+            params.cost_usd = patch.cost_usd;
+        }
+        if (patch.usage !== undefined) {
+            sets.push("usage_json = @usage_json");
+            params.usage_json = JSON.stringify(patch.usage);
+        }
         if (sets.length === 0)
             return;
         const result = this.db

package/dist/runstore/sqlite/schema.d.ts

@@ -1 +1 @@
-export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  verification_outcome TEXT NOT NULL DEFAULT 'not_run',\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n\nCREATE TABLE IF NOT EXISTS verification_check_results (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  check_id TEXT NOT NULL,\n  check_type TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  evidence_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt, check_id),\n  FOREIGN KEY (run_id, stage_id, attempt)\n    REFERENCES stage_executions(run_id, stage_id, attempt)\n);\n\nCREATE INDEX IF NOT EXISTS idx_verification_check_results_execution\n  ON verification_check_results (run_id, stage_id, attempt, check_id);\n\nCREATE TABLE IF NOT EXISTS feedback_loops (\n  run_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  policy_json TEXT NOT NULL,\n  state TEXT NOT NULL,\n  current_replay_id TEXT,\n  current_replay_number INTEGER,\n  deferred_send_back_json TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, loop_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state\n  ON feedback_loops (run_id, state, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replays (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  target_stage_id TEXT NOT NULL,\n  replay_number INTEGER NOT NULL,\n  max_replays INTEGER NOT NULL,\n  replay_session TEXT NOT NULL,\n  route_stage_ids_json TEXT NOT NULL,\n  feedback_envelope_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, replay_id),\n  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number\n  ON feedback_replays (run_id, loop_id, replay_number);\nCREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop\n  ON feedback_replays (run_id, loop_id, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  stage_attempt INTEGER NOT NULL,\n  session_origin_attempt INTEGER,\n  session_mode TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  emitted_envelope_json TEXT,\n  PRIMARY KEY (run_id, replay_id, stage_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay\n  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);\n\nCREATE TABLE IF NOT EXISTS fork_generations (\n  run_id TEXT NOT NULL,\n  generation_id TEXT NOT NULL,\n  replay_id TEXT,\n  fork_parent_stage_id TEXT NOT NULL,\n  generation_number INTEGER NOT NULL,\n  clone_stage_ids_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, generation_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number\n  ON fork_generations (run_id, fork_parent_stage_id, generation_number);\nCREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay\n  ON fork_generations (run_id, replay_id, created_at);\n";
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  verification_outcome TEXT NOT NULL DEFAULT 'not_run',\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  cost_usd REAL,\n  usage_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n\nCREATE TABLE IF NOT EXISTS verification_check_results (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  check_id TEXT NOT NULL,\n  check_type TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  evidence_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt, check_id),\n  FOREIGN KEY (run_id, stage_id, attempt)\n    REFERENCES stage_executions(run_id, stage_id, attempt)\n);\n\nCREATE INDEX IF NOT EXISTS idx_verification_check_results_execution\n  ON verification_check_results (run_id, stage_id, attempt, check_id);\n\nCREATE TABLE IF NOT EXISTS feedback_loops (\n  run_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  policy_json TEXT NOT NULL,\n  state TEXT NOT NULL,\n  current_replay_id TEXT,\n  current_replay_number INTEGER,\n  deferred_send_back_json TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, loop_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state\n  ON feedback_loops (run_id, state, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replays (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  target_stage_id TEXT NOT NULL,\n  replay_number INTEGER NOT NULL,\n  max_replays INTEGER NOT NULL,\n  replay_session TEXT NOT NULL,\n  route_stage_ids_json TEXT NOT NULL,\n  feedback_envelope_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, replay_id),\n  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number\n  ON feedback_replays (run_id, loop_id, replay_number);\nCREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop\n  ON feedback_replays (run_id, loop_id, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  stage_attempt INTEGER NOT NULL,\n  session_origin_attempt INTEGER,\n  session_mode TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  emitted_envelope_json TEXT,\n  PRIMARY KEY (run_id, replay_id, stage_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay\n  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);\n\nCREATE TABLE IF NOT EXISTS fork_generations (\n  run_id TEXT NOT NULL,\n  generation_id TEXT NOT NULL,\n  replay_id TEXT,\n  fork_parent_stage_id TEXT NOT NULL,\n  generation_number INTEGER NOT NULL,\n  clone_stage_ids_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, generation_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number\n  ON fork_generations (run_id, fork_parent_stage_id, generation_number);\nCREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay\n  ON fork_generations (run_id, replay_id, created_at);\n";

package/dist/runstore/sqlite/schema.js

@@ -57,6 +57,8 @@ CREATE TABLE IF NOT EXISTS stage_executions (
   started_at TEXT,
   finished_at TEXT,
   envelope_json TEXT,
+  cost_usd REAL,
+  usage_json TEXT,
   PRIMARY KEY (run_id, stage_id, attempt),
   FOREIGN KEY (run_id) REFERENCES runs(run_id)
 );

package/dist/runstore/stageExecution.d.ts

@@ -1,10 +1,13 @@
 import type { StageEnvelope } from "../types/envelope.js";
+import type { StageUsage } from "../types/usage.js";
 import type { StageLogEvent, StageSnapshot } from "./port.js";
 export type StageExecutionPatch = {
     status?: StageSnapshot["status"];
     started_at?: string;
     finished_at?: string;
     envelope?: StageEnvelope | null;
+    cost_usd?: number;
+    usage?: StageUsage;
 };
 export declare function executionStatusFromEvents(events: StageLogEvent[]): StageSnapshot["status"];
 export declare function deriveExecutionPatchFromEvent(event: StageLogEvent, current: Pick<StageSnapshot, "status"> & {

package/dist/runstore/stageExecution.js

@@ -14,9 +14,13 @@ export function deriveExecutionPatchFromEvent(event, current) {
     else if (eventName === "waiting_for_input") {
         patch.status = "waiting_for_input";
     }
-    else if (eventName === "succeeded" || eventName === "failed") {
-        patch.status = eventName;
+    else if (event.event === "succeeded" || event.event === "failed") {
+        patch.status = event.event;
         patch.finished_at = at;
+        if (event.usage) {
+            patch.cost_usd = event.usage.costUsd;
+            patch.usage = event.usage;
+        }
     }
     return patch;
 }

package/dist/runstore/stageInstanceId.d.ts

@@ -1,4 +1,5 @@
 import type { RunPipelineDagSnapshot } from "./port.js";
 export declare function mintCloneInstanceId(catalogId: string, n: number): string;
 export declare function mintCloneInstanceIds(catalogId: string, count: number, startAt?: number): string[];
+export declare function cloneInstanceOrdinal(instanceId: string, catalogId: string): number | undefined;
 export declare function definitionIdForInstance(snapshot: RunPipelineDagSnapshot | null | undefined, instanceId: string): string;

package/dist/runstore/stageInstanceId.js

@@ -16,6 +16,15 @@ export function mintCloneInstanceIds(catalogId, count, startAt = 1) {
     guardPositiveInteger(startAt, "startAt");
     return Array.from({ length: count }, (_, i) => mintCloneInstanceId(catalogId, startAt + i));
 }
+export function cloneInstanceOrdinal(instanceId, catalogId) {
+    const prefix = `${catalogId}~`;
+    if (!instanceId.startsWith(prefix))
+        return undefined;
+    const n = Number(instanceId.slice(prefix.length));
+    if (!Number.isInteger(n) || n < 1)
+        return undefined;
+    return n;
+}
 export function definitionIdForInstance(snapshot, instanceId) {
     const node = snapshot?.nodes.find((n) => n.id === instanceId);
     if (!node)

package/dist/runstore/stageSnapshot.js

@@ -18,11 +18,14 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
     let status;
     let envelope;
     let attempt_count;
+    let cost_usd;
     if (latest !== null) {
         events = await store.listStageEvents(runId, stageId, latest.attempt);
         status = stageStatusFromEvents(events);
         envelope = await tryReadEnvelope(store, runId, stageId, latest);
         attempt_count = await store.countStageAttempts(runId, stageId);
+        const executions = await store.listStageExecutions(runId, stageId);
+        cost_usd = sumStageExecutionCost(executions);
     }
     else {
         events = await store.listStageEvents(runId, stageId);
@@ -42,5 +45,13 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
         last_at,
         attempt_count,
         ...(pending ? { pending_prompt: pending } : {}),
+        ...(cost_usd !== undefined ? { cost_usd } : {}),
     };
 }
+/** Sum cost across every attempt — retries are real spend too, so a stage's total isn't just its latest attempt. */
+function sumStageExecutionCost(executions) {
+    const costs = executions.map((e) => e.cost_usd).filter((c) => c !== undefined);
+    if (costs.length === 0)
+        return undefined;
+    return costs.reduce((sum, c) => sum + c, 0);
+}

package/dist/runtime/cloneSchedule.d.ts

@@ -1,30 +1,26 @@
 import type { RunPipelineDagSnapshot } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { NeedTerminalState, ResolvedPipelineDag } from "../types/pipeline.js";
-import { type ActiveCohort } from "./forkGeneration.js";
+import type { ResolvePriorEnvelopeResult } from "./envelopeRouting.js";
 import type { StageScheduleState } from "./pipelineScheduler.js";
 export declare function isCloneInstance(dag: ResolvedPipelineDag, stageId: string): boolean;
 export declare function sequentialLaterCloneIds(dag: ResolvedPipelineDag, stageId: string, completedEnvelopes: Map<string, StageEnvelope>): string[];
 export declare function skipRejectedNeedDependents(dag: ResolvedPipelineDag, parentId: string, states: Map<string, StageScheduleState>, observed: NeedTerminalState, onSkip: (stageId: string) => void): void;
 export declare function failureIsAccepted(dag: ResolvedPipelineDag, failedId: string, states: Map<string, StageScheduleState>): boolean;
-/**
- * A fresh clone_forks fanout targeting a catalog id that already has
- * instances is only safe when every existing instance was put back to
- * `pending` by the current retry cascade (`retryDownstreamIds`) — that means
- * an ancestor was legitimately retried and this parent re-emitted the same
- * fanout for reactivation. Instances that are still active/terminal, or
- * merely `pending` without having gone through a retry reset (e.g. an
- * envelope processed twice in one live run), are rejected as before.
- *
- * Feedback-loop replay is different: the prior cohort was superseded
- * (`skipped`) and a new generation must mint fresh `~N` ids, so
- * `forceFreshCloneIds` bypasses the conflict.
- */
-export declare function cloneFanoutConflict(dag: ResolvedPipelineDag, envelope: StageEnvelope, states: Map<string, StageScheduleState>, retryDownstreamIds: ReadonlySet<string>, options?: {
-    forceFreshCloneIds?: boolean;
-}): string | undefined;
-export declare function nextFreeCloneSuffix(snapshot: RunPipelineDagSnapshot, catalogId: string): number;
-export declare function protectedClonableChildIds(dag: ResolvedPipelineDag, predecessorId: string, envelope: StageEnvelope): Set<string>;
+export type MintResult = {
+    kind: "none";
+} | {
+    kind: "error";
+    reason: string;
+} | {
+    kind: "minted";
+    dag: RunPipelineDagSnapshot;
+    catalogChildId: string;
+    instanceIds: string[];
+};
+export declare function mint(dag: ResolvedPipelineDag, emitterId: string, envelope: StageEnvelope): MintResult;
+export declare function assignment(dag: ResolvedPipelineDag, stageId: string, definitionId: string, completedEnvelopes: Map<string, StageEnvelope>): ResolvePriorEnvelopeResult | undefined;
+export declare function protectedClonableChildIds(dag: ResolvedPipelineDag, predecessorId: string, _envelope: StageEnvelope): Set<string>;
 /**
  * Downstream closure for a retry, resolved through clone-instance ids and
  * static multi-parent edges. Catalog-level children (e.g. a join stage) are
@@ -38,17 +34,4 @@ export declare function protectedClonableChildIds(dag: ResolvedPipelineDag, pred
 export declare function cloneRetryDownstream(dag: ResolvedPipelineDag, stageIds: string[]): Set<string>;
 export declare function cloneFailureContinuesSchedule(dag: ResolvedPipelineDag, stageId: string, completedEnvelopes: Map<string, StageEnvelope>): boolean;
 export declare function cloneFailFastSkipIds(dag: ResolvedPipelineDag, stageId: string, completedEnvelopes: Map<string, StageEnvelope>): string[];
-export declare function cloneScheduleAllowsRun(dag: ResolvedPipelineDag, stageId: string, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>, options?: {
-    activeCohortForNeeds?: (needsId: string) => ActiveCohort;
-    activeCloneIdsForNeeds?: (needsId: string) => Set<string> | null;
-}): boolean;
-export type ApplyCloneForksResult = {
-    dag: RunPipelineDagSnapshot;
-    skippedIds: string[];
-    /** Freshly minted instance ids keyed by clonable catalog successor id. */
-    mintedBySuccessor?: Map<string, string[]>;
-};
-export declare function applyCloneForksToSchedule(dag: ResolvedPipelineDag, predecessorId: string, envelope: StageEnvelope, states: Map<string, StageScheduleState>, options?: {
-    forceFreshCloneIds?: boolean;
-}): ApplyCloneForksResult;
-export declare function applyCloneForksFromEnvelopes(dag: ResolvedPipelineDag, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>): ApplyCloneForksResult;
+export declare function cloneScheduleAllowsRun(dag: ResolvedPipelineDag, stageId: string, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>): boolean;