@sweny-ai/core 0.1.128 → 0.1.130

package/dist/cli/main.js

@@ -27,6 +27,8 @@ import * as readline from "node:readline";
 import { loadDotenv, loadConfigFile, applyAgentFileConfig } from "./config-file.js";
 import { buildCredentialMap } from "./credentials.js";
 import { nonInteractiveUsage, runNew } from "./new.js";
+import { buildRunRecord, createNodeTimer, historyDisabled, newRunId, recordRun } from "./run-history.js";
+import { registerRunsCommand } from "./runs.js";
 import { runE2eRun, runWithWallClockBudget, DEFAULT_WORKFLOW_TIMEOUT_MS } from "./e2e.js";
 import { createVerboseToolObserver } from "./verbose-observer.js";
 import { createRunLogger, renderReceiptLine, summarizeRun, writeStepSummary, WORKFLOW_RUN_DESCRIPTION, WORKFLOW_RUN_OPTIONS, } from "./run-output.js";
@@ -884,7 +886,31 @@ export async function workflowRunAction(file, options) {
     if (wfCloudHandle?.dashboardUrl && !isJson) {
         console.log(c.subtle(`  cloud: ${wfCloudHandle.dashboardUrl}`));
     }
-    const observer = composeObservers(wfProgressObserver, options.verbose ? createVerboseToolObserver() : undefined, options.stream ? createStreamObserver() : undefined, createCloudStreamObserver(config, wfCloudHandle));
+    // Run history (#388): metadata-only record under .sweny/runs/, written once at run end.
+    const nodeTimer = createNodeTimer();
+    const runId = newRunId(runStart);
+    let historyRecorded = false;
+    const recordHistory = (results, trace, crashed) => {
+        if (historyRecorded || historyDisabled(options.history, fileConfig["history"]))
+            return;
+        historyRecorded = true;
+        try {
+            recordRun(buildRunRecord({
+                runId,
+                workflow,
+                startedAtMs: runStart,
+                durationMs: Date.now() - runStart,
+                results,
+                trace,
+                nodeDurations: nodeTimer.durations,
+                crashed,
+            }));
+        }
+        catch {
+            // history must never fail a run
+        }
+    };
+    const observer = composeObservers(wfProgressObserver, nodeTimer.observer, options.verbose ? createVerboseToolObserver() : undefined, options.stream ? createStreamObserver() : undefined, createCloudStreamObserver(config, wfCloudHandle));
     // #325: this is the primary run path (GitHub Action / CLI / MCP all land
     // here), and previously never passed signal/timeoutMs/max_steps to
     // execute() at all: a wedged node (hung tool call, runaway model turn)
@@ -912,6 +938,7 @@ export async function workflowRunAction(file, options) {
         }), wfTimeoutMs, `Workflow ${workflow.name}`);
         const wfDurationMs = Date.now() - runStart;
         const wfHasFailed = [...results.values()].some((r) => r.status === "failed");
+        recordHistory(results, trace, false);
         // Close the cloud lifecycle session BEFORE the JSON early-exit so
         // every workflow run reports a terminal status, regardless of how
         // the CLI returns (json, mermaid, or normal stdout).
@@ -957,6 +984,7 @@ export async function workflowRunAction(file, options) {
         const crashMsg = err instanceof Error ? err.message : String(err);
         console.error(chalk.red(`\n  Error: ${crashMsg}\n`));
         runLogger.flush();
+        recordHistory(nodeTimer.lastResults, undefined, true);
         console.error(`  ${renderReceiptLine(summarizeRun(new Map(), Date.now() - runStart, true), isTTY)}\n`);
         // Finalize the cloud run as failed (covers thrown errors, incl.
         // RouteEvaluationError). Without this a crashed workflow run stays
@@ -1032,6 +1060,8 @@ const workflowRunCmd = workflowCmd
 for (const [flags, description] of WORKFLOW_RUN_OPTIONS) {
     workflowRunCmd.option(flags, description);
 }
+workflowRunCmd.option("--no-history", "Do not record this run in .sweny/runs/ (or set `history: off` in .sweny.yml)");
+registerRunsCommand(program);
 workflowCmd
     .command("diagram <file>")
     .description("Render a workflow as a Mermaid diagram (raw .mmd by default; .md output auto-fences)")

package/dist/cli/new.d.ts

@@ -120,11 +120,10 @@ export declare function writeWorkflowFile(cwd: string, id: string, yaml: string,
     exists?: boolean;
     path: string;
 };
-/**
- * Make sure `.env` is gitignored: create `.gitignore` if missing, append
- * `.env` if absent. Returns what happened.
- */
+/** Make sure `.env` is gitignored. */
 export declare function ensureGitignoreEnv(cwd: string): "created" | "appended" | "present";
+/** Make sure local run history (`.sweny/runs/`) is gitignored. */
+export declare function ensureGitignoreRuns(cwd: string): "created" | "appended" | "present";
 /** Usage printed (exit 2) when `sweny new` has no terminal and no --yes. */
 export declare function nonInteractiveUsage(): string;
 /**

package/dist/cli/new.js

@@ -443,22 +443,30 @@ export function writeWorkflowFile(cwd, id, yaml, options) {
     return { written: true, path: target };
 }
 /**
- * Make sure `.env` is gitignored: create `.gitignore` if missing, append
- * `.env` if absent. Returns what happened.
+ * Make sure `line` is in `.gitignore`: create the file if missing, append the
+ * line if absent. Returns what happened.
  */
-export function ensureGitignoreEnv(cwd) {
+function ensureGitignoreLine(cwd, line) {
     const gitignorePath = path.join(cwd, ".gitignore");
     if (!fs.existsSync(gitignorePath)) {
-        fs.writeFileSync(gitignorePath, ".env\n", "utf-8");
+        fs.writeFileSync(gitignorePath, `${line}\n`, "utf-8");
         return "created";
     }
     const content = fs.readFileSync(gitignorePath, "utf-8");
-    if (content.split(/\r?\n/).some((line) => line.trim() === ".env"))
+    if (content.split(/\r?\n/).some((l) => l.trim() === line))
         return "present";
     const sep = content.length === 0 || content.endsWith("\n") ? "" : "\n";
-    fs.appendFileSync(gitignorePath, `${sep}.env\n`, "utf-8");
+    fs.appendFileSync(gitignorePath, `${sep}${line}\n`, "utf-8");
     return "appended";
 }
+/** Make sure `.env` is gitignored. */
+export function ensureGitignoreEnv(cwd) {
+    return ensureGitignoreLine(cwd, ".env");
+}
+/** Make sure local run history (`.sweny/runs/`) is gitignored. */
+export function ensureGitignoreRuns(cwd) {
+    return ensureGitignoreLine(cwd, ".sweny/runs/");
+}
 /** The command to show in next steps: `npx` users have no `sweny` on PATH. */
 function cliCommand() {
     return process.env.npm_command === "exec" ? "npx @sweny-ai/core" : "sweny";
@@ -784,6 +792,7 @@ export async function runNew(options) {
         p.log.success("Created .gitignore with .env");
     else if (ignoreResult === "appended")
         p.log.success("Added .env to .gitignore");
+    ensureGitignoreRuns(cwd);
     // 5. Next steps
     const requiredCreds = credentials.filter((c) => !c.optional);
     const credUrls = requiredCreds.filter((c) => c.url).map((c) => `  ${c.key}: ${c.url}`);

package/dist/cli/run-history.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Local run history for `sweny workflow run`: one small JSON record per run
+ * under `.sweny/runs/`, read back by `sweny runs` and `sweny runs diff`.
+ *
+ * METADATA ONLY. A record holds ids, statuses, durations, counts, token and
+ * cost totals, and routing edges. It never holds prompts, node outputs, tool
+ * inputs/outputs, error text, or environment values.
+ *
+ * `schema_version` is the compatibility contract: a future resume journal
+ * builds on this format, so readers skip records with a version they do not
+ * know instead of guessing.
+ */
+import type { ExecutionEvent, ExecutionTrace, NodeResult, Workflow } from "../types.js";
+export declare const RUN_HISTORY_SCHEMA_VERSION = 1;
+export declare const RUN_HISTORY_DIR: string;
+export declare const RUN_HISTORY_KEEP = 200;
+export type RunStatus = "success" | "failed" | "crashed";
+export interface RunNodeRecord {
+    id: string;
+    status: "success" | "failed" | "skipped";
+    duration_ms: number;
+    tool_calls: number;
+    /** input + output tokens; null when the node reported no usage. */
+    tokens: number | null;
+    /** SDK-reported cost; null when none was reported (never estimated). */
+    cost_usd: number | null;
+    retries: number;
+}
+export interface RunTotals {
+    nodes_total: number;
+    nodes_ok: number;
+    nodes_skipped: number;
+    tool_calls: number;
+    tokens: number | null;
+    cost_usd: number | null;
+}
+export interface RunRecord {
+    schema_version: number;
+    run_id: string;
+    workflow_id: string;
+    workflow_hash: string;
+    started_at: string;
+    duration_ms: number;
+    status: RunStatus;
+    nodes: RunNodeRecord[];
+    routes: Array<{
+        from: string;
+        to: string;
+    }>;
+    totals: RunTotals;
+}
+/** sha256 (hex) of the workflow as canonical JSON: keys sorted, undefined dropped. */
+export declare function hashWorkflow(workflow: Workflow): string;
+/** Sortable id: `YYYYMMDD-HHMMSS-<6 hex>` in UTC, so filename order is run order. */
+export declare function newRunId(startedAtMs: number, rand?: () => string): string;
+export interface NodeTimer {
+    observer: (event: ExecutionEvent) => void;
+    durations: Map<string, number>;
+    /** Last result seen per node: lets a crashed run still record the nodes that finished. */
+    lastResults: Map<string, NodeResult>;
+}
+export declare function createNodeTimer(now?: () => number): NodeTimer;
+export interface BuildRunRecordInput {
+    runId: string;
+    workflow: Workflow;
+    startedAtMs: number;
+    durationMs: number;
+    results: Map<string, NodeResult>;
+    trace?: ExecutionTrace;
+    nodeDurations?: Map<string, number>;
+    crashed?: boolean;
+}
+export declare function buildRunRecord(i: BuildRunRecordInput): RunRecord;
+/** Atomic write: temp file in the same directory, fsync, rename. Returns the path, or null on failure. Never throws. */
+export declare function writeRunRecord(record: RunRecord, cwd?: string): string | null;
+/** Delete the oldest records beyond `keep`. Returns the number removed. Never throws. */
+export declare function pruneRuns(cwd?: string, keep?: number): number;
+/** History is on unless `--no-history` (options.history === false) or `.sweny.yml` has `history: off`. */
+export declare function historyDisabled(optionHistory: unknown, configHistory: unknown): boolean;
+/** Write one record then prune. Never throws; warns on stderr if the write failed. */
+export declare function recordRun(record: RunRecord, cwd?: string): boolean;
+/** All readable records, newest first. Corrupt files and unknown schema versions are skipped. */
+export declare function listRuns(cwd?: string): RunRecord[];
+/** Exact run id, or a unique prefix. */
+export declare function findRun(runs: RunRecord[], ref: string): RunRecord | undefined;

package/dist/cli/run-history.js

@@ -0,0 +1,219 @@
+/**
+ * Local run history for `sweny workflow run`: one small JSON record per run
+ * under `.sweny/runs/`, read back by `sweny runs` and `sweny runs diff`.
+ *
+ * METADATA ONLY. A record holds ids, statuses, durations, counts, token and
+ * cost totals, and routing edges. It never holds prompts, node outputs, tool
+ * inputs/outputs, error text, or environment values.
+ *
+ * `schema_version` is the compatibility contract: a future resume journal
+ * builds on this format, so readers skip records with a version they do not
+ * know instead of guessing.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { summarizeRun } from "./run-output.js";
+export const RUN_HISTORY_SCHEMA_VERSION = 1;
+export const RUN_HISTORY_DIR = path.join(".sweny", "runs");
+export const RUN_HISTORY_KEEP = 200;
+// ── Hash + ids ──────────────────────────────────────────────────
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            const v = value[k];
+            if (v !== undefined)
+                out[k] = canonicalize(v);
+        }
+        return out;
+    }
+    return value;
+}
+/** sha256 (hex) of the workflow as canonical JSON: keys sorted, undefined dropped. */
+export function hashWorkflow(workflow) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify(canonicalize(workflow)))
+        .digest("hex");
+}
+const RUN_ID_RE = /^\d{8}-\d{6}-[0-9a-f]{6}$/;
+/** Sortable id: `YYYYMMDD-HHMMSS-<6 hex>` in UTC, so filename order is run order. */
+export function newRunId(startedAtMs, rand = () => crypto.randomBytes(3).toString("hex")) {
+    const d = new Date(startedAtMs);
+    const p = (n) => String(n).padStart(2, "0");
+    return (`${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}-` +
+        `${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}-${rand()}`);
+}
+export function createNodeTimer(now = Date.now) {
+    const entered = new Map();
+    const durations = new Map();
+    const lastResults = new Map();
+    return {
+        durations,
+        lastResults,
+        observer(event) {
+            if (event.type === "node:enter")
+                entered.set(event.node, now());
+            else if (event.type === "node:exit") {
+                const start = entered.get(event.node);
+                if (start !== undefined)
+                    durations.set(event.node, (durations.get(event.node) ?? 0) + (now() - start));
+                lastResults.set(event.node, event.result);
+            }
+        },
+    };
+}
+// ── Build the record ────────────────────────────────────────────
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+export function buildRunRecord(i) {
+    const summary = summarizeRun(i.results, i.durationMs, i.crashed);
+    const retries = new Map();
+    for (const s of i.trace?.steps ?? []) {
+        if (s.retryAttempt !== undefined)
+            retries.set(s.node, Math.max(retries.get(s.node) ?? 0, s.retryAttempt));
+    }
+    const nodes = [...i.results].map(([id, r]) => {
+        const u = r.usage;
+        const hasTokens = !!u && (isNum(u.inputTokens) || isNum(u.outputTokens));
+        const tokens = hasTokens
+            ? (isNum(u.inputTokens) ? u.inputTokens : 0) + (isNum(u.outputTokens) ? u.outputTokens : 0)
+            : null;
+        return {
+            id,
+            status: r.status,
+            duration_ms: Math.max(0, Math.round(i.nodeDurations?.get(id) ?? 0)),
+            tool_calls: r.toolCalls?.length ?? 0,
+            tokens,
+            cost_usd: u && isNum(u.costUsd) ? u.costUsd : null,
+            retries: retries.get(id) ?? 0,
+        };
+    });
+    return {
+        schema_version: RUN_HISTORY_SCHEMA_VERSION,
+        run_id: i.runId,
+        workflow_id: i.workflow.id,
+        workflow_hash: hashWorkflow(i.workflow),
+        started_at: new Date(i.startedAtMs).toISOString(),
+        duration_ms: Math.max(0, Math.round(i.durationMs)),
+        status: i.crashed ? "crashed" : summary.ok ? "success" : "failed",
+        nodes,
+        routes: (i.trace?.edges ?? []).map((e) => ({ from: e.from, to: e.to })),
+        totals: {
+            nodes_total: summary.nodesTotal,
+            nodes_ok: summary.nodesOk,
+            nodes_skipped: summary.nodesSkipped,
+            tool_calls: summary.toolCalls,
+            tokens: summary.tokens ?? null,
+            cost_usd: summary.costUsd ?? null,
+        },
+    };
+}
+// ── Write, prune, read ──────────────────────────────────────────
+/** Atomic write: temp file in the same directory, fsync, rename. Returns the path, or null on failure. Never throws. */
+export function writeRunRecord(record, cwd = process.cwd()) {
+    const dir = path.join(cwd, RUN_HISTORY_DIR);
+    const final = path.join(dir, `${record.run_id}.json`);
+    const tmp = path.join(dir, `.${record.run_id}.json.${process.pid}.tmp`);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const fd = fs.openSync(tmp, "w");
+        try {
+            fs.writeSync(fd, JSON.stringify(record, null, 2) + "\n");
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, final);
+        return final;
+    }
+    catch {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // nothing to clean
+        }
+        return null;
+    }
+}
+/** Delete the oldest records beyond `keep`. Returns the number removed. Never throws. */
+export function pruneRuns(cwd = process.cwd(), keep = RUN_HISTORY_KEEP) {
+    try {
+        const dir = path.join(cwd, RUN_HISTORY_DIR);
+        const files = fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith(".json") && RUN_ID_RE.test(f.slice(0, -5)))
+            .sort();
+        const extra = files.slice(0, Math.max(0, files.length - keep));
+        for (const f of extra)
+            fs.rmSync(path.join(dir, f), { force: true });
+        return extra.length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** History is on unless `--no-history` (options.history === false) or `.sweny.yml` has `history: off`. */
+export function historyDisabled(optionHistory, configHistory) {
+    if (optionHistory === false)
+        return true;
+    return typeof configHistory === "string" && ["off", "false", "no", "0"].includes(configHistory.trim().toLowerCase());
+}
+/** Write one record then prune. Never throws; warns on stderr if the write failed. */
+export function recordRun(record, cwd = process.cwd()) {
+    const written = writeRunRecord(record, cwd);
+    if (!written) {
+        process.stderr.write(`  ⚠ could not write run history to ${RUN_HISTORY_DIR}\n`);
+        return false;
+    }
+    pruneRuns(cwd);
+    return true;
+}
+function isRecord(v) {
+    const r = v;
+    return (!!r &&
+        typeof r === "object" &&
+        r.schema_version === RUN_HISTORY_SCHEMA_VERSION &&
+        typeof r.run_id === "string" &&
+        typeof r.workflow_id === "string" &&
+        typeof r.started_at === "string" &&
+        Array.isArray(r.nodes) &&
+        Array.isArray(r.routes) &&
+        !!r.totals &&
+        typeof r.totals === "object");
+}
+/** All readable records, newest first. Corrupt files and unknown schema versions are skipped. */
+export function listRuns(cwd = process.cwd()) {
+    const dir = path.join(cwd, RUN_HISTORY_DIR);
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith(".json") && !f.startsWith("."));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
+            if (isRecord(parsed))
+                out.push(parsed);
+        }
+        catch {
+            // corrupt record: skip
+        }
+    }
+    return out.sort((a, b) => a.started_at === b.started_at ? b.run_id.localeCompare(a.run_id) : b.started_at.localeCompare(a.started_at));
+}
+/** Exact run id, or a unique prefix. */
+export function findRun(runs, ref) {
+    const exact = runs.find((r) => r.run_id === ref);
+    if (exact)
+        return exact;
+    const matches = runs.filter((r) => r.run_id.startsWith(ref));
+    return matches.length === 1 ? matches[0] : undefined;
+}

package/dist/cli/runs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `sweny runs` and `sweny runs diff`: read-only views over `.sweny/runs/`.
+ * Metadata only. Color only when `color` is true (TTY).
+ */
+import type { Command } from "commander";
+import { type RunRecord } from "./run-history.js";
+export declare function formatAge(startedAt: string, nowMs?: number): string;
+export declare function formatRunsTable(runs: RunRecord[], color: boolean, nowMs?: number): string;
+export declare function formatRunDiff(a: RunRecord, b: RunRecord, color: boolean): string;
+/** Pick two runs: explicit refs, or the newest two runs of one workflow (--workflow, else the newest workflow with two or more runs). a = older, b = newer. */
+export declare function pickRunsForDiff(runs: RunRecord[], refs: string[], workflowId?: string): {
+    a: RunRecord;
+    b: RunRecord;
+} | {
+    error: string;
+};
+export declare function registerRunsCommand(program: Command): Command;

package/dist/cli/runs.js

@@ -0,0 +1,216 @@
+/**
+ * `sweny runs` and `sweny runs diff`: read-only views over `.sweny/runs/`.
+ * Metadata only. Color only when `color` is true (TTY).
+ */
+import chalk from "chalk";
+import { findRun, listRuns } from "./run-history.js";
+import { formatCost, formatReceiptDuration, formatTokenCount } from "./run-output.js";
+// ── Small formatters ────────────────────────────────────────────
+export function formatAge(startedAt, nowMs = Date.now()) {
+    const s = Math.max(0, Math.round((nowMs - Date.parse(startedAt)) / 1000));
+    if (s < 60)
+        return "just now";
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 48)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+const ICON = { success: "✓", failed: "✗", crashed: "✗", skipped: "−" };
+function paint(text, status, color) {
+    if (!color)
+        return text;
+    if (status === "success")
+        return chalk.green(text);
+    if (status === "skipped")
+        return chalk.dim(text);
+    return chalk.red(text);
+}
+const tokensText = (n) => (n === null ? "-" : formatTokenCount(n));
+const costText = (n) => (n === null ? "-" : formatCost(n));
+function pad(s, w, right = false) {
+    return right ? s.padStart(w) : s.padEnd(w);
+}
+// ── sweny runs ──────────────────────────────────────────────────
+export function formatRunsTable(runs, color, nowMs = Date.now()) {
+    if (runs.length === 0)
+        return "  No runs recorded yet. Run `sweny workflow run <file>` to start a history.\n";
+    const rows = runs.map((r) => ({
+        status: r.status,
+        cells: [
+            r.run_id,
+            r.workflow_id,
+            `${ICON[r.status] ?? "?"} ${r.status}`,
+            formatReceiptDuration(r.duration_ms),
+            tokensText(r.totals?.tokens ?? null),
+            costText(r.totals?.cost_usd ?? null),
+            formatAge(r.started_at, nowMs),
+        ],
+    }));
+    const head = ["ID", "WORKFLOW", "STATUS", "DURATION", "TOKENS", "COST", "AGE"];
+    const rightAligned = new Set([3, 4, 5]);
+    const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r.cells[i].length)));
+    const line = (cells, status) => "  " +
+        cells
+            .map((c, i) => {
+            let t = pad(c, widths[i], rightAligned.has(i));
+            if (i === 2 && status)
+                t = paint(t, status, color);
+            return t;
+        })
+            .join("  ")
+            .trimEnd();
+    const headLine = line(head);
+    return [color ? chalk.dim(headLine) : headLine, ...rows.map((r) => line(r.cells, r.status))].join("\n") + "\n";
+}
+// ── sweny runs diff ─────────────────────────────────────────────
+const sign = (n) => (n > 0 ? "+" : n < 0 ? "-" : "");
+/** Like the receipt duration, but keeps one decimal under 10s so small deltas stay visible. */
+function fmtDur(ms) {
+    return ms >= 1000 && ms < 10_000 ? `${Math.round(ms / 100) / 10}s` : formatReceiptDuration(ms);
+}
+const deltaDuration = (a, b) => `${sign(b - a)}${fmtDur(Math.abs(b - a))}`;
+const deltaTokens = (a, b) => `${sign(b - a)}${formatTokenCount(Math.abs(b - a))}`;
+const deltaCost = (a, b) => `${sign(b - a)}${formatCost(Math.abs(b - a))}`;
+const deltaCount = (a, b) => `${sign(b - a)}${Math.abs(b - a)}`;
+/** `label a → b (+delta)` for a numeric metric; null when unchanged. */
+function metric(label, a, b, show, delta) {
+    if (a === b)
+        return null;
+    if (a === null || b === null)
+        return `${label} ${a === null ? "-" : show(a)} → ${b === null ? "-" : show(b)}`;
+    return `${label} ${show(a)} → ${show(b)} (${delta(a, b)})`;
+}
+function nodeChanges(a, b) {
+    return [
+        metric("duration", a.duration_ms, b.duration_ms, fmtDur, deltaDuration),
+        metric("tokens", a.tokens, b.tokens, formatTokenCount, deltaTokens),
+        metric("cost", a.cost_usd, b.cost_usd, formatCost, deltaCost),
+        metric("tools", a.tool_calls, b.tool_calls, String, deltaCount),
+        metric("retries", a.retries, b.retries, String, deltaCount),
+    ].filter((x) => x !== null);
+}
+const routeKey = (r) => `${r.from} → ${r.to}`;
+export function formatRunDiff(a, b, color) {
+    const dim = (s) => (color ? chalk.dim(s) : s);
+    const out = [];
+    const hdr = (tag, r) => `  ${tag}  ${r.run_id}  ${r.workflow_id}  ${paint(`${ICON[r.status] ?? "?"} ${r.status}`, r.status, color)}  ${formatReceiptDuration(r.duration_ms)}`;
+    out.push(hdr("a", a), hdr("b", b), "");
+    const short = (h) => h.slice(0, 7);
+    out.push(a.workflow_hash === b.workflow_hash
+        ? `  workflow   unchanged (${short(a.workflow_hash)})`
+        : `  workflow   changed ${short(a.workflow_hash)} → ${short(b.workflow_hash)}`);
+    if (a.workflow_id !== b.workflow_id)
+        out.push(`  id         ${a.workflow_id} → ${b.workflow_id}`);
+    out.push(a.status === b.status
+        ? `  status     ${ICON[b.status]} ${b.status} (same)`
+        : `  status     ${ICON[a.status]} ${a.status} → ${paint(`${ICON[b.status]} ${b.status}`, b.status, color)}`);
+    const tot = [
+        metric("duration  ", a.duration_ms, b.duration_ms, formatReceiptDuration, deltaDuration),
+        metric("tokens    ", a.totals.tokens, b.totals.tokens, formatTokenCount, deltaTokens),
+        metric("cost      ", a.totals.cost_usd, b.totals.cost_usd, formatCost, deltaCost),
+    ];
+    for (const t of tot)
+        if (t)
+            out.push(`  ${t}`);
+    out.push("", "  nodes");
+    const aNodes = new Map(a.nodes.map((n) => [n.id, n]));
+    const bNodes = new Map(b.nodes.map((n) => [n.id, n]));
+    const ids = [...new Set([...b.nodes.map((n) => n.id), ...a.nodes.map((n) => n.id)])];
+    const w = Math.max(4, ...ids.map((i) => i.length));
+    for (const id of ids) {
+        const na = aNodes.get(id);
+        const nb = bNodes.get(id);
+        if (na && !nb) {
+            out.push(`    ${pad(id, w)}  ${dim("removed")} (was ${ICON[na.status]} ${na.status})`);
+        }
+        else if (!na && nb) {
+            out.push(`    ${pad(id, w)}  ${paint(`added ${ICON[nb.status]} ${nb.status}`, nb.status, color)}`);
+        }
+        else if (na && nb) {
+            const st = na.status === nb.status ? ICON[nb.status] : `${ICON[na.status]} → ${paint(ICON[nb.status], nb.status, color)}`;
+            const ch = nodeChanges(na, nb);
+            out.push(`    ${pad(id, w)}  ${st}  ${ch.length ? ch.join("   ") : dim("no change")}`);
+        }
+    }
+    out.push("", "  routes");
+    const ar = new Set(a.routes.map(routeKey));
+    const br = new Set(b.routes.map(routeKey));
+    const onlyA = [...ar].filter((r) => !br.has(r));
+    const onlyB = [...br].filter((r) => !ar.has(r));
+    if (onlyA.length === 0 && onlyB.length === 0)
+        out.push("    identical");
+    for (const r of onlyA)
+        out.push(`    - ${r}  ${dim("(only in a)")}`);
+    for (const r of onlyB)
+        out.push(`    + ${r}  ${dim("(only in b)")}`);
+    return out.join("\n") + "\n";
+}
+/** Pick two runs: explicit refs, or the newest two runs of one workflow (--workflow, else the newest workflow with two or more runs). a = older, b = newer. */
+export function pickRunsForDiff(runs, refs, workflowId) {
+    if (refs.length === 1)
+        return { error: "Pass two run ids, or none to diff the last two runs of a workflow." };
+    if (refs.length === 2) {
+        const a = findRun(runs, refs[0]);
+        const b = findRun(runs, refs[1]);
+        if (!a)
+            return { error: `No run matches "${refs[0]}". Run \`sweny runs\` to list ids.` };
+        if (!b)
+            return { error: `No run matches "${refs[1]}". Run \`sweny runs\` to list ids.` };
+        return { a, b };
+    }
+    // No --workflow: the newest workflow that has at least two runs to compare.
+    const counts = new Map();
+    for (const r of runs)
+        counts.set(r.workflow_id, (counts.get(r.workflow_id) ?? 0) + 1);
+    const wf = workflowId ?? runs.find((r) => (counts.get(r.workflow_id) ?? 0) >= 2)?.workflow_id ?? runs[0]?.workflow_id;
+    const same = wf ? runs.filter((r) => r.workflow_id === wf) : [];
+    if (same.length < 2) {
+        return { error: wf ? `Need two runs of "${wf}" to diff; found ${same.length}.` : "No runs recorded yet." };
+    }
+    return { a: same[1], b: same[0] };
+}
+// ── Command wiring ──────────────────────────────────────────────
+export function registerRunsCommand(program) {
+    const runsCmd = program
+        .command("runs")
+        .description("List recent workflow runs recorded in .sweny/runs/ (metadata only)")
+        .option("--workflow <id>", "Only runs of this workflow")
+        .option("--limit <n>", "Max runs to show", "20")
+        .option("--json", "Output run records as JSON")
+        .action((opts) => {
+        const limit = Number(opts.limit ?? "20");
+        if (!Number.isInteger(limit) || limit < 1) {
+            console.error(chalk.red("  --limit must be a positive integer"));
+            process.exitCode = 1;
+            return;
+        }
+        let runs = listRuns();
+        if (opts.workflow)
+            runs = runs.filter((r) => r.workflow_id === opts.workflow);
+        runs = runs.slice(0, limit);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(runs, null, 2) + "\n");
+            return;
+        }
+        process.stdout.write("\n" + formatRunsTable(runs, process.stdout.isTTY ?? false) + "\n");
+    });
+    runsCmd
+        .command("diff [a] [b]")
+        .description("Compare two runs (default: the last two runs of the same workflow)")
+        .option("--workflow <id>", "Workflow to pick the default pair from")
+        .action((a, b, opts) => {
+        const refs = [a, b].filter((x) => x !== undefined);
+        const runs = listRuns();
+        const picked = pickRunsForDiff(runs, refs, opts.workflow);
+        if ("error" in picked) {
+            console.error(chalk.red(`  ${picked.error}`));
+            process.exitCode = 1;
+            return;
+        }
+        process.stdout.write("\n" + formatRunDiff(picked.a, picked.b, process.stdout.isTTY ?? false) + "\n");
+    });
+    return runsCmd;
+}

package/dist/executor.js

@@ -19,6 +19,7 @@ import { evaluateRequires } from "./requires.js";
 import { buildRetryPreamble } from "./retry.js";
 import { resolveExecutionModel } from "./model.js";
 import { buildToolAliases } from "./skills/index.js";
+import { validateWorkflow } from "./schema.js";
 import { resolveAgentAccess } from "./agent-env.js";
 import { fenceUntrusted } from "./untrusted.js";
 /**
@@ -1052,6 +1053,16 @@ function validate(workflow, skills) {
         if (!workflow.nodes[edge.to])
             throw new Error(`Edge references unknown node: "${edge.to}"`);
     }
+    // Same structural validation the CLI loader runs (reachability, self-loops,
+    // ambiguous edges, unbounded cycles, reserved eval policies, retry and
+    // max_iterations ceilings). Library callers, Studio's simulator and run.ts
+    // reach execute() without the loader, so without this they got none of it
+    // (#326). Runs once per execute() call, before any node runs. Skill
+    // availability stays a warning below, so no knownSkills here.
+    const structural = validateWorkflow(workflow);
+    if (structural.length > 0) {
+        throw new Error(`Invalid workflow "${workflow.id}":\n${structural.map((e) => `  ${e.code}: ${e.message}`).join("\n")}`);
+    }
     // Check that each node has at least one available skill (if it lists any)
     for (const [nodeId, node] of Object.entries(workflow.nodes)) {
         if (node.skills.length === 0)

package/dist/schema.d.ts

@@ -776,6 +776,22 @@ export declare const nodeToolsZ: z.ZodEffects<z.ZodObject<{
     deny?: string[] | undefined;
     allow?: string[] | undefined;
 }>;
+/**
+ * Ceiling on `retry.max`. Each retry attempt re-invokes the agent on the
+ * node (full model spend), so an unbounded value here is an unbounded spend
+ * multiplier per node, independent of the workflow-level `max_steps` budget.
+ * 10 comfortably covers every declared workflow today (max observed: 1) while
+ * still catching a fat-fingered value (e.g. a missing digit) at author time
+ * instead of at runtime. See #325.
+ */
+export declare const NODE_RETRY_MAX_CEILING = 10;
+/**
+ * Ceiling on an edge's `max_iterations`. A bounded back-edge is still a spend
+ * multiplier (each lap re-runs model nodes), and the default `max_steps` is
+ * 200, so a value above this can never be reached in a default run and only
+ * hides a typo. See #325.
+ */
+export declare const EDGE_MAX_ITERATIONS_CEILING = 100;
 export declare const nodeRetryZ: z.ZodObject<{
     max: z.ZodNumber;
     instruction: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
@@ -2735,7 +2751,7 @@ export declare function parseWorkflow(raw: unknown): {
     }> | undefined;
 };
 export interface WorkflowError {
-    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL";
+    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL" | "EDGE_ITERATIONS_EXCEEDED" | "RETRY_MAX_EXCEEDED";
     message: string;
     nodeId?: string;
 }
@@ -3347,6 +3363,7 @@ export declare const workflowJsonSchema: {
                     readonly max_iterations: {
                         readonly type: "integer";
                         readonly minimum: 1;
+                        readonly maximum: 100;
                         readonly description: "Max times this edge can be followed. Enables controlled retry loops.";
                     };
                 };

package/dist/schema.js

@@ -230,7 +230,14 @@ const retryInstructionReflectZ = z.object({ reflect: z.string().min(1) }).strict
  * still catching a fat-fingered value (e.g. a missing digit) at author time
  * instead of at runtime. See #325.
  */
-const NODE_RETRY_MAX_CEILING = 10;
+export const NODE_RETRY_MAX_CEILING = 10;
+/**
+ * Ceiling on an edge's `max_iterations`. A bounded back-edge is still a spend
+ * multiplier (each lap re-runs model nodes), and the default `max_steps` is
+ * 200, so a value above this can never be reached in a default run and only
+ * hides a typo. See #325.
+ */
+export const EDGE_MAX_ITERATIONS_CEILING = 100;
 export const nodeRetryZ = z
     .object({
     max: z.number().int().min(1).max(NODE_RETRY_MAX_CEILING),
@@ -263,7 +270,7 @@ export const edgeZ = z
     from: z.string().min(1),
     to: z.string().min(1),
     when: z.string().optional(),
-    max_iterations: z.number().int().min(1).optional(),
+    max_iterations: z.number().int().min(1).max(EDGE_MAX_ITERATIONS_CEILING).optional(),
 })
     .strict();
 /**
@@ -352,13 +359,25 @@ export function parseWorkflow(raw) {
 export function validateWorkflow(workflow, knownSkills) {
     const errors = [];
     const nodeIds = new Set(Object.keys(workflow.nodes));
+    const entryExists = nodeIds.has(workflow.entry);
     // Entry must exist
-    if (!nodeIds.has(workflow.entry)) {
+    if (!entryExists) {
         errors.push({
             code: "MISSING_ENTRY",
             message: `Entry node "${workflow.entry}" does not exist`,
         });
     }
+    // Adjacency over real nodes, built once (O(nodes + edges)) so reachability
+    // and cycle detection stay linear on large graphs.
+    const outAll = new Map();
+    const outUnbounded = new Map();
+    const push = (m, k, v) => {
+        const l = m.get(k);
+        if (l)
+            l.push(v);
+        else
+            m.set(k, [v]);
+    };
     // Edge targets must exist
     for (const edge of workflow.edges) {
         if (!nodeIds.has(edge.from)) {
@@ -382,6 +401,18 @@ export function validateWorkflow(workflow, knownSkills) {
                 nodeId: edge.from,
             });
         }
+        if (edge.max_iterations != null && edge.max_iterations > EDGE_MAX_ITERATIONS_CEILING) {
+            errors.push({
+                code: "EDGE_ITERATIONS_EXCEEDED",
+                message: `Edge from "${edge.from}" to "${edge.to}" declares max_iterations ${edge.max_iterations}, above the ceiling of ${EDGE_MAX_ITERATIONS_CEILING}`,
+                nodeId: edge.from,
+            });
+        }
+        if (nodeIds.has(edge.from) && nodeIds.has(edge.to)) {
+            push(outAll, edge.from, edge.to);
+            if (!edge.max_iterations && edge.from !== edge.to)
+                push(outUnbounded, edge.from, edge.to);
+        }
     }
     // Edge determinism: a node with two or more out-edges that have no `when`
     // clause is ambiguous. The executor's resolveNext picks the first such edge
@@ -396,9 +427,7 @@ export function validateWorkflow(workflow, knownSkills) {
             continue;
         if (edge.when)
             continue;
-        const list = unconditionalByNode.get(edge.from) ?? [];
-        list.push(edge.to);
-        unconditionalByNode.set(edge.from, list);
+        push(unconditionalByNode, edge.from, edge.to);
     }
     for (const [from, targets] of unconditionalByNode) {
         if (targets.length > 1) {
@@ -409,60 +438,63 @@ export function validateWorkflow(workflow, knownSkills) {
             });
         }
     }
-    // Don't check reachability if there are structural errors
-    if (errors.length > 0)
-        return errors;
-    // Reachability: BFS from entry
-    const visited = new Set();
-    const queue = [workflow.entry];
-    while (queue.length > 0) {
-        const id = queue.shift();
-        if (visited.has(id))
-            continue;
-        visited.add(id);
-        for (const edge of workflow.edges) {
-            if (edge.from === id && !visited.has(edge.to)) {
-                queue.push(edge.to);
+    // Reachability: BFS from entry. Skipped only when the entry is missing
+    // (every node would be reported, which is noise). All other diagnostics
+    // accumulate so one pass reports every structural problem.
+    if (entryExists) {
+        const visited = new Set([workflow.entry]);
+        const queue = [workflow.entry];
+        for (let i = 0; i < queue.length; i++) {
+            for (const to of outAll.get(queue[i]) ?? []) {
+                if (!visited.has(to)) {
+                    visited.add(to);
+                    queue.push(to);
+                }
             }
         }
-    }
-    for (const nodeId of nodeIds) {
-        if (!visited.has(nodeId)) {
-            errors.push({
-                code: "UNREACHABLE_NODE",
-                message: `Node "${nodeId}" is unreachable from entry "${workflow.entry}"`,
-                nodeId,
-            });
+        for (const nodeId of nodeIds) {
+            if (!visited.has(nodeId)) {
+                errors.push({
+                    code: "UNREACHABLE_NODE",
+                    message: `Node "${nodeId}" is unreachable from entry "${workflow.entry}"`,
+                    nodeId,
+                });
+            }
         }
     }
     // Detect unbounded cycles: the graph with max_iterations edges removed must be acyclic.
     // If removing bounded edges still leaves a cycle, it can loop forever.
-    const unboundedEdges = workflow.edges.filter((e) => !e.max_iterations && e.from !== e.to);
-    // DFS-based cycle detection on the unbounded subgraph
+    // Iterative DFS with an explicit stack so a deep chain cannot overflow the
+    // call stack (#326).
     const WHITE = 0, GRAY = 1, BLACK = 2;
     const color = new Map();
     for (const id of nodeIds)
         color.set(id, WHITE);
-    function dfs(node) {
-        color.set(node, GRAY);
-        for (const e of unboundedEdges) {
-            if (e.from !== node)
+    const findCycle = (start) => {
+        const stack = [{ node: start, i: 0 }];
+        color.set(start, GRAY);
+        while (stack.length > 0) {
+            const top = stack[stack.length - 1];
+            const outs = outUnbounded.get(top.node) ?? [];
+            if (top.i >= outs.length) {
+                color.set(top.node, BLACK);
+                stack.pop();
                 continue;
-            const c = color.get(e.to);
+            }
+            const to = outs[top.i++];
+            const c = color.get(to);
             if (c === GRAY)
-                return e.to; // back-edge found → cycle
+                return to; // back-edge found → cycle
             if (c === WHITE) {
-                const cycle = dfs(e.to);
-                if (cycle)
-                    return cycle;
+                color.set(to, GRAY);
+                stack.push({ node: to, i: 0 });
             }
         }
-        color.set(node, BLACK);
         return null;
-    }
+    };
     for (const id of nodeIds) {
         if (color.get(id) === WHITE) {
-            const cycleNode = dfs(id);
+            const cycleNode = findCycle(id);
             if (cycleNode) {
                 errors.push({
                     code: "UNBOUNDED_CYCLE",
@@ -472,6 +504,18 @@ export function validateWorkflow(workflow, knownSkills) {
             }
         }
     }
+    // Retry ceiling for workflows that never went through zod (library callers,
+    // the e2e batch runner). Mirrors nodeRetryZ so every path enforces it (#325).
+    for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+        const max = node.retry?.max;
+        if (max != null && max > NODE_RETRY_MAX_CEILING) {
+            errors.push({
+                code: "RETRY_MAX_EXCEEDED",
+                message: `Node "${nodeId}" declares retry.max ${max}, above the ceiling of ${NODE_RETRY_MAX_CEILING}`,
+                nodeId,
+            });
+        }
+    }
     // Reject eval policies that are reserved in the vocabulary but not yet
     // implemented. The Zod schema accepts the whole EVAL_POLICIES enum (the
     // published JSON schema advertises them as reserved), but only `all_pass`
@@ -941,6 +985,7 @@ export const workflowJsonSchema = {
                     max_iterations: {
                         type: "integer",
                         minimum: 1,
+                        maximum: EDGE_MAX_ITERATIONS_CEILING,
                         description: "Max times this edge can be followed. Enables controlled retry loops.",
                     },
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.128",
+  "version": "0.1.130",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"