stageflow 0.18.0 → 0.23.0

package/README.md

@@ -190,7 +190,7 @@ Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository
 
 Host MCP via `sf ui` or `sf mcp` at `http://127.0.0.1:3847/mcp` (URL printed on boot). Sessions are the default. Point a Cursor (or other) MCP client at that URL. Do not run both hosts against the same store.
 
-HITL-aware tools include `wait_run`, `answer_gate`, and `list_waiting`. Full tool list: [docs/mcp.md](docs/mcp.md).
+HITL-aware tools include `wait_run`, `answer_gate`, `list_waiting`, and `decide_feedback_loop`. Inspect tools (`list_providers`, `list_models`, `describe_pipeline`, …) are read-only. Full tool list: [docs/mcp.md](docs/mcp.md).
 
 Stages use project `.mcp.json` plus stage `mcp` names. See [YAML catalog — Stage MCP](docs/yaml-catalog.md#stage-mcp).
 
@@ -222,6 +222,7 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 | [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) |
 | [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
+| [mcp-hitl-tour](examples/mcp-hitl-tour/) | MCP-first HITL: gates, fan-out/join, `wait_for_human` decide |
 | [ci-validate](examples/ci-validate/) | Strict validate in CI |
 
 Index: [examples/README.md](examples/README.md)

package/dist/agent/activity.d.ts

@@ -74,6 +74,10 @@ export type StageLifecycleEvent = {
 } | {
     event: "skipped";
 }
+/** A previously skipped stage is runnable again (parent succeeded). */
+ | {
+    event: "reopened";
+}
 /** Operator explicitly authorized a new attempt after verified failure. */
  | {
     event: "manual_recovery_requested";
@@ -82,6 +86,11 @@ export type StageLifecycleEvent = {
 /** Operator chose to leave the verified failure terminal. */
  | {
     event: "manual_recovery_stopped";
+} | {
+    event: "feedback_loop_decided";
+    decision: "extend" | "continue" | "abandon";
+    loopId: string;
+    reason?: string;
 };
 export type StageLogLine = StageActivityEvent | StageLifecycleEvent;
 export declare function truncateActivityText(value: unknown, limit?: number): string | undefined;

package/dist/agent/activityObserver.d.ts

@@ -1,5 +1,6 @@
 import { type StageActivityEvent } from "./activity.js";
 export declare const TOOL_PROGRESS_THROTTLE_MS = 300;
+export declare const STREAM_FLUSH_THROTTLE_MS = 300;
 export type StageActivityObserver = {
     onAssistantTextDelta(delta: string): void;
     onThinkingDelta(delta: string): void;
@@ -10,6 +11,8 @@ export type StageActivityObserver = {
 };
 export type CreateStageActivityObserverOptions = {
     onActivity?: (event: StageActivityEvent) => void;
+    /** Fired for every non-empty assistant text delta, regardless of writeStderr. */
+    onAssistantTextDelta?: (delta: string) => void;
     writeStderr?: boolean;
     toolProgressThrottleMs?: number;
 };

package/dist/agent/activityObserver.js

@@ -1,5 +1,6 @@
 import { truncateActivityText, } from "./activity.js";
 export const TOOL_PROGRESS_THROTTLE_MS = 300;
+export const STREAM_FLUSH_THROTTLE_MS = 300;
 function writeIndentedPreview(preview) {
     for (const line of preview.split("\n")) {
         process.stderr.write(`    ${line}\n`);
@@ -127,7 +128,11 @@ export function createStageActivityObserver(options = {}) {
     };
     return {
         onAssistantTextDelta(delta) {
-            if (!writeStderr || !delta) {
+            if (!delta) {
+                return;
+            }
+            options.onAssistantTextDelta?.(delta);
+            if (!writeStderr) {
                 return;
             }
             assistantStreamedForMessage = true;

package/dist/agent/claudeAdapter.js

@@ -47,6 +47,7 @@ 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 { composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.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). */
@@ -295,6 +296,29 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
             await clearClaudeSessionMarker(markerPath);
             return { kind: "completed", result: { ok: true, envelope: emitCapture.envelope, usage } };
         }
+        if (controller.signal.aborted && sessionId !== undefined) {
+            await writeClaudeSessionMarker(markerPath, { sessionId, usage });
+            return {
+                kind: "completed",
+                result: {
+                    ok: false,
+                    reason: stageTimeoutReason(timeoutMs),
+                    envelope: emitCapture.envelope,
+                    usage,
+                },
+            };
+        }
+        if (controller.signal.aborted) {
+            return {
+                kind: "completed",
+                result: {
+                    ok: false,
+                    reason: stageTimeoutReason(timeoutMs),
+                    envelope: emitCapture.envelope,
+                    usage,
+                },
+            };
+        }
         return {
             kind: "completed",
             result: {
@@ -385,6 +409,20 @@ export class ClaudeAgentAdapter {
                 if (!pre.ok) {
                     return { status: "completed", result: { ok: false, reason: pre.reason } };
                 }
+                if (input.sessionMode === "timeout_resume") {
+                    const marker = await readClaudeSessionMarker(markerPath);
+                    if (marker?.sessionId === undefined) {
+                        return {
+                            status: "completed",
+                            result: {
+                                ok: false,
+                                reason: "missing Claude session to resume; use retry to start a new attempt",
+                            },
+                        };
+                    }
+                    const outcome = await runTurn(input, pre.model, markerPath, composeTimeoutResumePrompt(), marker.sessionId, usage);
+                    return applyOutcome(outcome);
+                }
                 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);
             },

package/dist/agent/fakeAgent.js

@@ -69,7 +69,9 @@ export class FakeAgent {
         let started = false;
         let resumeCorrupt = false;
         const sessionMode = input.sessionMode ?? "fresh";
-        const skipHitlPark = sessionMode === "feedback_resume" || sessionMode === "new_session";
+        const skipHitlPark = sessionMode === "feedback_resume" ||
+            sessionMode === "timeout_resume" ||
+            sessionMode === "new_session";
         if (sessionMode === "feedback_resume" && input.feedbackLoopContext === undefined) {
             return createCompletedOnlyStageHandle({
                 stageId: runtimeStageId(input),

package/dist/agent/piAdapter.js

@@ -48,6 +48,7 @@ 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";
+import { TIMEOUT_ABORT_TOOL_RESULT, composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
@@ -370,8 +371,12 @@ 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, usage) {
-    const observer = createStageActivityObserver({ onActivity, writeStderr: true });
+function attachStageProgress(session, onActivity, usage, onAssistantTextDelta) {
+    const observer = createStageActivityObserver({
+        onActivity,
+        onAssistantTextDelta,
+        writeStderr: true,
+    });
     const verbose = readActivityVerbose();
     const unsubscribe = session.subscribe((event) => {
         routeSessionEventToProgress(event, {
@@ -1028,6 +1033,7 @@ export class PiAgentAdapter {
         let sessionManager;
         let resumeWaiting = false;
         let feedbackResume = false;
+        let timeoutResume = false;
         let forceNewSession = sessionMode === "new_session";
         if (sessionMode === "feedback_resume") {
             if (input.feedbackLoopContext === undefined) {
@@ -1049,6 +1055,23 @@ export class PiAgentAdapter {
             ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
             feedbackResume = true;
         }
+        else if (sessionMode === "timeout_resume") {
+            if (!existsSync(sessionFile)) {
+                throw new StageSessionReconstructError(`stage session file missing for timeout_resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            }
+            try {
+                sessionManager = SessionManager.open(sessionFile, path.dirname(sessionFile), input.roots.cwd);
+            }
+            catch (err) {
+                throw new StageSessionReconstructError(`stage session file corrupt or unreadable for timeout_resume: ${sessionFile}`, {
+                    stageId: runtimeStageId(input),
+                    sessionFile,
+                    cause: err,
+                });
+            }
+            ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
+            timeoutResume = true;
+        }
         else if (sessionMode !== "new_session") {
             if (sessionMode === "waiting_resume" || existsSync(sessionFile)) {
                 if (existsSync(sessionFile)) {
@@ -1100,7 +1123,7 @@ export class PiAgentAdapter {
                 return;
             }
             session = bound;
-            unsubscribeProgress = attachStageProgress(session, input.onActivity, wiring.usage);
+            unsubscribeProgress = attachStageProgress(session, input.onActivity, wiring.usage, input.onAssistantTextDelta);
         })();
         const runWithTimeout = async (work) => {
             await preparePromise;
@@ -1115,13 +1138,17 @@ export class PiAgentAdapter {
                 const workPromise = work();
                 const abortPromise = new Promise((_, reject) => {
                     controller.signal.addEventListener("abort", () => {
-                        reject(new Error(`stage timed out after ${timeoutMs}ms`));
+                        void session?.abort();
+                        reject(new Error(stageTimeoutReason(timeoutMs)));
                     });
                 });
                 await Promise.race([workPromise, abortPromise]);
                 return { ...resultFromCapture(wiring.capture), usage: wiring.usage };
             }
             catch (err) {
+                if (sessionManager) {
+                    ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
+                }
                 if (wiring.capture.envelope && isAdvancingEnvelope(wiring.capture.envelope)) {
                     return { ok: true, envelope: wiring.capture.envelope, usage: wiring.usage };
                 }
@@ -1151,6 +1178,15 @@ export class PiAgentAdapter {
                         await session.prompt(composeFeedbackResumePrompt(input));
                         return;
                     }
+                    if (timeoutResume) {
+                        syncAgentMessagesFromSession(session, sessionManager);
+                        if (findOpenToolCall(sessionManager)) {
+                            injectOpaqueAnswerIntoSession(sessionManager, TIMEOUT_ABORT_TOOL_RESULT);
+                            syncAgentMessagesFromSession(session, sessionManager);
+                        }
+                        await session.prompt(composeTimeoutResumePrompt());
+                        return;
+                    }
                     const userPrompt = composeStageUserPrompt(input, wiring.emitDefName, wiring.providerEmitHint, wiring.artifactDefName);
                     await session.prompt(userPrompt);
                 });

package/dist/agent/port.d.ts

@@ -11,7 +11,7 @@ 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";
+export type StageSessionMode = "fresh" | "waiting_resume" | "feedback_resume" | "timeout_resume" | "new_session";
 export type StageRepairContext = {
     prior_attempt: number;
     /** Operator-authored instructions for an explicitly approved manual retry. */
@@ -60,6 +60,8 @@ export type StageRunInput = {
     sessionMode?: StageSessionMode;
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
+    /** Optional raw assistant-text-delta sink, fired alongside onActivity, not instead of it. */
+    onAssistantTextDelta?: (delta: string) => void;
     skillFilePath?: string;
     forkEmitContext?: ForkEmitContext;
     cloneEmitContext?: CloneEmitContext;

package/dist/agent/providerInspect.d.ts

@@ -0,0 +1,19 @@
+import { type PiHomeDetectResult, type ProviderAuthContext, type ProviderAuthStatus, type ProviderSummary, type ProvidersListResult } from "./providerAuth.js";
+export type ProviderReadinessRow = ProviderSummary & {
+    configured: boolean;
+    authKind?: ProviderAuthStatus["authKind"];
+    source?: string;
+};
+export type ProviderReadinessInspect = {
+    authShell: ProvidersListResult["authShell"];
+    via: ProvidersListResult["via"];
+    detect: PiHomeDetectResult;
+    providers: ProviderReadinessRow[];
+};
+export declare function inspectProviderReadiness(cwd: string, ctx?: ProviderAuthContext): Promise<ProviderReadinessInspect>;
+export declare function mapProviderAuthError(err: unknown): {
+    status: number;
+    body: {
+        error: string;
+    };
+};

package/dist/agent/providerInspect.js

@@ -0,0 +1,35 @@
+import { defaultContext, detectPiHome, getAuthStatus, listProviders, ProviderAuthError, } from "./providerAuth.js";
+function statusList(statuses) {
+    return Array.isArray(statuses) ? statuses : [statuses];
+}
+export async function inspectProviderReadiness(cwd, ctx = defaultContext) {
+    const listed = await listProviders(cwd, ctx);
+    const statuses = statusList(await getAuthStatus(cwd, undefined, ctx));
+    const statusById = new Map(statuses.map((status) => [status.providerId, status]));
+    const detect = detectPiHome(cwd);
+    return {
+        authShell: listed.authShell,
+        via: listed.via,
+        detect,
+        providers: listed.providers.map((provider) => {
+            const status = statusById.get(provider.id);
+            return {
+                ...provider,
+                configured: status?.configured ?? false,
+                ...(status?.authKind !== undefined
+                    ? { authKind: status.authKind }
+                    : {}),
+                ...(status?.source !== undefined ? { source: status.source } : {}),
+            };
+        }),
+    };
+}
+export function mapProviderAuthError(err) {
+    if (err instanceof ProviderAuthError) {
+        return { status: err.status, body: { error: err.message } };
+    }
+    return {
+        status: 500,
+        body: { error: "Provider auth operation failed" },
+    };
+}

package/dist/agent/stageTimeout.d.ts

@@ -0,0 +1,9 @@
+export declare const STAGE_TIMEOUT_REASON_PREFIX = "stage timed out after ";
+export declare function stageTimeoutReason(timeoutMs: number): string;
+export declare function isStageTimeoutReason(reason: string | undefined): boolean;
+export declare function lastFailedReason(events: ReadonlyArray<{
+    event: string;
+    reason?: string;
+}>): string | undefined;
+export declare const TIMEOUT_ABORT_TOOL_RESULT = "Command aborted: the stage timed out. Continue without a debugger. Do not use --inspect or --inspect-brk.";
+export declare function composeTimeoutResumePrompt(): string;

package/dist/agent/stageTimeout.js

@@ -0,0 +1,24 @@
+export const STAGE_TIMEOUT_REASON_PREFIX = "stage timed out after ";
+export function stageTimeoutReason(timeoutMs) {
+    return `${STAGE_TIMEOUT_REASON_PREFIX}${timeoutMs}ms`;
+}
+export function isStageTimeoutReason(reason) {
+    return (typeof reason === "string" && reason.startsWith(STAGE_TIMEOUT_REASON_PREFIX));
+}
+export function lastFailedReason(events) {
+    let reason;
+    for (const event of events) {
+        if (event.event === "failed")
+            reason = event.reason;
+    }
+    return reason;
+}
+export const TIMEOUT_ABORT_TOOL_RESULT = "Command aborted: the stage timed out. Continue without a debugger. Do not use --inspect or --inspect-brk.";
+export function composeTimeoutResumePrompt() {
+    return [
+        "The previous turn was interrupted because the stage timed out.",
+        "Continue the same work from the conversation above. Do not start over.",
+        "Do not attach a debugger (no --inspect or --inspect-brk).",
+        "Finish the stage and emit the envelope when done.",
+    ].join(" ");
+}

package/dist/agent/streamLogRedact.d.ts

@@ -0,0 +1,2 @@
+/** Scrub common secret-shaped substrings before text is persisted or returned. */
+export declare function redactSecrets(text: string): string;

package/dist/agent/streamLogRedact.js

@@ -0,0 +1,13 @@
+const SECRET_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
+    /\bghp_[A-Za-z0-9]{20,}\b/g,
+    /\b[A-Za-z_]*KEY[A-Za-z_]*\s*[:=]\s*['"]?[A-Za-z0-9+/_-]{16,}['"]?/gi,
+];
+/** Scrub common secret-shaped substrings before text is persisted or returned. */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of SECRET_PATTERNS) {
+        out = out.replace(pattern, "[redacted]");
+    }
+    return out;
+}

package/dist/cli/artifactCommand.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "node:fs";
 import path from "node:path";
 import { readRunArtifact } from "../mcp/readArtifact.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { isInsideDir } from "../runstore/workspaceLayout.js";
 export const ARTIFACT_USAGE = `Usage:
@@ -73,7 +74,6 @@ function resolveSafeOutPath(outPath, cwd) {
 }
 export async function runArtifactCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -99,7 +99,7 @@ export async function runArtifactCommand(args, options = {}) {
         out.error(ARTIFACT_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     try {
         const contents = await readRunArtifact(store, parsed.runId, parsed.artifactPath);
         if (parsed.outPath !== undefined) {

package/dist/cli/envelopeCommand.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { buildHandoffDeliverable, isHandoffSkipped, } from "./handoffFormat.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 export const ENVELOPE_USAGE = `Usage:
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]`;
@@ -198,7 +199,6 @@ function formatHandoffHuman(result) {
 }
 export async function runEnvelopeCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -224,7 +224,7 @@ export async function runEnvelopeCommand(args, options = {}) {
         out.error(ENVELOPE_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     let runContext;
     try {
         runContext = resolveRunContext(parsed, cwd, store);

package/dist/cli/exportRunCommand.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { projectRun } from "../projection/projectRun.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { isInsideDir } from "../runstore/workspaceLayout.js";
 export const EXPORT_RUN_USAGE = `Usage:
@@ -94,7 +95,6 @@ function assertRunComplete(status, runId) {
 }
 export async function runExportRunCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -126,7 +126,7 @@ export async function runExportRunCommand(args, options = {}) {
         out.error(EXPORT_RUN_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     try {
         const detail = await store.readRun(runId);
         assertRunComplete(detail.status, runId);

package/dist/cli/graphCommand.d.ts

@@ -0,0 +1,15 @@
+import type { LoadedPipeline } from "../types/pipeline.js";
+export declare const GRAPH_USAGE = "Usage:\n  sf graph --pipeline <path> [--json]\n\n  Prints a definition-time view of how a pipeline graph is wired, before any run.\n  --pipeline loads and resolves the pipeline (same resolution as sf validate / sf run).\n  --json dumps the resolved DAG as JSON instead of the terminal diagram.";
+export type GraphCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runGraphCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<GraphCommandIo>;
+    loadPipeline?: (nameOrPath: string, opts: {
+        cwd?: string;
+        projectRoot?: string;
+    }) => Promise<LoadedPipeline>;
+}): Promise<number>;

package/dist/cli/graphCommand.js

@@ -0,0 +1,79 @@
+import { loadPipeline } from "../config/loadPipeline.js";
+import { renderGraph } from "./graphRender.js";
+export const GRAPH_USAGE = `Usage:
+  sf graph --pipeline <path> [--json]
+
+  Prints a definition-time view of how a pipeline graph is wired, before any run.
+  --pipeline loads and resolves the pipeline (same resolution as sf validate / sf run).
+  --json dumps the resolved DAG as JSON instead of the terminal diagram.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseGraphArgs(args) {
+    if (args.length === 0) {
+        return { help: false, json: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, json: false };
+    }
+    let pipeline;
+    let json = 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 === "--pipeline") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --pipeline");
+            }
+            pipeline = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, pipeline, json };
+}
+export async function runGraphCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const out = { ...defaultIo, ...options.io };
+    const loadPipelineFn = options.loadPipeline ?? loadPipeline;
+    try {
+        const parsed = parseGraphArgs(args);
+        if (parsed.help) {
+            out.error(GRAPH_USAGE);
+            return 0;
+        }
+        if (parsed.pipeline === undefined) {
+            throw new Error("Missing value for --pipeline");
+        }
+        const loaded = await loadPipelineFn(parsed.pipeline, { cwd, projectRoot });
+        if (parsed.json) {
+            out.log(JSON.stringify(loaded.dag, null, 2));
+            return 0;
+        }
+        out.log(renderGraph(loaded.dag));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Graph command failed";
+        out.error(message);
+        out.error(GRAPH_USAGE);
+        return 1;
+    }
+}

package/dist/cli/graphRender.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+export declare function renderGraph(dag: ResolvedPipelineDag): string;

package/dist/cli/graphRender.js

@@ -0,0 +1,85 @@
+const MAX_WIDTH = 80;
+// Clip to MAX_WIDTH code points so the picture fits an 80-column terminal.
+function clampWidth(text, max = MAX_WIDTH) {
+    const chars = [...text];
+    if (chars.length <= max)
+        return text;
+    return chars.slice(0, max - 1).join("") + "…";
+}
+function cloneModeSuffix(node) {
+    return node.clone_mode ? ` (${node.clone_mode})` : "";
+}
+function buildAnnotations(node) {
+    const parts = [];
+    if (node.entry)
+        parts.push("entry");
+    if (node.clone_cap !== undefined) {
+        parts.push(`clone ${node.clone_cap}${cloneModeSuffix(node)}`);
+    }
+    if (node.replay_safe === false) {
+        parts.push("replay_safe: false");
+    }
+    return parts.join(" · ");
+}
+// loadPipeline returns a topologically ordered DAG, so a DF walk over childrenOf yields a stable, dependency-ordered list.
+function orderedNodeIds(dag) {
+    const visited = new Set();
+    const order = [];
+    const walk = (id) => {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        order.push(id);
+        for (const child of dag.childrenOf[id] ?? [])
+            walk(child);
+    };
+    for (const root of dag.roots)
+        walk(root);
+    for (const node of dag.nodes) {
+        if (!visited.has(node.id))
+            walk(node.id);
+    }
+    return order;
+}
+function cloneBandLabel(node) {
+    if (node.clone_cap === undefined)
+        return "";
+    return ` child~${node.clone_cap}${cloneModeSuffix(node)}`;
+}
+function loopCueLine(node) {
+    if (!node.feedback_loop)
+        return "";
+    const fl = node.feedback_loop;
+    const note = fl.on_max_replays ? `   (${fl.on_max_replays})` : "";
+    return `   ↩ loop ×${fl.max_replays} → ${fl.target}${note}`;
+}
+export function renderGraph(dag) {
+    const byId = new Map(dag.nodes.map((node) => [node.id, node]));
+    const order = orderedNodeIds(dag);
+    const lines = [];
+    const push = (line) => lines.push(clampWidth(line));
+    order.forEach((id, idx) => {
+        const node = byId.get(id);
+        const marker = node.entry ? "▶ " : "  ";
+        const annotations = buildAnnotations(node);
+        push(`${marker}${id}` + (annotations ? `   ${annotations}` : ""));
+        const loopCue = loopCueLine(node);
+        if (loopCue)
+            push(loopCue);
+        if (idx < order.length - 1) {
+            const children = dag.childrenOf[id] ?? [];
+            if (children.length === 1) {
+                push("   │");
+                push(`   ▼${cloneBandLabel(node)}`);
+            }
+            else if (children.length > 1) {
+                children.forEach((childId, ci) => {
+                    const isLast = ci === children.length - 1;
+                    const branch = isLast ? "└─" : "├─";
+                    push(`   ${branch}▶ ${childId}${cloneBandLabel(node)}`);
+                });
+            }
+        }
+    });
+    return lines.join("\n") + "\n";
+}