stageflow 0.15.0 → 0.18.0

package/README.md

@@ -31,13 +31,12 @@ The same pipeline runs three ways without rewriting anything:
 - **Path-based CLI** — `--pipeline` and `--task` take filesystem paths (no bare-id lookup)
 - **Pi-native** — runs on `@earendil-works/pi-coding-agent`; reuse an existing Pi login (`pi_home`) or store credentials in `~/.stageflow/agent/auth.json` (`sf_owned`)
 - **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
-- **Verified stage execution** — pipeline-owned completion checks with durable evidence, automatic repair, and manual recovery ([guide](docs/verified-stage-execution.md))
+- **Verified stage execution** — after-phase `verify` checks with durable evidence, plus `on_verify_fail` repair or manual operator recovery ([guide](docs/verified-stage-execution.md))
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
 - **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
-- **Parallel stages** — pipeline DAG with fan-out and join (see [YAML catalog](docs/yaml-catalog.md))
-- **Clonable fan-out** — clone one successor N times at completion, then join (see [YAML catalog](docs/yaml-catalog.md#clonable-successors))
+- **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
 - **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
 
 ## Architecture at a glance
@@ -219,7 +218,6 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 | [hello-world](examples/hello-world/) | Single stage, domain-neutral |
 | [plan-review](examples/plan-review/) | Multi-stage with operator gate — SDLC-style **example** |
 | [conditional-fork](examples/conditional-fork/) | Exclusive fork routing with operator branch choice |
-| [clonable-fanout](examples/clonable-fanout/) | Clone one successor N times, then join |
 | [stage-mcp](examples/stage-mcp/) | Stage MCP via project `.mcp.json` and a local echo fixture |
 | [playwright-mcp](examples/playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) |
 | [context7-mcp](examples/context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) |

package/dist/agent/activity.d.ts

@@ -11,6 +11,7 @@
  * those Q&A bodies.
  */
 import type { AskOperatorAnswer, AskOperatorPrompt } from "../tools/askOperator.js";
+import type { StageUsage } from "../types/usage.js";
 export declare const ACTIVITY_TEXT_LIMIT = 2000;
 export declare const ACTIVITY_TEXT_LIMIT_ENV = "STAGEFLOW_ACTIVITY_TEXT_LIMIT";
 export declare const ACTIVITY_VERBOSE_ENV = "STAGEFLOW_ACTIVITY_VERBOSE";
@@ -65,9 +66,11 @@ export type StageLifecycleEvent = {
     event: "resumed";
 } | {
     event: "succeeded";
+    usage?: StageUsage;
 } | {
     event: "failed";
     reason: string;
+    usage?: StageUsage;
 } | {
     event: "skipped";
 }

package/dist/agent/claudeAdapter.js

@@ -43,10 +43,12 @@ import { isAdvancingEnvelope } from "../envelope/check.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, summarizeAnswer, } from "../tools/askOperator.js";
 import { buildStageflowMcpServer, EMIT_STAGE_ENVELOPE_TOOL_NAME, STAGEFLOW_MCP_SERVER_NAME, WRITE_STAGE_ARTIFACT_TOOL_NAME, ASK_OPERATOR_TOOL_NAME, } from "./claudeTools.js";
 import { createClaudeActivityMapper } from "./claudeActivity.js";
+import { readActivityVerbose } from "./activity.js";
 import { composeStageUserPrompt } from "./piAdapter.js";
 import { claudeSessionMarkerPath, clearClaudeSessionMarker, readClaudeSessionMarker, writeClaudeSessionMarker, } from "./claudeSession.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen, runtimeStageId, } from "./port.js";
 import { StageMcpError } from "../config/resolveStageMcpServers.js";
+import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 /** Built-in tool allowlist, mirroring Pi's sealed-session base set (read/bash/write/edit). */
 const CLAUDE_BUILTIN_TOOLS = ["Read", "Write", "Edit", "Bash"];
 function resolveClaudeModel(stageModel) {
@@ -102,6 +104,65 @@ function failedPassedMcpConnect(resolved, listed) {
     }
     return undefined;
 }
+/** Merge one query() call's per-model totals (this call's own turns only) into the stage-level accumulator. */
+function mergeClaudeModelUsage(usage, modelUsage) {
+    if (!modelUsage)
+        return;
+    for (const [key, entry] of Object.entries(modelUsage)) {
+        addModelUsage(usage, entry.canonicalModel ?? key, {
+            inputTokens: entry.inputTokens,
+            outputTokens: entry.outputTokens,
+            cacheReadInputTokens: entry.cacheReadInputTokens,
+            cacheCreationInputTokens: entry.cacheCreationInputTokens,
+            costUsd: entry.costUSD,
+        });
+    }
+}
+const TRAILING_RESULT_WAIT_MS = 2000;
+/**
+ * emit_stage_envelope's tool_result lands on a "user" message, which the
+ * caller interrupts and breaks on immediately (never-let-it-go-dangling) —
+ * well before the SDK's own "result" message (the one carrying cost/token
+ * totals) would naturally arrive. There can be more than one trailing frame
+ * after the interrupted tool-result (observed: another "user" frame before
+ * "result"), so this drains messages in a loop, bounded by one overall time
+ * budget rather than a single peek. By the docstring above, `interrupt()`
+ * resolving means the CLI subprocess has already exited, so its trailing
+ * frames are normally already queued or arrive within milliseconds — this
+ * claims them without risking a real hang.
+ */
+async function drainTrailingResultUsage(stream, usage) {
+    const debug = readActivityVerbose();
+    const deadline = Date.now() + TRAILING_RESULT_WAIT_MS;
+    try {
+        while (Date.now() < deadline) {
+            const next = await Promise.race([
+                stream.next(),
+                new Promise((resolve) => setTimeout(() => resolve({ done: true, value: undefined }), deadline - Date.now())),
+            ]);
+            if (debug) {
+                console.error(`[claudeAdapter] drainTrailingResultUsage: done=${next.done} type=${!next.done ? next.value?.type : "n/a"}`);
+            }
+            if (next.done)
+                return;
+            const message = next.value;
+            if (message.type === "result") {
+                if (debug) {
+                    console.error(`[claudeAdapter] drainTrailingResultUsage: modelUsage=${JSON.stringify(message.modelUsage)}`);
+                }
+                mergeClaudeModelUsage(usage, message.modelUsage);
+                return;
+            }
+            // not "result" yet (e.g. another "user"/"system" frame) — keep draining within the budget
+        }
+    }
+    catch (err) {
+        if (debug) {
+            console.error(`[claudeAdapter] drainTrailingResultUsage: threw ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // best-effort; a natural stop may already have ended the turn
+    }
+}
 async function* singleUserMessage(text) {
     yield {
         type: "user",
@@ -110,7 +171,7 @@ async function* singleUserMessage(text) {
     };
 }
 /** One `query()` call — either the stage's initial turn or a resume turn. */
-async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
+async function runTurn(input, model, markerPath, promptText, resumeSessionId, usage) {
     const timeoutMs = input.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -187,15 +248,23 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
             }
             if (message.type === "user" &&
                 (emitCapture.envelope !== undefined || askCapture.prompt !== undefined)) {
+                if (readActivityVerbose()) {
+                    console.error(`[claudeAdapter] interrupting on user tool-result frame`);
+                }
                 try {
                     await stream.interrupt();
                 }
                 catch {
                     // best-effort backstop; a natural stop may have already ended the turn
                 }
+                await drainTrailingResultUsage(stream, usage);
                 break;
             }
             if (message.type === "result") {
+                if (readActivityVerbose()) {
+                    console.error(`[claudeAdapter] main loop saw result: modelUsage=${JSON.stringify(message.modelUsage)}`);
+                }
+                mergeClaudeModelUsage(usage, message.modelUsage);
                 break;
             }
         }
@@ -204,26 +273,27 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
             if (resolvedSessionId === undefined) {
                 return {
                     kind: "completed",
-                    result: { ok: false, reason: "ask_operator called but no session_id was observed" },
+                    result: { ok: false, reason: "ask_operator called but no session_id was observed", usage },
                 };
             }
             await writeClaudeSessionMarker(markerPath, {
                 sessionId: resolvedSessionId,
                 prompt: askCapture.prompt,
+                usage,
             });
             return { kind: "waiting", sessionId: resolvedSessionId, request: askCapture.prompt };
         }
         await clearClaudeSessionMarker(markerPath);
-        return { kind: "completed", result: resultFromCapture(emitCapture) };
+        return { kind: "completed", result: { ...resultFromCapture(emitCapture), usage } };
     }
     catch (err) {
         if (askCapture.prompt !== undefined && sessionId !== undefined) {
-            await writeClaudeSessionMarker(markerPath, { sessionId, prompt: askCapture.prompt });
+            await writeClaudeSessionMarker(markerPath, { sessionId, prompt: askCapture.prompt, usage });
             return { kind: "waiting", sessionId, request: askCapture.prompt };
         }
         if (emitCapture.envelope && isAdvancingEnvelope(emitCapture.envelope)) {
             await clearClaudeSessionMarker(markerPath);
-            return { kind: "completed", result: { ok: true, envelope: emitCapture.envelope } };
+            return { kind: "completed", result: { ok: true, envelope: emitCapture.envelope, usage } };
         }
         return {
             kind: "completed",
@@ -231,6 +301,7 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
                 ok: false,
                 reason: err instanceof Error ? err.message : String(err),
                 envelope: emitCapture.envelope,
+                usage,
             },
         };
     }
@@ -254,6 +325,7 @@ export class ClaudeAgentAdapter {
         let bootstrapped = false;
         let waiting;
         let pendingAnswer;
+        const usage = emptyStageUsage();
         const applyOutcome = (outcome) => {
             if (outcome.kind === "waiting") {
                 waiting = { sessionId: outcome.sessionId, prompt: outcome.request };
@@ -275,6 +347,11 @@ export class ClaudeAgentAdapter {
                     if (marker?.prompt !== undefined) {
                         waiting = { sessionId: marker.sessionId, prompt: marker.prompt };
                     }
+                    if (marker?.usage) {
+                        for (const [model, breakdown] of Object.entries(marker.usage.models)) {
+                            addModelUsage(usage, model, breakdown);
+                        }
+                    }
                 }
                 if (waiting) {
                     if (pendingAnswer === undefined) {
@@ -301,14 +378,14 @@ export class ClaudeAgentAdapter {
                         await clearClaudeSessionMarker(markerPath);
                         return { status: "completed", result: { ok: false, reason: pre.reason } };
                     }
-                    const outcome = await runTurn(input, pre.model, markerPath, resumePromptText(parsedAnswer), sessionId);
+                    const outcome = await runTurn(input, pre.model, markerPath, resumePromptText(parsedAnswer), sessionId, usage);
                     return applyOutcome(outcome);
                 }
                 const pre = preflight(input);
                 if (!pre.ok) {
                     return { status: "completed", result: { ok: false, reason: pre.reason } };
                 }
-                const outcome = await runTurn(input, pre.model, markerPath, composeStageUserPrompt(input, EMIT_STAGE_ENVELOPE_TOOL_NAME, undefined, WRITE_STAGE_ARTIFACT_TOOL_NAME), undefined);
+                const outcome = await runTurn(input, pre.model, markerPath, composeStageUserPrompt(input, EMIT_STAGE_ENVELOPE_TOOL_NAME, undefined, WRITE_STAGE_ARTIFACT_TOOL_NAME), undefined, usage);
                 return applyOutcome(outcome);
             },
             deliverAnswer(answer) {

package/dist/agent/claudeSession.d.ts

@@ -1,8 +1,11 @@
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageRunInput } from "./port.js";
+import type { StageUsage } from "../types/usage.js";
 export type ClaudeSessionMarker = {
     sessionId: string;
     prompt?: AskOperatorPrompt;
+    /** Cost/tokens accumulated by turns run so far, so a restart resuming this stage doesn't lose prior spend. */
+    usage?: StageUsage;
 };
 /**
  * Derives a stable, per-attempt path from `input.resumeToken` — the same

package/dist/agent/claudeTools.d.ts

@@ -45,10 +45,8 @@ export type AskOperatorCapture = {
  * nothing else catches one drifting from the other.
  *
  * Field presence mirrors the typebox schema's own conditionality:
- * `clone_forks` only exists when a stage can clone-fork at all, and
  * `fork_choice` is required (not just present) when the stage has a fork
- * to route. Building this statically would silently offer the model a
- * `clone_forks` field on stages that have nowhere to route one.
+ * to route.
  */
 export declare function buildEmitStageEnvelopeShape(options: {
     forkEmitContext?: ForkEmitContext;
@@ -62,7 +60,6 @@ export declare function buildEmitStageEnvelopeShape(options: {
     artifacts: z.ZodArray<z.ZodString>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     fork_choice: z.ZodArray<z.ZodString> | z.ZodOptional<z.ZodArray<z.ZodString>>;
-    clone_forks?: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>> | undefined;
     checklist_attestations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         check_id: z.ZodString;
         items: z.ZodArray<z.ZodString>;

package/dist/agent/claudeTools.js

@@ -40,10 +40,8 @@ export const ASK_OPERATOR_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__ask_op
  * nothing else catches one drifting from the other.
  *
  * Field presence mirrors the typebox schema's own conditionality:
- * `clone_forks` only exists when a stage can clone-fork at all, and
  * `fork_choice` is required (not just present) when the stage has a fork
- * to route. Building this statically would silently offer the model a
- * `clone_forks` field on stages that have nowhere to route one.
+ * to route.
  */
 export function buildEmitStageEnvelopeShape(options) {
     return {
@@ -54,9 +52,6 @@ export function buildEmitStageEnvelopeShape(options) {
         fork_choice: options.forkEmitContext !== undefined
             ? z.array(z.string())
             : z.array(z.string()).optional(),
-        ...(options.cloneEmitContext !== undefined
-            ? { clone_forks: z.array(z.record(z.string(), z.unknown())) }
-            : {}),
         checklist_attestations: z
             .array(z.object({
             check_id: z.string().min(1),

package/dist/agent/fakeAgent.js

@@ -3,7 +3,6 @@ import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
 import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
-import { assertCloneForks } from "../envelope/cloneForks.js";
 import { assertForkEnvelope } from "../envelope/forkChoice.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
 import { tryParsePendingPrompt } from "../runtime/stageHitl.js";
@@ -154,15 +153,15 @@ export class FakeAgent {
                 ? behavior.envelope
                 : undefined;
             try {
-                const envelope = assertRequiredEnvelope(envelopeValue);
+                let envelope = assertRequiredEnvelope(envelopeValue);
+                if (envelope.status === "success" && envelope.payload === undefined) {
+                    envelope = { ...envelope, payload: {} };
+                }
                 assertFeedbackLoopAction(envelope, input.feedbackLoopEmitContext);
                 const isFeedbackSendBack = envelope.feedback_loop?.action === "send_back";
                 if (!isFeedbackSendBack && input.forkEmitContext !== undefined) {
                     assertForkEnvelope(envelope, input.forkEmitContext);
                 }
-                if (!isFeedbackSendBack && input.cloneEmitContext !== undefined) {
-                    assertCloneForks(envelope, input.cloneEmitContext);
-                }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);
                 if (!isAdvancingEnvelope(envelope)) {
                     input.onActivity?.({ event: "agent_end" });

package/dist/agent/piAdapter.d.ts

@@ -5,6 +5,7 @@ import "./cursorProvider.js";
 import { type StageActivityObserver } from "./activityObserver.js";
 import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
 import type { StageGateKind } from "../types/stage.js";
+import { type StageUsage } from "../types/usage.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
@@ -56,6 +57,7 @@ export declare function extractPartialResultText(partialResult: unknown): string
 export type RouteSessionEventToProgressOptions = {
     observer: StageActivityObserver;
     verbose: boolean;
+    usage?: StageUsage;
 };
 /**
  * Adapter-edge routing: stream deltas to the observer, map milestones to

package/dist/agent/piAdapter.js

@@ -47,6 +47,7 @@ import { findProviderSupport } from "./providerSupport.js";
 import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
 import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
+import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
@@ -302,13 +303,29 @@ export function extractPartialResultText(partialResult) {
     }
     return String(partialResult);
 }
+/** Merge one assistant message's usage/cost (as reported by pi-ai) into the stage-level accumulator. */
+function mergePiAssistantUsage(usage, message) {
+    if (!message || typeof message !== "object")
+        return;
+    const msg = message;
+    if (msg.role !== "assistant" || typeof msg.model !== "string" || !msg.usage)
+        return;
+    const u = msg.usage;
+    addModelUsage(usage, msg.model, {
+        inputTokens: u.input,
+        outputTokens: u.output,
+        cacheReadInputTokens: u.cacheRead,
+        cacheCreationInputTokens: u.cacheWrite,
+        costUsd: u.cost?.total ?? 0,
+    });
+}
 /**
  * Adapter-edge routing: stream deltas to the observer, map milestones to
  * StageActivityEvent. Verbose thinking / live tool partials go to observer
  * hooks (stderr streams + coalesced/throttled persist via onActivity).
  */
 export function routeSessionEventToProgress(event, options) {
-    const { observer, verbose } = options;
+    const { observer, verbose, usage } = options;
     if (event.type === "message_update") {
         const ame = event.assistantMessageEvent;
         if (ame && typeof ame === "object") {
@@ -334,6 +351,9 @@ export function routeSessionEventToProgress(event, options) {
     }
     if (event.type === "message_end" || event.type === "agent_end") {
         observer.onStreamBoundary();
+        if (usage && event.type === "message_end") {
+            mergePiAssistantUsage(usage, event.message);
+        }
     }
     if (event.type === "agent_start" ||
         event.type === "turn_start" ||
@@ -350,13 +370,14 @@ export function routeSessionEventToProgress(event, options) {
  * Map Pi session events to StageActivityEvent at the adapter edge, then
  * forward to the activity observer (stderr + onActivity).
  */
-function attachStageProgress(session, onActivity) {
+function attachStageProgress(session, onActivity, usage) {
     const observer = createStageActivityObserver({ onActivity, writeStderr: true });
     const verbose = readActivityVerbose();
     const unsubscribe = session.subscribe((event) => {
         routeSessionEventToProgress(event, {
             observer,
             verbose,
+            usage,
         });
     });
     return () => {
@@ -383,23 +404,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             emitHint += `\nFailed-check evidence from attempt ${input.repairContext.prior_attempt}:\n${JSON.stringify(input.repairContext.failed_checks, null, 2)}`;
         }
     }
-    if (input.cloneEmitContext !== undefined) {
-        const allowedActions = input.cloneEmitContext.allowedActions ?? ["skip", "once", "fanout"];
-        const successorLines = input.cloneEmitContext.clonableSuccessors.map((successor) => {
-            const header = `- ${successor.successorId} (clone_cap: ${successor.cloneCap})`;
-            if (successor.cloneInputSchema === undefined) {
-                return header;
-            }
-            return `${header}\n  Assignment schema (io.input.schema):\n${JSON.stringify(successor.cloneInputSchema, null, 2)}`;
-        });
-        emitHint += `\nClonable successors — emit clone_forks covering each of these ids exactly once:\n${successorLines.join("\n")}`;
-        emitHint += `\nEach once or fanout envelope is a full StageEnvelope — it requires status ("success" or "failure"), summary (non-empty string), and artifacts (array of strings). io.input.schema fields belong in envelope.payload, not at the top level of the clone_forks item.`;
-        emitHint += `\nAllowed clone actions: ${allowedActions.join(", ")}`;
-    }
     if (input.feedbackLoopEmitContext !== undefined) {
         emitHint += `\nFeedback-loop decision: this stage is a feedback-loop source. On status=success, feedback_loop is required. Emit either {"action":"continue"} to proceed downstream or {"action":"send_back","target":"…"} to request another pass.`;
         emitHint += `\nAllowed send_back target: ${input.feedbackLoopEmitContext.target}.`;
-        emitHint += `\nA send_back decision cannot be combined with fork_choice or clone_forks.`;
+        emitHint += `\nA send_back decision cannot be combined with fork_choice.`;
     }
     const attempt = input.roots.attempt ?? 1;
     const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;
@@ -752,6 +760,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     const { roots } = input;
     const provider = findProviderSupport(input.stage.model);
     const capture = {};
+    const usage = emptyStageUsage();
     const askWaitChannel = existingAskWaitChannel ?? new AskOperatorWaitChannel();
     const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext, input.cloneEmitContext, {
         checks: input.stage.pre_emit_checks,
@@ -864,6 +873,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             providerEmitHint: provider?.emitToolHint?.(emitDef.name),
             restoreProvider,
             capture,
+            usage,
             askWaitChannel,
             connecting: attached.connecting,
             cancelConnecting: attached.cancel,
@@ -1090,7 +1100,7 @@ export class PiAgentAdapter {
                 return;
             }
             session = bound;
-            unsubscribeProgress = attachStageProgress(session, input.onActivity);
+            unsubscribeProgress = attachStageProgress(session, input.onActivity, wiring.usage);
         })();
         const runWithTimeout = async (work) => {
             await preparePromise;
@@ -1109,16 +1119,17 @@ export class PiAgentAdapter {
                     });
                 });
                 await Promise.race([workPromise, abortPromise]);
-                return resultFromCapture(wiring.capture);
+                return { ...resultFromCapture(wiring.capture), usage: wiring.usage };
             }
             catch (err) {
                 if (wiring.capture.envelope && isAdvancingEnvelope(wiring.capture.envelope)) {
-                    return { ok: true, envelope: wiring.capture.envelope };
+                    return { ok: true, envelope: wiring.capture.envelope, usage: wiring.usage };
                 }
                 return {
                     ok: false,
                     reason: err instanceof Error ? err.message : String(err),
                     envelope: wiring.capture.envelope,
+                    usage: wiring.usage,
                 };
             }
             finally {

package/dist/agent/port.d.ts

@@ -8,6 +8,7 @@ import type { StageActivityEvent } from "./activity.js";
 import type { ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import type { QaExchange } from "../hitl/qaTrail.js";
+import type { StageUsage } from "../types/usage.js";
 /** Opaque to runtime; adapters interpret. */
 export type StageResumeToken = string;
 export type StageSessionMode = "fresh" | "waiting_resume" | "feedback_resume" | "new_session";
@@ -77,10 +78,12 @@ export declare function runtimeStageId(input: Pick<StageRunInput, "stage" | "sta
 export type StageRunResult = {
     ok: true;
     envelope: StageEnvelope;
+    usage?: StageUsage;
 } | {
     ok: false;
     reason: string;
     envelope?: StageEnvelope;
+    usage?: StageUsage;
 };
 /** Opaque wait-request blob; T2 owns concrete prompt shapes later. */
 export type OpaqueWaitRequest = unknown;

package/dist/cli/runOutput.js

@@ -2,6 +2,21 @@ import { projectRun } from "../projection/projectRun.js";
 function stringify(payload) {
     return JSON.stringify(payload, null, 2);
 }
+function formatUsd(amount) {
+    return `$${amount.toFixed(4)}`;
+}
+/** Best-effort total cost for a run; undefined (not thrown) on any read failure or when no stage reported usage. */
+async function tryReadTotalCostUsd(store, runId) {
+    if (!store)
+        return undefined;
+    try {
+        const detail = await store.readRun(runId);
+        return detail.total_cost_usd;
+    }
+    catch {
+        return undefined;
+    }
+}
 function isBusyCode(code) {
     return code === "busy_capacity" || code === "busy_checkout";
 }
@@ -80,14 +95,19 @@ function baseRunCompletionPayload(result) {
     }
     return payload;
 }
-function formatRunCompletionJson(result) {
-    return stringify(baseRunCompletionPayload(result));
+async function formatRunCompletionJsonWithCost(result, store) {
+    const totalCostUsd = await tryReadTotalCostUsd(store, result.runId);
+    return stringify({
+        ...baseRunCompletionPayload(result),
+        ...(totalCostUsd !== undefined ? { total_cost_usd: totalCostUsd } : {}),
+    });
 }
 async function formatRunCompletionJsonWithStages(result, store) {
     const detail = await store.readRun(result.runId);
     const projection = projectRun(detail);
     return stringify({
         ...baseRunCompletionPayload(result),
+        ...(detail.total_cost_usd !== undefined ? { total_cost_usd: detail.total_cost_usd } : {}),
         stages: projection.stages,
     });
 }
@@ -101,18 +121,21 @@ function writeStartFailureHuman(started, io) {
         io.error(`conflictingCheckout: ${started.conflictingCheckout}`);
     }
 }
-function writeCompletionHuman(result, io) {
+function writeCompletionHuman(result, io, totalCostUsd) {
     switch (result.outcome) {
         case "waiting":
             io.error(`Pipeline waiting. Run folder: ${result.runDir} (${result.runId})`);
-            return;
+            break;
         case "failed":
             io.error(`Pipeline failed: ${result.reason}`);
             io.error(`Run folder: ${result.runDir}`);
-            return;
+            break;
         case "succeeded":
             io.log(`Pipeline succeeded. Run folder: ${result.runDir}`);
-            return;
+            break;
+    }
+    if (totalCostUsd !== undefined) {
+        io.error(`Cost: ${formatUsd(totalCostUsd)}`);
     }
 }
 function exitCodeForRunOutcome(outcome) {
@@ -151,11 +174,12 @@ export async function reportCliRun(event, options) {
             }
         }
         else {
-            options.io.log(formatRunCompletionJson(event.result));
+            options.io.log(await formatRunCompletionJsonWithCost(event.result, options.store));
         }
     }
     else {
-        writeCompletionHuman(event.result, options.io);
+        const totalCostUsd = await tryReadTotalCostUsd(options.store, event.result.runId);
+        writeCompletionHuman(event.result, options.io, totalCostUsd);
     }
     return exitCodeForRunOutcome(event.result.outcome);
 }

package/dist/config/cloneChain.d.ts

@@ -0,0 +1,12 @@
+import type { PipelineStageRef, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export type DetectedCloneChain = {
+    emitterId: string;
+    cloneChildId: string;
+    joinId: string;
+    arrayField: string;
+    ref: string;
+};
+export declare function detectCloneChains(stages: StageConfig[], refs: PipelineStageRef[], pipelineId: string): LoadOutcome<DetectedCloneChain[]>;
+export declare function applyCloneChains(stages: StageConfig[], refs: PipelineStageRef[], dag: ResolvedPipelineDag, pipelineId: string): LoadOutcome<void>;