stageflow 0.13.0 → 0.16.0

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/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 () => {
@@ -390,10 +411,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             if (successor.cloneInputSchema === undefined) {
                 return header;
             }
-            return `${header}\n  Assignment schema (clone_input_schema):\n${JSON.stringify(successor.cloneInputSchema, null, 2)}`;
+            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). clone_input_schema fields belong in envelope.payload, not at the top level of the clone_forks item.`;
+        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) {
@@ -431,6 +452,9 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
         `Goal: ${input.task.goal}`,
         input.task.context ? `Context: ${input.task.context}` : "",
         input.task.constraints ? `Constraints: ${input.task.constraints}` : "",
+        input.task.input !== undefined
+            ? `Input: ${JSON.stringify(input.task.input, null, 2)}`
+            : "",
         formatPriorEnvelope(input.priorEnvelope, input.priorEnvelopes, input.priorEnvelopesByStage),
         input.feedbackLoopContext !== undefined
             ? formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode)
@@ -749,6 +773,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,
@@ -861,6 +886,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             providerEmitHint: provider?.emitToolHint?.(emitDef.name),
             restoreProvider,
             capture,
+            usage,
             askWaitChannel,
             connecting: attached.connecting,
             cancelConnecting: attached.cancel,
@@ -1087,7 +1113,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;
@@ -1106,16 +1132,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

@@ -1,13 +1,14 @@
 import type { StageEnvelope, TerminalEnvelope } from "../types/envelope.js";
 import type { CompletionContract } from "../types/completion.js";
 import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
-import type { StageConfig } from "../types/stage.js";
+import type { LoadedStageConfig } from "../types/stage.js";
 import type { FeedbackLoopConfig } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
 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";
@@ -45,7 +46,7 @@ export type FeedbackLoopContext = {
 };
 export type StageRunInput = {
     roots: StageRoots;
-    stage: StageConfig;
+    stage: LoadedStageConfig;
     /** Runtime instance id (`work~2`). Defaults to `stage.id` when omitted. */
     stageId?: string;
     task: TaskFile;
@@ -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/initTemplates.d.ts

@@ -1,3 +1,3 @@
 export declare const STAGEFLOW_YAML = "version: 1\ncatalog:\n  pipelines:\n    - pipelines\n  tasks:\n    - tasks\n  patterns:\n    pipeline: \"*.pipeline.yaml\"\n    task: \"*.task.yaml\"\n";
-export declare const HELLO_PIPELINE_YAML = "id: hello\nstages:\n  - id: hello\n    system_prompt: Say hello and emit a success envelope.\n    model: anthropic/claude-sonnet-4-5\n";
+export declare const HELLO_PIPELINE_YAML = "id: hello\nmodel: anthropic/claude-sonnet-4-5\nstages:\n  - id: hello\n    system_prompt: Say hello and emit a success envelope.\n";
 export declare const HELLO_TASK_YAML = "id: hello\ngoal: Run the hello pipeline scaffold.\n";

package/dist/cli/initTemplates.js

@@ -9,10 +9,10 @@ catalog:
     task: "*.task.yaml"
 `;
 export const HELLO_PIPELINE_YAML = `id: hello
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: hello
     system_prompt: Say hello and emit a success envelope.
-    model: anthropic/claude-sonnet-4-5
 `;
 export const HELLO_TASK_YAML = `id: hello
 goal: Run the hello pipeline scaffold.

package/dist/cli/migrateYamlCommand.d.ts

@@ -0,0 +1,18 @@
+export declare const MIGRATE_YAML_USAGE = "Usage:\n  sf migrate-yaml [path] [--root <path>] [--write] [--json] [--force]\n\n  Convert legacy catalog YAML to target YAML (io / verify / on_verify_fail).\n  Dry-run is the default. --write applies changes. Path may be a pipeline,\n  stage, task, or catalog root. Does not rewrite .stageflow snapshots.";
+export type MigrateYamlCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export type MigrateYamlJson = {
+    ok: boolean;
+    write: boolean;
+    planned: string[];
+    written: string[];
+    skipped: string[];
+    errors: string[];
+};
+export declare function runMigrateYamlCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<MigrateYamlCommandIo>;
+}): Promise<number>;

package/dist/cli/migrateYamlCommand.js

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { applyMigrateYamlPlan, fileDirtyVsHead, planMigrateYaml, } from "../config/migrateYaml.js";
+export const MIGRATE_YAML_USAGE = `Usage:
+  sf migrate-yaml [path] [--root <path>] [--write] [--json] [--force]
+
+  Convert legacy catalog YAML to target YAML (io / verify / on_verify_fail).
+  Dry-run is the default. --write applies changes. Path may be a pipeline,
+  stage, task, or catalog root. Does not rewrite .stageflow snapshots.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseMigrateYamlArgs(args) {
+    if (args.length === 0) {
+        return { help: false, write: false, json: false, force: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, write: false, json: false, force: false };
+    }
+    let target;
+    let root;
+    let write = false;
+    let json = false;
+    let force = false;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--write") {
+            write = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--root") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --root");
+            }
+            root = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else if (target !== undefined) {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+        else {
+            target = arg;
+        }
+    }
+    if (target !== undefined && root !== undefined) {
+        throw new Error("Use at most one of a positional path or --root");
+    }
+    return { help, target: target ?? root, write, json, force };
+}
+function planToJson(plan, options) {
+    return {
+        ok: options.ok,
+        write: options.write,
+        planned: plan.writes.map((item) => item.file),
+        written: options.written,
+        skipped: plan.skipped,
+        errors: [...plan.errors, ...(options.extraErrors ?? [])],
+    };
+}
+function formatHuman(plan, write, extraErrors) {
+    const lines = [];
+    const errors = [...plan.errors, ...extraErrors];
+    if (errors.length > 0) {
+        lines.push("Migration failed:");
+        for (const error of errors)
+            lines.push(`  ${error}`);
+        return lines.join("\n");
+    }
+    if (write) {
+        if (plan.writes.length === 0) {
+            lines.push("Nothing to write.");
+        }
+        else {
+            lines.push("Wrote:");
+            for (const item of plan.writes)
+                lines.push(`  ${item.file}`);
+        }
+    }
+    else if (plan.writes.length === 0) {
+        lines.push("Nothing to migrate.");
+    }
+    else {
+        lines.push("Would write:");
+        for (const item of plan.writes)
+            lines.push(`  ${item.file}`);
+        lines.push("");
+        lines.push("Dry-run; pass --write to apply.");
+    }
+    if (plan.skipped.length > 0) {
+        lines.push("");
+        lines.push("Skipped:");
+        for (const file of plan.skipped)
+            lines.push(`  ${file}`);
+    }
+    return lines.join("\n");
+}
+export async function runMigrateYamlCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const out = { ...defaultIo, ...options.io };
+    try {
+        const parsed = parseMigrateYamlArgs(args);
+        if (parsed.help) {
+            out.error(MIGRATE_YAML_USAGE);
+            return 0;
+        }
+        const target = path.resolve(cwd, parsed.target ?? ".");
+        const plan = await planMigrateYaml(target, { cwd, projectRoot });
+        const extraErrors = [];
+        if (plan.errors.length > 0) {
+            if (parsed.json) {
+                out.log(JSON.stringify(planToJson(plan, { write: parsed.write, written: [], ok: false }), null, 2));
+            }
+            else {
+                out.error(formatHuman(plan, parsed.write, extraErrors));
+                out.error(MIGRATE_YAML_USAGE);
+            }
+            return 1;
+        }
+        if (parsed.write && !parsed.force) {
+            for (const item of plan.writes) {
+                if (fileDirtyVsHead(item.absPath)) {
+                    extraErrors.push(`Refusing to overwrite uncommitted changes in ${item.file} (pass --force)`);
+                }
+            }
+            if (extraErrors.length > 0) {
+                if (parsed.json) {
+                    out.log(JSON.stringify(planToJson(plan, {
+                        write: true,
+                        written: [],
+                        ok: false,
+                        extraErrors,
+                    }), null, 2));
+                }
+                else {
+                    out.error(formatHuman(plan, parsed.write, extraErrors));
+                }
+                return 1;
+            }
+        }
+        let written = [];
+        if (parsed.write) {
+            await applyMigrateYamlPlan(plan);
+            written = plan.writes.map((item) => item.file);
+        }
+        if (parsed.json) {
+            out.log(JSON.stringify(planToJson(plan, {
+                write: parsed.write,
+                written,
+                ok: true,
+            }), null, 2));
+        }
+        else {
+            out.log(formatHuman(plan, parsed.write, extraErrors));
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Migrate-yaml command failed";
+        out.error(message);
+        out.error(MIGRATE_YAML_USAGE);
+        return 1;
+    }
+}