@sweny-ai/core 0.1.129 → 0.1.131

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/package.json

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